Skip to main content

Use knowledge

Boundary statement​

A knowledge base stores operator-supplied sources for retrieval; a model does not “know” a document merely because it was uploaded. The document must finish processing, retrieval must return a qualifying chunk, the knowledge base must be attached to the run, and the resulting context and citation must be observable.

Knowledge is not memory​

Knowledge resources are named collections of documents and indexed chunks. Agent memory is a separate opt-in system for captured or explicitly written records across user, agent, session, global, and task scopes. A selected model's conversation context and a live citation event are also separate: neither is a durable knowledge document.

StateAuthorityUse in a runObservable boundary
Knowledge base and documentConfigured persistence, tenant/user scopedSelected by agent or conversation policyKnowledge admin API/UI
Indexed chunksConfigured persistence plus the current embedding pipelineRanked retrieval contextSearch results and retrieval audit
CitationRuntime event derived from a retrieved chunkShows what source contributedChat source badge / normalized event
Model outputProvider responseMay use retrieved contextCompletion text; validate against the source fact

Packaged UI workflow​

  1. Open Admin → Knowledge at /admin/knowledge and choose Add Knowledge Base. Create a name and optional description.
  2. Select the knowledge base and upload a supported document. Upload acceptance creates a pending record; it does not mean indexing completed.
  3. Watch processing move from pending through processing to indexed. A failed document displays its error and offers retry with the original or a replacement file. Never treat failed as indexed.
  4. Search the knowledge base for a distinctive fact. Require a non-empty ranked result above the selected threshold.
  5. In Chat, attach the knowledge base directly with the Knowledge capability or select an agent whose knowledge configuration includes it.
  6. Ask a question whose answer depends on the indexed source. Confirm the answer contains the source fact and the transcript displays the source document as a citation.

Deleting a knowledge base or document removes its durable source and search data. Treat those UI actions as destructive.

API workflow​

The knowledge resource is mounted at /api/knowledge:

StageRequestObservable result
CreatePOST /api/knowledge201 Created with a tenant/user-owned knowledge-base ID.
IngestMultipart POST /api/knowledge/{kb_id}/documents202 Accepted with a pending document record.
Observe processingGET /api/knowledge/{kb_id}/documents/{document_id}pending, processing, indexed, or failed with an error.
RetrievePOST /api/knowledge/{kb_id}/searchRanked chunks with score, metadata, and document ID.
AttachPOST /api/uar/sessions/{conversation_id}/agent-config or conversation policy APIKnowledge-base selection for the next resolved run.
RunPOST /v1/chat/completions with the same session identifierA genuine model response through the selected conversation.
Inspect provenanceStream the run/chat responseKnowledge-base/document citation events and source identity.

The search and chat paths share the hardened retrieval pipeline: query decomposition, per-query retrieval, deduplication, verification annotation, result limiting, and a rag.retrieval.decision audit record occur before context injection.

RC3 ingestion verification​

Use the mounted upload, status and retrieval paths with a fresh fact-bearing document. For local English OCR, enable kreuzberg.ocr_enabled and use a readable scan. The Linux image supplies pinned English data. Require terminal failure without an indexed generation for malformed or empty extraction. Rebuild indexes when replacing an embedding model, even if vector width matches. See RC3 document and embedding checks.

Durable authority and live state​

Configured persistence is the durable authority for knowledge bases, documents, document status, chunks, and ownership. The UI polls while documents are pending or processing and projects the returned state; a local upload-progress message is not durable status.

Retrieval results and citations are run-scoped observations. A citation names the knowledge base, document, and source used for that run, but it does not copy the entire durable source into the event stream. A process-local result list is not a replacement for persisted documents or a subsequent retrieval.

Genuine model use​

To claim grounded inference, use a fact that is absent from the prompt except through the selected document. Observe all four boundaries: indexed document, non-zero ranked retrieval, source citation, and the genuine model's answer.

The retained 2026-08-22 server-full record, source SHA d41bf7c3a447869896664d44ac0563e1b4a1d9f3, observed one API-created knowledge base return a ranked match with score 0.8674219 and influence one genuine openai/gpt-5.4-mini request. It separately observed the packaged UI create a knowledge base, upload and index a text file, select it, return the distinctive fact, and display that file as the source. These results apply only to those artifacts, provider/model, profile, checkout, and date.

Failure boundaries​

  • Upload acceptance without an ingestion pool leaves the document saved but not processed.
  • A failed extraction or embedding stays failed and exposes its error.
  • A search result below the configured threshold is not injected.
  • An attached name or ID outside the resolved policy universe is not authority to read another tenant's knowledge.
  • A plausible model answer without retrieval and citation evidence is not a grounded-inference result.

Profile limits​

  • server-full includes the packaged Knowledge UI and the server ingestion, retrieval, chat, and citation paths described here.
  • minimal contains the server and persistence base but does not inherit the full document-intelligence/admin-UI claim. Verify its actual feature composition before promising ingestion formats or UI behavior.
  • embedded-mobile exposes no knowledge HTTP/UI path. The host supplies persistence and an embedding backend and calls the shared transport-free knowledge/run services in process.

No retained result transfers to another profile. Continue with Use agent memory.