Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Get started

Start Cortrix locally and run your first query.

Go from a machine with only Git and Docker to a local Cortrix you can query.

1 - Overview

What Cortrix is, what it’s made of, and where it stands today.

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.

Important

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:

NeedWhat it means
Agent workflowsAn agent needs to read source material, use tools, and keep track of what happened
Context for a taskA 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 tasksSome 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 blockWhat it covers
Semantic Processing Chain (SPC)Parsing, OCR fallback, chunking, enrichment, embedding, and indexing
Hybrid query and rerankerVector search, BM25, rank fusion, and reranking
AI interaction memoryMemory APIs and typed memory records
Agent observabilitySession, trace, and agent identity
Source-level traceabilityInspectable source context across chunks, documents, and turns
Namespaces and cross-namespace queryLogical query scope for projects and workflows
Local embeddingONNX Runtime and BGE-M3
Access pathsHTTP, MCP, the Python SDK, framework adapters, data import, and PostgreSQL
Note

A namespace is a logical query scope. It is not an authentication, authorization, access-control, or tenant-security boundary.

Components in the repository

ComponentLocationRole
cortrix-serversrc/The C++ backend and HTTP API
OpenAPI specapi/openapi.yamlThe public HTTP API contract
MCP servercortrix-mcp/An MCP server for IDE and agent clients
Python SDKsdk/python/The Python client
Built-in Agentcortrix-agent/A fixed-flow RAG chat service
Web UIweb/The local web interface

Access paths

PathBest for
HTTP APIYour own services, or direct calls from an agent
MCP serverIDE agents and MCP-compatible clients
Python SDKPython applications and RAG pipelines
Built-in AgentLocal 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

2 - Quickstart

Start Cortrix locally with Docker and run your first query.

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

git clone --branch v1.0.0-rc.2 --depth 1 \
  https://github.com/cortrix/cortrix.git
cd cortrix
CORTRIX_SOURCE_REVISION="$(git rev-parse HEAD)" \
  docker compose -f deploy/docker-compose.yml up --build --wait

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:

 Container deploy-cortrix-1 Started
 Container deploy-cortrix-1 Waiting
 Container deploy-cortrix-1 Healthy
Note

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.

Tip

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

curl -fsS http://127.0.0.1:8420/api/v1/system/health/ready

status should be ready, and every component’s status should be ok:

{
  "components": {
    "catalog": { "catalog_db_open": true, "status": "ok" },
    "disk": { "stage": "warn", "status": "ok" },
    "embedding_execution_provider": {
      "active_ep": "cpu",
      "configured_ep": "cpu",
      "fallback": false,
      "model_configured": true,
      "policy_mismatch": false,
      "preferred_ep": "cpu",
      "status": "ok"
    },
    "quickstart_demo": { "proof_file_present": true, "status": "ok" },
    "reranker_execution_provider": {
      "active_ep": "cpu",
      "configured_ep": "cpu",
      "fallback": false,
      "model_configured": true,
      "policy_mismatch": false,
      "preferred_ep": "cpu",
      "status": "ok"
    },
    "secret_provider": { "provider_type": "env", "status": "ok" },
    "spc_pipeline": { "queue_depth": 0, "status": "ok", "workers": 2 }
  },
  "status": "ready",
  "version": "1.0.0-rc.2"
}

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

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["demo"],
    "query": "What does semantic storage keep close to the agents that need it?",
    "top_k": 5,
    "rerank": true
  }' \
  http://127.0.0.1:8420/api/v1/query

The response should include content from quickstart-demo.txt and a numeric rerank_score. Here is a real response, with metadata shortened:

{
  "meta": {
    "coverage_ratio": 1.0,
    "crag_verdict": "incorrect",
    "deduplicated_chunks": [],
    "deduplicated_chunks_count": 0,
    "latency_ms": 367,
    "namespaces_failed": [],
    "namespaces_queried": ["demo"],
    "namespaces_succeeded": ["demo"],
    "warnings": []
  },
  "results": [
    {
      "child_id": "01M409ADX4M34WZD0EWVRYEMQJ",
      "content": "Cortrix QuickStart demo\nCortrix provides semantic storage for agentic applications. In this demo,\nsemantic storage keeps durable context close to the agents that need it.\nThe local embedding model finds relevant passages, and the local reranker\norders those passages without sending the document or query to an LLM service.",
      "metadata": {
        "source_path": "quickstart-demo.txt",
        "mime_type": "text/plain"
      },
      "namespace": "demo",
      "rerank_score": 0.9929662942886353,
      "score": 0.01666666753590107
    }
  ]
}

Identifiers, latency, and scores will differ on your machine.

Stop or reset

To stop the service and keep your data and the downloaded models:

