Deel B · Module 05
Geheugen & retrieval (RAG)
Hoe weet een agent meer dan in zijn context past?
Leerdoelen
Na deze module kun je:
- de stappen van een RAG-pijplijn benoemen (knippen, indexeren, zoeken, in de prompt zetten) en aanwijzen waar het fout kan gaan;
- voorspellen of een vraag beter gevonden wordt met embeddings, met BM25 of met beide, en uitleggen wat contextual retrieval toevoegt;
- kiezen tussen alles in de prompt, RAG, agentic search en notities op schijf, voor een gegeven hoeveelheid en soort kennis.
Voorkennis-check
Twee vragen over embeddings en context. Fout? Lees A1 Tokens & embeddings en B4 Context eerst terug.
Waar zitten we?
Retrieval en geheugen horen bij laag 3, de loop: vóór of tijdens een beurt haalt de applicatie of de agent zelf informatie op en zet die in de context. Het model (laag 1) leert er niets van; het leest alleen wat in de request staat.
De stof in drie lagen
Kern ± 5 min lezen, daarna drie vragen uitproberen
Een model weet wat er in zijn training zat (A3) en wat er in de context staat (B4). Jullie interne documentatie, de tickets van vorige week en de 40.000 pagina's van een kennisbank staan in geen van beide. Er zijn vier manieren om die kennis bij het model te krijgen:
| Aanpak | Hoe | Wanneer |
|---|---|---|
| Alles in de prompt | de hele kennisbank meesturen, met prompt caching | klein genoeg om in het venster te passen, en vaak dezelfde |
| RAG | vooraf knippen en indexeren; per vraag de beste stukken (chunks) zoeken en in de prompt zetten | grote, vrij statische kennisbanken; vragen die het antwoord in een paar passages hebben |
| Agentic search | de agent zoekt zelf met tools (grep, zoek-API, MCP) en leest gericht | code en andere bronnen die steeds veranderen; vragen die meerdere zoekstappen vragen |
| Geheugen op schijf | de agent schrijft notities en leest ze in een volgende sessie terug | wat de agent zelf leert: voorkeuren, beslissingen, valkuilen |
RAG is a method that retrieves relevant information from a knowledge base and appends it to the user's prompt, significantly enhancing the model's response.
Bij RAG valt of staat alles met de zoekstap. Wat de retriever niet vindt, ziet het model niet, en dan antwoordt het met wat het wél ziet, ook als dat over iets anders gaat. Probeer hieronder drie vragen met drie zoekmethoden. Let op de derde vraag: daar heeft geen van de methoden genoeg, totdat je contextual retrieval aanzet.
Samengevat: embeddings vinden betekenis, BM25 vindt exacte woorden (codes, ID's, namen), en samen vinden ze het meest. Een chunk die bij het knippen zijn context verliest ("het bedrijf", "vorig kwartaal"), is voor allebei onvindbaar. Contextual retrieval zet daarom een korte context vóór elke chunk.
Verdieping embeddings, hybride zoeken, contextual retrieval, geheugen
De RAG-pijplijn
- Knippen: de documenten in chunks van meestal hooguit een paar honderd tokens.
- Indexeren: per chunk een embedding (een vector die betekenis codeert, A1) en een lexicale index (TF-IDF/BM25).
- Zoeken: de vraag krijgt ook een embedding; zoek de dichtstbijzijnde chunks (cosine similarity) én de beste BM25-treffers.
- Fuseren en herordenen: combineer beide lijsten (rank fusion), eventueel met een reranker die per chunk opnieuw scoort.
- In de prompt: de top-K chunks gaan als context mee met de vraag.
Let op: Anthropic levert zelf geen embeddingmodel. De documentatie noemt Voyage AI als aanbieder, met algemene modellen, codespecifieke modellen (voyage-code-4) en rerankers, maar raadt aan meerdere leveranciers te vergelijken.
Waarom hybride
While embedding models excel at capturing semantic relationships, they can miss crucial exact matches.
Het voorbeeld uit het artikel: een gebruiker zoekt "Error code TS-999". Een embeddingmodel vindt documenten over foutcodes in het algemeen, maar kan de exacte TS-999 missen. BM25 zoekt die string letterlijk. Omgekeerd vindt BM25 geen synoniemen ("terugsturen" tegenover "retourneren"). Daarom combineer je ze.
Contextual retrieval
Het probleem: door het knippen verliest een chunk zijn context. "De omzet groeide met 3%" zegt niet welk bedrijf of welk kwartaal. De oplossing: laat een model per chunk een korte context schrijven (meestal 50–100 tokens), met het hele document erbij, en zet die vóór de chunk. Daarna pas embedden en indexeren.
This method can reduce the number of failed retrievals by 49% and, when combined with reranking, by 67%.
Dat lijkt duur, want per chunk stuur je het hele document mee. Met prompt caching laad je het document één keer in de cache en verwijs je er per chunk naar (D5).
Agentic search: hoe Claude Code het doet
Claude Code gebruikt geen vectorindex van je code. Het zoekt just-in-time met Grep, Glob en Read (B4). Dat werkt goed voor code: die verandert voortdurend (een index veroudert), en exacte namen van functies en symbolen zijn precies waar lexicaal zoeken sterk in is. Met een code-intelligence-plugin (LSP) springt Claude bovendien rechtstreeks naar definities. Externe kennis (een wiki, tickets, een documentatieportaal) haal je binnen met een MCP-server die een zoektool aanbiedt (C3). Of die server intern RAG gebruikt, maakt voor de agent niet uit.
Geheugen: notities die de sessie overleven
Retrieval gaat over kennis die al bestaat. Geheugen gaat over wat de agent zelf leert. Claude Code heeft twee mechanismen, die allebei bij de start van elke sessie laden:
- CLAUDE.md: wat jij schrijft (C1).
- Auto memory: notities die Claude zelf bijhoudt in
~/.claude/projects/<project>/memory/, met een indexMEMORY.mden een bestand per onderwerp. Machine-lokaal, gedeeld tussen worktrees van dezelfde repo.
The first 200 lines of
MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation.
De index laadt, de onderwerpbestanden leest Claude als het ze nodig heeft. Dat is retrieval in het klein: een korte index altijd in de context, de details op aanvraag.
Onder de motorkap BM25, de contextprompt, keuzes en metingen
BM25 in één alinea
BM25 bouwt voort op TF-IDF: een woord telt zwaarder als het vaak in de chunk staat (term frequency) en zelden in de hele collectie (inverse document frequency). BM25 voegt twee correcties toe: herhaling verzadigt (tien keer "omzet" is niet tien keer zo relevant), en lange chunks worden genormaliseerd naar de gemiddelde lengte. Het resultaat is snel, uitlegbaar en sterk op exacte termen. De oefenrepo bevat een implementatie van ±20 regels.
De contextprompt uit het artikel
Prompt per chunk (Contextual Retrieval)
<document>
{{WHOLE_DOCUMENT}}
</document>
Here is the chunk we want to situate within the whole document
<chunk>
{{CHUNK_CONTENT}}
</chunk>
Please give a short succinct context to situate this chunk within the overall
document for the purposes of improving search retrieval of the chunk. Answer
only with the succinct context and nothing else.
Ontwerpkeuzes
- Chunkgrootte: te klein en de context gaat verloren, te groot en de embedding wordt een gemiddelde van te veel onderwerpen. Knip bij voorkeur op natuurlijke grenzen (secties, functies) en neem koppen mee.
- Top-K: meer chunks vergroten de kans dat het antwoord erbij zit, maar ook de ruis en de kosten (B4). Het artikel meet met recall@20: het percentage relevante documenten dat níét in de top 20 zit.
- Reranking: haal ruim op (top-N), laat een rerankmodel elke chunk opnieuw scoren en geef alleen de beste K door (in het artikel: 20). Dat kost een extra stap per vraag, maar het model verwerkt minder ruis.
- Meet de retrieval los van het antwoord: een goed antwoord op een slecht gevonden context is toeval, een slecht antwoord op een goede context is een promptprobleem (D3).
If your knowledge base is smaller than 200,000 tokens (about 500 pages of material), you can just include the entire knowledge base in the prompt that you give the model, with no need for RAG or similar methods.
Uitgewerkt voorbeeld: één chunk, met en zonder context
Uit het kwartaalverslag van Acme B.V. over Q2 2026 komt deze chunk. Gevraagd wordt: "Hoeveel groeide de omzet van Acme in Q2?"
Zonder context (zo wordt hij geïndexeerd)
Resultaten: De omzet groeide met 3% ten opzichte van het vorige kwartaal, tot 4,2 miljoen euro.
Met context (contextual retrieval)
Uit het kwartaalverslag van Acme B.V. over Q2 2026: de omzetresultaten van Acme in het tweede kwartaal.
Resultaten: De omzet groeide met 3% ten opzichte van het vorige kwartaal, tot 4,2 miljoen euro.
- "Acme" en "Q2" ontbreken. De BM25-zoeker in de oefenrepo zet een chunk over Globex ("De omzet van Globex groeide in Q2 2026 …") op 1. Het model krijgt dan het verkeerde bedrijf te zien en antwoordt met 7%.
- Gegenereerde context, geschreven door een klein model met het hele document erbij. Nu staat de Acme-chunk bovenaan. De context wordt alleen gebruikt om te vinden; in de prompt kun je hem meesturen of weglaten.
Laat een zoekmachine falen, en repareer hem met context
Starter: oefenrepo/b5-rag/. Drie korte documenten, een BM25-zoeker (rag_demo.py, alleen standaardbibliotheek) en een script dat met claude -p per chunk een context laat schrijven.
Opdracht
python3 rag_demo.py "Wat betekent TS-999?". Waarom vindt BM25 dit meteen?python3 rag_demo.py "Hoeveel groeide de omzet van Acme in Q2?". Welke chunk staat bovenaan, en wat zou een model dan antwoorden?python3 rag_demo.py --context "Hoeveel groeide de omzet van Acme in Q2?"(gebruikt de handgeschrevencontexts.voorbeeld.json). Wat verandert er?- Draai
./make_contexts.sh: Claude schrijft nu zelf de contexten, met de prompt uit het artikel. Vergelijkcontexts.jsonmet het voorbeeld en herhaal stap 3. - Maak het kapot. Vraag:
"Hoe lang duurt het voor ik mijn geld terugkrijg?". Er is geen document over terugbetalen. Wat geeft de zoeker terug? Wat moet een RAG-applicatie dan tegen het model zeggen?
Verwacht resultaat
Stap 1: support-foutcodes.md#2 (TS-999) op plek 1: de exacte term komt maar in één chunk voor en weegt dus zwaar.
Stap 2: de Globex-chunk op 1, de Acme-chunk op 2. Een model dat alleen de top-1 krijgt, zegt "7%".
Stap 3: de Acme-chunk op 1, met de context erboven.
Stap 4: de door Claude geschreven contexten verschillen in woordkeus, maar noemen bedrijf en kwartaal. Meestal staat Acme daarna op 1. Gebeurt dat niet, kijk dan naar de context: welk woord ontbreekt?
Stap 5: drie chunks met lage scores die niets met terugbetalen te maken hebben. BM25 geeft altijd een top 3. Een goede applicatie zet een minimumscore of laat het model expliciet zeggen dat het antwoord niet in de bronnen staat.
Als het niet werkt, kijk naar …
make_contexts.shfaalt. Werktclaude -p "hallo"in je shell? Zo niet: inloggen of je API-key instellen. Wil je geen modelcalls doen, sla stap 4 dan over.- Andere scores dan verwacht. Heb je de documenten aangepast? BM25 hangt af van de hele collectie (IDF): één extra document met "omzet" verandert alle scores.