The Retrieval Surface¶
How a tier pulls the slice it needs from substrate, on demand — without dredging the whole file.
[TUNABLE — retrieval mechanism]
New here? This page is about how an AI agent fetches just the small piece of a file it needs — instead of reading the whole thing — so its limited working memory doesn't fill up with stuff it never asked for. You care because that "fetch the slice, not the file" habit is what keeps a federation of agents fast, cheap, and focused.
TL;DR¶
In plain terms: agents pass each other a pointer ("the answer is in this file") and grab the actual detail only when they need it. This page is the knob for how that grab works. Read on for the two retrieval methods and the four supporting settings.
The minimal-sufficient bus relays a pointer and keeps the detail in substrate, pulled on demand. This page is the dial for how that pull happens. Two grades sit on the surface: lexical / grep-grade (the default — git grep / ripgrep, path- and tag-scoped, no infrastructure, rebuildable for free) and embeddings / vector (opt-in — semantic retrieval for where lexical misses). Around the grade sit four more dials: what's indexed, chunk granularity, refresh cadence, and per-tier scope. The whole surface is provider-agnostic, and the index is always a rebuildable cache derived from git, never a source of truth. The [INVARIANT] constraints that keep retrieval from becoming a back-door — tier-partitioned scope, as-of + re-verify, pointer-not-truth — live in Retrieval discipline and are in force behind every dial here.
Why this dial exists¶
"Pull on demand" is only as light as the pull. If a receiver answers a detail question by reading the whole LEDGER, the whole tagged return, or the whole commit history, the bus stayed light but the pull flooded the receiver's context — the relay vector of pollution simply reopened one step downstream. Retrieval closes it: the receiver pulls the minimal-sufficient slice instead of the whole file. This dial sets the mechanism that makes the pull surgical; the discipline guardrail keeps that mechanism honest.
Choosing your pathway¶
One gate, two lanes. Where: the gate routes by need — almost everyone to Lane A. How: Lane A is git grep/ripgrep, native and zero-setup; Lane B is embeddings → store → pointer, wired via MCP on Claude Code or baked into the loop on a local model. Why: Lane A gives immediate budget relief at no cost; Lane B buys semantic recall for the few who provision it. Both lanes obey the same three constraints — no harness exemption.
Two lanes sit on this surface. Pick by need, not by appetite — most adopters stay in Lane A forever.
| Lane A — default (start here) | Lane B — advanced (opt-in) | |
|---|---|---|
| Grade | lexical / grep-grade | embeddings / vector |
| Setup | none — native to the harness | bring-your-own-infra |
| Cost | none — no vendor, no embeddings | embeddings + store + index-build |
| Budget relief | immediate — pull the slice, not the file | same, plus semantic recall |
| Who | every adopter, any harness | those who hit real semantic misses |
| Help needed | none — you already have it | self-served (see the runbook + reference below) |
Lane A is the provisioned happy path. Lexical retrieval is already what an agent harness does natively — Claude Code's grep/glob, or git grep/ripgrep on a local model. It needs nothing, costs nothing, and immediately relieves the budget/context problem the bus would otherwise create. Turn it on and stop here unless you have a concrete reason not to.
Lane B is opt-in and self-served. Reach for it only when lexical demonstrably misses — the slice you need is phrased unlike any query that would find it. It is the natural fit for self-hosted / local models (Qwen and the like), where you control the loop and can bake retrieval in. On Claude Code it is reachable too — you wire a vector / semantic-search source through an MCP server (or a custom tool/hook); Claude Code consumes retrieval but does not host the index, so you still provision the store yourself.
Harness × model — where vector plugs in¶
| Claude Code | Local model (Qwen, etc.) | |
|---|---|---|
| Lexical | native (grep/glob) |
you build it (git grep / ripgrep) |
| Vector | via an MCP server / custom tool (consume; don't host the index) | baked into the loop directly |
| Index / embeddings | host yourself, expose via MCP | host, call inline |
| Customization | through defined seams (MCP / tools / hooks / sub-agents) | full loop control |
| Fit for heavy vector | possible, heavier wiring | natural fit |
Whichever cell you land in, the same three discipline constraints bind — there is no harness exemption.
The dials¶
1. Retrieval grade¶
How the slice is located.
| Grade | Mechanism | Infra | Cost | Best for |
|---|---|---|---|---|
| Lexical / grep-grade (default) | git grep, ripgrep; path- and tag-scoped lexical search |
none — runs anywhere git runs | near-zero; rebuildable for free | the common case — finding a known term, tag, ledger entry, or section |
| Embeddings / vector (opt-in) | embeddings over chunks + a vector store; semantic similarity | a vector store + an embeddings provider, server-side on the host | index-build + query cost; provider dependency | semantic retrieval where the right slice doesn't share the query's words |
Lexical is the default deliberately: it honours the framework's no-specialized-databases stance, it needs no provider, and for most "where did we record X" pulls it is sufficient. Reach for the vector grade only when lexical demonstrably misses — when the slice you need is phrased differently from how you'd ask for it. Even then, the vector store is a cache (see dial 5), never a new durability layer.
2. Index corpus — what's indexed¶
What the retrieval layer covers, per tier:
- The tier's own folder — LEDGER, HANDOVER_LOG, LEFTOVERS, CLAUDE.md.
- The inboxes it receives — the tagged returns and briefs that legitimately reach it.
- Its own memories.
- The substrate it owns or reviews, at the relevant tags.
It does not cover other tiers' working folders. This is not a preference — the per-tier partition is the [INVARIANT] floor set by Retrieval discipline §1. The tunable part is only which of the entitled corpus a project bothers to index (e.g. memories on or off), never whether the partition holds.
3. Chunk granularity¶
How finely the corpus is split into retrievable units.
- Per-section (default for docs/specs) — a heading and its body. Aligns with how briefs cite (
§10K), so a hit maps cleanly to a substrate citation. - Per-return / per-entry (default for ledgers and inboxes) — one tagged return or ledger line per chunk. Keeps a hit minimal-sufficient.
- Per-commit-body (for history) — the commit message body as the unit, with the diff reachable by pointer.
Finer chunks return less noise per hit (better pollution containment) at the cost of more hits to assemble; coarser chunks risk dragging in detail the receiver never needed. Bias finer for high-stakes lanes.
4. Refresh cadence¶
How current the index is kept relative to the substrate it covers.
- Per-commit (default) — the index updates when the substrate it covers advances, so the
as-ofwatermark tracks the tip closely. - Scheduled — periodic rebuild; cheaper, but a wider staleness window.
- On-demand — rebuilt before a retrieval-heavy session; lowest standing cost, highest first-query latency.
Whatever the cadence, every hit carries its as of <commit> watermark and load-bearing use re-reads the frozen blob — the staleness constraint holds regardless of how fresh the index happens to be.
5. Index locus — the cache, never the record¶
Where the index lives and what authority it has.
- Rebuildable cache (the only sane setting) — the index is derived from git and can be dropped and regenerated. It holds pointers (
file @ tag § chunk) and, for the vector grade, embeddings. The authoritative content stays in the commit history. - Source-of-record (anti-pattern — off the table) — load-bearing content living only in the index. This breaks git foundations and provenance law; documented only so adopters recognize and avoid it.
Defaults¶
| Dial | Default | Range |
|---|---|---|
| Retrieval grade | lexical / grep-grade | lexical / embeddings-vector |
| Index corpus | own folder + received inboxes + owned substrate (+ memories) | same — partition is [INVARIANT]; memory inclusion is the only toggle |
| Chunk granularity | per-section (docs) · per-return (ledgers/inboxes) | per-section / per-return / per-commit-body |
| Refresh cadence | per-commit | per-commit / scheduled / on-demand |
| Index locus | rebuildable cache | rebuildable cache / source-of-record (anti-pattern) |
| Embeddings provider | — (n/a at lexical default) | any, server-side — provider-agnostic |
How to choose¶
- Start lexical. Most "where did we record X" pulls are lexical. Adopt the vector grade only after you observe lexical misses on slices phrased differently from the query.
- Keep chunks fine for high-stakes lanes — finer chunks return less noise per hit, which is the whole point of retrieval as a pollution defense.
- Match refresh cadence to substrate velocity — per-commit where the substrate moves fast and decisions are time-sensitive; scheduled or on-demand for slow, low-stakes corpora.
- Never let the index become the record. If dropping the index would lose information, the information was in the wrong place — move it to substrate.
- Run index-build server-side, off the tiers' context budget, so the mechanism that fights pollution doesn't become a pollution source itself.
Runbook: provisioning and switching grades¶
Readiness at a glance¶
| Grade | Provisioning required | Ready out of the box? | Reverse cost |
|---|---|---|---|
| Lexical / grep-grade | none — git + ripgrep | yes, immediately | n/a — it is the floor |
| Embeddings / vector | embeddings provider + vector store + server-side index-build, partitioned per tier | no — the adopter provisions it; opt-in | free — drop the cache, fall back to lexical |
The framework ships no infrastructure — it is a framework, not a tool; you bring your own host. Lexical is "ready" precisely because it needs nothing. Vector is "ready" only once an adopter has provisioned it to the acceptance bar below — that checklist is the definition of "fully provisioned."
Decision gate — do you actually need vector?¶
Stay on lexical unless all of these hold:
- You have observed lexical misses — slices you needed were phrased differently from any query that would find them (semantic, not keyword, gaps).
- The corpus is large enough that the miss rate actually costs cycles.
- You accept an embeddings-provider dependency and the cost + staleness window a built index introduces.
If any fails, lexical is the correct, cheaper, git-native answer. Most federations never need to flip.
Runbook A — lexical (default · zero provisioning)¶
- Nothing to stand up. Git is the index.
- Pull pattern (provider-agnostic): scope the search to the tier's entitled paths at a tag — own folder + received inboxes + owned substrate — e.g.
git grep -n <query> <tag> -- <entitled-paths>, or ripgrep over agit archiveof the tag. Scoping to entitled paths is the partition. - Return pointers (
file @ tag § section), not pasted text; re-read the frozen blob before citing. - Refresh: none — rebuilding is free because there is nothing built.
All three discipline constraints hold for free: you scope to entitled paths (partition), you pin the tag (as-of), git is the source (pointer-not-truth).
Runbook B — vector (opt-in · provisioned)¶
- Phase 0 — Prerequisites (provider-agnostic). An embeddings provider (configurable), a vector store (configurable), and a host to run index-build server-side, off every tier's context budget.
- Phase 1 — Partition the namespaces. Create one index namespace per tier, each scoped strictly to that tier's entitled corpus. Do not create a single shared collection — that is the back-door. The partition is
[INVARIANT]. - Phase 2 — Chunk + embed. Split per the granularity dial; embed each chunk; store metadata = file path + tag/commit + section anchor → the pointer
file @ tag § section. - Phase 3 — Stamp freshness. Record the watermark (the commit each namespace was built from) so every hit can carry
as of <commit>. - Phase 4 — Wire refresh. Trigger rebuild on substrate advance per the cadence dial; server-side; never on a tier's budget.
- Phase 5 — Query path. The tier queries only its own namespace → top-k candidate pointers → re-reads the frozen blob at the tag → cites the substrate. The chunk is never pasted as the answer.
Reference setup (a worked vector path)¶
The framework mandates no stack, but a concrete reference shortens Lane B. A maintained, on-thesis path:
- Chunking + embedding: Anthropic's Contextual Retrieval — prepend each chunk's context before embedding, so a hit is self-locating and minimal-sufficient. That is the same goal as the bus discipline, which is why it composes cleanly with the
as-of+ pointer-not-truth constraints rather than fighting them. - Embeddings provider: any — Anthropic offers no first-party embeddings endpoint and points to Voyage AI; substitute whatever your stack prefers.
- Vector store: any.
- Wiring: expose the store to the agent as an MCP retrieval server (the harness-agnostic seam), or call it inline on a local model.
Every component is swappable — this is a reference, not a requirement, exactly as Claude Code is the reference harness rather than a mandated one. Whatever you pick still has to clear the acceptance bar.
The switch (the toggle)¶
The grade switch is a cycle-boundary flip with a lifecycle provisioning prerequisite on the vector side — you don't turn vector on mid-cycle; you provision it (Phases 0–4) out of band, then cut over at a clean seam.
- Lexical → vector cutover: ① provision to the acceptance bar; ② run shadow for one cycle — both grades answer the same pulls, lexical stays authoritative, compare recall; ③ cut over at the seam, keeping lexical as fallback.
- Vector → lexical rollback: free and instant — drop the namespaces (a rebuildable cache) and fall back to
git grep. Zero loss, because nothing load-bearing lived only in the index (pointer-not-truth).
Acceptance bar — what "fully provisioned" means¶
Vector is provisioned only when every box passes — this checklist is the answer to "is it ready?":
- Per-tier namespaces — no shared/global collection (partition holds; firewall intact).
-
as of <commit>on every hit, and load-bearing use re-reads the frozen blob. - Drop-and-rebuild proven — delete the index, regenerate from git, identical pointers.
- Index-build runs server-side, off every tier's context budget.
- Providers are configuration — embeddings + store swappable (provider-agnostic).
- Chunk size tuned so a hit is minimal-sufficient (no oversized chunks).
Until every box is checked, stay on lexical — an unfinished vector setup is the back-door, not an upgrade.
Remember this¶
- Start with lexical (plain text search). It is
git grep/ ripgrep — already built into your agent, free, needs no setup, and handles almost every "where did we write X" lookup. Most teams never need anything more. - Only reach for vector (semantic search) when keyword search keeps missing — i.e. the thing you need is worded nothing like what you'd search for. It costs money and infrastructure, so opt in deliberately.
- The index is a throwaway cache, never the original. You can delete it and rebuild it from git at any time; nothing important should live only in it.
- This is a customization dial — to see where it sits in the bigger picture, visit the mental model.
How this connects¶
- The minimal-sufficient bus (guardrail) — specifies the pull-on-demand this surface mechanizes.
- Retrieval discipline (guardrail) — the
[INVARIANT]constraints (partition,as-of+ re-verify, pointer-not-truth) bounding every dial here. - Context patterns (tunable) — the sibling context surface; retrieval is how a fresh or loaded tier reloads only the relevant slice instead of full history.
- Provenance law (axiom) — the hit is a pointer; the frozen blob is the truth; the cite is the substrate.
- Git foundations (axiom) — keeps the index a rebuildable cache, not a specialized database.
- Cycle toggles / Project-lifecycle toggles — the grade switch is a cycle-boundary flip with a lifecycle provisioning prerequisite on the vector side (see the runbook).