Claude Code et Codex : révolution de la mémoire avec Neo4j

L'implémentation des hooks permet à Claude Code, Codex et Cursor de bénéficier d'une mémoire persistante via Neo4j, tout en évitant le verrouillage fournisseur. Le véritable enjeu n'est pas de savoir quand le prochain modèle supérieur sera disponible, mais plutôt qui saura construire le cadre adéquat autour de ces technologies. Un cadre constitue l'infrastructure entourant le modèle : la boucle d'agent, les définitions d'outils, la gestion du contexte, la mémoire, les prompts et les flux de travail, transformant un LLM brut en un produit utile. Des exemples de ces cadres incluent Cursor, Claude Desktop, et d'autres.

Un débat persiste dans le domaine des outils de codage IA : s'engager dans un cadre spécifique implique-t-il un verrouillage fournisseur ? La mémoire est l'aspect le plus critique de cette question. Si la mémoire de l'agent est confinée dans un cadre fermé ou derrière une API propriétaire, elle n'est pas réellement possédée, et les coûts de changement peuvent s'accumuler rapidement. Cependant, cela ne doit pas être le cas.

L'idée centrale de cet article est simple : garder la couche de mémoire en dehors du cadre, permettant ainsi à n'importe quel cadre de s'y connecter.

Conception de la mémoire agentique unifiée

Cet article démontre comment construire une couche de mémoire partagée qui fonctionne à travers trois agents de codage différents — Claude Code, Codex d'OpenAI, et Cursor — en utilisant des hooks comme mécanisme d'intégration et Neo4j comme magasin persistant. Le code pour l'intégration des hooks est disponible sur GitHub.

Les outils MCP ne suffisent pas pour la mémoire

Les serveurs MCP (Model Context Protocol) sont souvent utilisés pour donner aux agents accès à des systèmes externes. Et ils fonctionnent. Une base de données Neo4j peut être exposée comme un outil MCP et l'agent peut l'interroger quand il le décide.

Cependant, les outils MCP sont initiés par l'agent. Le modèle doit décider d'appeler l'outil, et il doit savoir quand et pourquoi le faire. Cela signifie que :

• L'agent doit "se souvenir de se souvenir", il doit décider de manière proactive de stocker quelque chose qui vaut la peine d'être rappelé plus tard.
• Il n'y a aucune garantie de cohérence, une session peut tout enregistrer, la suivante peut ne rien enregistrer.
• Le jugement du modèle est sollicité concernant ce qui est important pour la mémoire, en temps réel, pendant qu'il est occupé à faire autre chose.

Ce qui est vraiment souhaité, c'est une journalisation passive et déterministe, qui capture chaque événement de session indépendamment de ce que fait le modèle, sans consommer de son contexte ou de son attention.

C'est exactement ce que les hooks offrent.

Fonctionnement des hooks

Les hooks permettent d'écrire des flux programmatiques et déterministes basés sur un ensemble d'événements prédéfinis. Les hooks sont des commandes shell qui s'exécutent automatiquement lors des événements de cycle de vie : lorsque la session commence, lorsque l'utilisateur soumet un prompt, avant et après chaque utilisation d'outil, et lorsque la session se termine. L'agent ne décide pas de les appeler, ils s'exécutent de manière programmatique.

L'idée clé est que les hooks sont remarquablement standardisés entre les fournisseurs. Claude Code, Codex, Cursor, et d'autres prennent tous en charge essentiellement les mêmes événements de cycle de vie :

• SessionStart pour le début de la session de l'agent
• UserPromptSubmit (ou beforeSubmitPrompt dans Cursor) pour lorsque l'utilisateur envoie un message
• PreToolUse / PostToolUse pour avant et après chaque appel d'outil
• Stop pour la fin de la session

Le hook reçoit une charge utile JSON sur stdin avec l'ID de session, le nom de l'événement, les détails de l'outil, et le prompt utilisateur. Et le hook peut émettre JSON sur stdout pour injecter un contexte supplémentaire dans la conversation. Même contrat, trois cadres/clients.

Couche de mémoire partagée

Maintenant, il est nécessaire d'un endroit pour persister la mémoire. Petite précision : un responsable de Neo4j travaille chez Neo4j, donc cet exemple l'utilise.

Structure de session

Le modèle est simple. Chaque session d'agent est un nœud, connecté à une liste chaînée de nœuds d'événements, un par invocation de hook. Les événements sont typés par l'événement de cycle de vie qui les a déclenchés : SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop. Une session se termine par une chronologie ordonnée de tout ce qui s'est passé pendant cette exécution.

Tous les cinq types d'événements sont écrits dans le magasin, ce qui donne une piste d'audit complète de chaque session à travers chaque cadre. Deux d'entre eux sont également des points d'injection. SessionStart se déclenche avant que l'agent ne lise son prompt système, donc tout ce que le hook émet là est ajouté au prompt système. C'est ainsi que la mémoire persistante au niveau de l'agent pénètre dans le contexte. UserPromptSubmit se déclenche juste avant que le message utilisateur ne soit envoyé, et tout ce qui y est émis est ajouté au prompt utilisateur. C'est le hook pour le contexte au niveau du tour, comme l'intégration de souvenirs pertinents à ce que l'utilisateur vient de taper.

Exemples d'interactions dans Cursor

Si les résultats sont inspectés dans le navigateur Neo4j.

Un exemple de session persistée sous forme de graphique dans Neo4j.

