RAG & Knowledge Base
Per-project knowledge bases and the Agentic-RAG retrieval loop.
Each project can have one or more knowledge bases — collections of uploaded documents, chunked and embedded for retrieval.
Agentic-RAG, not static RAG
Retrieval is agent-initiated, not a fixed pre-processing step glued in front of every prompt. A knowledge-retrieval step in a flow (or an agent with knowledge-base access) decides whether it needs to retrieve, based on the conversation so far:
User Query
│
▼
Agent decides it needs more context
│
▼
Retrieval call
│
▼
Embed query → search knowledge base → top matching documents
│
▼
Inject retrieved context → model → responseA knowledge base attached to an agent is used in one of two retrieval modes,
chosen on the agent: When required (on_demand, the default — the agent
chooses when to call it) or Each input (always — retrieval runs
unconditionally before every generation). A flow's RAG Retrieval step
always retrieves.
Storage isolation
Every knowledge base is backed by its own dedicated, uniquely named storage partition — this prevents cross-tenant data access at the storage layer itself, not just at the query layer.
Hybrid search
Retrieval combines vector similarity with keyword-based search for more accurate results than vector-only retrieval, plus metadata filtering (e.g. by document type) where relevant.
Every hit has two numbers: score only orders the results (it comes from
rank fusion and stays small, roughly 0.01–0.03), while similarity is the
0–1 cosine similarity of the best vector match (0 when only the keyword
search found the passage). A similarity threshold — the Score threshold of
the retrieval step in a flow, or score_threshold in the search API — is
compared with similarity, so values such as 0.5 work as expected.
Knowledge base options
| Option | Values | Notes |
|---|---|---|
| Embedding model | an embedding provider | Required, fixed after creation |
| Knowledge mode | Standard (default), Graph Based | Fixed after creation. Graph Based also extracts the entities and relationships of your documents into a graph, which suits questions that span many documents or ask how things relate. It needs a graph extraction model (a chat provider, editable later) and costs extra model calls while indexing. A flow's RAG Retrieval step searches it by entity; an agent can also run corpus-wide searches |
| Chunking | Fixed (default), Semantic | Fixed after creation. Semantic chunking starts a new chunk where the topic shifts and keeps a heading together with its text; the chunk size is still the upper limit |
| Chunk size / overlap | characters | Fixed after creation; the overlap must be smaller than the chunk size |
| Evidence Based | off by default | Editable. Retrieved passages are numbered, so the agent cites them as [n] and the run reports them as sources. Once the answer is complete, one extra model call checks whether every claim is supported by the cited passages and the run records the verdict as a groundedness step (verified, unsupported with the claims, or skipped when the check could not run). The verdict is only reported: the answer is not changed, and the check's tokens are counted in the run's usage |
Document ingestion
Uploading a document triggers an asynchronous pipeline: text extraction → chunking → embedding via the knowledge base's configured embedding provider → storage in the knowledge base.
- Accepted files: PDF, TXT, MD, DOCX and CSV, checked on the server (not
only by the browser). Other types are refused with
415; an empty or whitespace-only file, a "PDF" that is not a PDF, or a binary file renamed to.txtis refused with422. - DOCX tables are indexed along with the paragraphs: each table row becomes
one line (
cell | cell) in reading order. - Chunk size and overlap are measured in characters, not tokens. The overlap must be smaller than the chunk size.
- Semantic chunking keeps a heading together with the text under it and joins very short pieces to their neighbour; a document that fits in one chunk stays one chunk.
- A knowledge base needs an embedding model when it is created (a Graph Based one also needs a graph extraction model). Its name cannot be blank.
- Status and reason: a document is
pending→processing→readyorfailed. A failed document says why infailure_reason(for example: the file could not be read, it contains no text, the embedding model is gone, indexing failed). An unreadable file fails immediately; a temporary problem is retried a few times first. To try again, replace the file of the failed document or delete it. - Chunks of a document are listed in document order. A chunk's text can be edited (up to 4096 bytes of text, 2048 bytes of metadata).
Graph index
A Graph Based knowledge base builds its entity graph while documents are
indexed; the communities used for broad questions are built on request
(Rebuild Graph Index). graph_index_status shows building, failed
(with graph_index_error) or idle, and graph_index_stale tells that
documents changed since the last build.
Text documents, updates and limits
Besides file uploads, Markdown and plain-text documents can be added directly
as text. A document can be replaced later (a new file, or new
text for documents added as text): the old content stays searchable until the
new content is indexed, then it is swapped. A document that is still being
processed cannot be replaced (409 document_busy), and sending identical
content changes nothing. Deleting a document is permanent.
Limits are always enforced: a document may not exceed 3 MB (413 document_too_large) and a project may not store more than 1 GB in total (413 project_storage_quota_exceeded).
Related
- Providers — how the embedding model is configured
- Guides → Set up a knowledge base