Core concepts
You’ll keep running into six concepts when you use Cortrix. Here’s what each one means and how they relate.
How the concepts relate
flowchart LR
NS[Namespace] --> DOC[Document]
DOC --> BLK[Block]
NS --> MEM[Memory]
MEM --> BLK
Q[Query] --> BLK
Documents and memories both belong to a namespace. Documents and memory records produce blocks, and blocks are what a query searches.
Namespace
A namespace is a logical collection boundary for documents, blocks, memory, and queries. You name a namespace when you write, and you list one or more namespaces when you query.
Document
A document is source material you upload to Cortrix. It can be parsed and indexed.
Block
A block is the smallest searchable unit, derived from a document or a memory record. Query results are blocks, along with the source each one came from.
Query
A query is a retrieval request over one or more namespaces. The request names its scope with a plural namespaces array:
The deprecated singular namespace field is rejected on query requests. Other endpoints may still use a singular namespace field where their OpenAPI definition requires it.
Memory
Memory is structured long-term information, captured from interactions or written explicitly through the API.
Agent surface
An agent surface is a programmatic path that lets an agent use Cortrix: the HTTP API, MCP, the Python SDK, or the built-in Agent service.
Local models and LLM roles
These two are easy to mix up:
- Local neural models: the quickstart uses two local ONNX models. BGE-M3 handles embedding and bge-reranker-v2-m3 handles reranking. They run on your machine’s CPU and send nothing to an external service.
- LLM roles:
semantic_llm,vision_llm,agent_llm,doc_summary_llm, andenricher_llmare separate, optional capabilities. You configure them only when you’re testing a feature that uses them.
So LLM_ENABLED=false doesn’t mean embedding or reranking is off.