Deterministic, on-demand retrieval

Retrieval is deterministic and cheap: the agent searches and extracts what it needs on demand, rather than being fed a pre-built index assembled before anyone knew what the task was. Ask the same question twice and the same material comes back, because the retrieval is a search over the actual artefacts rather than a nearest-neighbour lookup in an embedding space that was built last week.

This is the run-time half of context. What the organisation writes down and keeps current - the docs, the ADRs, the ownership records - belongs to Knowledge Management, and this guide assumes those artefacts exist. The question here is what actually reaches the model when it starts work on a specific task, how it got there, and whether the same task would get the same material tomorrow.

The practical shape of this is agentic search. Instead of embedding the repository into a vector store and retrieving the top-k chunks by similarity, the agent runs the tools an engineer would run - grep, a symbol query, a structural extraction over the parse tree, a scoped subagent that reads a directory and reports back file-and-line citations. Each of these is exact, explicable and repeatable. When it returns the wrong thing you can see why, and fix the query rather than re-tune an index.

Cheap matters as much as deterministic. Assembling context is not free: an overstuffed window degrades reasoning as reliably as a missing file does, and every token of speculatively-retrieved material is a token the model spends attention on. On-demand retrieval means the agent pays for what the task needs, when it needs it, and nothing else - which is also why pruning unused skills and idle MCP servers recovers a meaningful share of the window before any retrieval happens at all.

Knowing what to retrieve still requires knowing what kinds of context exist. Five are worth naming, because each has a different volatility and therefore a different retrieval strategy:

1. System-level context - The architecture and infrastructure of the system: how services are deployed, what infrastructure they run on, how they communicate, what the scalability and reliability constraints are. An agent working on a microservice without system-level context doesn't know whether it's a standalone service or one of two hundred in a mesh. It doesn't know if horizontal scaling is available or if there's a single-region constraint.

2. Code-level context - The codebase itself: module structure, dependency graph, existing abstractions, test patterns, build conventions. Code-level context is what IDE tools naturally provide - file contents, imports, definitions. The agent can read the files, but it can only read what fits in its context window.

3. Org-level context - Team structure, ownership maps, who to contact for what, what teams' current priorities are, what's in-progress vs. completed. An agent that doesn't know that the authentication team owns the auth-service might modify that service in a way that's technically correct but violates a team boundary.

4. Historical context - Why decisions were made: Architecture Decision Records (ADRs), git commit history with meaningful messages, design documents, post-mortems. An agent that doesn't know a particular pattern was explicitly rejected three years ago after a production incident will confidently re-suggest the rejected pattern.

5. Operational context - The current state of the running system: deployment status, error rates, latency metrics, recent incidents, on-call alerts. An agent working on code related to a currently-degraded service needs to know the service is degraded - and why - to make safe suggestions.

The volatility of each level decides how it should be retrieved. System-level and Code-level context lives in the repository and is best searched on demand, because it is exactly the material grep and structural extraction are good at. Org-level and Operational context change faster than any index could track and should be queried live from the systems of record at the moment the agent needs them. Historical context sits in between: stable enough to search, large enough that you want the search to be targeted rather than exhaustive.

At L3 (Systematic), organisations have identified which of these context types they are providing and which they are not, and are retrieving each one by a method that returns the same answer every time.

Deterministic retrieval is what makes an agent's failures diagnosable. When retrieval is a similarity search over an index, a bad suggestion has no traceable cause: you cannot tell whether the material was absent, present but unranked, or present and ignored. When retrieval is a search the agent ran and logged, the failure is attributable, and it can be classified by context level:

• Agent suggested a pattern we explicitly rejected in 2022 → Historical context gap → fix: ADRs in context
• Agent modified a service owned by another team without coordination → Org-level context gap → fix: ownership data via MCP
• Agent didn't account for the fact that this runs on single-region infrastructure → System-level context gap → fix: infrastructure documentation in CLAUDE.md
• Agent created a utility function that already exists in a shared library → Code-level context gap → fix: better codebase indexing, RAG over the repo
• Agent suggested adding caching to a service that's currently in a degraded state due to a memory leak → Operational context gap → fix: production telemetry in context

