Knowledge base

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.

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.

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"]}'

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'],
})

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

See 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 and 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.

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}'

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,
})

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.

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.

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 removes documents by file id, by tag, or both.

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.