Skip to main content

Knowledge Bases

A knowledge base is a collection of documents you curate: pasted text, web pages, files, Git repositories, Confluence spaces and manifests. The platform splits each document into chunks, indexes them for search by meaning and by keyword, and, when an agent with an attached knowledge base starts work, adds the chunks most relevant to the conversation to the agent's context.

Use a knowledge base when an agent needs to answer from material that is too large for a system prompt and changes only when you change it: product documentation, policies, runbooks, FAQs.

You manage knowledge bases under Resources → Knowledge.

How an agent uses a knowledge base​

A knowledge base is attached to one agent. When that agent is initialised for a chat, the platform:

  1. finds the knowledge bases attached to the agent (at most three are searched);
  2. searches each one for content relevant to the conversation, taking up to five matching chunks per knowledge base;
  3. adds them to the agent's instructions under a Memory Context section, alongside any memories, with each chunk shortened to its first 400 characters.

Knowledge-base content is fetched as part of the agent's memory, so the agent must have Memory turned on. An agent with memory off is never given knowledge-base content, even if knowledge bases are attached to it.

Content that came from outside the platform (web pages, Git repositories and Confluence) is marked as untrusted when it is retrieved. When untrusted content is added to an agent's context, the session is labelled as carrying it before any tool call runs, so governance policy can account for instructions that may have been planted in a fetched page.

note

A knowledge base attached to one agent is invisible to every other agent in the project. To give two agents the same material, create a knowledge base for each.

Ways to add content​

SourceButton on the Documents tabWhat happensProcessed
TextIngest TextYou paste content and an optional titleImmediately
Web pageIngest URLThe page is fetched and its main body text extractedIn the background
Git repositoryIngest GitThe repository is shallow-cloned and every file matching a glob filter (default **/*.md) is ingested, one document per fileIn the background
ConfluenceIngest ConfluenceA whole space, or a parent page and all its descendants, is fetched and each page ingestedIn the background
ManifestAdd ManifestA manifest from the same project is converted to readable text (name, type, version, description, purpose, parameters, data and schema)Immediately
FileUpload FileThe file is converted to textIn the background

Upload accepts PDF, DOCX, PPTX, XLSX, HTML, Markdown, plain text and CSV files, up to 50 MB by default. Git ingestion has default caps of 2,000 matching files, 10 MB per file and 25 MB in total. Git and Confluence can authenticate with an integration; see Setting Up a Knowledge Base for the secret names each one looks for.

What happens to content on the way in​

  • Chunking. Text is split into chunks of roughly 1,500 characters, on natural boundaries where possible.
  • Secret scrubbing. Before anything is stored, common secret patterns (API keys, bearer tokens, Slack and GitHub tokens, AWS access keys, private-key blocks and password=/token= style values) are replaced with [REDACTED].
  • De-duplication. A chunk whose text is identical to one already in the knowledge base is skipped, so re-running an ingest of unchanged content adds nothing.
  • Embedding. Each chunk is given an embedding so it can be found by meaning (see below).

Because identical chunks are skipped but changed chunks are not merged, re-ingesting a document you have edited adds the new chunks alongside the old ones. Delete the old document first when you update content.

Search: by meaning, with a keyword fallback​

Search combines two matches: a meaning-based match on each chunk's embedding and a full-text keyword match. "How do I get my money back?" can find a passage about refunds even though they share no words.

The embedding model is the knowledge base's own Embedding LLM Config ID if you set one, otherwise your organisation's Default Embedding Model (set by a platform administrator under Settings). Embeddings are stored at a fixed width of 1536 dimensions, so an embedding model you choose must produce 1536-dimension vectors; the platform tests the model when you save and rejects one that returns a different width.

A chunk with no embedding can be found only by its exact words. That happens when:

  • neither the knowledge base nor your organisation has an embedding model, so every chunk is stored keyword-only;
  • the embedding call failed while the content was being ingested (the chunk is stored anyway, without an embedding).

The platform retries a few missing embeddings at a time whenever the knowledge base is searched or ingested into. To check and fix a knowledge base completely, use the API or the platform tools:

OperationWhat it tells you or does
Readiness (GET /knowledge-bases/{id}/readiness, tool get_knowledge_base_readiness)Whether search is semantic, partial, keyword-only or empty; how many chunks lack an embedding; whether the embedding model can be used; whether the base is attached to one agent or inactive
Re-embed (POST /knowledge-bases/{id}/reembed, tool reembed_knowledge_base)Embeds chunks that are missing one, up to 200 per call by default (1,000 maximum). Safe to repeat until nothing remains. Requires the Editor role

Testing what a knowledge base returns​

The Search tab on a knowledge base runs the same search an agent's context is built from, returning the ten best chunks with their scores. If an agent is not using the right material, search here with the kind of question a user would ask and check what comes back.

Managing content​

  • The Documents tab lists content grouped by source: one row per file, page, URL, Git file or titled text, with a chunk count. It shows the 500 most recently added chunks.
  • The delete icon on a row deletes every chunk from that source. All pages from one Confluence ingest share a source, so they are deleted together.
  • Deleting a knowledge base deletes all of its documents.

Changes take effect the next time the agent is initialised; you never need to edit the agent.

Settings​

FieldNotes
NameRequired
DescriptionShown in the agent's Attach KB list
Agent ID (optional)The numeric ID of the agent this knowledge base is attached to. Usually easier to set from the agent's Memory tab
Embedding LLM Config ID (optional)The numeric ID of an embedding model under Resources → Models. Leave empty to use your organisation's default
Embedding DimensionsMust be 1536

Through the API a knowledge base can also be set inactive (is_active: false). An inactive knowledge base keeps its content but disappears from the Knowledge list and from agent search; list it again with include_inactive=true.