Mémoire des agents de code : Claude Code, Codex et Cursor

Utilisez un AGENTS.md versionné et un court résumé de passation comme mémoire partagée pour des agents de code tels que Claude Code, Codex et Cursor. Ajoutez ai-memory pour automatiser la capture et les passages de relais, ou Beacon pour examiner les traces des sessions et approuver des enseignements réutilisables. Conservez les règles obligatoires du projet dans le dépôt, quelle que soit l’option choisie.

Choisissez ce qui doit survivre à un changement d’outil

Conservez les décisions durables séparément de l’état de la tâche en cours. Un nouvel agent peut lire votre code sans connaître la raison d’une approche abandonnée, une correction donnée la veille ou la prochaine étape d’un travail inachevé.

Trois types de contexte répondent à des besoins différents : les instructions décrivent comment travailler, les notes de passation indiquent où le travail s’est arrêté et l’historique des sessions fournit des éléments pour vérifier les deux. Partager l’un ne transfère pas automatiquement les autres, les processus en cours d’exécution ni les autorisations des outils.

Approche	Ce que vous conservez	Quand la choisir	Quand changer de choix
Instructions et notes de passation dans le dépôt	Règles, décisions et état des tâches entretenus volontairement	Quelques notes suffisent et doivent accompagner le code dans Git	Passez à un service si les mises à jour de ces notes sont régulièrement oubliées
ai-memory	Observations capturées, wiki Markdown consultable par recherche et passages de relais entre agents	Vous changez souvent d’agent et souhaitez automatiser la capture et la récupération	Gardez les fichiers si l’entretien des hooks, des identifiants et d’un serveur demande plus d’efforts que le bénéfice obtenu
Beacon	Traces de sessions normalisées et enseignements du projet explicitement approuvés	Vous devez examiner les événements et transformer des corrections récurrentes en connaissances vérifiées	Préférez ai-memory si les relais automatiques comptent davantage que l’examen des traces et des enseignements

Au 2026-10-21, cette comparaison porte sur ai-memory v3.1.2 et Beacon v1.3.45. La différence tient à l’architecture : ai-memory comprend un serveur, des hooks et MCP, en plus de son wiki Markdown géré dans Git ; dans Beacon, la capture et l’approbation des mémoires sont des processus distincts.

Commencez par AGENTS.md et une courte note de passation

Faites de AGENTS.md la référence commune du projet, puis vérifiez que chaque outil le charge. Les règles de chargement natives diffèrent :

