Het duurste aan werken met een agent is het steeds opnieuw uitleggen van context. Elke ochtend leg je de beslissingen van gisteren opnieuw uit, plak je het laatste commit-bericht, en stel je opnieuw vast welke bug de implementatie blokkeert. Vermenigvuldig dit met elke sessie en de verborgen kosten zijn uren per week, geen minuten.
STATE.md elimineert die belasting. Eén bestand, bijgewerkt aan het einde van elke sessie, geladen aan het begin van de volgende. De discipline: voordat je een sessie afsluit, besteed je drie minuten aan het bijwerken van het bestand. Morgen besparen die drie minuten er twintig.
STATE.md bevat drie dingen, niets meer.
Beslissingen: wat je hebt afgesproken en waarom. Zonder het waarom heropent je toekomstige zelf de beslissing. "Postgres triggers in plaats van cron voor de dagelijkse samenvatting: triggers zijn transactioneel, cron racet met het schrijfp pad."
In uitvoering: wat half klaar is, specifiek genoeg om over te dragen. "Migratie 014 geschreven in /migrations/014_add_subscription_columns.sql maar niet toegepast. Moet worden uitgevoerd voordat de webhook handler live gaat."
Blokkades: wat de voortgang stopt, inclusief wat je hebt geprobeerd. "Stripe webhook handtekening faalt in testomgeving. Ruwe body parser geprobeerd, nog steeds 400. Volgende: controleer env var in Vercel preview."
Beperk het tot 60-80 regels. Wanneer iets is opgelost, verwijder het dan. Wanneer iets is verzonden, archiveer het dan.
De update discipline. Voeg een Stop hook toe om jezelf eraan te herinneren:
{
"hooks": {
"Stop": [
{
"command": "echo 'Voordat je afsluit: update STATE.md met beslissingen, in-uitvoering en blokkades van deze sessie.'"
}
]
}
}De herinnering alleen is niet genoeg; de gewoonte moet automatisch zijn. De snelste weg: doe het vijf opeenvolgende sessies. Tegen sessie zes voelt het verkeerd om af te sluiten zonder bij te werken. Het ongemak is het signaal dat de gewoonte is gevormd.
MEMORY.md is de index voor alles wat duurzaam is. Elke vermelding is één regel die naar een afzonderlijk bestand verwijst. Vier typen:
user_*: duurzame feiten over jou: tijdzone, carrièrecontext, voorkeuren. user_location.md
feedback_*: regels geleerd van fouten, met een betrouwbaarheidsveld. Begin bij 0.3, verhoog naar 0.5 wanneer het patroon terugkeert, promoot naar CLAUDE.md bij 0.9+. feedback_public_endpoints_need_rate_limits.md
project_*: gedateerde status en beslissingen voor één project. Archiveer wanneer het is verzonden. project_stripe_integration_2026_05.md
reference_*: opzoektabellen voor mensen, tools, API's. reference_neon_db_config.md
Houd elke indexregel onder de 200 tekens en de index onder de 200 regels. Daarna worden vermeldingen afgekapt en kan Claude ze niet zien.
STATE.md is voor nu. MEMORY.md is voor altijd. De vuistregel: als je het in een standup zou zeggen, gaat het in STATE.md. Als je het in een wiki of onboarding-document zou schrijven, gaat het in een geheugenbestand. Standups zijn vluchtig; wiki's zijn duurzaam.
Wanneer een project wordt verzonden en STATE.md nog steeds vijf regels erover bevat, verplaats die regels dan naar een gedateerd project_* geheugenbestand en wis ze. Het project is niet gestopt met belangrijk zijn; het is gestopt met actueel zijn. Dat onderscheid houdt STATE.md nuttig.
Schrijf status, geen dagboek. Een dagboekvermelding: "Geworven aan de Stripe-integratie. Het was lastig." Een statusvermelding: "Webhook-eindpunt op app/api/webhooks/stripe/route.ts. Handtekeningverificatie werkt lokaal, faalt in Vercel preview (verkeerd ruw body-formaat). Volgende: controleer rawBody middleware-configuratie." De ene geeft de volgende sessie een startpunt; de andere geeft het een memoire.
Nog twee anti-patronen: in-uitvoering vermeldingen zonder een concrete volgende actie die een nieuwe sessie zou kunnen uitvoeren, en dubbele vermeldingen voor hetzelfde onderwerp over sessies heen. Voeg duplicaten samen: één onderwerp, één vermelding, alleen de huidige status.
Een goede sessie-update is negen tot twaalf regels: één beslissing met onderbouwing, één in-uitvoering item met volgende stap, één blokkade met wat je hebt geprobeerd.
Schalen voorbij 50 geheugenbestanden: de digest-laag. Elke MEMORY.md pointerregel kost ongeveer 100-150 tokens. Bij 200 regels is dat 20-30K tokens aan pure pointers. De oplossing: STRATEGY-DIGEST.md, een samenvatting van 2-3 zinnen van elk belangrijk document plus een "Gebruik wanneer:" veld:
## q2-positioning.md
Q2 positionering richt zich op AI-enablement in mid-market sales organisaties.
Gebruik wanneer: het bespreken van de doelklant, prijzen of leadkwalificatie.Claude leest de digest (ongeveer 3K tokens) en laadt een volledig document alleen wanneer relevant. Bij 25 strategiedocumenten is dat 3K tokens in plaats van 50K. Het "Gebruik wanneer:" veld is het routeringsmechanisme: schrijf het als een specifieke triggerconditie, niet als een beschrijving van het bestand.
STATE.md legt de huidige status vast (beslissingen, in uitvoering, blokkades) onder 80 regels; werk het bij aan het einde van de sessie en archiveer de geschiedenis snel. MEMORY.md indexeert duurzame kennis in vier typen (gebruiker, feedback, project, referentie), beperkt tot 200 regels. Begin vanavond met drie regels: één beslissing, één in uitvoering item, één blokkade. Drie regels zijn beter dan nul terwijl de gewoonte zich vormt.