Een AI-assistent zonder state is een goudvis met een goede uitspraak. Slim binnen één sessie. Volkomen vergeten in de volgende. Iedere ochtend begin je weer met "even uitleggen aan welk project ik werk".
In de eerste maanden Claude Code is dat acceptabel, je leert het systeem kennen, je context-window is overzichtelijk. Maar als je serieus AI-werk gaat doen, wordt het al snel het grootste productiviteitslek.
Vandaag, voor AI peers en hobbyisten die voorbij de eerste experimenten zijn: vier concrete patronen voor state management in Claude Code-projecten. Geen vector-databases nodig. Geen RAG-pipeline. Wel: gestructureerde markdown-bestanden, hooks, en discipline.
Wat bedoel ik met "state"?
Drie soorten geheugen die een werkende AI-agent nodig heeft:
1. Project-state, wat is de huidige status van mijn werk? Welke features zijn af, welke draaien, welke wachten op review?
2. Decision-state, welke beslissingen heb ik eerder genomen, en waarom? Wat zijn de "trade-offs" die het systeem moet respecteren?
3. Personal-state, wie ben ik, hoe werk ik, wat zijn mijn voorkeuren?
Iedere goed-werkende AI-setup heeft alle drie. Een gemiddelde MKB-implementatie heeft geen van drieën, en dat is precies waarom ze niet werken.
Patroon 1, Memory directory met SessionStart hook
Het simpelste werkbare patroon. Een lokale directory .claude/memory/ met markdown-bestanden, geladen via een SessionStart-hook.
.claude/
└── memory/
├── MEMORY.md ← index van alle memory-bestanden
├── project_status.md ← huidige projectstatus
├── decisions.md ← logged beslissingen
└── preferences.md ← persoonlijke voorkeurenDe SessionStart-hook (zie vorige post over hooks) leest dit bij iedere nieuwe sessie en injecteert het als context.
MEMORY.md voorbeeld:
# Project Memory
## Active project
SEO-tool, AI-native voor MKB en agencies.
Status: pre-launch (target: 19 mei 2026).
SaaS, niet open source.
## Active branches
- `main`, stabiel, wacht op v1.0 release
- `feature/geo-extractor`, bezig, ~70% klaar
## Recent decisions
- Gekozen voor Supabase ipv eigen Postgres → schaal-redenen
- Geen Stripe, wel Mollie → Nederlands MKB
## Blocked
- Wachten op definitieve productnaam voor 19 mei launchDit is je centrale memory. Bij iedere sessie weet Claude wat er speelt, geen herhaling nodig.
Patroon 2, Auto-update memory bij iedere sessie-einde
Memory schrijven met de hand vergeet je. Dus: laat Claude het zelf doen.
Stop hook (in .claude/hooks/auto_update_memory.sh) detecteert sessie-einde en kan Claude vragen om een korte memory-update te genereren:
#!/bin/bash
#.claude/hooks/auto_update_memory.sh
# Stuur Claude een prompt om memory te updaten
# (alleen bij sessies > 10 minuten, om triviale runs te skippen)
INPUT=$(cat)
SESSION_DURATION=$(echo "$INPUT" | jq -r '.session_duration_sec // 0')
if ((SESSION_DURATION > 600)); then
# Trigger een mini-prompt: "Update MEMORY.md met de belangrijkste
# ontwikkelingen uit deze sessie"
cat <<EOF >>.claude/memory/_session_log.md
## Session $(date -u +%Y-%m-%dT%H:%M:%SZ)
Duration: ${SESSION_DURATION}s
[Claude: review en samenvatten in MEMORY.md indien relevant]
EOF
fi
echo '{}'In de praktijk werk ik met een eenvoudiger patroon: aan het einde van een productieve sessie tik ik handmatig update memory als instructie aan Claude. Hij leest dan de eigen sessie-context en update MEMORY.md zelf. Geeft mij controle, kost niets.
Patroon 3, Decision log voor architectuur-keuzes
Voor projecten met serieuze technische beslissingen: een aparte .claude/memory/decisions.md met format:
# Architecture Decisions
## 2026-04-15, Supabase ipv eigen Postgres
**Context:** SEO-tool moet schaalbaar opslag voor crawl-data hebben
**Decision:** Supabase managed Postgres
**Reasoning:**
- Auto-scaling zonder DBA-werk
- Built-in auth (we hebben dat sowieso nodig)
- Realtime subscriptions voor dashboard
**Trade-offs:**
- Vendor lock-in (mitigeren met regelmatige pg_dump backups)
- Iets duurder bij groot volume (acceptabel)
**Alternatives evaluated:** RDS, Neon, eigen Postgres
**Reversibility:** Hoog, Postgres-data is eenvoudig migreerbaar
## 2026-04-22, Geen Redis cache
**Context:** Performance vragen
**Decision:** Voorlopig geen cache-laag
**Reasoning:** Premature optimization. Bij <10K queries/dag is Postgres prima.
**Trade-offs:** Bij groei moet dit eventueel terug
**Reversibility:** HoogDit is decision-state in actie. Iedere belangrijke keuze schriftelijk vastgelegd, met reasoning en trade-offs. Claude kan dit lezen en respecteren, als hij voorstelt om Redis toe te voegen, wijst hij op de eerder gemaakte beslissing.
In mijn ervaring: zonder decision log vergeet Claude (en jij) waarom dingen zoals ze zijn. Met decision log heb je effectief een persistent architectuur-geheugen.
📖 Lees ook: Mijn AI-manager werd slechter naarmate ik langer met hem praatte: waarom state management onlosmakelijk verbonden is met context-beheer.
Patroon 4, Per-task state files
Voor langlopende taken die meerdere sessies kosten: aparte state-bestanden per taak.
Voorbeeld voor een blog-pipeline taak:
.claude/work/
└── 2026-05-19-seo-tool-launch/
├── status.md ← waar staan we?
├── research.md ← bronnen en notities
├── outline.md ← uitgewerkte structuur
└── draft.md ← lopende draftIedere keer dat je terugkomt op deze taak, lees je .claude/work/[task-name]/status.md en je weet exact waar je was.
Dit patroon is goud waard voor projecten die je niet dagelijks oppakt. Een blog die je over 3 weken afmaakt, een feature die wacht op klant-feedback, een refactor die je in stukjes doet.
Wat NIET in state hoort
Drie soorten informatie die ik bewust niet in state-bestanden zet:
Niet: Iedere bash-command die ik draai. Dat is sessie-context, geen project-state. Verspilt context-window.
Niet: Code-snippets van features die af zijn. De code zelf is de state, niet een markdown-versie ervan. Houd het DRY.
Niet: Persoonlijke afspraken of geheime info. State-bestanden gaan in git en kunnen lekken. Houd het op project-niveau.
Vuistregel: state moet lange-termijnwaardevol zijn (waarom we iets hebben gedaan, waar we naartoe willen) en nietkorte-termijn ruis (wat ik vandaag aan het doen ben).
Mijn eigen state-stack (concreet)
Voor wie het wil overnemen, mijn eigen setup:
.claude/
├── memory/
│ ├── MEMORY.md ← centraal, ~50 regels max
│ ├── decisions.md ← architectuur-beslissingen
│ ├── preferences.md ← mijn werkstijl
│ └── lessons_learned.md ← wat ik fout deed (en hoe ik het wil voorkomen)
├── hooks/
│ ├── load_memory.sh ← SessionStart
│ ├── auto_commit_memory.sh ← Stop
│ └──...
└── work/
└── [active-task-folders]/Plus, op project-niveau, CLAUDE.md en .claude/rules/.
Per sessie wordt dit hele complex automatisch geladen. Resultaat: iedere nieuwe sessie weet alles dat relevant is, niet meer, niet minder.
Wat doe je deze week?
Drie acties:
- Maak
.claude/memory/MEMORY.mdmet max 50 regels. Wat is het project? Wat is de status? Welke beslissingen zijn recent? Wat blokkeert? - Voeg een SessionStart-hook toe die deze MEMORY.md laadt (zie vorige post).
- Begin een decision log. Iedere keer dat je een architectuur-keuze maakt: schrijf het op in
.claude/memory/decisions.mdmet context, beslissing, reasoning, trade-offs.
Volgende week: context engineering, hoe je voorkomt dat je memory en context-bestanden verzanden in ruis.
Veelgestelde vragen
Vier patronen, één resultaat
Een AI-agent zonder state is een goudvis. Vier patronen lossen dat op: memory directory met SessionStart-hook, auto-update bij sessie-einde, een decision log voor architectuur-keuzes, en per-task state files voor langlopend werk.
Begin deze week met een MEMORY.md van 50 regels en een SessionStart-hook die hem laadt. Daarmee heb je 80% van de waarde. De rest groeit organisch met je gebruik.
Vragen over jouw state-setup of Claude Code workflow? Volg me op LinkedIn, daar deel ik wekelijks build-in-public updates. Of lees hoe ik AI-architectuur aanpak voor het MKB.