Knowledge Bases vs Document Repositories for AI Agents

A support agent gets asked for "a waterproof speaker under $200 like the one in the kitchen ad," and it confidently returns a product that was discontinued last quarter, at the old price, with a feature it never had. The team's first instinct is to blame the model. The real culprit is almost always retrieval: the agent is pulling from a document repository that stores chunks of prose and metadata, not a modeled view of the catalog, and it has no way to enforce the constraints that actually matter.

This is the heart of the knowledge base versus document repository question for AI agents. A document repository, a vector index of chunks or a wiki of pages, addresses exactly one slice of what an agent needs. Sanity Context (previously Agent Context) is the AI Content Operating System for this problem, an intelligent backend that gives agents structured, governed access to your content rather than a pile of embeddings to guess against.

The distinction matters because context is not one thing. It has different lifetimes and owners, and a repository only covers retrieved content, one of four quadrants, not the whole game. This guide contrasts the established repository pattern with a knowledge base built for agents, then maps out where each one wins.

The repository model: chunks, pages, and one query strategy

A document repository is the pattern most teams reach for first, and it comes in two common shapes. The first is a vector database, Pinecone, Weaviate, pgvector, where you chunk your content, embed the chunks, and store them alongside metadata filters. The second is a wiki, Notion or Confluence, where content lives as pages of prose that an AI add-on crawls and answers over. Both are document repositories in the literal sense: they hold documents (or fragments of them) and retrieve by similarity.

The shape works well for one job, fuzzy semantic recall. Ask a vector index for something conceptually close to your query and it will surface the nearest neighbors. The trouble starts when the question carries hard constraints. A request like "trail runners under $150 like a Hoka" mixes a semantic intent ("like a Hoka") with structured predicates (price under 150, category trail running, in stock). Pure vector search cannot resolve the structural constraints and returns empty or wrong results, so the model hallucinates or hedges. Pure structured query, on the other hand, falls over on the vague "something like X" half of the request.

Repositories paper over this with a metadata-filter layer bolted onto the index, but the structured constraints and the semantic ranking live in separate systems that you stitch together in application code. There is no single query that says "filter on these facts, then rank by relevance." That gap is exactly where agent answers go wrong, and it is structural to the repository model, not a tuning problem you can prompt your way out of.

Why hybrid retrieval beats any single method

The most useful result in this space is that no single retrieval method is enough. Anthropic's contextual retrieval research measured it directly. Contextual embeddings alone cut top-20 retrieval failures by 35 percent. Adding contextual BM25, classic keyword matching, took that to 49 percent. Adding a reranking layer on top brought it to 67 percent. The shape of the improvement holds whether you read the paper closely or just notice that none of the three layers alone was enough.

That is the whole argument against treating a repository as a retrieval strategy. Keyword search (BM25) catches literal matches: a part number, a product name, a policy clause. Embeddings catch semantic intent: "waterproof" matching "IP67-rated." Structured predicates enforce the filters that have to hold: price, stock location, category. Each covers a different failure mode, and a system built around only one of them inherits the failures of the other two.

This is why "we have embeddings" is not a retrieval strategy. A vector index is one ingredient. A knowledge base built for agents has to compose all three, ideally in a single pass so the filters constrain the candidate set before relevance ranking runs. In Sanity Context, that is exactly what GROQ does: structured predicates filter on category, price, and stockLocation, then a score() pipeline blends boost([title] match text::query($queryText), 2) for BM25 keyword matching, title weighted twice, with text::semanticSimilarity($queryText), ordered by _score. One query, all three layers, no glue between separate systems.

Freshness: the hidden line item a repository never closes

The cost that does not show up in a proof of concept is freshness. A document repository built on a separate vector database is only as current as your last indexing run. When a price changes, a description is edited, a product is published, or an SKU is deleted, the embeddings and the index have to be updated, or the agent answers from stale data. Building that pipeline yourself, incremental indexing, re-embedding on change, deletion handling, and backfill, is a permanent line item on your roadmap. It never finishes, because content never stops changing.

This is where a knowledge base that lives inside the content backend pulls ahead of a repository bolted on beside it. Because dataset embeddings in Sanity Context are tied to the content itself, an update propagates within minutes; there is no separate vector pipeline to keep in sync. The Content Lake keeps the search index fresh on content change as a property of the system, not a job your team owns. The same edit that publishes the new price updates what the agent can retrieve.

Sanity's own production data sharpens the point. When you look at how agents actually call the Sanity Context MCP endpoint, structured retrieval dominates: GROQ queries and schema lookups make up the heavy majority of calls, with semantic search a small slice. Embeddings are opt-in, off by default, and most projects shipping on the endpoint never turn them on. The teams running agents in production are leaning on fresh structured retrieval, not on a vector index they have to babysit.

Retrieval is a context problem, not a model problem

