Concepts

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 → response

A 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.

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

OptionValuesNotes
Embedding modelan embedding providerRequired, fixed after creation
Knowledge modeStandard (default), Graph BasedFixed 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
ChunkingFixed (default), SemanticFixed 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 / overlapcharactersFixed after creation; the overlap must be smaller than the chunk size
Evidence Basedoff by defaultEditable. 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 .txt is refused with 422.
  • 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 → ready or failed. A failed document says why in failure_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).

On this page