Claude Code memory: de complete gids voor context

Elke Claude Code-sessie begint op dezelfde manier: geen herinnering aan gisteren. Je besteedt maandag twintig minuten aan het uitleggen van de auth-flow van je API, en dinsdag leg je het opnieuw uit, omdat niets aan hoe het model werkt dat automatisch meeneemt. Dat gat is de meest gevraagde fix die we horen van teams die Claude Code dagelijks draaien, en het is ook het meest misverstane, want "geef Claude geheugen" is niet één feature. Het zijn vier mechanismen met verschillende taken, kosten en faalmodi.

Deze gids zet ze op een rij: wat elke laag echt oplost, wat in welke thuishoort, hoe je een memory-skill zoals claude-mem opzet, en de tokenrekensom die verklaart waarom onthouden goedkoop is terwijl elke sessie dezelfde feiten opnieuw ontdekken dat niet is.

Het groundhog-day-probleem

Een taalmodel heeft geen state tussen API-calls. Elk bericht dat je stuurt, bevat het hele gesprek tot dan toe, en zodra dat gesprek eindigt, eindigt ook alles wat het model "wist" over je project. Open morgen een nieuwe sessie en je bent terug bij een blanco blad, wat er ook toevallig op schijf staat.

Dat zou prima zijn als sessies kort en op zichzelf staand waren. Dat zijn ze niet. Echt werk beslaat dagen: je fixt maandag een bug, hetzelfde patroon duikt donderdag op in een ander bestand, en de agent heeft geen manier om die twee te verbinden tenzij iets buiten het gesprek die verbinding heeft meegedragen. Elke sessie zonder dat betaalt een herontdekkingsbelasting: dezelfde bestanden lezen, dezelfde conventies opnieuw leren, af en toe een fout herhalen die al gefixt was.

De oplossing is geen groter contextvenster. Contextvensters zijn al groot, en het probleem is geen capaciteit, het is continuïteit. Wat je wilt, is een plek buiten het gesprek waar feiten en beslissingen overleven, plus een manier voor Claude om het juiste stukje van die plek terug te laden wanneer het ertoe doet. Dat is geheugen, en Claude Code geeft je vier manieren om het te bouwen.

De vier lagen van Claude-geheugen

Laag één is CLAUDE.md: statische projectfeiten die je één keer schrijft, die volledig laden bij de start van elke sessie. Laag twee is auto-memory, een map met bestanden waar Claude zelf naar schrijft, feiten opstapelend over tijd zonder dat jij ze met de hand hoeft te schrijven. Laag drie zijn memory-skills, die sessiecontext automatisch vastleggen en comprimeren en later weer terugspuiten. Laag vier is de laagdrempelige optie: een plat notitiebestand dat de agent leest en bijwerkt omdat jij dat zei.

Het zijn geen concurrerende opties. Ze lossen verschillende problemen op, en de meeste serieuze setups draaien er twee of drie tegelijk.

Laag 1: CLAUDE.md, statische feiten die altijd laden

CLAUDE.md is het oudste en simpelste geheugenmechanisme van Claude Code. Het is een markdown-bestand dat Claude Code vindt door omhoog te lopen vanaf je werkdirectory, en het laadt volledig, elke sessie, voordat je iets typt. Dat maakt het de juiste plek voor feiten die bijna altijd waar zijn: hoe je de tests draait, welke package manager de repo gebruikt, welke map legacy en verboden terrein is.

Het is de verkeerde plek voor alles wat vaak verandert of alleen af en toe geldt, want "laadt volledig, elke sessie" is ook de kost ervan. Een CLAUDE.md van 3.000 regels is ongeveer 30.000 tokens belasting bij elk verzoek, of dat verzoek er nu iets van nodig heeft of niet. We behandelen de volledige rekensom en een echt geannoteerd voorbeeld in onze CLAUDE.md best-practices-gids; de korte versie is dat CLAUDE.md stabiele feiten wil, geen groeiend logboek.

Daar loopt CLAUDE.md ook tegen zijn grenzen aan. Het is statisch: jij schrijft het, Claude leest het, en het bijwerken is een handmatige klus die jij moet onthouden. De volgende drie lagen bestaan om feiten af te handelen die vanzelf opstapelen.

Laag 2: auto-memory en memory-mappen

