Quatre règles pour une mémoire d’agent qui reste fiable
Enregistrer davantage de notes ne résoudra pas le problème de mémoire de l’agent de codage. Quatre règles garantissent son intégrité : la visibilité de l’obsolescence, la censure en cas d’échec, le troncature explicite et le respect des contraintes.
Sources: Your Coding Agent Has a Memory Problem. Storing More Won’t Fix It.
Ouvrez une deuxième fenêtre de chat et votre agent de codage n’en saura rien. Pas moins que avant, mais rien du tout. La décision prise il y a quarante minutes concernant le refus de l’approche basée sur des files d’attente a disparu. De même que la contrainte selon laquelle l’équipe de sécurité du client ne validera jamais une nouvelle base de données, ainsi que les trois impasses que vous avez déjà explorées afin que personne n’ait à les reprendre. Le contexte ne survit pas à une fenêtre.
C’est pourquoi la routine est la suivante : collez le contenu de l’ancien chat, tapez tout ce dont vous vous souvenez, et expliquez à nouveau ce que vous ne parvenez pas à retrouver. Cela prend facilement dix à quinze minutes par changement, et les demandes premium se perdent dans des conclusions que vous avez déjà obtenues une fois.
Rien sur ces plateformes ne comble cette lacune, car chaque fonctionnalité de mémoire est conçue pour servir précisément ce que l’on cherche à oublier. Une solution proposée par un développeur a été de créer sa propre couche de mémoire : environ 2 600 lignes de code en Node, sans dépendances en temps de exécution, capable de servir GitHub Copilot, Claude Code et Codex. Presque immédiatement, cela a soulevé un problème sur lequel personne ne met en garde.
Stocker plus aggrave les choses
La véritable faille d’un système de mémoire n’est pas l’oubli. C’est se souvenir à tort, et ce, avec assurance.
Imaginez une note indiquant « l’authentification utilise JWT », écrite à l’époque où c’était vrai et retrouvée quatre mois après que le code a été basculé vers des sessions côté serveur. Cette information ne disparaît pas dans l’incertitude : elle est récupérée, considérée comme fiable et utilisée comme base, ce qui conduit à un agent qui se trompe de manière spécifique et affirmée, tout en étant même capable de citer une source. C’est nettement pire qu’un agent qui dit « Je ne sais pas comment fonctionne l’authentification ici », car ce dernier vous demande de l’aide, tandis que l’agent affirmé met son erreur en œuvre.
Ainsi, le stockage n’est pas le lieu où réside l’ingénierie ingénieuse, puisqu’il ne s’agit en fin de compte que d’un dossier et d’un schéma. La partie difficile consiste à garantir que les connaissances enregistrées restent exactes alors que le code qui les sous-tend évolue. La conception a abouti à quatre garanties, chacune nécessitant peu de code mais beaucoup de maîtrise de soi.
Qui écrit les notes
L’auteur est un modèle de langage, et presque chaque choix de conception en découle. Ses entrées ne sont pas fiables, non pas parce que quelqu’un agit de mauvaise foi, mais parce qu’elles proviennent d’une conversation qui a pu inclure une clé API, une chaîne de connexion ou l’adresse e-mail de quelqu’un. Le format de ses sorties ne peut pas être considéré comme acquis, et chaque itération de correction consomme une requête réelle.
Le dernier point se manifeste de manière inattendue : le validateur signale tous les problèmes en même temps au lieu de s’arrêter au premier.
export function validateNode(input) {
const e = [];
// ...every check pushes onto e instead of throwing...
if (e.length) throw new ValidationError(e);
return n;
}
Essayer rapidement est un réflexe, mais ici c’est une erreur. Un modèle capable de corriger sa propre sortie peut tout réparer en une seule itération au lieu de détecter les défauts un par un, ce qui entraîne une demande supplémentaire à chaque fois. C’est un petit changement, mais il fait la différence entre une seule tentative et cinq.
Les notes existent en quatre types, ce qui est important ici : system, decision, convention et constraint.
Règle 1 : rendre visible la date de péremption lors de l’utilisation de la note
On ne peut pas éviter le problème lié à JWT par rapport aux sessions. Une note peut être exacte le lundi et fausse en mars, quel que soit le design. Ce qui est possible, c’est d’afficher l’âge d’une note au moment précis où quelqu’un s’apprête à s’y fier, car c’est le seul instant où l’on peut agir.
Chaque note enregistre le HEAD du répertoire au moment où elle a été capturée :
id: auth-service
type: system
title: Auth uses server sessions
scope: repo
confidence: observed
captured_sha: a1b2c3d # repo HEAD at capture
repos: [orders-api]
edges:
- rel: depends-on
dst: postgres-primary
Lors de la récupération, cela se traduit par un comptage des commits :
captured 47 commits ago — verify before trusting
Il n’y a aucun modèle impliqué, aucune tâche planifiée ni aucun analyseur en arrière-plan pour évaluer la fraîcheur. Une seule commande git rev-list --count ..HEAD suffit, et elle est déterministe ainsi que suffisamment peu coûteuse pour être exécutée directement.
Trois petits détails se sont avérés plus importants que l’idée principale.
Une histoire réécrite donne une réponse différente. Lorsque le commit n’est plus accessible en raison d’un rebase ou d’un prune, afficher zéro commit constituerait une fausse information rassurante. L’outil indique plutôt « histoire réécrite, vérifier ». « Inconnu » et « frais » sont des réponses différentes, et elles doivent rester distinctes.
Les notes ne sont annotées que dans le répertoire qu’elles concernent. Le nombre de commits mesuré par rapport à une histoire non liée n’est qu’un bruit se faisant passer pour un signal. Une note limitée à orders-api et consultée pendant que vous travaillez sur billing-api est laissée tranquille, sans être marquée comme réécrite.
if (Array.isArray(node.repos) && node.repos.length &&
!node.repos.includes(here)) return null;
Il existe un seuil. En dessous de dix commits, la notion de péremption n’est pas du tout mentionnée, car un avertissement affiché en permanence relève de la décoration et non d’un véritable avertissement. Ce seuil est configurable. Un second seuil, plus élevé, à 100 commits déclenche la commande doctor qui liste les notes nécessitant une révision approfondie, vous permettant ainsi de chercher activement plutôt que de recevoir des indications une par une.
Règle 2 : les échecs de censure sont clos
Le texte du magasin est affiché en clair sur un poste de travail d’entreprise, et le modèle a écrit son contenu à partir de conversations pouvant contenir n’importe quoi. Ainsi, aucune donnée n’est écrite sur le disque sans avoir été scannée au préalable. Quatorze familles de modèles détectent des éléments tels que des clés AWS, des tokens GitHub et Slack, des clés privées, des JWT, des tokens porteurs, des chaînes de connexion aux bases de données, des cookies de session, des adresses IP de plage privée et des noms d’hôtes internes, ainsi que des adresses e-mail ; chaque élément détecté est remplacé par <redacted:kind> avant d’être enregistré.
« Fail-closed » effectue des tâches spécifiques, visibles dans les premières lignes de la fonction :
export function redact(text, opts = {}) {
if (typeof text !== 'string') {
throw new TypeError('redact() requires a string; refusing to write unscanned content');
}
Donnez-lui quelque chose qu’il ne peut pas scanner, et il ne sautera pas la vérification pour continuer. Il interrompra l’écriture. Une opération de censure doit échouer de manière à ce que « rien ne soit écrit », et jamais de telle sorte que « celui-ci ait échappé ». Il n’y a pas non plus de drapeau de débordement, car un tel drapeau est quelque chose que l’on utilisera finalement un vendredi soir à six heures.
Deux choix à l’intérieur méritent d’être défendus.
Les chaînes de connexion restent intactes. Un URI tel que postgres://user:hunter2@db.internal:5432/orders contient ses identifiants directement, de sorte que l’ensemble du URI est remplacé, et non seulement le mot de passe. Un URI partiellement censuré transmet toujours au lecteur l’hôte, le port, le nom de la base de données et le nom d’utilisateur.
Les secrets dans le formulaire de tâche doivent se prouver utiles. Une règle naïve pour password: <quelque chose> engloberait également une phrase comme « la politique de rotation des mots de passe est de 90 jours », c’est pourquoi la règle exige des guillemets ou une longue séquence sans guillemets :
{
kind: 'assigned-secret',
re: /\b(?:api[_-]?key|secret|password|token|client[_-]?secret|
access[_-]?key)\b\s*[:=]\s*(?:"[^"\n]{6,}"|'[^'\n]{6,}'|[^\s"'`,;)]{12,})/gi,
}
Une rédaction qui déforme le prose ordinaire devient inutile, et alors elle ne protège plus rien. Tout le module présente une seule exception : votre identité git reste intacte, car elle est déjà présente dans chaque commit que vous avez envoyé, et la cacher ne ferait qu’ rendre les notes plus difficiles à lire.
Règle 3 : la troncature n’est jamais silencieuse
Une requête de niveau 2 sur un nœud bien connecté peut retourner cinquante notes, dépassant ainsi la fenêtre de contexte que le système est conçu pour protéger. C’est pourquoi un budget en octets est fixé à 8 KB par défaut, avec un élagage automatique dès dépassement. Rien de tout cela n’est surprenant. Ce qui est important, c’est ce qui se passe après l’élagage :
3 nodes omitted for budget: legacy-batch-job, vendor-sftp-quirk,
old-retry-policy
Every omitted id gets printed, with no exceptions. This rule carries the most conviction, because silent truncation is the failure that looks like success. Given eight of eleven notes and no sign that three are missing, an agent assumes it sees everything and replies as confidently as that implies. The missing three are probably the ones it needed: they were dropped as peripheral to the query, and a surprising constraint often sits at the edge.
Pruning goes deepest-first, then least-connected:
.sort((a, b) => b.depth - a.depth || a.degree - b.degree || ...)
Depth means distance from what was actually asked, and a low degree suggests a node nobody needed as a hub. Breaking final ties by id gives identical bytes for the same query every time, so the reindex determinism test checks something real.
Rule 4: constraints are never dropped
Not at any cap, in either tier, with no exceptions.
const removable = nodes.filter((n) => n.depth > 0 && n.type !== 'constraint');
Deux éléments échappent au tri : la note de base que vous avez demandée et chaque contrainte. La logique repose sur les coûts, non sur les préférences. Une contrainte peut indiquer que le client ne donnera pas son accord pour une nouvelle base de données, qu’un service ne peut pas accéder à Internet, ou que l’équipe de la plateforme a déjà rejeté Kafka. C’est précisément cette contrainte qui empêche un agent d’envoyer une douzaine de demandes vers une approche vouée à l’échec dès le départ. Réduire une demande pour économiser quatre cents octets revient à remplacer un coût faible par un coût élevé : les octets sont peu chers, mais un projet sans issue l’est beaucoup moins.
Cela crée un cas dont le code doit tenir compte dès le départ. Si la note de base ainsi que les contraintes dépassent déjà le budget alloué, ce dernier doit être ajusté :
Note: 9,412 bytes returned, over the 8,192 budget, because constraints
are never dropped.
Cela a été signalé mais n’a pas été corrigé, car la correction impliquerait de supprimer ce qui mérite d’être conservé.
Le magasin est en markdown, et l’index est jetable
Un choix structurel permet de respecter les quatre règles : les notes sont des fichiers markdown ordinaires avec du frontmatter YAML, et index.db est un cache qui peut être supprimé à tout moment.
~/.agents/memory/
notes/<type>/<id>.md the source of truth
notes/archive/ superseded and decayed notes; never deleted
index.db disposable SQLite cache
ROUTING.md generated map of everything known
Une seule commande index régénère la base de données à partir des notes, octet par octet. La base de données existe parce que parcourir un graphe en SQL est rapide, tandis que parcourir un répertoire de fichiers est lent. Le moteur utilise une CTE récursive avec une limite de profondeur et UNION à la place de UNION ALL, de sorte qu’une boucle contradicts ne peut pas se récuser tant que SQLite n’a pas fermé. Aucune couche graphique distincte n’existe au-dessus de SQLite ; c’est la CTE qui s’en charge.
Rien d’important n’est conservé uniquement dans l’index. Si SQLite est endommagé, le cache est perdu. En supprimant l’outil, il ne reste qu’un dossier contenant du markdown lisible, utile lorsque rien n’est installé. Les connaissances devraient durer plus longtemps que les indices qui les accompagnent, et un stockage binaire propriétaire échoue déjà dès le premier jour.
C’est aussi ce qui lui permet d’être installé dans un environnement restreint, qui était l’objectif initial. Node inclut désormais node:sqlite dans son noyau depuis la version 22.5, de sorte que l’index n’a besoin d’aucun paquet, d’aucun service et d’aucune connexion réseau. Sur un poste de travail géré, proposer un script Node et proposer une nouvelle base de données entraîne des discussions et des résultats très différents.
Ce qui a été délibérément omis
Rien n’est enregistré automatiquement : c’est vous qui le déclenchez, ou c’est la fonction de transfert qui s’en charge. C’est une limite délibérée. Un processus en arrière-plan qui surveille votre session et choisit ce qui doit être conservé est la fonctionnalité que tout le monde demande, mais c’est aussi celle qui risque le plus de submerger le système de données bruitées et peu fiables. Toutes les règles d’honnêteté mentionnées ci-dessus s’affaiblissent à mesure que des notes de faible qualité s’accumulent. Dix bonnes notes en une semaine valent plus que quatre cents, ce qui est le résultat obtenu lorsque le modèle agit de sa propre initiative.
Le partage d’équipe, la synchronisation multi-ordinateur et un serveur MCP sont également reportés. Un serveur MCP lirait le même stockage, il s’agit donc d’une addition et non d’une réécriture.
Une affirmation reste encore non prouvée. Le test pertinent est une lecture en conditions réelles : un nouveau chat, dans un répertoire non modifié depuis un mois, qui répond correctement uniquement à partir du résumé de routage. Cela nécessite un temps réel et ne peut pas être simulé dans un ensemble de tests. Soixante et onze tests réussissent sur Linux, macOS et Windows avec Node 22 et 24, mais aucun d’eux ne montre ce que l’on souhaite vraiment savoir.
La partie à retenir
Toute personne qui intègre de la mémoire dans un flux de travail d’agent, qu’il s’agisse du sien ou d’un produit qu’elle distribue, peut appliquer ces quatre règles au-delà de ce projet :
- Indiquez l’ancienneté devant celui qui lit les informations, là où celles-ci sont utilisées, et non sur un tableau de bord que personne n’ouvre.
- Permettez au nettoyeur d’échouer en ne rien écrivant, et n’ajoutez pas de drapeau de débordement.
- Imprimez ce que vous avez omis, car une suppression silencieuse donne l’impression d’une couverture complète.
- Résolvez d’abord les problèmes qui ne peuvent jamais être ignorés avant que le budget ne devienne serré, car les décisions prises sous pression sont pires.
Aucune de ces mesures n’est difficile à mettre en œuvre. Toutes quatre peuvent être facilement négligées et restent invisibles tant qu’elles fonctionnent, ce qui explique précisément pourquoi il vaut la peine de les noter.