J'ai passé 5 jours à déboguer la mémoire de mon agent OpenClaw. Voici tout ce que j'ai appris.

Mon agent s'appelle Chiti. Il tourne sur Telegram, gère le support client de deux produits SaaS, rédige des tweets, administre les factures et coordonne avec mon cofondateur à travers les fuseaux horaires. C'est ce que j'ai de plus proche d'un employé junior.

Et pendant des semaines, il n'arrêtait pas d'oublier des choses.

Pas de façon subtile. Je passais une heure à configurer un cron daily, je changeais de modèle, et à la session suivante, Chiti agissait comme si on ne s'était jamais parlés. Je référençais une décision prise deux jours plus tôt et il me regardait sans comprendre. Je lui demandais de continuer une tâche et il repartait de zéro.

J'ai donc arrêté de développer des fonctionnalités et j'ai passé 5 jours, dès que j'avais du temps, juste à réparer la mémoire. Voici tout ce que j'ai trouvé, tout ce que j'ai cassé, et tout ce qui a effectivement marché.

Jour 1 : L'agent oublie tout après les longues conversations

Le premier problème était simple à décrire et douloureux à diagnostiquer.

Après de longues conversations, Chiti commençait à perdre le contexte antérieur. Pas progressivement, ça disparaissait d'un coup. Des choses que je lui avais dites 20 messages plus tôt n'étaient plus là. Des décisions prises en début de session ? Jamais arrivées.

Le coupable était la compaction. Quand la conversation remplit la fenêtre de contexte, OpenClaw compresse les messages plus anciens en un résumé pour faire de la place aux nouveaux. Le résumé capture l'essentiel mais perd les détails. Noms, chiffres, décisions précises – disparus.

C'est voulu. La fenêtre de contexte est limitée. Mais le comportement par défaut traite tout de manière égale, ce qui signifie que votre instruction soigneusement rédigée du message n°3 reçoit le même traitement qu'une discussion banale du message n°7.

Ce que j'ai fait :

J'ai activé le vidage mémoire avant la compaction. Cela demande à l'agent d'écrire le contexte important sur le disque avant que le compresseur ne s'exécute.

1{
2  "compaction": {
3    "memoryFlush": {
4      "enabled": true,
5      "softThresholdTokens": 4000
6    }
7  }
8}

Lorsque la session approche de la limite de contexte, OpenClaw déclenche un tour silencieux qui rappelle à l'agent de sauvegarder les faits durables dans memory/YYYY-MM-DD.md avant que la compaction ne les efface. L'agent écrit ce qui compte, la compaction s'exécute, et les éléments importants survivent sur le disque même si le résumé de contexte les perd.

Ce que j'ai appris :

La compaction n'est pas l'ennemi. Perdre des informations pendant la compaction, oui. La solution est de s'assurer que tout ce qui mérite d'être retenu soit écrit dans un fichier avant que le compresseur n'y touche. Si c'est uniquement dans la fenêtre de contexte, c'est temporaire. Si c'est sur le disque, ça survit.

Jour 2 : La recherche renvoie des résultats inutiles

Avec les journaux quotidiens qui s'accumulaient et MEMORY.md qui grossissait, j'avais besoin que l'agent trouve vraiment les choses. La recherche mémoire intégrée renvoyait des résultats non pertinents ou manquait des correspondances évidentes.

Le problème venait du moteur de recherche. La recherche par défaut d'OpenClaw basée sur SQLite utilise des embeddings vectoriels (similarité sémantique) pour trouver les fragments pertinents. Cela fonctionne pour des requêtes larges mais peine avec les correspondances exactes. Je cherchais un nom de client spécifique et j'obtenais des résultats sur un sujet complètement différent qui utilisait un langage similaire.

Ce que j'ai fait :

J'ai basculé vers QMD comme moteur de recherche mémoire. QMD combine BM25 (correspondance par mots-clés) avec des embeddings vectoriels et un re-ranker. Ainsi, quand je cherche « échec de paiement Charles », il trouve les résultats qui contiennent ces mots exacts ET les résultats sémantiquement liés, puis les re-classe par pertinence.

J'ai aussi configuré les chemins QMD pour inclure mon dossier d'apprentissages :

1{
2  "memory": {
3    "qmd": {
4      "paths": [
5        {
6          "path": "/Users/ramya/clawd",
7          "name": "memory-root",
8          "pattern": "MEMORY.md"
9        },
10        {
11          "path": "/Users/ramya/clawd",
12          "name": "memory-alt",
13          "pattern": "memory_alt.md"
14        },
15        {
16          "path": "/Users/ramya/clawd/memory",
17          "name": "memory-dir",
18          "pattern": "**/*.md"
19        },
20        {
21          "path": "/Users/ramya/clawd/learnings",
22          "name": "learnings",
23          "pattern": "**/*.md"
24        }
25      ]
26    }
27  }
28}