De middelste laag is een memory-map, vaak ~/.claude/memory/ of een projectlokaal equivalent, waar Claude gestructureerde notities schrijft over wat het leert en die terugleest bij de start van toekomstige sessies. In tegenstelling tot CLAUDE.md schrijft niemand de meeste van deze items met de hand. De agent beslist dat iets de moeite van onthouden waard is, een beslissing die je nam, een voorkeur die je uitte, een feit waarvoor het moest graven, en legt het weg met genoeg structuur om later terug te vinden.

Hier leeft de Memory Management-skill, en het is de hoogst scorende skill in deze categorie op SkillProof: 9,2 van de 10. We draaiden hem over een volle week echte sessies, geen enkele demo-run, en hij hield stand onder echt gebruik. Claude herinnerde betrouwbaar projectbeslissingen en voorkeuren die het had opgeslagen, en de recall-precisie bleef hoog naarmate de opslag groeide, het deel dat in naïeve implementaties meestal het eerst breekt.

Wat deze laag scheidt van CLAUDE.md, is dat hij ook selectief is op de terugweg, niet alleen op de heenweg. Een goed gebouwde memory-skill indexeert wat hij heeft opgeslagen en haalt het relevante stukje op voor de huidige taak, zodat de opslag kan groeien naar duizenden items terwijl elke sessie niet voor ze allemaal betaalt.

Laag 3: memory-skills, claude-mem en automatische vastlegging

De derde laag neemt het idee verder. In plaats van dat Claude midden in het gesprek beslist wat het waard is om op te slaan, legt een specifieke skill de hele sessie automatisch vast, comprimeert die, en spuit de relevante context terug in de volgende sessie. Claude-mem is het duidelijkste voorbeeld van dit patroon. Zijn pitch is "aanhoudende context over sessies heen voor elke agent": het houdt in de gaten wat je agent tijdens een sessie doet, comprimeert die activiteit met een AI-samenvattingsstap, en toont de gecomprimeerde versie de volgende keer dat het relevant is, over Claude Code heen en, volgens de eigen documentatie, verschillende andere agent-runtimes.

We moeten eerlijk zijn over waar het staat in onze tests. Claude-mem verscheen via onze GitHub-crawler met 85.685 sterren, waarom het in de wachtrij staat voor een volledige test in plaats van al een oordeel te dragen; we publiceren geen score voordat we een skill schoon hebben geïnstalleerd en tegen echt werk hebben gedraaid, dezelfde lat die Memory Management al haalde. Wat we nu wel kunnen zeggen is architectonisch: automatische vastlegging verwijdert het moment waarop jij anders zou stoppen en midden in de sessie beslissen of iets de moeite van onthouden waard is. De skill beslist het voor je. Of dat standhoudt over een volle week op een schone machine is waar de testwachtrij voor bestaat om te beantwoorden.

Laag 4: platte bestanden als geheugen

De laatste laag heeft geen skill nodig: een plat markdown-bestand, meestal zoiets als notes.md of progress.md, dat je Claude vraagt te lezen bij de start van een sessie en bij te werken aan het eind. Geen indexering, geen automatische vastlegging, geen scoring. Jij bent het geheugensysteem; het bestand is gewoon waar je het opschrijft.

Deze laag wordt onderschat omdat hij te simpel klinkt om ertoe te doen. Dat is hij niet. Voor een soloproject met één bijdrager en een handvol lopende draadjes verslaat een notitiebestand dat je echt onderhoudt een geautomatiseerd geheugensysteem waar je nooit naar kijkt. Het faalpatroon ligt wel volledig bij jou: niemand snoeit het, niemand markeert tegenstrijdigheden, en het groeit uit tot een muur tekst met dezelfde blinde vlekken die elk onbeheerd document ontwikkelt. Het werkt precies zo goed als jouw discipline om het bij te werken, niet beter.

Wat hoort waar: de beslistabel

