Module 2 · Tools, Knowledge, Memory & Research Design · scripted

RAG: The Librarian Who Reads Ahead

30 minoutcomes: context-engineering, knowledge-systems

The librarian who reads ahead

Everything the agent has fetched so far, it fetched itself — it read the manual, searched the document, asked the library. Now meet the other arrangement. Imagine a librarian who sees your research question before you arrive, guesses what you'll need, and stacks those books on your desk. You never asked; the desk is simply loaded when you sit down. That is retrieval-augmented generation — RAG — and here is the whole machine, map first:

The RAG pipeline

Walk the two halves. Ahead of time: cut the documents into chunks, compute each chunk's address in meaning-space, store them. At task time: compute the task's address, pull the chunks nearest to it, and paste their text into the prompt — before the model says a single word.

Nothing was added to the model

The model did not learn the documents. It was not trained,
not extended, not connected to a database.

We changed the DOCUMENT IT RESPONDS TO. Retrieval is prompt
construction — the one big prompt, built partly by machine.

And name who is holding the projector: whoever chunks, embeds, ranks, and inserts is casting shadows onto the agent's wall. RAG is a shadow-casting machine built out of code — which is exactly why its small design choices matter so much. Let's break it, one choice at a time.

"Use RAG" is not a method

Every arrow in the diagram hides a decision, and each decision can quietly change what the model believes. Watch four of them fail.

Example 1 · The chunk boundary cuts the truth in half
user

Can we schedule a delivery to Quay 3 for 23:30 Thursday? [retrieved chunk 41]: "…§142: Deliveries outside ordinary working hours (23:00–06:00) are permitted only at Quay 3, subject to a maximum sound level of 55 dB…"

assistant

Yes — night deliveries are permitted at Quay 3, provided you stay under 55 dB. I'll schedule it for 23:30 Thursday.

NoteConfident, cited, wrong. Chunk 42 — the next one, not retrieved — begins: "…except during the herring season (weeks 45–2), when the quiet period extends to all quays." The chunker cut a rule from its exception at a paragraph boundary, and the retrieval returned only the half that matched. The model answered correctly about the text it was shown. The pipeline decided what that text was.

This is the tearing principle from earlier, now with a sharper consequence: at ingestion, a bad tear costs a strip its aboutness; at retrieval, it delivers half a rule as if it were whole. Chunking is a decision about which sentences are allowed to be separated — and rules travel with their exceptions or they lie.

Example 2 · The query is a shadow too
user

My postdoc keeps buying equipment without asking — what's the rule?

NoteVersion A embeds the user's words verbatim. The query's neighbors in the space: passages about personnel disputes and supervision — because the sentence is mostly about a postdoc misbehaving. Retrieved: the conflict-resolution policy. Unhelpful.
NoteVersion B rewrites before embedding: "procurement authorization — who may purchase equipment, approval thresholds". Retrieved: the procurement policy, §3 approval limits. The document didn't change; the store didn't change. Only the question's address changed — the query is one more cast shadow, and it can be engineered.

How many books on the desk? (k and the threshold)

k = 1the one nearest chunk. If the answer spans two passages — rule here, definition there — the agent reasons from a fragment.
k = 20twenty chunks, most merely nearby-ish. The real rule is on the desk — under nineteen almost-relevant pages. The wall fills; the Goldilocks problem, again: this time the RETRIEVER causes it, not the tool.

threshold: "only chunks closer than X" — but on a question the corpus doesn't cover, the nearest chunks are still *somewhere*, and they will still be retrieved. Distance is relative; the desk is never empty, even when the library has nothing.

That last line deserves its own alarm: retrieval always returns something. Nearest is not the same as near. The most dangerous RAG answer is the one assembled from confidently-inserted chunks that were merely the least-far-away.

How you hand over the stack

One more decision, and it may matter most of all: the framing of the retrieved text when it enters the prompt. Remember the no-wall principle — anything entering the conversation can instruct. The retrieved chunks enter at the user's seat. Watch the same chunk under two framings:

Example 3a · "Use this information"
user

When was the harbor's east crane installed? Use the following information to answer: [chunk] "…the west crane, installed 1987, remains the harbor's primary heavy-lift asset…"

assistant

The east crane was installed in 1987.

NoteThe chunk is about the west crane — the corpus never mentions the east crane at all. But the framing said use this, so the model obeyed: it treated an irrelevant passage as mandatory evidence and bent it to fit the question. The librarian stacked the wrong book, and the instructions said "cite it anyway."
Example 3b · "Possibly relevant"
user

When was the harbor's east crane installed? The following was retrieved automatically and is possibly relevant — ignore it if it does not answer the question: [chunk] "…the west crane, installed 1987, remains the harbor's primary heavy-lift asset…"

assistant

The retrieved passage covers the west crane (1987); I don't have information about the east crane's installation. If you can point me to harbor infrastructure records, I can check there.

NoteSame chunk, same model, same question. The framing changed the chunk's status — from orders to evidence — and the agent was free to notice the mismatch. Retrieved text should be offered the way a careful colleague offers a source: "this may help," never "this is the answer."

The framing rule

Retrieved text speaks from the user's seat, with the power
to instruct. Frame it as EVIDENCE, not ORDERS:

  "possibly relevant · retrieved automatically · ignore freely"

And remember what else rides in on retrieved text: anything
anyone ever wrote into the corpus. A stranger's words, delivered
to the seat that steers. Hold that thought — it returns when we
treat security.

The librarian and the stacks

So which is right — the librarian who reads ahead, or the agent who walks into the stacks itself, as it has all along? Put them side by side:

Push vs. pull

RAG (push)agent-directed (pull)
who decidesthe pipeline, the agent,
before the modelmid-conversation
speaks
costone retrieval, tool calls + loop
no extra loopiterations — paid
iterationsper fetch
reacts tothe task as first everything learned
statedso far; can refine, follow up, change rung
fails bystacking the wrong not knowing the
desk, invisiblylibrary exists, or not bothering to look

Neither wins outright, and production systems almost always mix them: pre-load the plausible; let the agent fetch the rest. The desk gets the obvious books; the stacks stay open, with the ladder's rungs — string search, meaning search, ask — available when the stack turns out to be wrong or thin.

The budget principle

Retrieval before the question is a BET.
Retrieval after the question is a PURCHASE.
Bets are cheap and sometimes wrong; purchases are exact and
cost iterations. Budget for both — and give the agent a way
to notice when the bet missed.
The librarian's performance review
  • In Example 1, list every party who could have prevented the wrong answer: the chunker, the retriever, the framer, the agent. What would each have had to do differently?
  • Your research corpus: which questions about it are safe to answer from a pre-stacked desk — and which require walking the stacks?
Your turn

Take one real document from your domain — a policy, a methods handbook, a long review. (1) Chunk it two ways: fixed-size windows vs. cuts at its natural structure. (2) Write three questions whose answers you know, and run both chunkings: where does a boundary separate a rule from its exception? (3) For your worst failure, write the framing that would have let the agent notice the retrieval was wrong — and the follow-up tool call that repairs it.