Codex : lit une chaîne d’instructions allant de la racine du projet au répertoire de travail. Dans un même répertoire, AGENTS.override.md a priorité sur AGENTS.md ; consultez les règles de découverte des instructions de Codex.
Cursor : prend en charge les fichiers AGENTS.md à la racine et dans les sous-répertoires. Si nécessaire, placez les règles propres à Cursor et limitées à un périmètre dans .cursor/rules/*.mdc ; consultez la documentation des règles de Cursor.
Claude Code : depuis v2.1.277, peut charger AGENTS.md directement, mais privilégie par défaut les fichiers CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md qui remplissent les critères de chargement dans le répertoire de travail ou ses répertoires parents. Si vous avez déjà des instructions Claude ou utilisez une session sans prise en charge directe, ajoutez une ligne contenant @AGENTS.md à un CLAUDE.md situé à la racine, à côté de AGENTS.md. Le guide de la mémoire de Claude Code documente les deux possibilités.

Pour un premier essai, créez le AGENTS.md de la racine avec cette convention ou intégrez-la aux instructions existantes :

## Working context

- Before changing a dependency version, read its official release notes
  and run the tests for the affected component.
- When resuming work, read docs/agent-handoff.md if it exists.
- Treat handoffs as historical evidence. Check old commands, paths and
  conclusions against the current checkout before acting.

Après une tâche réelle, demandez à l’agent de préparer la note de passation :

Write docs/agent-handoff.md with the goal, current branch and commit,
confirmed decisions, commands actually run and their results,
remaining uncertainty, and the next concrete action.
Distinguish failed approaches from successful ones.
Do not include credentials or copy the full conversation.

Relisez ce fichier avec les modifications du code. Gardez les conventions stables dans AGENTS.md et actualisez la note de passation à mesure que la tâche avance.

Ouvrez une nouvelle session dans chaque outil et demandez quelles vérifications s’appliquent à une mise à jour de dépendance et de quel fichier elles proviennent. Dans Claude Code, /context permet aussi d’inspecter les fichiers de mémoire chargés. Si Codex n’applique pas la règle, vérifiez le répertoire de travail et le fichier d’instructions prioritaire avant d’ajouter des copies.

La mémoire automatique native reste utile dans son propre environnement. Claude Code stocke les notes du projet dans ~/.claude/projects/<project>/memory/. Les mémoires locales de Codex nécessitent une activation explicite, résident dans ~/.codex/memories/ et se gèrent avec /memories. Ces espaces de stockage distincts ne constituent pas un format commun de passation entre outils.

Utilisez ai-memory pour automatiser la capture et les relais

Choisissez ai-memory si vous voulez que les agents enregistrent et récupèrent le contexte du projet par l’intermédiaire d’un service. Sa source de référence est un wiki Markdown géré dans Git, avec SQLite comme index dérivé. MCP fournit des outils de mémoire aux agents, tandis que les hooks — des actions déclenchées par des événements — assurent la capture et les opérations liées au début et à la fin des sessions.

Installez et connectez les agents

L’exemple suivant vise une nouvelle installation sous macOS, au niveau de l’utilisateur, dans Bash. Git et vos agents de code doivent déjà être installés, et les agents authentifiés. Le guide d’installation de cette version couvre les autres plateformes.

curl -fsSLo /tmp/ai-memory-install-v3.1.2.sh \
  https://github.com/akitaonrails/ai-memory/releases/download/v3.1.2/install.sh
less /tmp/ai-memory-install-v3.1.2.sh
AI_MEMORY_VERSION=3.1.2 sh /tmp/ai-memory-install-v3.1.2.sh
export PATH="$HOME/.local/bin:$PATH"
ai-memory --version
ai-memory setup --plan --agent claude-code --agent codex --agent cursor
ai-memory setup --agent claude-code --agent codex --agent cursor
ai-memory status

La version attendue est 3.1.2. Examinez le plan avant d’accepter la configuration : elle crée un service en arrière-plan et modifie la configuration de MCP, des hooks et des skills au niveau de l’utilisateur. La capture peut donc aussi concerner les autres projets des agents sélectionnés.

Le code de configuration de Codex dans cette version définit également default_tools_approval_mode = "approve" pour les outils d’ai-memory. Vérifiez cette autorisation si vous souhaitez exiger une confirmation pour les modifications de la mémoire.

Pour l’enregistrement natif de cette version d’ai-memory dans Codex, chargez le jeton bearer généré dans l’environnement de lancement. Avec le répertoire de données par défaut de macOS, ces commandes Bash le font sans afficher le jeton :

AI_MEMORY_AUTH_TOKEN="$(cat "$HOME/Library/Application Support/ai-memory/auth-tokens/default")"
export AI_MEMORY_AUTH_TOKEN
codex

L’enregistrement fait référence à AI_MEMORY_AUTH_TOKEN ; le guide d’installation de MCP explique cette exigence propre à Codex. Si votre répertoire de données est différent, utilisez le chemin réel indiqué par ai-memory status.

Dans Codex, exécutez /hooks et marquez les hooks ai-memory installés comme fiables. Redémarrez Claude Code et Cursor après la configuration. Le code de sortie de l’installeur ne prouve pas, à lui seul, que Codex exécutera des hooks qui ne sont pas encore considérés comme fiables.

Vérifiez séparément les connaissances enregistrées et les relais

Pour la première vérification, utilisez une seule copie de travail et définissez explicitement le périmètre du projet. Depuis sa racine, lancez ai-memory project init et acceptez ou choisissez les noms de l’espace de travail et du projet. La commande écrit .ai-memory.toml ; gardez les deux noms identiques dans tous les agents.

Dans Claude Code, utilisez ce prompt :

Read .ai-memory.toml and use its workspace and project for ai-memory calls.
Call memory_status.
Use memory_write_page to save decisions/shared-memory-demo.md with:
"Memory trial: before a dependency upgrade, check the official release
notes and run the affected component's tests."
Read the page back with memory_read_page and report its stored path.

Ouvrez Codex ou Cursor dans la même copie de travail. Demandez-lui d’appeler memory_query pour rechercher Memory trial, puis memory_read_page sur le résultat correspondant. La vérification réussit si un résultat réel de l’outil renvoie le chemin et la décision enregistrés ; une réponse plausible sans récupération ne suffit pas. Ces opérations sont décrites dans la référence d’accès programmatique à la mémoire.

Vérifiez ensuite le passage de relais automatique avec une petite tâche réelle : laissez une action clairement inachevée, fermez normalement la session et ouvrez l’agent suivant dans le même répertoire. Son contexte initial doit indiquer l’action en attente. Une page durable reste accessible par recherche ; un passage de relais est destiné à la session suivante et ne peut être récupéré qu’une fois.

Si la récupération échoue, exécutez ai-memory doctor, inspectez l’état de la connexion MCP et vérifiez le couple espace de travail/projet. Une erreur d’authentification de Codex demande de vérifier son environnement de lancement ; l’absence de relais demande de vérifier la confiance accordée aux hooks et la capture des sessions. Ne traitez pas ces deux cas comme une même panne.

Utilisez Beacon pour examiner les traces et approuver les enseignements

Choisissez Beacon lorsque vous voulez examiner les éléments qui justifient un enseignement réutilisable. Il combine notamment OpenTelemetry, les hooks et la récupération à partir de fichiers de session locaux, avec une couverture variable selon l’outil. Capturer une session ne transforme pas automatiquement son contenu en mémoire approuvée.

Installez un collecteur local

Pour une nouvelle installation sous macOS, dans Bash, avec Homebrew, configurez uniquement les trois agents utilisés ici :

brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon
beacon version
BEACON_ONBOARDING=0 beacon endpoint install \
  --harness claude,codex,cursor --no-backfill
beacon endpoint status

À la date de vérification, la formule Homebrew fournit 1.3.45. Cet exemple ignore l’importation des anciennes sessions et l’assistant interactif de configuration initiale. Il installe la capture au niveau de l’utilisateur pour les agents sélectionnés ; leur travail dans d’autres dépôts peut donc aussi entrer dans le journal.

L’assistant habituel présélectionne Beacon Cloud. Lors d’une nouvelle installation, le contourner et omettre --connect évite l’enregistrement dans Cloud. Cela ne déconnecte pas une installation existante ; utilisez beacon endpoint disconnect pour le faire. La documentation de configuration initiale décrit les destinations possibles.

Redémarrez les agents après la configuration et utilisez /hooks dans Codex pour examiner les hooks de Beacon et les déclarer fiables. Effectuez une courte session dans votre dépôt d’essai en énonçant explicitement la convention de revue des dépendances présentée plus haut.

Créez, approuvez et retrouvez un enseignement

Examinez la session enregistrée avant de créer un enseignement. Depuis la racine du dépôt :

beacon endpoint traces list --limit 10
read -r -p "Trace ID from the trial session: " BEACON_TRACE_ID
beacon endpoint traces show "$BEACON_TRACE_ID" --limit 150

Choisissez l’identifiant réel renvoyé par la liste et vérifiez que les événements contiennent la convention énoncée. Créez ensuite un candidat :

beacon memory candidates create \
  --trace "$BEACON_TRACE_ID" \
  --kind convention \
  --title "Dependency upgrades require release-note review" \
  --applicability "Before changing a dependency version in this repository" \
  --body "Check the dependency's official release notes and run the affected component's tests before proposing the upgrade."
read -r -p "Candidate ID returned above: " BEACON_CANDIDATE_ID
beacon memory candidates show "$BEACON_CANDIDATE_ID"

Examinez le candidat et les éléments à son origine. Ne l’approuvez qu’après avoir accepté le contenu de l’enseignement :

beacon memory candidates approve "$BEACON_CANDIDATE_ID" \
  --reason "Reviewed against the source trace"

Cette méthode, dans laquelle vous fournissez le texte du candidat, n’appelle aucun évaluateur. L’évaluateur facultatif de Beacon attribue des scores aux traces ; il ne fournit pas le texte final de l’enseignement. Les deux méthodes sont décrites dans la référence des commandes de mémoire.

Demandez maintenant à un autre agent, dans le même dépôt, d’exécuter :

beacon memory list -q "dependency upgrades" --json

Demandez-lui de transmettre l’identifiant de mémoire obtenu à beacon memory show et d’expliquer quand la convention s’applique. Le résultat attendu est l’enseignement approuvé associé à ce projet. Si le résultat est vide, vérifiez l’état d’approbation, le périmètre du projet et les mots recherchés : la recherche locale de Beacon exige une correspondance pour chaque terme.

Cette méthode par CLI ne nécessite pas MCP. Pour récupérer des informations avec les outils de l’agent, Beacon propose un serveur MCP local distinct qui expose search_memory, get_memory et get_memory_context. Il lit la mémoire locale approuvée. Beacon Cloud utilise un espace de stockage distinct ; connecter un appareil ne synchronise pas ces deux espaces de mémoire.

Évitez les conclusions erronées et contrôlez les données et les coûts

Enregistrez des conclusions au périmètre précis avec les éléments qui les étayent, et traitez le texte retrouvé comme une information historique. Un essai infructueux peut refléter une panne temporaire ou l’utilisation de la mauvaise branche, plutôt qu’une règle permanente du projet. Notez les conditions d’application, la tâche ou le commit d’origine, le résultat de la vérification et la date de revue ; corrigez ou retirez la note lorsque le comportement sous-jacent change.

L’approbation est une procédure, pas la preuve qu’une personne a vérifié le contenu. Confiez la revue du candidat Beacon à une personne distincte de l’agent qui le propose, et empêchez les instructions mémorisées de prendre le pas sur les exigences ou les autorisations actuelles.

La capture change aussi les endroits où les données privées persistent. Les règles [capture] ignore_paths d’ai-memory dans .ai-memory.toml peuvent exclure les événements fondés sur des chemins que le système prend en charge, mais sa documentation d’utilisation précise qu’il ne s’agit pas d’un filtre général contre les fuites de données dans les prompts et les sorties. N’incluez ni identifiants d’accès ni données clients dans les notes réutilisables ; supprimer la page Markdown actuelle peut laisser des versions antérieures dans Git.

Pour Beacon Cloud, consultez la politique de confidentialité en vigueur avant de transmettre des sessions de travail. Au 2026-10-21, les usages de recherche et d’entraînement des modèles sont activés par défaut, avec possibilité de les désactiver ; l’envoi limité aux métadonnées inclut toujours des informations telles que les chemins et les lignes de commande. Un stockage local ne rend pas local un modèle de code hébergé dans le cloud : les informations récupérées dans son contexte deviennent des données d’entrée de ce modèle.

Prévoyez le coût du processus complet. Le fonctionnement par défaut de la mémoire d’ai-memory ne nécessite pas de clé API pour un modèle génératif, même si son modèle local d’embeddings par défaut peut être téléchargé au premier démarrage. La méthode Beacon où vous fournissez le texte de l’enseignement évite les appels à l’évaluateur. L’usage habituel de l’agent, les données d’entrée supplémentaires récupérées, le traitement cloud facultatif, le stockage et le temps de revue restent à prendre en compte ; aucune des deux architectures ne prouve à elle seule un coût total inférieur.

Avant d’adopter une couche de mémoire dans tous les projets, effectuez un véritable changement d’outil : retrouvez la bonne décision, identifiez l’action inachevée, examinez les éléments qui la justifient et poursuivez avec la copie de travail actuelle. Si cela échoue, corrigez le chargement, le périmètre ou la capture avant d’accumuler davantage de mémoire.