Without this vocabulary, context gaps get described as "the AI is bad", which leads to no actionable fix. With it, they become specific infrastructure investments.

The levels also map onto the maturity progression: L2 provides basic Code-level context (an instruction file with project information). L3 retrieves all five deterministically and on demand. L4 automates assembly. L5 keeps what is retrieved fresh.

The industry moved decisively this way during 2026. Anthropic dropped vector search in Claude Code in favour of agentic grep and tool-search, and Microsoft's FastContext (June 15) uses a repo-explorer subagent that returns compact file-line citations and cuts coding-agent tokens by up to 60%. Both are the same bet: an index is a stale, lossy, expensive copy of something the agent could have read directly, and a tool call that reads the real thing beats a retrieval that approximates it.

1. Audit your current context coverage - For each of the five levels, ask two questions: can the agent get this at all, and does it get the same thing every time? Rate each level none, partial, or systematic, and note which ones currently arrive via an index rather than a search.
2. Identify your biggest gap - The level with "none" coverage is your starting point. Don't try to address all five levels at once.
3. Give the agent search tools before you give it an index - Make sure the agent can grep, list files, query symbols and extract by structure, and that it is instructed to use them. Most teams discover the agent was capable of finding the file all along and had simply been handed a summary instead.
4. Retire any index you cannot explain - If a vector store is in the path, test it against plain search on twenty real tasks. Keep it only where it demonstrably wins, and be honest about its cost: a copy of the repository that must be rebuilt, can go stale silently, and cannot tell you why it returned what it did.
5. Query the volatile levels live - Org-level and Operational context change faster than any snapshot. Expose service ownership and deployment status through tools the agent calls at the moment it needs them, so the answer is current by construction rather than fresh by luck.
6. Validate each level with a probe question, run twice - Ask the agent something that requires each level: "Who owns the auth service?" for Org, "What is the current deployment status of the payments service?" for Operational, "Why don't we use Redis for session storage?" for Historical. Run each probe twice. A different answer the second time is a retrieval defect, and it is invisible to any evaluation that runs each case once.

Treating Code-level context as the only kind that matters. Teams that have done good L2 work often stop there - they've improved autocomplete and basic agent suggestions, and declare success. But for agents tackling larger tasks, the other four context levels are equally important. Code-level context alone doesn't prevent the agent from violating team ownership, ignoring historical decisions, or making unsafe changes to degraded services.

Reaching for an index before exhausting search. A vector database feels like the serious answer to "the agent cannot find things", and it usually is not. It introduces a second copy of the truth that has to be kept in sync, it makes retrieval unrepeatable, and it answers with fragments whose provenance the model cannot check. Try exact search, structural extraction and a scoped subagent first; adopt an index only where you can show it beating them on real tasks.

Confusing context level with information priority. Operational context is not more important than Historical context - they're different dimensions of the same picture. An agent that has excellent operational context but no Historical context will make safe suggestions about the current system state while confidently repeating patterns that were explicitly rejected years ago.

Trying to provide all five levels through static files. System-level and Code-level context can live in CLAUDE.md. Org-level, Historical, and Operational context changes faster than static files can keep up with. Organizations that try to maintain these as static documents spend significant effort on a losing battle. MCP servers are the right infrastructure for dynamic context.

Measuring retrieval quality only once per case. An evaluation that runs each scenario a single time cannot distinguish a retrieval strategy that works from one that worked that time. Run the same probes repeatedly and treat variance as a defect in its own right - it is the difference between a context system you can reason about and one you can only hope about.

Not measuring context quality by level. If you track agent suggestion quality as a single number, you can't tell which context level is causing failures. Separate your quality metrics: how often does the agent make architectural errors (System), violation-of-conventions errors (Code), team boundary violations (Org), repeated historical mistakes (Historical), and operationally unsafe suggestions (Operational)?