Geheugentype	Beste voor	Laadt	Onderhoud
CLAUDE.md	Stabiele, altijd-ware feiten (buildcommando's, conventies, valkuilen)	Volledig, elke sessie	Handmatig, met de hand bewerken
Auto-memory / memory-map	Beslissingen en voorkeuren die zich over tijd opstapelen	Selectief, bij ophalen	Grotendeels automatisch (skill-beheerd)
Memory-skills (claude-mem)	Volledige sessiecontext, vastgelegd zonder dat jij beslist wat telt	Gecomprimeerd, geïnjecteerd wanneer relevant	Automatische vastlegging, af en toe review
Plat notitiebestand	Soloprojecten, simpele lopende draadjes	Handmatig, jij vertelt Claude het te lezen	Volledig handmatig

Lees die tabel op basis van wat verandert, niet op basis van wat handig is om op te zetten. Zou een feit over zes maanden nog steeds waar zijn, dan hoort het in CLAUDE.md. Is het een beslissing van deze week die later weer kan gaan tellen, dan hoort het in memory. Kun je niet voorspellen wat je moet onthouden en wil je niet ter plekke beslissen, dan is dat het geval voor automatische vastlegging. Geldt niets daarvan, dan verslaat een notitiebestand nog steeds niets.

Claude-mem stap voor stap opzetten

Het algemene patroon voor een automatische-vastlegging-memory-skill ziet er zo uit, met claude-mem als het concrete voorbeeld:

1. Kloon de skill. git clone https://github.com/thedotmack/claude-mem in een werkdirectory, en volg dan het installatiescript van de repo in plaats van bestanden met de hand te kopiëren. Memory-skills moeten meestal een hook registreren, niet alleen een SKILL.md neerzetten.

2. Herstart Claude Code. De installatie bedraadt doorgaans een sessiestart- of sessie-einde-hook zodat vastlegging gebeurt zonder dat jij iets aanroept. Een herstart is wat die hook oppikt.

3. Draai een normale sessie. Test hem niet met een speeltaak. Doe echt werk; het punt is zien wat hij de moeite van onthouden vindt wanneer niemand op de test let.

4. Start je volgende sessie en check wat er terugkwam. Vraag Claude wat het zich herinnert over het werk van gisteren voordat je iets anders zegt. Iets specifieks en correct betekent dat vastlegging werkt. Iets vaags of fouts betekent de config checken voordat je hem iets belangrijks toevertrouwt.

5. Zet een reviewritme. Automatische vastlegging zonder review verandert in automatische opstapeling van ruis. Geef jezelf een terugkerend slot van tien minuten om te scannen wat is opgeslagen (meer hierover onder memory-hygiëne, hieronder).

Wil je liever starten met iets dat al gescoord is, dan is Memory Management de handmatige-maar-geteste route: installeer de skillmap in ~/.claude/skills/, en die maakt bij het eerste gebruik zijn eigen memory-map aan, geen aparte hookinstallatie nodig.

De tokeneconomie van geheugen

Hier is de rekensom die de setupkosten de moeite waard maakt. Zeg dat een projectfeit 500 woorden kost om vanaf nul uit te leggen: de vorm van je auth-flow, waarom een bepaalde tabel twee foreign keys heeft, wat het deployscript echt doet. Vers uitgelegd in chat is dat ongeveer 650 tokens input, elke keer dat je het opnieuw uitlegt, bovenop de tijd die je kwijt bent aan het typen en de tijd die Claude kwijt is aan het redeneren erover in dat bericht.

Opgeslagen in memory kost hetzelfde feit die 650 tokens één keer, om te schrijven. Ophalen daarna kost een fractie daarvan: een goed geïndexeerde memory-laag haalt een gecomprimeerde samenvatting op, vaak onder de 100 tokens, alleen wanneer de huidige taak dat feit raakt. Leg het vijf keer in een maand uit in chat en je hebt ongeveer 3.250 tokens besteed aan het herleren van wat memory 650 tokens had gekost om te leren en 500 in totaal om vijf keer op te halen: een ruwe verhouding van vijf op één die breder wordt naarmate het feit vaker nodig is.

Vergelijk dat met alles in CLAUDE.md proppen: een feit dat één sessie op twintig relevant is, laadt nog steeds mee op de andere negentien, zonder selectiviteit om die kost terug te winnen. De vaste preambule die je setup elke beurt meedraagt (CLAUDE.md, toolschema's, memory-injecties) concurreert direct met je echte werk om ruimte en aandacht. We hebben dit dieper gemeten, met echte before/after-tokenaantallen, in onze tokenkostengids; memory is één regel in dat grotere plaatje, vaak de goedkoopste fix ten opzichte van wat hij bespaart.

Memory-hygiëne: het reviewritueel

Een geheugensysteem dat alleen opstapelt, is geen feature, het is een langzaam lek. Verouderde items falen niet luidruchtig; er crasht niets wanneer Claude een beslissing terughaalt die je drie weken geleden hebt teruggedraaid. Het handelt gewoon stilletjes naar verouderde informatie, en jij verbrandt debugtijd om uit te zoeken waarom de agent vol vertrouwen ongelijk heeft over iets waarvan jij weet dat je het al gefixt hebt.

Draai een maandelijkse pass, tien minuten, dezelfde discipline als het CLAUDE.md-reviewritueel dat we elders aanraden. Open de memory-opslag. Vraag je voor elk item dat load-bearing lijkt af of het nog waar is, of een beslissing die het beschrijft sindsdien is teruggedraaid, en of het specifiek genoeg is om op te handelen. Verwijder alles wat faalt. Een memory-opslag waar je trots op bent, is een jaar erin kleiner dan hij drie maanden erin was; de groei zou in precisie moeten zitten, niet in volume.

De betrouwbaarste trigger voor een review is echter niet de kalender. Het is het moment dat Claude iets fout doet door een verouderde memory. Behandel dat als een bug: fix het item in dezelfde adem als de fout, niet bij je volgende geplande pass.

Privacy: wat wordt vastgelegd, waar het leeft

Memory-skills lezen wat er in je sessies gebeurt, dus de eerlijke vraag is wat wordt vastgelegd en waar het terechtkomt. Voor bestandgebaseerd geheugen, Memory Management, claude-mem en de plat-notities-aanpak allemaal, is het antwoord meestal hetzelfde: alles wordt weggeschreven naar platte bestanden op je eigen schijf, meestal onder ~/.claude/ of een projectlokale memory-map, niet naar een server van derden. Er verlaat niets je machine tenzij je die bestanden commit naar een gedeelde repo of een skill expliciet een remote-sync-feature documenteert.

Dat is goed nieuws voor controle en slecht nieuws voor de aanname dat het automatisch veilig is. Een memory-bestand is een platte-tekstverslag van waar je aan werkte, en het kan credentials bevatten die terloops genoemd zijn, klantnamen, of architectuurdetails die je niet in een publieke repo zou willen. Lees wat er echt in een memory-map staat voordat je die samen met je code commit, en check voordat je een memory-skill installeert de bron ervan op wat "legt alles vast wat je agent doet" echt betekent, inclusief of commando-output met secrets ook wordt meegeveegd. Automatische vastlegging verdient dezelfde scepsis als elke tool die je terminal leest.

FAQ

Heeft Claude Code ingebouwd aanhoudend geheugen?

Deels. CLAUDE.md geeft je statisch, altijd geladen geheugen out of the box, en dat is echt ingebouwd, geen installatie nodig. Alles voorbij statische feiten, geheugen dat opstapelt, geïndexeerd wordt, en selectief opgehaald wordt, komt momenteel van een skill in plaats van een native feature.

Wat is het verschil tussen CLAUDE.md en een memory-skill?

CLAUDE.md laadt volledig, elke sessie, en jij onderhoudt het met de hand. Een memory-skill schrijft en leest een groeiende opslag selectief, haalt alleen op wat relevant is voor de huidige taak, en het meeste schrijven gebeurt zonder dat jij het handmatig doet. Gebruik CLAUDE.md voor feiten die nooit veranderen; gebruik een memory-skill voor feiten die opstapelen.

Is claude-mem nu veilig om te installeren?

We kunnen er nog geen oordeel over geven. Het staat in onze testwachtrij, niet gescoord, ondanks zijn grote aanhang op GitHub. Installeer het zoals je iets ongescoords zou installeren: eerst in een project waarin je kunt experimenteren, en lees de bron voordat je het gevoelige sessies toevertrouwt.

Hoeveel kost het draaien van een memory-skill aan tokens?

Minder dan het alternatief in bijna elk geval. Opslag zelf is bijna gratis omdat het op schijf leeft, niet in context. Ophalen bij sessiestart kost doorgaans veel minder dan hetzelfde feit opnieuw uitleggen in chat, en het gat wordt groter naarmate dat feit vaker opnieuw uitgelegd zou moeten worden.

Moet ik meer dan één geheugenlaag tegelijk gebruiken?

Ja, en de meeste werkende setups doen dat: CLAUDE.md voor feiten die nooit veranderen, plus óf een memory-skill óf een gedisciplineerd notitiebestand voor feiten die opstapelen. Behandel ze als complementair in plaats van een favoriet te kiezen. Het punt is elk type feit matchen aan de laag die ervoor gebouwd is, niet je settelen op één mechanisme voor alles.