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 votre agent est confinée dans un cadre fermé ou derrière une API propriétaire, vous ne la possédez pas réellement, 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

Dans cet article, nous allons démontrer 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. Vous pouvez exposer une base de données Neo4j comme un outil MCP et laisser l'agent 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.
• Vous comptez sur le jugement du modèle concernant ce qui est important pour la mémoire, en temps réel, pendant qu'il est occupé à faire autre chose.

Ce que vous voulez vraiment, 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 vous offrent.

Fonctionnement des hooks

Les hooks vous 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, nous avons besoin d'un endroit pour persister la mémoire. Petite précision : je travaille chez Neo4j, donc nous l'utiliserons dans cet exemple.

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 vous 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 nous inspectons les résultats 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. Vous ne pouvez pas réutiliser le LLM avec lequel l'agent communique. Si vous souhaitez un travail alimenté par LLM à l'intérieur d'un hook, vous devez effectuer votre propre appel de modèle, 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. Vous pourriez en principe déclencher une mise à jour de mémoire 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. Vous pouvez également ajouter un contexte supplémentaire lorsque l'événement de soumission de prompt utilisateur se déclenche, mais c'est en mode ajout uniquement ; vous ne pouvez pas manipuler d'autres parties du prompt.

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, je pense que vous aurez presque toujours besoin des deux. Dans ce projet, nous n'avons que des hooks, pas d'outils MCP, mais vous pouvez toujours brancher le MCP officiel de Neo4j pour permettre à l'agent d'explorer le graphique.

Mise en œuvre

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

Si vous ne possédez pas votre mémoire, vous ne possédez pas votre agent. 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 vous 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 vous appartient entièrement. Vous pouvez passer de Cursor à Claude Code à Codex en cours de projet et reprendre exactement là où vous vous étiez arrêté. La compréhension de votre agent sur qui vous êtes, ce sur quoi vous travaillez, et comment vous préférez travailler vous suit, et non l'inverse.