Ce que j'ai appris :

La recherche purement sémantique semble bonne en théorie, mais échoue sur les noms propres, les chiffres spécifiques et les phrases exactes. La recherche hybride (mots-clés + vecteurs + re-ranking) est nettement meilleure pour une mémoire d'agent réelle. Si votre agent ne trouve pas quelque chose que vous savez présent dans ses fichiers, c'est probablement le moteur de recherche le goulot d'étranglement, pas les fichiers eux-mêmes.

Jour 3 : L'agent trouve mais ne l'utilise pas

Ce fut le jour le plus frustrant. J'avais confirmé que la recherche fonctionnait, je pouvais interroger manuellement et obtenir les bons résultats. Mais pendant les conversations réelles, Chiti n'allait pas chercher le contexte pertinent alors qu'il existait clairement en mémoire.

Le problème était que la récupération n'est pas automatique. L'agent doit décider de chercher. Et si la conversation ne déclenche pas les bons signaux, il ne va pas consulter.

Ce que j'ai fait :

J'ai ajouté des instructions explicites de récupération dans la séquence de démarrage. Au lieu d'espérer que l'agent cherche quand nécessaire, je lui ai dit quand chercher :

markdown

Avant de commencer une tâche :

• Chercher dans les journaux quotidiens le contexte connexe
• Vérifier LEARNINGS.md pour les règles concernant ce type de tâche
• Si un client est mentionné, chercher son historique

J'ai aussi construit un test de récupération. Je plantais un marqueur spécifique dans le journal quotidien – quelque chose comme « MARQUEUR : 2026-02-20 — Pense toujours à vérifier le statut git avant de prétendre que le code est poussé. » Puis j'attendais, je démarrais une nouvelle session et je demandais : « Quel était le marqueur d'hier ? » Si l'agent le trouvait, la récupération fonctionnait. Sinon, quelque chose était cassé.

Ce que j'ai appris :

Il y a une différence entre « l'information existe » et « l'agent utilise l'information ». Les deux sont nécessaires. L'infrastructure de recherche gère la première partie. Les instructions de démarrage et les habitudes de récupération gèrent la seconde. Testez les deux séparément.

Jour 4 : Rendre le système résistant à la compaction

À ce stade, j'avais le vidage mémoire, la recherche hybride et les instructions de récupération. Mais je continuais à perdre du contexte dans un scénario spécifique : les sessions très longues où la compaction s'exécutait plusieurs fois.

Le problème était que le vidage mémoire ne se déclenche qu'une fois par cycle de compaction. Si la session était assez longue pour deux ou trois compactions, seule la première bénéficiait du vidage. Tout ce qui suivait était à risque.

Ce que j'ai fait :

J'ai configuré l'élagage de contexte pour travailler avec la compaction :

1{
2  "contextPruning": {
3    "mode": "cache-ttl",
4    "ttl": "6h",
5    "keepLastAssistants": 3
6  }
7}

Cela élague agressivement l'ancien contexte après 6 heures tout en conservant les 3 dernières réponses de l'assistant. Combiné avec le vidage mémoire, cela signifie que l'agent écrit les éléments importants sur le disque tôt, et l'ancien contexte est nettoyé avant de provoquer un débordement.

J'ai aussi ajouté un protocole de test MARQUEUR : après tout changement de configuration significatif, je plante un marqueur dans le journal quotidien et teste la récupération à travers les limites de compaction. Si le marqueur survit, le changement a fonctionné. Sinon, quelque chose a cassé.

Ce que j'ai appris :

Les sessions longues sont là où les systèmes de mémoire sont vraiment testés. Les conversations courtes atteignent rarement la compaction. Ce sont les sessions de travail approfondi de 2 heures où l'on perd le contexte sans comprendre pourquoi. Testez votre système de mémoire sous charge, pas seulement lors de discussions rapides.

Jour 5 : Le prompt système était gonflé de 28 %

Ce fut le jour où tout a pris sens. J'ai lancé /context detail et fixé les chiffres.

Mon agent chargeait 11 887 tokens de prompt système avant même de lire mon message. 51 compétences, dont 20 que je n'avais jamais utilisées. MEMORY.md faisait 200 lignes de wiki d'entreprise chargées à chaque session. Et j'avais deux séquences de démarrage concurrentes – une dans BOOT.md (qu'OpenClaw ne reconnaît même pas) et une enfouie 200 lignes profondément dans AGENTS.md.

Pire encore, chaque fois que je changeais de modèle, Chiti oubliait tout. Aucun protocole de passation. Aucune sauvegarde du contexte en cours. Juste perdu.

La cause racine :

