Knowledge Base (RAG)

The knowledge base stores document and other knowledge chunks with embeddings and keyword-search metadata. It supports semantic, keyword, and hybrid retrieval; hybrid results combine ranked lists through Reciprocal Rank Fusion. Relevance still depends on your corpus, model, and query.

Storage and models

Use embedded PGlite or PostgreSQL with pgvector. Register an embedding-capable model and bind the embedding topic. Dimensions follow the selected model; changing models requires checking/rebuilding incompatible vectors. There is no universal fixed 768-dimensional requirement. Apply the migrations shipped with your checkout.

GET /api/knowledge/readiness checks database and embedding readiness. A failed check returns 503 with reasons; empty retrieval is not proof that indexing worked.

Search

curl -X POST http://localhost:3005/api/knowledge/search \
  -H "Authorization: Bearer $OCTIPUS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"authentication design","mode":"hybrid"}'

mode can be hybrid, semantic, or keyword. Agent knowledge tools also support graph-oriented retrieval; the REST search route does not accept graph mode. Inspect tool schemas for their available filters.

What belongs in each store

Store	Content
Knowledge base	Documents, captions, repository maps, notes and selected knowledge artifacts
Long-term memory	User facts with retrieval and supersession history
Workflow state	Session-scoped agent outputs and workflow coordination
Knowledge graph	Authored notes and explicit links between knowledge entities

Raw source-code files are excluded from knowledge indexing. Read code through filesystem/repository tools; repository maps and design documents can be indexed. A source-type value in an old client does not make raw code an accepted source.

The current schema uses purpose and scope/version metadata; old examples with source_type and a fixed vector dimension are obsolete. Use the actual schema and migrations rather than creating the table manually from documentation.

Indexing and inspection

Documents and supported sources can be indexed by their owning workflows. Check actual processing/indexing outcomes: a saved document and a searchable knowledge entry are separate results. Agent output storage is not unrestricted raw-code ingestion.

The Knowledge page supports browse/search and entry inspection. Common endpoints are GET /api/knowledge, /api/knowledge/stats, /api/knowledge/:id, POST /api/knowledge/index, and DELETE /api/knowledge/:id. Cleanup and retention policies differ by purpose; deleting a source and deleting one chunk are different operations. For source details, see the repository’s RAG guide.