kaeru donne à Claude Code et Codex une mémoire durable sous forme de graphe via MCP

Quiconque travaille avec des agents IA depuis plus d'une semaine connaît cette scène. Vous ouvrez un projet, et l'agent pose une question à laquelle vous avez déjà répondu hier. Une demi-heure plus tard, il propose de réparer ce que vous aviez décidé de ne pas toucher, et il se montre convaincant, car il en ignore la raison. Et quand le contexte déborde et que la conversation est comprimée en résumé, la moitié de la discussion se réduit à deux lignes.

L'équipe Lamantin AI propose de traiter ce problème avec une couche de mémoire dédiée. L'outil s'appelle kaeru, et son code source est sur GitHub. Voici une analyse de son fonctionnement et de ses points faibles. L'auteur du texte est le développeur de l'outil lui-même : lisez donc ceci comme un regard de l'intérieur.

Pourquoi un fichier de règles ne suffit pas

La première étape est la même pour tout le monde : CLAUDE.md, AGENTS.md, .cursorrules ou une note dans Obsidian. Environ un mois plus tard, les problèmes commencent :

• le fichier n'est mis à jour que lorsqu'on y pense, c'est-à-dire trois jours plus tard et avec perte de détails ;
• il ne fait que grossir : ajouter est facile, supprimer est effrayant, et l'agent accorde le même crédit à une règle d'hier et à une règle annulée il y a un mois ;
• il contient le « quoi » mais pas le « pourquoi » : « ne pas toucher au parseur » sans raison ne peut ni être vérifié ni être annulé ;
• chaque membre de l'équipe a son propre fichier.

Les ADR et les gestionnaires de tâches comme beads règlent une partie des problèmes, mais pas la couche de travail entre les commits : hypothèses, vérifications, particularités des environnements de test. Tout verser dans le dépôt revient à encombrer l'historique, et ne rien noter revient à perdre l'information. C'est pour cette couche que kaeru a été conçu.

Comment ça fonctionne

kaeru tourne sur votre machine en tant que serveur MCP, auquel se connectent Claude Code, Codex, Cursor et d'autres clients. La mémoire est stockée sous forme de graphe : observations (« les fichiers du client arrivent en cp1251 »), décisions, tâches avec échéances, hypothèses avec le résultat de leur vérification, documents. Les liens sont typés : « a donné naissance à », « remplace », « réfute », « confirme », « bloque », « contredit ». L'agent peut enregistrer toute la chaîne, de l'observation à la décision, comme un raisonnement.

Exemple tiré de l'article : l'agent soupçonne que l'export nocturne échoue à cause de la taille du fichier. Il teste avec un fichier de 2 Go et enregistre immédiatement l'hypothèse avec le verdict « réfutée ». Si l'export plante de nouveau une semaine plus tard, l'agent suivant partira d'une autre piste. Sans mémoire, c'est le résultat négatif qui se perd en premier : les solutions réussies finissent dans le code, les échecs nulle part.

L'ancien peut être remplacé explicitement. L'appel à replace marque l'entrée précédente comme remplacée et montre quelles conclusions s'appuyaient sur elle. L'entrée n'est pas supprimée, son historique est conservé, et l'on peut ouvrir sa version à n'importe quel moment.

Il existe aussi des rappels : une entrée peut être masquée jusqu'à une date donnée. Exemple de l'auteur : le certificat de l'environnement de test est renouvelé tous les six jours. Le cinquième jour, cette information est utile ; le premier, elle ne fait que gêner. Le délai du rappel se compte à partir de la première présentation, il ne « brûle » donc pas pendant des vacances.

Ce que font les hooks et ce que fait le serveur

Le serveur gère le stockage et la synthèse. Le moment où la demander et ce qu'il faut faire lors de la compression du contexte sont décidés par le client, via les hooks de Claude Code et de Codex. L'auteur a écrit une partie des hooks pour son propre usage, et ils ne sont pas encore inclus dans kaeru. Le dépôt contient kaeru-first : avant que l'agent pose une question à l'humain, le hook cherche des correspondances dans la mémoire et propose de lire d'abord ce qui a été trouvé.

Une observation utile : on a simplement suggéré à l'agent de lire les raisonnements enregistrés, et en sept sessions il ne l'a jamais fait. C'est pourquoi la synthèse est injectée automatiquement au démarrage de la session.

Limites

• kaeru ne garantit pas la véracité des entrées. L'agent peut y consigner des absurdités tout comme dans un fichier de règles. L'avantage est que l'on voit de quelles observations une conclusion est issue, et qu'on peut marquer l'erreur et refaire la chaîne.
• Le remplacement de l'ancien doit être déclenché par l'agent lui-même. Chez l'auteur, deux règles avec des ID différents des mêmes personnes dans GitLab ont coexisté pendant deux semaines : la nouvelle a été enregistrée, l'ancienne n'a pas été remplacée.
• Une correspondance de mots ne signifie pas que l'entrée contient la réponse.
• Le serveur d'équipe kaeru-cloud est à déployer chez vous. Il est conçu pour une équipe de confiance, avec un seul espace commun séparé par projets ; il n'y a pas encore d'isolation entre utilisateurs et organisations. Par défaut, les projets sont privés, et avant l'envoi les entrées sont analysées à la recherche de clés et de jetons.

Que faire de tout cela

Si vos agents travaillent plus de quelques jours sur un même projet, il vaut la peine de répartir les connaissances en deux couches. Les accords durables restent dans le dépôt (règles, ADR) et passent en revue. Les découvertes de travail, les hypothèses rejetées et les « pourquoi » exigent un stockage séparé, avec historique et remplacement explicite de l'obsolète. Même sans kaeru, deux pratiques méritent d'être adoptées : consigner les hypothèses avec leur verdict, et fournir automatiquement à l'agent une courte synthèse plutôt que d'espérer qu'il la lise de lui-même.