Agent operational memory

Agent operational memory betekent dat je de regels en lessen voor een AI-agent opschrijft in gewone tekstbestanden die hij aan het begin van elke sessie leest. Zonder zulke bestanden begint de agent elk gesprek blanco, zoals een uitzendkracht die elke ochtend dezelfde uitleg nodig heeft. Met een bestand vol huisregels, zoals "vraag altijd eerst voordat je iets verwijdert", blijft hij werken zoals je hebt afgesproken.

Waarom is het nodig?

Een taalmodel onthoudt eerdere gesprekken niet. Volgens de documentatie van Claude Code begint elke sessie met een leeg contextvenster, de tekst die het model in één keer kan zien. Wat de agent in een eerdere sessie leerde, is weg tenzij iemand het heeft opgeschreven. In mei 2026 beschreef een gebruiker op het Reddit-forum r/AI_Agents wat dat betekent: na uren uitleggen welke tools een agent mag gebruiken en wanneer hij eerst moet vragen, begon bij een nieuwe codeertool of MCP-server de uitleg opnieuw.

De naam is beschrijvend. De tools zelf spreken van instructiebestanden, zoals AGENTS.md en CLAUDE.md, en van memory (geheugen).

Hoe werkt het?

De bestanden zijn platte tekst, meestal Markdown, en ze veranderen het gedrag van de agent zonder dat het model opnieuw wordt getraind, zoals bij fine-tuning. Claude Code laadt bijvoorbeeld twee soorten aan het begin van elke sessie:

• Instructies die je zelf schrijft: buildcommando's, afspraken, regels als "doe altijd X". Claude Code leest CLAUDE.md. AGENTS.md is een open formaat voor hetzelfde doel, dat onder meer Codex van OpenAI, Jules van Google en Cursor lezen.
• Notities die de agent zelf schrijft. Met auto memory bewaart Claude Code correcties en voorkeuren, en in september 2026 laadt het de eerste 200 regels of 25 kB van de index MEMORY.md in elke nieuwe sessie.

Instructiebestanden zijn gelaagd. Claude Code kent een bestand voor de hele organisatie, een persoonlijk bestand voor al je projecten en een projectbestand dat het team via versiebeheer deelt, zodat elke wijziging in de regels zichtbaar is. Ze overschrijven elkaar niet: Claude Code laadt ze allemaal, met het bestand dat het dichtst bij de werkmap staat als laatste. Bij AGENTS.md wint het dichtstbijzijnde bestand.

Anthropic noemt de variant waarbij de agent zelf schrijft structured note-taking (Effective context engineering for AI agents, september 2025): notities buiten het contextvenster, zoals een bestand NOTES.md, die de agent later terugleest.

Waarom zet je niet alles in het gesprek?

Anthropic beschrijft context rot: hoe meer tokens een contextvenster bevat, hoe slechter een model informatie daaruit terugvindt. De documentatie van Claude Code raadt aan elke CLAUDE.md onder de 200 regels te houden, omdat langere bestanden meer context innemen en minder consequent worden gevolgd.

Waar gaat het mis?

• Het bestand is context, en niets dwingt het af. Volgens de documentatie van Claude Code is strikte naleving niet gegarandeerd. Voor iets wat nooit mag gebeuren, verwijst ze naar hooks: scripts die op vaste momenten draaien, wat het model ook besluit.
• Geven twee bestanden verschillende regels voor hetzelfde, dan kiest Claude er mogelijk willekeurig één.
• Elke tool heeft eigen bestandsnamen. AGENTS.md wil één bestand voor veel agents zijn, maar in september 2026 leest Claude Code het standaard alleen als een project geen CLAUDE.md heeft.
• Notities die de agent schrijft, kunnen verouderen. Claude Code bewaart ze als gewone Markdown die je kunt lezen, aanpassen of verwijderen.

Voorbeeld

Stel: een developer gebruikt een coding agent in meerdere projecten. Een persoonlijk bestand zegt "gebruik conventional commits", en het projectbestand zegt "deze codebase valideert invoer met Zod". Maakt de agent twee keer dezelfde fout, dan voegt de developer één regel toe aan het projectbestand, en de volgende sessie begint met die regel. De Reddit-gebruiker uit de discussie hierboven ging in een vervolgbericht verder: een gestructureerd bestand dat commando's als rm -rf en git push --force als riskant markeert, zodat de agent er extra voorzichtig mee is.