OpenClaw charge automatiquement ces fichiers à chaque nouvelle session : AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md.

Tout le reste – LEARNINGS.md, journaux quotidiens, docs, fichiers de référence – l'agent doit les lire lui-même à l'aide d'outils. Si l'instruction de lire ces fichiers ne se trouve pas dans l'un des fichiers chargés automatiquement (spécifiquement AGENTS.md), l'agent ne les verra jamais.

Mon BOOT.md contenait toute la séquence de démarrage. Mais OpenClaw ne charge pas automatiquement BOOT.md. Les instructions restaient donc là, non lues, sans effet.

Ce que j'ai fait :

J'ai fait un audit complet et un nettoyage :

1. Déplacé la séquence de démarrage en haut d'AGENTS.md (le seul endroit fiable pour les instructions de démarrage)
2. Supprimé BOOT.md (non reconnu par OpenClaw)
3. Supprimé BOOTSTRAP.md (fichier d'onboarding unique, déjà complété, gaspille 361 tokens à chaque session)
4. Réduit MEMORY.md de 200 à 90 lignes en déplaçant les documents de référence dans un dossier docs/
5. Supprimé 20 compétences marketing inutilisées qui consommaient 3 000 tokens par session
6. Ajouté une discipline d'écriture : chaque tâche enregistre son résultat, chaque erreur devient une règle
7. Ajouté un protocole de passation : avant tout changement de modèle ou fin de session, l'agent écrit le contexte actuel dans le journal quotidien

La séquence de démarrage ressemble maintenant à ceci :

markdown

Avant de faire QUOI QUE CE SOIT :

1. Lire USER.md
2. Lire learnings/LEARNINGS.md
3. Lire memory/YYYY-MM-DD.md (aujourd'hui + hier)
4. Lire MEMORY.md (session principale uniquement, jamais dans les groupes)
5. Lire PROTOCOL_COST_EFFICIENCY.md
6. Afficher : CHARGÉ : USER | LEARNINGS | DAILY | MEMORY | PROTOCOL

La discipline d'écriture :

markdown

Après chaque tâche :

1. Enregistrer décision + résultat → memory/YYYY-MM-DD.md
2. Si erreur → ajouter à learnings/LEARNINGS.md
3. Si contexte important → mettre à jour MEMORY.md (uniquement lors des revues heartbeat, jamais directement pendant les tâches)

Le protocole de passation :

markdown

Avant la fin de session ou le changement de modèle :

Écrire la section PASSATION dans memory/YYYY-MM-DD.md :

• Ce qui a été discuté
• Ce qui a été décidé
• Tâches en attente avec détails précis
• Prochaines étapes restantes

Résultats :

• Prompt système : 11 887 → 8 529 tokens
• Compétences : 51 → 32
• Tokens par session : 18 280 → 14 627
• 28 % plus léger. Même agent. Mêmes modèles. Juste moins de bruit.

Ce que j'ai appris :

La vraie solution n'était pas d'ajouter plus de fichiers. C'était de supprimer ceux qui ne servaient à rien. Chaque token dans le prompt système est un surcoût que l'agent porte à chaque message. Compétences inutilisées, fichiers mémoire gonflés, fichiers que le système ne lit même pas – tout s'additionne en silence.

Les règles que j'aurais aimé connaître dès le premier jour

Après 5 jours à casser et réparer des choses, voici les règles que je donnerais à quiconque configure la mémoire d'OpenClaw :

1. Seuls ces fichiers sont chargés automatiquement : AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md.

Tout le reste nécessite une instruction de lecture explicite dans AGENTS.md. Si ce n'est pas dans la séquence de démarrage, l'agent ne le verra pas. BOOT.md n'existe pas vraiment dans OpenClaw. J'en ai eu un pendant des semaines. Il ne faisait rien.

2. La séquence de démarrage va en haut d'AGENTS.md.

Pas au milieu. Pas en bas. Tout en haut. Les fichiers chargés automatiquement sont injectés dans le prompt système, donc les instructions de démarrage doivent être la première chose que l'agent traite.

3. La discipline d'écriture est plus importante que la discipline de lecture.

La plupart des gens configurent des fichiers que l'agent doit lire, mais n'imposent jamais l'écriture en retour. Si l'agent n'enregistre pas les décisions, résultats et erreurs sur le disque, ces choses n'existent que dans la fenêtre de contexte. Et la fenêtre de contexte est compactée. L'écriture en retour est ce qui transforme le contexte temporaire en mémoire permanente.

4. Ne jamais écrire directement dans MEMORY.md pendant les tâches.

Les journaux quotidiens sont bruts et en mode ajout uniquement. MEMORY.md est une mémoire à long terme organisée. Si vous laissez l'agent déverser n'importe quoi dans MEMORY.md, il gonfle en un fouillis de 200 lignes en quelques semaines. Organisez MEMORY.md lors de revues périodiques (heartbeat ou cron) en distillant les enseignements des journaux quotidiens récents. J'ai appris cela d'un autre utilisateur d'OpenClaw qui a surpris son agent en train de faire exactement ça – gonfler MEMORY.md avec du bruit non organisé jusqu'à le rendre inutile.

5. LEARNINGS.md est le fichier le plus sous-estimé.

Chaque erreur que fait l'agent devrait devenir une règle d'une ligne. « Ne prétends jamais que le code est poussé sans vérifier le statut git. » « Ne lis pas tout MEMORY.md dans les discussions de groupe. » « Confirme toujours le fuseau horaire de l'utilisateur avant de planifier. » Ces règles s'accumulent. Après quelques semaines, votre agent a un manuel d'opérations personnel construit à partir de ses propres échecs.

6. Testez la récupération, pas seulement le stockage.

Stocker des informations et les récupérer sont deux problèmes différents. J'ai eu des fichiers indexés et interrogeables mais jamais consultés parce que l'agent ne savait pas qu'il devait les chercher. Plantez des marqueurs, testez entre sessions, testez entre changements de modèle. Si l'agent ne peut pas trouver ce que vous avez stocké hier, le stockage ne sert à rien.

7. Le protocole de passation est la solution pour les changements de modèle.

Les agents OpenClaw perdent tout contexte lorsque vous changez de modèle. Le nouveau modèle démarre avec une fenêtre de contexte vierge – il ne voit que les fichiers chargés automatiquement. Sans un protocole de passation qui enregistre l'état actuel dans le journal quotidien avant le changement, le nouveau modèle n'a aucune idée de ce qui se passait. C'est mon plus gros point de douleur pendant des semaines.

8. Lancez /context detail régulièrement.

Cette commande montre exactement ce qui consomme vos tokens. Compétences que vous avez oublié avoir installées, fichiers qui ont grossi sans que vous le remarquiez, outils que vous n'utilisez jamais. J'ai trouvé 20 compétences inutilisées qui brûlaient 3 000 tokens par session. C'est 3 000 tokens de surcoût sur chaque message, pour des fonctionnalités que je n'avais jamais touchées.

9. La recherche hybride bat la recherche purement sémantique.

BM25 (mots-clés) + vecteurs (sens) + re-ranking donne des résultats nettement meilleurs que les vecteurs seuls. Noms de clients, chiffres spécifiques, phrases exactes – la recherche sémantique les rate. La recherche par mots-clés les attrape. Utilisez les deux.

10. La compaction n'est pas l'ennemi. Le contexte non écrit, oui.

J'ai passé des jours à lutter contre la compaction avant de réaliser que la solution était plus simple : assurez-vous que tout ce qui est important soit écrit dans un fichier avant que la compaction ne s'exécute. Le vidage mémoire gère cela automatiquement. Si c'est sur le disque, ça survit à la compaction. Si c'est seulement dans la conversation, c'est à risque.

Ma configuration actuelle

Pour référence, voici à quoi ressemble mon espace de travail maintenant :

workspace/

├── AGENTS.md (séquence de démarrage + discipline d'écriture + protocole de passation)

├── SOUL.md (personnalité et comportement)

├── IDENTITY.md (nom, rôle)

├── USER.md (infos du propriétaire)

├── TOOLS.md (directives d'utilisation des outils)

├── HEARTBEAT.md (comportement de vérification autonome)

├── MEMORY.md (mémoire à long terme organisée, ~90 lignes)

├── PROTOCOL_COST_EFFICIENCY.md

├── learnings/

│ └── LEARNINGS.md (règles issues des erreurs)

├── memory/ (journaux quotidiens : YYYY-MM-DD.md)

├── docs/ (documents de référence déplacés de MEMORY.md)

│ ├── tweetsmash-arch.md

│ ├── knowledge-transfer.md

│ ├── infrastructure.md

│ └── group-chat-rules.md

└── skills/ (32 compétences, contre 51 auparavant)

Prompt système : 8 529 tokens. Tokens par session : 14 627 sur 200 000 de fenêtre de contexte (7,3 %). L'agent démarre, lit ce dont il a besoin, écrit ce qu'il apprend, et transmet le contexte avant les changements de modèle.

Il m'a fallu 5 jours pour en arriver là. La majeure partie du temps a été consacrée à désapprendre l'hypothèse que plus de fichiers équivaut à une meilleure mémoire. Ce n'est pas le cas. La discipline, oui. Mon expérience continue.

Je construis TweetSmash et LinkedMash — des outils de bookmarking pour les réseaux sociaux avec mon cofondateur. Je partage ce que j'apprends sur l'exécution d'agents OpenClaw en production sur X : @code_rams