Even with hybrid retrieval and perfect freshness, retrieval against a real catalog is harder than teams expect, and the difficulty has nothing to do with the model. Sanity ran a schema exploration against Sonos's catalog, an honest nightmare of a dataset, and landed around 83 percent accuracy by teaching the retrieval step things a schema alone would never reveal.

The failures were all context, not capability. There were counter-intuitive field names: a field called body that is actually a slug, a hero that is a reference to a mediaAsset rather than an image. There were second-order reference chains the schema does not connect on its own, where you have to chain a product to its productFeature and match on a feature id. And there were data-quality landmines, like a features array that is always empty, so the right move is to read from support-product instead. None of that is a model problem. The model needed to know the shape of the data, not just its types.

A document repository erases exactly this information. Once content is chunked into prose and embedded, the schema, the references, and the field semantics are gone, flattened into vectors. The agent cannot follow a reference chain it can no longer see. A knowledge base that preserves the modeled structure, the Content Lake behind Sanity Context, keeps those relationships queryable, which is what lets the retrieval step navigate a messy real-world catalog instead of guessing at it.

Context is four things; a repository covers one

The deepest reason a document repository under-serves an agent is that it solves one quadrant of a four-part problem. Context is not one thing. It is four things with different lifetimes, different owners, and different access patterns, and treating them as one means underbuilding three of them.

The first is static instructions: the system prompt, brand voice, escalation rules, and compliance guardrails. These are release-scoped and owned by product, brand, and legal teams. The second is per-turn runtime state: the single-turn working memory owned by your application. The third is retrieved content: product catalogs, docs, policy documents, pulled on demand based on the question. This is what most teams think context means, and it is important, but it is one of four, not the whole game. The fourth is agent-authored notes: cross-session memory the agent itself writes and owns.

A document repository addresses only retrieved content. It has nothing to say about where the system prompt lives or how it is governed. This is why Sanity Context isn't only an MCP: it ships an MCP endpoint, a knowledge base, and an ingest path, deliberately spanning more than the retrieval quadrant. Knowledge Bases turn messy sources, Sanity datasets, support databases, websites, and PDFs, into well-ordered, agent-readable documents with a clear table of contents, so agents answer faster, more accurately, and at lower cost. That is a content operating system for agents, not a pile of indexed chunks.

Governing agent instructions like content, not code

The quadrant repositories ignore most completely is static instructions, and it is the one with the highest blast radius. When an agent says the wrong thing, refuses the wrong request, or drifts off-brand, the fix lives in the system prompt. In most stacks that prompt is buried in code or a YAML file, edited by engineers, deployed on the release train, and invisible to the brand, support, and compliance teams who actually own its content.

Treating the prompt as a document changes who can safely touch it. In Sanity, the system prompt is a document split into role-owned fields: voice owned by Brand, escalation owned by Support, and mustNotSay owned by Compliance. That gives you versioning, real-time collaboration, scheduled publishing, rollback, role-based edits, and an eval gate, the same controls you already trust for your published content. Editors author agent behavior in the Studio, not in YAML, and tune the agent's voice and the scope of what it knows without touching code.

The staging story is the part repositories cannot match. Editors stage agent behavior with Content Releases the same way they stage the website: preview before you ship, with drafts, scheduling, history, permission gating, and audit trails. The customer pattern bears this out. One engineering team reported storing the system prompt in a Sanity document let editors tune the agent's voice with no code changes, and a banking customer wanted the whole organization, with product managers owning the prompt rather than waiting on a deploy. A document repository governs none of this; it was never built to.

A decision framework: when each one is the right call

Start with the question your agent actually has to answer. If every query is a fuzzy semantic lookup over a stable corpus of prose, FAQs, a help center, a static document set, a document repository or a wiki with an AI add-on is fast to stand up and may be all you need. The retrieval is mostly semantic over text, the content rarely changes, and there are no hard constraints to enforce.

The calculus flips the moment your agent has to honor structured facts. If answers depend on price, availability, entitlement, region, or any predicate that has to hold, a repository forces you to bolt a metadata-filter layer onto an index and stitch the structured and semantic halves together in application code. The moment your content changes often enough that staleness produces wrong answers, you inherit the freshness pipeline as a permanent cost. And the moment more than one team needs to govern what the agent says, you need a governance lane for instructions that a repository simply does not have.

Those three conditions, structured constraints, frequently-changing content, and multi-team governance, are the signal that you have outgrown the repository pattern. They are also exactly what Sanity Context is built for: native hybrid retrieval inside the Content Lake via a single GROQ query, dataset embeddings that stay fresh because they are tied to content, Knowledge Bases that turn messy sources into agent-readable documents, and Studio-governed instructions staged through Content Releases. Production agents connect to the Sanity Context MCP endpoint and get all of it on one retrieval path. The repository answers one quadrant well. A content operating system answers all four.