AI agent memory in Git: houd context reviewbaar

Een agent die altijd een groot context.md-bestand krijgt, weet misschien veel, maar niemand ziet meer welke aanname actueel is, wie die heeft gecontroleerd of waar hij vandaan komt. Dat maakt een handige geheugensteun langzaam een risico voor review en onderhoud.

Dit is een neutrale demo met fictieve systeemnamen. Er is geen gemeten tokenbesparing, retrievalscore of klantresultaat. Het patroon is bruikbaar omdat je de inhoud en de grenzen ervan zelf kunt toetsen.

Wanneer wordt een contextbestand een risico?

Wanneer het bestand tegelijk werkafspraken, oude besluiten, bronlinks, tijdelijke incidentnotities en runtime-status bevat. Een agent kan dan een verouderde regel als waarheid behandelen, een relevant record missen of onnodig gevoelige tekst lezen.

Zie memory daarom niet als één document, maar als een klein systeem met vijf rollen:

De OKF-specificatie kiest bewust voor leesbare Markdown-bestanden met YAML-frontmatter. Dat ondersteunt menselijke review en diffs. Het is geen voorschrift dat elk project precies deze velden moet gebruiken en ook geen autorisatiemodel.

Stap 1: maak een kleine, leesbare bundel

Start niet met alle projectbestanden. Maak alleen records voor informatie die een volgende taak echt nodig heeft. In deze demo moet een fictieve supportagent weten welk facturatiesysteem als bron geldt.

memory/
├── index.md
├── decisions/
│   └── billing-provider.md
└── sources/
    └── billing-provider.md

memory/index.md blijft klein. Het benoemt onderwerpen, geen lange achtergrondverhalen.

---
updated_at: 2026-09-09
owner: platform-team
---

# Project memory index

- Voor de facturatie-integratie: lees `decisions/billing-provider.md`.
- Controleer eerst de freshness-status; gebruik geen verlopen record als feit.
- Runtime-status, secrets en klantgegevens horen niet in deze bundel.

Dat laatste is een harde grens. Git is geen geheimbeheer. Laat sleutels in een daarvoor bedoeld secretsysteem en bewaar veranderlijke taakstatus in een database of queue.

Stap 2: geef een besluit herkomst en een vervaldatum

Een bruikbaar record is concreet genoeg om een taak te helpen, maar klein genoeg om te reviewen. Dit is voorbeeldinhoud, geen implementatieadvies voor een werkelijk betalingsproces:

---
id: billing-provider
owner: platform-team
source_url: https://docs.example.invalid/billing-contract-v3
verified_at: 2026-09-09
stale_after: 2026-10-09
status: active
---

# Besluit: facturatiebron

Gebruik voor nieuwe demo-aanroepen alleen de versie-3 contractbeschrijving.
Wijzigingen aan facturatiestatus lopen via de server-side integratielaag.
De agent mag geen betaalactie starten of credentials opvragen.

source_url laat een reviewer de herkomst controleren. stale_after zegt niet dat de inhoud fout is; het zegt dat de agent niet stilzwijgend op de inhoud mag blijven vertrouwen. Gebruik een repositorycontrole die ontbrekende paden, ongeldige datums en ontbrekende owners als fout markeert.

De jonge OKF Agent Memory-repository is een aanleiding om dit patroon te bekijken, geen reden om een product blind te installeren. De repository en v0.1.1-release zijn oorspronkelijke bronnen, maar een vroege release bewijst geen volwassenheid, audit of prestatieclaim.

Stap 3: laad via progressive disclosure

Progressive disclosure betekent hier: de agent krijgt eerst alleen de index. Pas wanneer de taak over facturatie gaat, leest hij één bijbehorend besluitrecord. Vervolgens controleert hij de bronstatus voordat hij een aanname gebruikt.

Dit is patroon-pseudocode, geen uitgevoerde library-call:

const index = readMarkdown("memory/index.md");
const recordPath = chooseRecord(index, task);
const record = readFrontmatter(recordPath);

if (!record.owner || !record.source_url) {
  return requestHumanReview("memory-record mist owner of bron");
}

if (new Date(record.stale_after) < today()) {
  return requestReverification(record.source_url);
}

return useOnly(record.body);

De belangrijke keuze is niet de functie-naam, maar de foutmodus: een ontbrekende bron of verlopen record leidt tot hercontrole, niet tot een zelfverzekerd antwoord. Log alleen record-ID, versie, status en stopreden. Log geen volledige prompts, klantinhoud of secrets als dat niet nodig is.

Stap 4: test ook de negatieve gevallen

Een markdownmap is pas memory wanneer de regels voor gebruik testbaar zijn. Voeg minimaal deze controles toe aan CI of aan een reviewcheck:

Een simpele validatieregel kan de kern duidelijk maken:

if record.isExpired OR record.sourceMissing OR record.containsSecret:
  stop_and_request_review

Dit is observability én governance: bewaar hoeveel records verlopen zijn, hoeveel checks blokkeren en welke record-ID's vaak worden gekozen. Trek daar geen kwaliteitsconclusie uit zonder de taak en foutmeldingen te beoordelen.

Wanneer is Git-memory niet genoeg?

Kies een database wanneer veel processen tegelijk records bijwerken, wanneer je op attributen moet zoeken of wanneer locks en transacties nodig zijn. Kies een workflow-engine wanneer een taak timers, retries, approvals of compensaties heeft. Kies recordniveau-autorisatie of een gespecialiseerd systeem wanneer kennis persoonsgegevens, contracten of andere gevoelige informatie bevat.

De trade-off is eenvoudig: een Git-bundel is prettig voor kleine, langzaam veranderende kennis die mensen willen reviewen. Hij is ongeschikt als je hem behandelt als een live state-store. Voor veilige grenzen rond een agent kun je ook lezen over coding agents en AI-agenten in productie. Voor een engineeringworkflow waarin context, review en uitvoering samenkomen, kun je een AI engineer inschakelen.

Samenvatting

AI agent memory wordt controleerbaar wanneer een agent niet één groeiend contextbestand krijgt, maar een index en kleine records met bron, eigenaar en freshness-status. Begin met synthetische informatie, maak fouten blokkerend en breid pas uit als de review- en privacygrenzen werken. Zo blijft context engineering een ontwerpkeuze in plaats van een verborgen geheugenlaag.