Knowledge base
The knowledge base holds documents and passages stored for retrieval by meaning rather than by exact match. It is the only one of a project's four stores that holds unstructured prose, and the only one where a question phrased in your own words can find writing that never used those words. If you have not yet chosen between the four, start at where your data goes.
Every deployment lists the knowledge-base tools. Where the service behind them is not configured,
knowledge-base-add and
knowledge-base-retrieve are present and failing, with
is not configured (no data-service URL), rather than absent from the tool list.
There is no knowledge base to create
This is the first thing that surprises people, and it saves a search for a creation call that does not exist. A knowledge base is not an object you provision. It is the project's stored content filtered by tag. Adding a document under a tag nobody has used before is all it takes to start one, and there is no corresponding step to delete a knowledge base — there are only documents and the tags they carry.
That is why tags are required on both sides of the operation, and why they are worth choosing carefully rather than treating as decoration.
Adding a document
knowledge-base-add takes the document text and a non-empty list
of tags. Both are required, and an add with no tags is refused rather than accepted quietly, because
a document stored with no tags could never be found again — retrieval has no way to reach it.
The project the document lands in comes from your scope, not from anything you send.
Retrieving
knowledge-base-retrieve works in two stages, and
understanding the order is the difference between getting results and getting an empty list.
First, tags narrow the corpus. Tags are required. Retrieval searches the documents filed under the tags you pass and nothing else. Passing a tag that nothing was stored under returns nothing, no matter how well-phrased the question is.
Then, meaning ranks what is left. An optional goal — a question in ordinary language — reorders
the narrowed set so the passages that are about your question come first. The goal does not widen
the search; it only decides the order within the tags you already named. Omit it and you get the
tagged documents without that ranking.
The rest is mechanical: a result limit, a cursor for paging through more than one page of results, and a switch for whether image payloads come back inline.
How agents use it
An agent reads this corpus when it has been configured to, and the tags it may read are part of that configuration. So the same tag vocabulary that scopes your own retrieval also scopes what an agent can see: giving an agent narrower tags is how you give it a narrower corpus, without moving any documents. See agents.
How it differs from the context graph
Both stores can hold something about the same subject, and the distinction is not about the subject — it is about the shape of the question.
| Knowledge base | Context graph | |
|---|---|---|
| Holds | Prose, as written | Entities and their relationships |
| Reached by | Tags, then ranked by meaning | Traversing relationships in a query |
| Answers | "What did we write about this?" | "What is this connected to?" |
| Returns | Passages, as evidence | Rows, as facts |
| Wrong for | A single current value | Long prose answered approximately |
A retrieved passage is evidence, not a lookup. Similarity ranking always returns its closest match, which means it returns something even when nothing is really relevant. That is a feature when the corpus is prose and a hazard when the question has exactly one correct answer. If you need the current credit limit for one customer, that belongs in the context graph, where there is exactly one of it and the answer is either there or absent.
The reverse mistake is subtler. A passage saying that two systems are connected cannot be walked from one to the other. Facts you will want to traverse belong in the graph even when they arrived inside a document — which is why a support transcript often lands in both stores: the prose here, and the customer, product and escalation it names as entities over there.
Governance
Adding and retrieving are governed like every other call. Each passes a policy decision first, draws on the project's quota, and is written to the audit record. That last part matters more here than elsewhere: "what did this agent read" is a question the audit record answers directly, rather than one you have to reconstruct from what the agent then said. See policy and approvals.