docker compose -f deploy/docker-compose.yml down

To remove the data and models as well:

docker compose -f deploy/docker-compose.yml down --volumes
Warning

--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 namespaces array and rerank=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.

Important

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.

PurposeModelSource
Embeddingonnx-community/bge-m3-ONNXDerived from BAAI/bge-m3
Rerankingonnx-community/bge-reranker-v2-m3-ONNXDerived 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

3 - Install with an AI agent

Hand setup and verification to a terminal-capable 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

Contract: cortrix-agent-quickstart/v1
Repository: https://github.com/cortrix/cortrix.git
Release: v1.0.0-rc.2
Commit: resolve and record the full commit referenced by the release tag
API bind: 127.0.0.1:8420

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 sudo or 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.0 or 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 --volumes unless 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:

Agent task
Install Cortrix locally under the cortrix-agent-quickstart/v1 contract.

Use only this repository and installation target:
- Repository: https://github.com/cortrix/cortrix.git
- Release: v1.0.0-rc.2
- Resolved commit: record the full commit from the exact release tag

Work in a new local directory. Do not modify, reset, delete, or reuse an
existing Cortrix checkout.

Before changing local state, verify that Git, Docker, Docker Compose, and curl
are available. Report available disk space, confirm that the required network
access is available, and check that 127.0.0.1:8420 is not already reserved by
another service. If a prerequisite is missing or the target directory already
exists, stop and report the blocker. Do not use sudo or install system-level
dependencies without asking me.

Clone the exact release, verify the origin URL, verify the exact tag, and record the full commit resolved by that tag. Start only the documented loopback Docker Compose path with CORTRIX_SOURCE_REVISION set to the checked-out commit.

Do not request or use any LLM or cloud provider key. Do not change firewall,
DNS, proxy, VPN, or system security settings. Do not expose a non-loopback
port. Do not disable ONNX, embedding, reranking, readiness, source checks, or
model integrity checks.

Wait until Docker Compose reports the service ready. Call the readiness
endpoint, then run the documented demo query with rerank=true. Verify that the
response contains source-backed quickstart-demo.txt content and numeric
rerank_score values.

Leave the verified service running. Do not delete volumes. Finish with the
exact report schema in this contract and mark the overall result PASS only when
every required assertion passes.

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.

git clone --branch v1.0.0-rc.2 --depth 1 \
  https://github.com/cortrix/cortrix.git cortrix
cd cortrix
test "$(git remote get-url origin)" = "https://github.com/cortrix/cortrix.git"
test "$(git describe --tags --exact-match)" = "v1.0.0-rc.2"
CORTRIX_SOURCE_REVISION="$(git rev-parse HEAD)"
test "$(printf '%s' "$CORTRIX_SOURCE_REVISION" | wc -c | tr -d ' ')" = "40"
CORTRIX_SOURCE_REVISION="$CORTRIX_SOURCE_REVISION" \
  docker compose -f deploy/docker-compose.yml up --build --wait

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:

curl -fsS http://127.0.0.1:8420/api/v1/system/health/ready

A source-backed reranked query:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["demo"],
    "query": "What does semantic storage keep close to the agents that need it?",
    "top_k": 5,
    "rerank": true
  }' \
  http://127.0.0.1:8420/api/v1/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

Report format
CORTRIX_AGENT_QUICKSTART=PASS|FAIL
contract=cortrix-agent-quickstart/v1
repository=https://github.com/cortrix/cortrix.git
release=v1.0.0-rc.2
commit=<observed full commit resolved by the exact release tag>
installation_directory=<absolute path>
platform=<os and architecture>
docker_version=<observed version>
docker_compose_version=<observed version>
available_disk=<observed value>
bind_address=127.0.0.1:8420
readiness=PASS|FAIL
source_content=PASS|FAIL
numeric_rerank_score=PASS|FAIL
external_llm_enabled=false
service_state=RUNNING|NOT_RUNNING
created_resources=<summary>
stop_command=docker compose -f deploy/docker-compose.yml down
destructive_cleanup_command=docker compose -f deploy/docker-compose.yml down --volumes
warnings=<none or exact warnings>
blocker=<none or exact blocker>

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_score is 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:

docker compose -f deploy/docker-compose.yml down

Removing the cached models and local data is a separate, destructive decision that’s yours to make:

docker compose -f deploy/docker-compose.yml down --volumes
Warning

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

4 - Core concepts

Namespaces, documents, blocks, queries, and memory.

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:

{
  "query": "How should an agent recover from an expired setup token?",
  "namespaces": ["your_namespace"],
  "top_k": 5,
  "rerank": true,
  "include_sources": true
}
Warning

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, and enricher_llm are 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.

Next steps