This is the multi-page printable view of this section. .
Get started
Go from a machine with only Git and Docker to a local Cortrix you can query.
1 - Overview
Cortrix is open source semantic storage built for AI agents. It’s agent-native storage for retrieval, memory, and API-driven AI applications.
It provides a semantic storage server with namespaces, documents, blocks, hybrid search, memory APIs, and agent-oriented access paths. It’s designed for agents and applications that need a programmable retrieval layer rather than a one-off vector database wrapper.
Cortrix is in active pre-release. The current version is v1.0.0-rc.2. Interfaces and features are at different levels of maturity, and authentication, authorization, and production readiness are not established. See Compatibility and status.
What is semantic storage?
Semantic storage connects information with the context an application needs to use it. Cortrix does this through retrieval, memory records, and links back to sources.
That maps to three needs in agent work:
| Need | What it means |
|---|---|
| Agent workflows | An agent needs to read source material, use tools, and keep track of what happened |
| Context for a task | A useful answer needs relevant material at the right moment. Storage keeps that material available, and retrieval decides which passages belong in the prompt |
| Memory across tasks | Some experience is worth carrying into the next task. Storage preserves it, but the system still needs to check whether an old observation applies |
Design
- Agent-native: designed around agent data workflows. Semantic processing, memory, and traceability are shared storage concerns rather than scattered integration code.
- Semantic storage: documents are parsed, chunked, embedded, and indexed in a shared semantic layer, so agent workflows can query meaning and source context together.
- Built to fit existing stacks: works with your existing databases, tools, and agent workflows while giving retrieval, memory, and audit a shared semantic layer.
Building blocks
| Building block | What it covers |
|---|---|
| Semantic Processing Chain (SPC) | Parsing, OCR fallback, chunking, enrichment, embedding, and indexing |
| Hybrid query and reranker | Vector search, BM25, rank fusion, and reranking |
| AI interaction memory | Memory APIs and typed memory records |
| Agent observability | Session, trace, and agent identity |
| Source-level traceability | Inspectable source context across chunks, documents, and turns |
| Namespaces and cross-namespace query | Logical query scope for projects and workflows |
| Local embedding | ONNX Runtime and BGE-M3 |
| Access paths | HTTP, MCP, the Python SDK, framework adapters, data import, and PostgreSQL |
A namespace is a logical query scope. It is not an authentication, authorization, access-control, or tenant-security boundary.
Components in the repository
| Component | Location | Role |
|---|---|---|
cortrix-server | src/ | The C++ backend and HTTP API |
| OpenAPI spec | api/openapi.yaml | The public HTTP API contract |
| MCP server | cortrix-mcp/ | An MCP server for IDE and agent clients |
| Python SDK | sdk/python/ | The Python client |
| Built-in Agent | cortrix-agent/ | A fixed-flow RAG chat service |
| Web UI | web/ | The local web interface |
Access paths
| Path | Best for |
|---|---|
| HTTP API | Your own services, or direct calls from an agent |
| MCP server | IDE agents and MCP-compatible clients |
| Python SDK | Python applications and RAG pipelines |
| Built-in Agent | Local fixed-flow chat over Cortrix storage |
To pick one, see Choose an access path.
Current status
Cortrix is in pre-release. To see whether a capability is in preview or in development, see Compatibility and status.
License
Cortrix Core is licensed under Apache-2.0. That applies to v1.0.0-rc.2 and later. The historical v1.0.0-rc.1 release remains under AGPL-3.0-only. Third-party material keeps its own license.
Next steps
- Quickstart: start Cortrix with Docker and run your first query.
- Install with an AI agent: hand setup and verification to an AI agent.
- Core concepts: learn about namespaces, documents, blocks, queries, and memory.
2 - Quickstart
In this quickstart you’ll start Cortrix v1.0.0-rc.2 on your machine with Docker and run a reranked query against the bundled demo document. The whole path uses real local embedding and reranking models, and you don’t need a key for any LLM service.
If you’d rather have an AI agent run these steps, see Install with an AI agent.
Prerequisites
- Git
- Docker with Docker Compose
curl- Enough disk space for the image, the build cache, and about 1.17 GB of model files
You don’t need a .env file, an LLM provider key, model tooling on the host, or any manual model download or conversion.
Steps
Clone and start
The first start builds the image from source and downloads the model files into the cortrix-data volume (its full name in Docker is deploy_cortrix-data). Later starts reuse that volume.
The command returns only when the service is ready. It ends with:
How long the first start takes depends on your machine and network. On an Apple silicon Mac with 5 CPUs assigned to Docker, the image build took about 6 minutes and the model download took under a minute.
If you see docker: unknown command: docker compose, the Compose plugin isn’t installed. If you have the standalone version, replace docker compose with docker-compose in each command.
Check readiness
status should be ready, and every component’s status should be ok:
Compose reports the service healthy only once the API, the embedding model, the reranker model, and the demo document are all ready. If a model download hits a missing file, a size or checksum mismatch, a symbolic link, or a download error, it fails outright rather than starting with incomplete models.
Run a reranked query
The response should include content from quickstart-demo.txt and a numeric rerank_score. Here is a real response, with metadata shortened:
Identifiers, latency, and scores will differ on your machine.
Stop or reset
To stop the service and keep your data and the downloaded models:
To remove the data and models as well:
--volumes deletes the cortrix-data volume. The next start downloads about 1.17 GB of models again.
What this path verifies
The quickstart:
- Builds the local Docker image from the checked-out source.
- Downloads pinned versions of the BGE-M3 embedding model and the bge-reranker-v2-m3 reranker.
- Publishes only the API, at
127.0.0.1:8420. The metrics port and the built-in Agent port aren’t published. - Keeps every external LLM role and the built-in Agent turned off.
- Sends a query with a plural
namespacesarray andrerank=true, and gets back source-backed demo content with numeric rerank scores.
It does not cover PDF, DOCX, images, OCR, authentication, internet-facing deployment, or retrieval-quality benchmarks, and it doesn’t establish production readiness.
The quickstart service has no authentication. By default Compose publishes it only on the host’s loopback address, so other machines can’t reach it. Don’t treat it as an internet-facing deployment.
Model provenance and integrity
deploy/model-manifest.tsv in the repository pins the repository, revision, path, expected size, SHA-256, upstream repository, upstream revision, and upstream license for every downloaded file.
| Purpose | Model | Source |
|---|---|---|
| Embedding | onnx-community/bge-m3-ONNX | Derived from BAAI/bge-m3 |
| Reranking | onnx-community/bge-reranker-v2-m3-ONNX | Derived from BAAI/bge-reranker-v2-m3 |
At startup, Cortrix downloads each manifest entry, verifies its size and SHA-256, and installs it atomically. If anything doesn’t match, the service doesn’t report ready.
Next steps
- Core concepts: understand the namespace, blocks, and query you just used.
- Choose an access path: connect to the running service through MCP or the Python SDK.
- Compatibility and status: see the current status of every capability.
3 - Install with an AI agent
On this page you’ll get a task brief you can hand to a terminal-capable AI agent. The agent installs Cortrix v1.0.0-rc.2 on your machine, verifies it, and returns a structured report.
This path runs the same loopback-only Docker flow as the Quickstart. It’s a local first-value setup, not an internet-facing, cloud, security, or production deployment procedure.
Prerequisites
The AI agent needs to be able to use your local filesystem, Git, Docker, Docker Compose, and curl. It can be a coding assistant or a broader agent runtime. Whether it qualifies depends on those capabilities. This page doesn’t claim that every version or configuration of any particular product has been validated.
Contract identity
Both the release tag and the full commit it resolves to must be recorded. A checkout of the mutable main branch doesn’t satisfy this contract.
What the agent may do
- Inspect local prerequisites: Git, Docker, Docker Compose,
curl, disk, network, and ports. - Create one new installation directory.
- Clone the declared repository and check out the declared release.
- Build and start the documented Docker Compose stack.
- Download the pinned model files that stack needs.
- Call the readiness and query endpoints on the loopback address.
- Leave the verified local service running.
- Report the files, containers, volumes, and commands it used.
What the agent must not do
- Modify, reset, delete, or reuse an existing Cortrix checkout.
- Use
sudoor install system-level dependencies without separate approval from you. - Request, read, store, or invent keys for LLM, cloud, GitHub, or any other service.
- Change firewall, DNS, proxy, VPN, or system security settings.
- Publish Cortrix on
0.0.0.0or any non-loopback address. - Turn off ONNX, embedding, reranking, model checksums, readiness, or source verification to make the run pass.
- Delete existing Docker images, containers, caches, or volumes.
- Run
docker compose down --volumesunless you explicitly ask for it. - Describe this contract as a production deployment or as production readiness.
Copyable agent task
Give your AI agent this brief exactly as written. It’s contract text, so don’t reword it:
Required execution path
The agent must create a new cortrix directory under a parent directory you approve. If cortrix already exists there, it must stop rather than overwrite or reuse it.
The first start downloads about 1.17 GB of pinned model files and can take several minutes. No .env file, provider key, host-side model tooling, manual model download or conversion, or separate bootstrap command is required.
Required verification
Readiness:
A source-backed reranked query:
The result must contain content from quickstart-demo.txt and a numeric rerank_score. A process that exits successfully without those two assertions is still a failed contract.
Required final report
PASS requires all of these: the exact repository and release, the 40-character commit that the tag resolves to, a loopback-only bind, readiness, source content, numeric rerank scores, external LLM roles left off, and a running service.
Failure behavior
The agent must stop and return FAIL when:
- A prerequisite is missing.
- The target directory already exists.
- The tag or commit doesn’t match what was expected.
- The API port is in use.
- The Docker build, a download, an integrity check, startup, or readiness fails.
- The query fails or lacks the required source content.
rerank_scoreis absent or isn’t numeric.- The service binds beyond the loopback address.
- Finishing the task would require a prohibited action.
The report must preserve the original error and name the next decision you need to make. The agent must not quietly switch to a different build profile or to weaker verification.
Stop or reset
After you’ve reviewed the report, you can ask the agent to stop the service:
Removing the cached models and local data is a separate, destructive decision that’s yours to make:
The agent must not run the cleanup command with --volumes unless you explicitly ask for it.
What this path doesn’t verify
An agent-assisted install doesn’t verify every HTTP API, parser, the built-in Agent, MCP, the SDK, authentication, tenants, security, benchmarks, or production behavior. Before you expand the deployment, read Compatibility and status and Choose an access path.
Next steps
- Quickstart: run the same flow yourself.
- Choose an access path
- Compatibility and status
4 - 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] --> BLKDocuments 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.