Une contrainte importante : les hooks s'exécutent en dehors de la session de modèle du cadre. Le LLM avec lequel l'agent communique ne peut pas être réutilisé. Si un travail alimenté par LLM est souhaité à l'intérieur d'un hook, un appel de modèle propre doit être effectué, ce qui ajoute de la latence à chaque événement que l'agent déclenche. C'est pourquoi les hooks ici ne font que deux choses : enregistrer des événements et injecter des mémoires pré-calculées. Ils restent rapides et déterministes.

Le véritable travail de mémoire se déroule dans une phase de rêve séparée : extraire des faits des sessions, résumer ce qui s'est passé, mettre à jour le graphique. C'est juste un travail par lots qui s'exécute toutes les quelques heures, lit les événements accumulés depuis la dernière exécution, et écrit de nouveau dans le magasin de mémoire. En principe, une mise à jour de mémoire pourrait être déclenchée de manière asynchrone chaque fois qu'une session s'arrête, mais cela semble un peu trop ; un lot périodique est plus simple et fonctionne bien pour cette démonstration.

La phase de rêve prend chaque événement depuis le dernier point de contrôle de la session, les remet à Claude avec le magasin de mémoire actuel, et lui demande d'écrire un petit ensemble de notes durables. Les notes elles-mêmes imitent un wiki en markdown, la même forme que Karpathy et d'autres ont tendance à utiliser pour la mémoire personnelle de LLM et la même forme que les compétences d'Anthropic utilisent déjà : chaque mémoire est un fichier à un chemin sémantique comme profile/role.md, tools/bash/common-flags.md, ou project/neo4j-skills.md, avec des métadonnées YAML en haut et du texte en dessous. Claude est invité à fusionner plutôt qu'à ajouter, donc un chemin est un document vivant, pas un journal ; si de nouveaux événements contredisent une ancienne note, l'ancienne note est réécrite. Le résultat est un arbre de petits fichiers markdown autonomes qu'une session future peut lire, indiscernables en forme d'une compétence, juste rédigés par la phase de rêve au lieu d'être faits à la main.

Accès à la mémoire

Le dernier élément du puzzle est de permettre à l'agent d'accéder à la couche de mémoire. Comme mentionné, il existe deux façons d'injecter des informations dans l'agent : les hooks et les outils MCP.

Les hooks sont déterministes et s'exécutent au début de chaque session pour peupler le prompt système. C'est ici que les informations de profil et les instructions sur la manière d'utiliser la mémoire efficacement doivent être intégrées. Un contexte supplémentaire peut également être ajouté lorsque l'événement de soumission de prompt utilisateur se déclenche, mais c'est en mode ajout uniquement ; d'autres parties du prompt ne peuvent pas être manipulées.

Les outils MCP, en revanche, donnent au LLM un accès direct à la couche de mémoire à la demande. Au lieu de recevoir passivement un contexte au démarrage, l'agent peut rechercher des mémoires pertinentes, stocker de nouvelles informations, et mettre à jour ou supprimer des entrées existantes. Essentiellement, c'est un CRUD de base sur les fichiers markdown abstraits stockés dans Neo4j.

À la fin, il semble que les deux seront presque toujours nécessaires. Dans ce projet, seuls des hooks sont utilisés, pas d'outils MCP, mais le MCP officiel de Neo4j peut toujours être branché pour permettre à l'agent d'explorer le graphique.

Mise en œuvre

De manière quelque peu intéressante, la façon dont les hooks ont été configurés était de pointer l'agent dans n'importe lequel des cadres et de lui demander d'installer des hooks, mais il est certain qu'il existe de meilleures approches également.

Si la mémoire n'est pas possédée, l'agent ne l'est pas non plus. Chaque cadre aujourd'hui construit son propre jardin clos de contexte, de préférences et d'historique de session. Les changer signifie repartir de zéro. Cela ne doit pas être le cas.

Les hooks brisent ce schéma. Ils permettent d'écrire des intégrations qui se branchent à n'importe quel cadre de l'extérieur et l'interface est remarquablement cohérente. Claude Code, Codex, et Cursor déclenchent tous les mêmes événements de cycle de vie : début de session, soumission de prompt, utilisation d'outil, fin de session. Le hook reçoit JSON sur stdin, émet éventuellement JSON sur stdout pour injecter du contexte, et c'est tout le contrat. Comme les hooks s'exécutent de manière déterministe à chaque événement, ils ne consomment pas l'attention du modèle ni ne comptent sur l'agent pour décider ce qui vaut la peine d'être sauvegardé. Les mêmes deux scripts Python gèrent tous les trois clients ; de minces wrappers shell qui passent un drapeau --client sont le seul lien par cadre.

Architecture

L'architecture a trois couches :

• Hooks (en ligne) — enregistrent passivement chaque événement dans Neo4j sous forme de liste chaînée par session. Pas d'appels de modèle, pas de coût de latence, juste un ajout.

• Phase de rêve (hors ligne) — un travail par lots lit les événements accumulés, demande à Claude de les distiller en mémoires markdown durables, et les écrit de nouveau. Les mémoires sont organisées par sujet et fusionnées plutôt qu'ajoutées, donc elles restent actuelles au lieu de croître indéfiniment.

• Injection (en ligne) — au début de la prochaine session dans n'importe quel cadre, les mémoires de profil sont chargées dans le contexte. À chaque prompt utilisateur, des mémoires pertinentes sont recherchées et ajoutées automatiquement.

Le résultat est une couche de mémoire qui se situe en dessous de tous les trois cadres, fonctionne sans que l'un d'eux ne connaisse les autres, et appartient entièrement à l'utilisateur. Il est possible de passer de Cursor à Claude Code à Codex en cours de projet et de reprendre exactement là où l'on s'était arrêté. La compréhension de l'agent sur qui est l'utilisateur, ce sur quoi il travaille, et comment il préfère travailler le suit, et non l'inverse.