> Source: https://wexa.ai/docs/context/knowledge-base

# Knowledge base

The knowledge base holds documents retrieved by tag and then by meaning. Adding needs the `fabric:orchestrate.write` grant, retrieving `fabric:orchestrate.read`, deleting `fabric:kb.delete`. To add a document in the console:

1. Open **Context Graph**, then **Knowledge Bases**.
2. Select **Add**. Drop files onto the dialog or click to browse. It accepts PDF, Word, PowerPoint, Markdown, text, CSV, JSON, images and video, up to 100 MB each, and lists any file type it skipped.
3. Type at least one tag and press Enter. Tags organise content for retrieval and do not change who can access it.
4. Select **Upload**.

## Limits

| Behavior | Detail |
|---|---|
| Creating a knowledge base | No such step. A new tag starts one. |
| Tags | Required on add and on retrieve. An add with none is refused. |
| Unknown tag | Retrieval returns nothing. |
| Goal | Orders the tagged set and never widens it. |
| Console upload | Up to 100 MB per file, at least one tag. |
| Unavailable store | `503` `S8:knowledge-base-unavailable`, raised as `UpstreamError`. |

**More details**

The **knowledge base** holds documents and passages stored for retrieval by meaning rather than by exact match, which makes it 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.

In the console you need access to the **Knowledge Bases** page, which the sidebar shows to roles that can curate context. Through the API, adding needs the `fabric:orchestrate.write` grant, retrieving needs `fabric:orchestrate.read`, and deleting needs `fabric:kb.delete`. If you have not yet chosen between the four stores, start at [where your data goes](/docs/context/overview#where-your-data-goes).

### Add a document

Through the API, `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. The project the document lands in comes from your scope, not from anything you send.

**Add a document**

**REST API**

```bash
curl -sS https://fabric.wexa.ai/v1/knowledge-base-add \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"content":"Purchases above the approval limit need a second approver.","tags":["procurement-policy"]}'
```

**TypeScript SDK**

```ts
import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.knowledgeBaseAdd({
  content: 'Purchases above the approval limit need a second approver.',
  tags: ['procurement-policy'],
})
```

**Python SDK**

```python
from wexa import Fabric

fabric = Fabric()
out = fabric.knowledge_base_add(
    "Purchases above the approval limit need a second approver.",
    tags=["procurement-policy"],
)
```

The document becomes a file in the project's Knowledge Base, the same as a console upload. An optional `name` sets the file name the console shows, and the result carries a `file_id`.

### More limits

| Behavior | Detail |
|---|---|
| Governance | Each call passes a policy decision, draws on the project's quota and is written to the audit record. The audit record answers "what did this agent read" directly. |

See [policy and approvals](/docs/governance/policy-and-approvals) for how a decision is made.

### How the knowledge base works

1. **There is no knowledge base to create.** It is the project's stored content filtered by **tag**. Adding a document under a tag nobody has used starts one.
2. **You add documents with tags.** Tags are required, because a document with no tags could never be found again.
3. **Tags narrow the corpus.** Retrieval searches the documents filed under the tags you pass and nothing else.
4. **Meaning ranks what is left.** An optional `goal`, a question in ordinary language, orders the narrowed set so the passages about your question come first.
5. **Agents read the same corpus** by tag, when they are configured to.

There is no step that deletes a knowledge base either. There are only documents and the tags they carry.

### Tell a missing tool from a failing one

Every deployment lists the knowledge-base tools. Where the service behind them is not configured, [`knowledge-base-add`](/docs/context/knowledge-base-add) and [`knowledge-base-retrieve`](/docs/context/knowledge-base-retrieve) are present and failing with `is not configured (no data-service URL)`, rather than absent from the tool list.

### Retrieve passages

In the console, open **Knowledge Bases**, then **Test Console**. Type a question in the goal box, choose at least one tag, and run it. The console shows the ranked passages. A goal on its own can never succeed, because retrieval needs tags.

Through the API, `knowledge-base-retrieve` works in the order the console does:

- **Tags come first.** They are required. A tag that nothing was stored under returns nothing, however well-phrased the question is.
- **The goal only reorders.** It does not widen the search. Omit it and you get the tagged documents without ranking.
- **The rest is mechanical.** A result limit, a cursor for paging through more than one page, and a switch for whether image payloads come back inline.

**Retrieve passages by tag and goal**

**REST API**

```bash
curl -sS https://fabric.wexa.ai/v1/knowledge-base-retrieve \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"tags":["procurement-policy"],"goal":"Who approves a large purchase?","limit":5}'
```

**TypeScript SDK**

```ts
import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.knowledgeBaseRetrieve({
  tags: ['procurement-policy'],
  goal: 'Who approves a large purchase?',
  limit: 5,
})
```

**Python SDK**

```python
from wexa import Fabric

fabric = Fabric()
out = fabric.knowledge_base_retrieve(
    tags=["procurement-policy"],
    goal="Who approves a large purchase?",
    limit=5,
)
```

The result shape is not recorded in the reference, so call it once and read what comes back.

### Choose between the knowledge base and the context graph

Both stores can hold something about the same subject. The difference is the shape of the question.

| | Knowledge base | [Context graph](/docs/context/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, so it returns something even when nothing is relevant. That suits prose and is a hazard when the question has exactly one correct answer. The current credit limit for one customer belongs in the context graph, where there is exactly one of it.

The reverse mistake is subtler. A passage saying 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. A support transcript often lands in both stores: the prose here, and the customer, product and escalation it names as entities there.

### Give an agent a narrower corpus

An agent reads this corpus when it has been configured to, and the tags it may read are part of that configuration. The same tag vocabulary that scopes your own retrieval scopes what an agent can see. Giving an agent narrower tags gives it a narrower corpus without moving any documents. See [agents](/docs/agents/overview).

### Classify a tag

In the console, **Tag classification** on the Knowledge Bases page labels what each tag holds. When an agent retrieves with a tag, model routing applies that tag's label, and a file with no label of its own inherits the strictest label of its tags. Only organization admins can change a label. Other roles see them read-only.

### Remove documents

[`delete-kb-document`](/docs/context/delete-kb-document) removes documents by file id, by tag, or both.

Warning: A tag removes every document filed under it, not one document. It is permanent, and agents stop seeing the removed content immediately. Retrieve first and look at what you are about to lose.

### When the knowledge base is unavailable

The documents live in a separate document store. When that store is down, or refuses the platform's own credential, every add, retrieve and delete fails the same way: `503` with the error `S8:knowledge-base-unavailable` and the message `knowledge base unavailable: its document store is not accepting requests right now`.

Nothing was stored or deleted, and the store's internal error is never returned. It is in the platform's own logs. Both SDKs raise it as `UpstreamError`, so retry later. An add that was held for approval spends its resume token when it is resumed, so after this error add the document again.