Deel B · Module 05

Geheugen & retrieval (RAG)

Hoe weet een agent meer dan in zijn context past?

Zone: machine ± 15 min kern

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:

Van "past in de prompt" naar "veel te groot"
AanpakHoeWanneer
Alles in de promptde hele kennisbank meesturen, met prompt cachingklein genoeg om in het venster te passen, en vaak dezelfde
RAGvooraf knippen en indexeren; per vraag de beste stukken (chunks) zoeken en in de prompt zettengrote, vrij statische kennisbanken; vragen die het antwoord in een paar passages hebben
Agentic searchde agent zoekt zelf met tools (grep, zoek-API, MCP) en leest gerichtcode en andere bronnen die steeds veranderen; vragen die meerdere zoekstappen vragen
Geheugen op schijfde agent schrijft notities en leest ze in een volgende sessie terugwat 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

  1. Knippen: de documenten in chunks van meestal hooguit een paar honderd tokens.
  2. Indexeren: per chunk een embedding (een vector die betekenis codeert, A1) en een lexicale index (TF-IDF/BM25).
  3. Zoeken: de vraag krijgt ook een embedding; zoek de dichtstbijzijnde chunks (cosine similarity) én de beste BM25-treffers.
  4. Fuseren en herordenen: combineer beide lijsten (rank fusion), eventueel met een reranker die per chunk opnieuw scoort.
  5. 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.

Anthropic, Introducing Contextual Retrieval

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%.

Anthropic, Introducing Contextual Retrieval (september 2024)

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 index MEMORY.md en 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.

Anthropic, Introducing Contextual Retrieval (2024; de huidige modellen hebben een venster van 1M tokens, maar zie B4 over context rot)

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.
  1. "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%.
  2. 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.
Doe-opdracht

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

  1. python3 rag_demo.py "Wat betekent TS-999?". Waarom vindt BM25 dit meteen?
  2. python3 rag_demo.py "Hoeveel groeide de omzet van Acme in Q2?". Welke chunk staat bovenaan, en wat zou een model dan antwoorden?
  3. python3 rag_demo.py --context "Hoeveel groeide de omzet van Acme in Q2?" (gebruikt de handgeschreven contexts.voorbeeld.json). Wat verandert er?
  4. Draai ./make_contexts.sh: Claude schrijft nu zelf de contexten, met de prompt uit het artikel. Vergelijk contexts.json met het voorbeeld en herhaal stap 3.
  5. 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.sh faalt. Werkt claude -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.

Zelftoets