Skip to main content

The Context Layer

The single highest-leverage component of an agentic platform. A centralized context layer gives every agent grounded, team-specific knowledge — the services you own, the runbooks you follow, the conventions you enforce, the incidents you've already debugged — so agents reason from your reality instead of the model's generic training data.

An ungrounded agent is a confident stranger. It knows software in general but nothing about your deploy pipeline, your on-call rotation, or why service X must never call service Y synchronously. The context layer is how that knowledge stops living only in senior engineers' heads.

This is RAG applied at the organizational scale, plus the indexing and retrieval infrastructure that makes it reliable. It is also the top of the context hierarchy: where a single repo authors a .agents/ directory and a system colocates into a poor man's monorepo, the org tier stops authoring and starts indexing — retrieving the right slice on demand instead of pasting it into every prompt.

Structure​

Every agent on the platform — coding, ops, review — calls the same retrieval interface. One source of truth, many consumers.

What to Build​

  1. Ingestion pipelines — pull from code, docs, wikis, ticket systems, incident retros, and design decisions. The unglamorous sources (postmortems, PR discussions, Slack threads) are often the most valuable because they encode why, not just what.
  2. Chunking strategy — how you split documents determines what gets retrieved. Code wants symbol- and file-aware chunking; prose wants semantic boundaries. Get this wrong and retrieval quality collapses.
  3. Hybrid retrieval — combine semantic (vector) search with keyword/BM25 and metadata filters. Pure vector search misses exact identifiers (function names, error codes); pure keyword misses paraphrase.
  4. Reranking — a second-stage model that reorders the top-k candidates by true relevance. The cheapest large win in most RAG systems.
  5. Freshness — stale context is worse than none. Re-index on merge, on deploy, on incident close. Tie ingestion to the events that change ground truth.
  6. Relationship structure — for "what calls this / who owns that" questions, a Knowledge Graph over services and ownership beats flat retrieval.

Key Characteristics​

  • One interface, many agents — centralizing retrieval means a grounding improvement helps every workflow at once.
  • Retrieval quality gates everything — garbage retrieval produces garbage generation, no matter how good the model. Measure retrieval precision/recall directly, not just end-task quality.
  • Grounding reduces hallucination — the most reliable defense against confident wrongness is putting real source material in the context.
  • Embeddings and chunking are coupled — changing one means re-evaluating the other. Version your index.
  • Access control is part of the design — agents must respect the same permissions as the humans they act for. Retrieval should never become a data-exfiltration side channel.

When to Use​

  • Agents repeatedly get team-specific facts wrong or invent plausible-but-false details.
  • Knowledge is trapped in senior engineers' heads, tickets, and old incident retros.
  • Multiple workflows need the same grounding, and you'd otherwise rebuild retrieval N times.
  • Onboarding is slow because context is scattered across a dozen systems.

Pitfalls​

  • Indexing everything, curating nothing — more documents is not more signal. Dead docs and abandoned wikis poison retrieval. See Tool Junk Drawer for the analogous failure with tools.
  • Set-and-forget indexes — an index that isn't refreshed silently rots into an Amnesiac Agent of organizational knowledge.
  • No retrieval evals — if you can't measure whether retrieval surfaces the right chunk, you're tuning blind.