Skip to content

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

Return to the regular view of this page.

Documentation

Start Cortrix, connect your agent or application, and look up exact interface behavior.

New to Cortrix? Start with Get started. If Cortrix is already running, jump to the task you have in mind.

1 - 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.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

1.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

1.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

1.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

2 - Guides

Upload documents, run queries, and work with memory, task by task.

Each guide covers one task, with commands you can copy and the output to expect.

2.1 - Upload documents

Write documents into a namespace and track their processing.

On this page you’ll create a namespace, upload documents in two different ways, confirm they’ve been processed, and learn how to delete one.

Note

The output on this page is real output from v1.0.0-rc.2. It differs from the OpenAPI spec in several places: upload results use the statuses pending and skipped where the spec lists queued, updating, and unchanged; a finished task reports completed where the spec says ready; source_type can be file, which isn’t in the spec’s list; timestamps are epoch milliseconds; and the validation error shown at the end has a code, request_id, and timestamp that don’t match the spec’s patterns. Write client code against what the server returns, and recheck after an upgrade.

Prerequisites

  • A running Cortrix service. See the Quickstart.
  • curl.

The examples target the service the quickstart starts, which has no authentication. When you connect to a service with authentication turned on, send the X-API-Key header with each request.

Two ways to upload

File uploadInline upload
EndpointPOST /api/v1/namespaces/{ns}/documentsPOST /api/v1/documents
Request bodymultipart/form-dataJSON
Best forUploading a file, including binary filesText your program already has in memory
ReturnsA doc_id right awayA task_id; processing is asynchronous
If the namespace doesn’t exist404 right awayThe request is accepted and the task fails later

Either way, the content goes through the same pipeline: parsing, chunking, embedding, and indexing.

Steps

Create a namespace

curl -fsS -H 'Content-Type: application/json' \
  -d '{"name": "guide", "display_name": "Guide"}' \
  http://127.0.0.1:8420/api/v1/namespaces
{
  "block_count": 0,
  "created_at": 1791069436679,
  "doc_count": 0,
  "name": "guide",
  "namespace": "guide",
  "status": "active",
  "updated_at": 1791069436679
}

Upload a file

First create a text file:

printf 'Refund policy\n\nCustomers can request a refund within 30 days of purchase.\nRefunds are issued to the original payment method within 5 business days.\n' \
  > refund-policy.txt

Upload it as multipart. file is required. title and metadata (a JSON string) are optional:

curl -fsS \
  -F 'file=@refund-policy.txt' \
  -F 'title=Refund policy' \
  http://127.0.0.1:8420/api/v1/namespaces/guide/documents
{
  "content_hash": "4cae8f4fef140499f28815e2372a3027b5dbb2634e14e7766bf609011f56545a",
  "doc_id": "01M420XEVFXR2YE9NZ6E49X8M7",
  "message": "Document uploaded successfully, processing queued",
  "source_path": "refund-policy.txt",
  "status": "pending"
}

Uploading a file with the same content again doesn’t reprocess it. Cortrix detects the duplicate by content hash and returns HTTP 200 with the same doc_id:

{
  "content_hash": "4cae8f4fef140499f28815e2372a3027b5dbb2634e14e7766bf609011f56545a",
  "doc_id": "01M420XEVFXR2YE9NZ6E49X8M7",
  "message": "Document unchanged, skipping reprocessing",
  "source_path": "refund-policy.txt",
  "status": "skipped"
}

Upload inline content

namespace and content are required. filename and metadata are optional:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespace": "guide",
    "content": "Shipping policy. Orders ship within 2 business days. Express shipping is available at checkout.",
    "filename": "shipping-policy.txt"
  }' \
  http://127.0.0.1:8420/api/v1/documents

The service returns HTTP 202 and a task:

{
  "namespace": "guide",
  "status": "queued",
  "task_id": "01M420XEVZMH2RRDH2CCZ4R8BE"
}

Check task progress

Look up the task with the task_id from the previous step:

curl -fsS http://127.0.0.1:8420/api/v1/documents/tasks/01M420XEVZMH2RRDH2CCZ4R8BE/progress
{
  "doc_id": "01M420XEVZMH2RRDH2CCZ4R8BC",
  "error_code": null,
  "error_msg": null,
  "meta": {
    "agent_decision_hint": "done_fetch_doc",
    "current_phase": "parsing",
    "retryable_if_fail": true
  },
  "processed_pages": 1,
  "progress_pct": 100.0,
  "status": "completed",
  "task_id": "01M420XEVZMH2RRDH2CCZ4R8BE",
  "total_pages": 1
}

A status of completed with error_code set to null means processing succeeded. meta.agent_decision_hint tells an agent what to do next.

Warning

An inline upload returns 202 even when the namespace doesn’t exist. The error shows up only in the task progress: error_code is CX_ERR_SPC_PROCESS_FAILED and meta.agent_decision_hint is inspect_error_code. So always check task progress after an inline upload. Don’t rely on the upload request succeeding.

Confirm the documents are ready

curl -fsS 'http://127.0.0.1:8420/api/v1/documents?namespace=guide'
{
  "documents": [
    {
      "document_id": "01M420XEVZMH2RRDH2CCZ4R8BC",
      "filename": "shipping-policy.txt",
      "namespace": "guide",
      "source_type": "file",
      "status": "ready"
    },
    {
      "document_id": "01M420XEVFXR2YE9NZ6E49X8M7",
      "filename": "refund-policy.txt",
      "namespace": "guide",
      "source_type": "http_upload",
      "status": "ready"
    }
  ],
  "total": 2
}

Queries can find a document once its status is ready. The list supports paging with limit (default 50, maximum 200) and offset.

Get a single document

Documents are stored per namespace, so pass namespace when you fetch one:

curl -fsS 'http://127.0.0.1:8420/api/v1/documents/01M420XEVFXR2YE9NZ6E49X8M7?namespace=guide'

Delete a document

curl -fsS -X DELETE \
  'http://127.0.0.1:8420/api/v1/documents/01M420XEVZMH2RRDH2CCZ4R8BC?namespace=guide'

A successful delete returns HTTP 204 with no body. The document and all of its blocks disappear from the list and from query results.

This is a soft delete: the document can still be restored during a retention period set by gc.soft_delete_retention_days. The default is 30 days, and 0 means delete immediately. After the retention period, garbage collection removes it permanently.

Batch submit

POST /api/v1/documents/batch submits 1 to 100 documents to one namespace in a single request. Each accepted document becomes an asynchronous task.

This endpoint uses partial-success semantics: it returns HTTP 200 even if some documents fail. Accepted documents are in results[], failures are in meta.failed[], and every failure carries structured error fields.

For the full request and response shapes, see the HTTP API reference.

When something goes wrong

Error responses share one structure, so you can decide whether to retry from retryable and category. For example, creating a namespace without name:

{
  "error": {
    "category": "permanent",
    "code": "INVALID_ARGUMENT",
    "message": "Missing 'name' field",
    "request_id": "571fa754f07d1413ef27cf5af3cb0367",
    "retry_after_ms": null,
    "retryable": false,
    "structured_data": {},
    "timestamp": "2026-10-03T23:17:05.349Z"
  }
}

Next steps

2.2 - Query and rerank

Run hybrid retrieval over one or more namespaces, with reranking.

On this page you’ll query one namespace and then several, learn to read the scores and metadata in a response, and see what to do when part of a query fails.

Prerequisites

  • A running Cortrix service. See the Quickstart.
  • A namespace with processed documents. This page reuses the guide namespace from Upload documents.

Run a query

Every query goes through one endpoint, POST /api/v1/query. query and namespaces are required:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide"],
    "query": "How long do refunds take?",
    "top_k": 3,
    "rerank": true
  }' \
  http://127.0.0.1:8420/api/v1/query

The response has two parts, meta and results. Only the key fields of results are shown here:

{
  "meta": {
    "coverage_ratio": 1.0,
    "latency_ms": 222,
    "namespaces_failed": [],
    "namespaces_queried": ["guide"],
    "namespaces_succeeded": ["guide"],
    "warnings": []
  },
  "results": [
    {
      "content": "Refund policy\nCustomers can request a refund within 30 days of purchase. ...",
      "metadata": { "source_path": "refund-policy.txt" },
      "namespace": "guide",
      "rerank_score": 0.824,
      "score": 0.0167
    },
    {
      "content": "Shipping policy. Orders ship within 2 business days. ...",
      "metadata": { "source_path": "shipping-policy.txt" },
      "namespace": "guide",
      "rerank_score": 0.0,
      "score": 0.0164
    }
  ]
}

The refund policy, which is relevant to the question, comes first with a rerank score of 0.824. The unrelated shipping policy gets a rerank score of 0.

Request parameters

ParameterTypeDefaultDescription
querystringRequiredThe query text
namespacesstring arrayRequiredThe namespaces to search
top_kinteger10How many results to return. The minimum is 1
rerankbooleantrueWhether to reorder candidates with the reranker model
include_sourcesboolean—When true, results include source information
filterobject—Filter conditions

For the full request shape, see the HTTP API reference.

Warning

Use the plural namespaces array. A singular namespace is rejected:

{
  "error": {
    "category": "permanent",
    "code": "CX_ERR_DEPRECATED_FIELD",
    "message": "Field 'namespace' is deprecated, use 'namespaces' array instead",
    "retryable": false,
    "structured_data": { "deprecated_field": "namespace", "use_instead": "namespaces" }
  }
}

Read the results

Each result is a block:

FieldMeaning
contentThe block’s text
namespaceThe namespace the block belongs to
metadata.source_pathThe original filename of the source document
rerank_scoreThe relevance score from the reranker model
scoreThe score after fusing the retrieval paths

Use rerank_score to judge whether a result is relevant to the question. score is the fused score used for ordering. Its values are small and aren’t a good absolute measure of relevance.

Query across namespaces

List several namespaces in namespaces, and the results are merged into one ranked list:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide", "demo"],
    "query": "How long do refunds take?",
    "top_k": 3
  }' \
  http://127.0.0.1:8420/api/v1/query

Each result’s namespace field tells you where it came from. Use ["*"] to query every namespace you have access to, up to 100.

Handle partial failure

When you query across namespaces, the request still returns HTTP 200 even if some namespaces fail. Check meta to see whether the result is complete:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespaces": ["guide", "nope"], "query": "refunds", "top_k": 2}' \
  http://127.0.0.1:8420/api/v1/query

Here nope doesn’t exist, and the response meta looks like this. Note that a missing or misspelled namespace is reported as CX_ERR_INDEX_CORRUPT, not as a not-found error:

{
  "coverage_ratio": 0.5,
  "namespaces_failed": [
    {
      "category": "permanent",
      "error_code": "CX_ERR_INDEX_CORRUPT",
      "message": "CX_ERR_INDEX_CORRUPT",
      "namespace": "nope",
      "retry_after_ms": null,
      "retryable": false,
      "structured_data": { "index_state": "unavailable", "namespace": "nope" }
    }
  ],
  "namespaces_queried": ["guide", "nope"],
  "namespaces_succeeded": ["guide"]
}
Important

Don’t judge completeness from the HTTP status code alone. A coverage_ratio below 1 means the results cover only some of the namespaces. Every entry in namespaces_failed carries retryable and category, which you can use to decide whether to retry.

Turn off reranking

Set rerank to false to skip reranking:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide"],
    "query": "How long do refunds take?",
    "top_k": 3,
    "rerank": false
  }' \
  http://127.0.0.1:8420/api/v1/query

In testing, the response still carried a rerank_score field with reranking off, but with completely different values. In the example above, the first result went from 0.824 to 0.033. Don’t compare scores across the two modes.

The response also carries a CX_WARN_RERANK_DISABLED warning.

For when reranking helps and when it doesn’t, see When to rerank.

Check for degraded results

meta.warnings is an array of JSON objects with string fields code, reason, and category; some entries also include an integer retry_after_ms in milliseconds. These warnings don’t change the HTTP status: the response still returns HTTP 200 with results.

For example, a request with "rerank": false adds this entry to meta.warnings:

{"code":"CX_WARN_RERANK_DISABLED","reason":"rerank_disabled","category":"permanent"}
CodeWhen it appearsreasoncategoryretry_after_msWhat to do
CX_WARN_RERANK_DISABLEDThe request sets "rerank": false. Ordering uses the fused retrieval score instead of the reranker model.rerank_disabledpermanent—Expected when you asked for it. Don’t retry. Set rerank to true or omit it if you want reranked order.
CX_WARN_LLM_RERANK_DEGRADEDThe request sets "llm_rerank": true, a query-time LLM is configured, and there are at least two results. LLM calls fail, time out, or return unusable rankings, leaving a window without any usable vote.llm_rerank_degradedtransient1000Results are usable and keep their order from before LLM reranking, never a partial LLM order. If LLM ordering matters, wait retry_after_ms and send the same request again.
CX_WARN_RAG_FUSION_DEGRADEDThe request sets "rag_fusion": true, a query-time LLM is configured, the query takes the multi-query path, and the LLM call that generates query variants fails.rag_fusion_degradedtransient5000Results are usable but come from the original query alone, without variants. To get fused results, wait retry_after_ms and retry.

The two LLM warnings report a failure of a step that ran. A missing warning doesn’t prove the step ran. To confirm, use ?explain=true and look for llm_rerank or rag_fusion under explain.llm_dependent_features; each key is present only when that step ran.

See how a query ran

Add ?explain=true and the response gains an explain section describing the path the query took:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespaces": ["guide"], "query": "How long do refunds take?", "top_k": 1}' \
  'http://127.0.0.1:8420/api/v1/query?explain=true'
{
  "complexity_score": 0.8999999761581421,
  "granularity": "auto",
  "query": "How long do refunds take?",
  "routing_path": "simple",
  "rrf_path_counts": { "dense": 1, "fts5": 1 },
  "via_path_counts": { "chunk": 1 }
}

The output is shortened. The full object has more fields, including ns_id, routing_decision_source, crag_verdict, crag_score, and llm_dependent_features.

rrf_path_counts shows that this query used both vector search (dense) and full-text search (fts5), and that the two result sets were then fused and ranked.

Next steps

2.3 - Work with memory

Write, list, edit, and delete memories.

On this page you’ll write memories explicitly through the API, then list, edit, and delete them.

Note

The output on this page is real output from v1.0.0-rc.2. It differs from the OpenAPI spec in several places: a memory’s status is active where the spec lists valid and invalidated; the default page_size is 50 where the spec says 20; and the responses to editing and deleting a memory have a different shape, and need an ns parameter the spec doesn’t declare.

Prerequisites

  • A running Cortrix service. See the Quickstart.
  • A namespace to hold the memories. This page uses assistant:
curl -fsS -H 'Content-Type: application/json' \
  -d '{"name": "assistant", "display_name": "Assistant memory"}' \
  http://127.0.0.1:8420/api/v1/namespaces

Memory types

TypeMeaning
factA fact
preferenceA preference
eventAn event. Event memories decay over time, while facts and preferences don’t

Write a memory

namespace, content, and memory_type are required. metadata is optional:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespace": "assistant",
    "content": "User preference: use Markdown for report format",
    "memory_type": "preference"
  }' \
  http://127.0.0.1:8420/api/v1/memory
{ "memory_id": "01M421CJRVM3KE0VYK5V8Y0753", "status": "active" }

A memory written this way is an explicit memory. It isn’t validated by an LLM.

List memories

curl -fsS 'http://127.0.0.1:8420/api/v1/memory?namespace=assistant'
{
  "memories": [
    {
      "content": "User preference: use Markdown for report format",
      "extracted_at": 1791069932315,
      "memory_id": "01M421CJRVM3KE0VYK5V8Y0753",
      "memory_type": "preference",
      "status": "active"
    }
  ],
  "page": 0,
  "page_size": 50,
  "total": 1
}

Query parameters:

ParameterDescription
namespaceRequired
memory_typeList only one type: fact, preference, or event
include_invalidatedWhen true, also return invalidated memories. The default is false
limit, offsetPaging

Edit a memory

An edit doesn’t overwrite the original. Cortrix creates a new memory and marks the old one invalidated:

curl -fsS -X PATCH -H 'Content-Type: application/json' \
  -d '{
    "ns": "assistant",
    "content": "User preference: use Markdown for reports and include a summary table"
  }' \
  http://127.0.0.1:8420/api/v1/memory/01M421CJRVM3KE0VYK5V8Y0753
{
  "invalidated_memory_id": "01M421CJRVM3KE0VYK5V8Y0753",
  "new_memory_id": "01M421CWYEK961J68WZ9KTNVS6"
}
Warning

The edit request body must include both ns and content, or the request returns 400 ns + content are required. The OpenAPI spec doesn’t list ns in this endpoint’s request body, so this page follows the tested behavior.

Delete a memory

Deleting a memory is a soft delete. The memory is marked invalidated, but it’s always kept and never physically removed. Pass the namespace as the ns query parameter:

curl -fsS -X DELETE \
  'http://127.0.0.1:8420/api/v1/memory/01M421CJTK0AQ19B9W4ZMWB3S4?ns=assistant'
{ "block_id": "01M421CJTK0AQ19B9W4ZMWB3S4", "status": "invalidated" }

Invalidated memories don’t appear in the list by default. Add include_invalidated=true to see them:

curl -fsS 'http://127.0.0.1:8420/api/v1/memory?namespace=assistant&include_invalidated=true'

Sessions

A memory session groups a set of conversation turns. namespace is required when you create one:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespace": "assistant", "user_id": "user_001"}' \
  http://127.0.0.1:8420/api/v1/memory/sessions
{
  "created_at": "2026-10-03T23:25:59.267Z",
  "namespace": "assistant",
  "session_id": "90fbdf71-f7dd-4a7a-a46b-5eac344871f2",
  "title": "",
  "user_id": "user_001"
}

To write a turn to a session, use POST /api/v1/memory/sessions/{session_id}/interactions. namespace, query_text, and response_text are required.

In development

CapabilityStatus
Automatic memory extraction from conversationsIn development. Not supported yet
Automatic handling of contradicting memoriesIn development. Not supported yet

Known limitation

POST /api/v1/memory/search requires query, namespace, and user_id. In testing, it didn’t return memories written explicitly through POST /api/v1/memory, and a regular query against the same namespace didn’t return them either. To read explicit memories, use the list endpoint above.

Next steps

2.4 - Watch a directory

Have Cortrix track file changes in a directory on the server.

On this page you’ll have Cortrix watch a directory: files already in it are imported into a namespace you choose, and files you add later are imported automatically.

Prerequisites

  • A running Cortrix service. See the Quickstart.
  • The directory must be on a filesystem the Cortrix server process can reach. When Cortrix runs in Docker, that means a path inside the container, not a path on the host.

The examples use a directory under the /data volume inside the container. To watch a directory on the host, mount it into the container first.

Steps

Prepare a directory and a namespace

Create a directory in the container and put a file in it. You can find the container name with docker ps:

docker exec deploy-cortrix-1 sh -c \
  'mkdir -p /data/watch-demo && echo "Onboarding checklist. New hires receive a laptop on day one and complete security training in week one." > /data/watch-demo/onboarding.txt'

Create the namespace that receives the files:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"name": "watched", "display_name": "Watched folder"}' \
  http://127.0.0.1:8420/api/v1/namespaces

Add a watcher

path and target_namespaces are required. recursive defaults to true, which includes subdirectories:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "path": "/data/watch-demo",
    "target_namespaces": ["watched"],
    "recursive": true
  }' \
  http://127.0.0.1:8420/api/v1/watch
{
  "id": "9a97d854",
  "path": "/data/watch-demo",
  "recursive": true,
  "status": "active",
  "target_namespaces": ["watched"]
}

target_namespaces can list several namespaces. Cortrix creates only one system-level watcher per directory and fans file changes out to every namespace subscribed to it.

Confirm existing files were imported

After a few seconds, list the documents in the namespace:

curl -fsS 'http://127.0.0.1:8420/api/v1/documents?namespace=watched'
{
  "documents": [
    {
      "document_id": "01M421DDBRNPRZKD50DNRYJR9V",
      "filename": "/data/watch-demo/onboarding.txt",
      "namespace": "watched",
      "source_ref": "/data/watch-demo",
      "source_type": "watch_dir",
      "status": "ready"
    }
  ],
  "total": 1
}

Documents that come from a watcher have a source_type of watch_dir, and filename is the file’s full path.

Confirm new files are imported automatically

Add another file to the directory:

docker exec deploy-cortrix-1 sh -c \
  'echo "Expense policy. Submit receipts within 14 days." > /data/watch-demo/expenses.txt'

After a few seconds, list the documents again. total is now 2, and the new file’s status is ready.

List and remove watchers

List all watchers:

curl -fsS http://127.0.0.1:8420/api/v1/watch

Remove a watcher, along with all of its namespace subscriptions:

curl -fsS -X DELETE http://127.0.0.1:8420/api/v1/watch/9a97d854

A successful removal returns HTTP 204.

Warning

Removing a watcher also deletes the documents it imported from that directory. If you want to keep them, don’t remove the watcher.

Known issue

The OpenAPI spec lists GET /api/v1/watch/{id}/events for reading a watcher’s event stream. In testing, this endpoint returned 404. It isn’t available in v1.0.0-rc.2.

Next steps

2.5 - Import from a database

Import data from a database into a namespace.
In development

In development. Not supported yet.

What to do instead

Until this capability is available, you can read the data from your database yourself, turn each row or group of rows into text, and write it with an inline upload or a batch submit.

Next steps

3 - Integrations

Connect Cortrix to your application, IDE, or agent.

Cortrix offers several access paths: the HTTP API, MCP, the Python SDK, framework adapters, and a built-in Agent.

3.1 - Choose an access path

Compare the HTTP API, MCP, the Python SDK, and the built-in Agent.

Cortrix has four access paths. This page helps you pick the one that fits your situation.

How to choose

Your situationChoose
You need precise control over requests, retries, authentication, and deployment, or you’re not using PythonHTTP API
You want an agent in your IDE, or another MCP-compatible client, to call CortrixMCP server
You’re writing a Python application, a RAG pipeline, or a test scriptPython SDK
You want local fixed-flow chat over what’s in Cortrix, without wiring up an agent frameworkBuilt-in Agent

HTTP API

Every other access path ends up calling the HTTP API. The contract is api/openapi.yaml in the repository. See the HTTP API reference for every endpoint.

Check that the service is ready:

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

Run a 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

When authentication is on, send your API key in the X-API-Key header.

MCP server

The MCP server exposes Cortrix’s HTTP API as a set of MCP tools covering health, query, upload, namespace management, memory, task status, directory watchers, and admin database import.

It supports local stdio transport only. There is no remote Streamable HTTP endpoint.

For setup, see MCP server.

Python SDK

The Python SDK provides a synchronous client, Cortrix, and an asynchronous client, AsyncCortrix. Both are fully typed and map the server’s structured errors to exceptions with fields.

It exposes resources for documents, namespaces, query, memory, directory watchers, authentication, tenants, system information, operations, and database import. For the status of each resource, see Python SDK.

For installation and usage, see Python SDK.

Built-in Agent

The built-in Agent is a FastAPI service that provides fixed-flow chat over Cortrix storage. It needs the agent_llm role configured, and it’s off by default in the quickstart.

Chat is the only mode.

See Built-in Agent.

Next steps

3.2 - MCP server

Let Claude Code, Cursor, and other MCP clients call Cortrix.

On this page you’ll install cortrix-mcp and connect it to an MCP client, so the agent in that client can query, upload documents, and manage memory.

cortrix-mcp exposes Cortrix’s HTTP API as 31 MCP tools: 29 regular tools and 2 admin tools. It talks HTTP directly to a running cortrix-server.

Prerequisites

  • A running Cortrix service. See the Quickstart.
  • Python 3.10 or later.
  • An MCP client that supports stdio transport.
Note

Only local stdio transport is supported. Cortrix doesn’t expose a remote or loopback Streamable HTTP MCP endpoint.

Install

Install the package from PyPI into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install cortrix-mcp

This gives you the cortrix-mcp command, which is the entry point for the MCP stdio server. Confirm the install:

pip list | grep -E '^(cortrix-mcp|mcp) '
cortrix-mcp               1.0.0rc2
mcp                       2.3.0
Note

Cortrix is in pre-release, so pip installs the latest pre-release, 1.0.0rc2. The Docker image cortrix/mcp isn’t published to a registry yet. To run the server in a container, build the image from cortrix-mcp/ in a clone of the repository.

Configuration

All configuration is passed through environment variables:

VariablePurposeDefault
CORTRIX_URLThe address of cortrix-serverhttp://127.0.0.1:8420
CORTRIX_NAMESPACEThe default namespacedefault
CORTRIX_API_KEYA Bearer token or API key for the target serverEmpty
CORTRIX_MCP_ADMINTurns on admin tools when the server accepts the caller as an adminfalse
CORTRIX_MCP_TIMEOUTHTTP timeout, in seconds30
CORTRIX_AGENT_IDThe agent identity sent as X-Agent-Id on every request. Allowed characters are [A-Za-z0-9_.:/-], up to 128 characters. An invalid value falls back to the defaultcortrix-mcp

The quickstart service has no authentication, so you don’t need CORTRIX_API_KEY. Its demo data lives in the demo namespace, so the examples below set the default namespace to demo.

Connect a client

Claude Code

Run this in your project directory. cortrix-mcp needs to be on your PATH. Otherwise, give the absolute path inside your virtual environment:

claude mcp add cortrix --scope project \
  --env CORTRIX_URL=http://127.0.0.1:8420 \
  --env CORTRIX_NAMESPACE=demo \
  -- cortrix-mcp
Added stdio MCP server cortrix with command: cortrix-mcp  to project config

This creates .mcp.json in the current directory:

.mcp.json
{
  "mcpServers": {
    "cortrix": {
      "type": "stdio",
      "command": "cortrix-mcp",
      "args": [],
      "env": {
        "CORTRIX_URL": "http://127.0.0.1:8420",
        "CORTRIX_NAMESPACE": "demo"
      }
    }
  }
}

Claude Code asks you to approve a project-scoped MCP server before using it. Start claude, approve cortrix, and then run /mcp to check the connection.

Tip

.mcp.json can contain absolute paths from your machine. The Cortrix repository’s .gitignore already ignores this file. Whether to commit it in your own project is up to you.

Cursor

Add this to ~/.cursor/mcp.json:

~/.cursor/mcp.json
{
  "mcpServers": {
    "cortrix": {
      "command": "cortrix-mcp",
      "env": {
        "CORTRIX_URL": "http://127.0.0.1:8420",
        "CORTRIX_NAMESPACE": "demo"
      }
    }
  }
}

Cline

Add this to cline_mcp_settings.json in your VS Code user directory:

cline_mcp_settings.json
{
  "mcpServers": {
    "cortrix": {
      "command": "cortrix-mcp",
      "env": {
        "CORTRIX_URL": "http://127.0.0.1:8420",
        "CORTRIX_NAMESPACE": "demo"
      },
      "disabled": false
    }
  }
}

Verify

Once connected, ask the agent to call cortrix_health. The result’s meta.category should be success:

{
  "data": { "status": "alive", "uptime_seconds": 195, "version": "1.0.0-rc.2" },
  "meta": {
    "retryable": false,
    "category": "success",
    "retry_after_ms": null,
    "structured_data": {
      "trace_id": "17912bb9-4f29-4a2f-9a35-e5ccd2ac28c8",
      "session_id": "mcp-session-da64d7e40fe9"
    }
  }
}

Then ask it to use cortrix_query to look up “What does semantic storage keep close to the agents that need it?”. It should return content from quickstart-demo.txt.

Tell the agent how to use Cortrix

Connecting the server gives the agent the tools. It doesn’t tell the agent which of your files are indexed, or that it should search them before it opens them. Add a short section like this to your project’s agent instructions, such as CLAUDE.md for Claude Code or AGENTS.md, and fill in the placeholders:

## Cortrix

The documents in <which files, for example "docs/ and design/"> are indexed in
Cortrix, namespace `<your-namespace>`. Search them through the `cortrix` MCP server.

- Before you open those files to answer a question, search with `cortrix_query`
  and pass `namespaces: ["<your-namespace>"]`. Start with the question itself, or
  the names and terms you need.
- Open a file only for what the hits leave open, and go to the files the hits point to.
- Cite from each hit's `metadata`: `doc_id`, `source_path`, and the fields this
  project sets at upload.

For the quickstart’s demo data, the namespace is demo.

When to turn off the agent’s own file tools

An agent that also has its own tools for reading and searching files, such as Claude Code’s Read, Grep and Glob, may search Cortrix and then keep opening files on its own. Each extra turn sends the whole conversation again, so a long answer can cost several times more. For a session that only answers questions from the indexed documents, start Claude Code without those tools:

claude --disallowedTools "Read Grep Glob"

Keep them on in a session that also edits code: Claude Code reads a file before it edits it.

Tools

GroupTools
Corecortrix_health, cortrix_query, cortrix_upload, cortrix_list_documents, cortrix_list_namespaces, cortrix_create_namespace, cortrix_memory_search, cortrix_log_interaction, cortrix_list_interactions, cortrix_document_status, cortrix_add_watcher, cortrix_list_watchers
Extendedcortrix_cross_ns_query, cortrix_async_upload, cortrix_memory_search_filter, cortrix_memory_extract_trigger
Tasks and explaincortrix_memory_extract, cortrix_task_status, cortrix_cancel_task, cortrix_query_explain
Memory and operationscortrix_memory_get_audit, cortrix_memory_revoke_fact, cortrix_memory_opt_out, cortrix_batch_submit, cortrix_list_operations, cortrix_memory_list, cortrix_memory_create, cortrix_memory_edit, cortrix_memory_invalidate
Admincortrix_admin_db_credential_register, cortrix_admin_db_import_run

For each tool’s parameters and status, see MCP tools.

Response schema

Every tool returns two layers: data holds the result, and meta tells the agent whether the call can be retried.

When a tool, the backend, authentication, a timeout, or validation fails, the result comes back with isError=true and keeps code, retryable, category, retry_after_ms, and structured_data.

The adapter defines 6 stable error codes of its own:

Error codeRetryableCategorySuggested wait (ms)
CX_ERR_MCP_BACKEND_TIMEOUTYestransient1000
CX_ERR_MCP_BACKEND_UNAVAILABLEYestransient5000
CX_ERR_MCP_SCHEMA_VALIDATION_FAILNopermanent—
CX_ERR_MCP_TOOL_NOT_FOUNDNopermanent—
CX_ERR_MCP_AUTH_MISSINGNoauth—
CX_ERR_MCP_ADMIN_REQUIREDNoauth—

Errors that come from cortrix-server itself pass through unchanged.

Trace a call

Every backend request carries X-Session-Id, a fresh X-Trace-Id, and X-Agent-Id. The server adopts these identifiers, so you can use the session_id in a tool’s meta.structured_data to look up the server-side trace directly:

curl -fsS http://127.0.0.1:8420/api/v1/traces/<session_id>

Protocol compatibility

  • The modern protocol 2026-07-28, through server/discover.
  • The legacy protocol 2025-11-25, through the initialize handshake.
  • Python dependency: mcp>=2.0.0,<3.0.0.

Next steps

3.3 - Python SDK

Use the Cortrix client in a Python application.

On this page you’ll install the Cortrix Python SDK, connect to a local Cortrix service, and run a query.

The SDK provides a synchronous client, Cortrix, and an asynchronous client, AsyncCortrix, both fully typed. Its runtime dependency is httpx, plus typing-extensions on Python versions before 3.12.

Prerequisites

  • A running Cortrix service. See the Quickstart.
  • Python 3.9 or later.

Install

Install the package from PyPI into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install cortrix

Confirm the installed version:

pip list | grep -E '^cortrix '
cortrix                   1.0.0rc2
Note

Cortrix is in pre-release, so pip installs the latest pre-release, 1.0.0rc2.

Your first query

Save this as check.py. It connects to the service the quickstart started and queries the demo namespace:

check.py
from cortrix import Cortrix

client = Cortrix(base_url="http://127.0.0.1:8420")

print(client.system.health())

results = client.search(
    "demo",
    "What does semantic storage keep close to the agents that need it?",
    top_k=5,
)
for item in results.results:
    print(round(item.rerank_score, 3), item.metadata["source_path"])
print(results.meta.coverage_ratio, results.meta.namespaces_succeeded)

client.close()

Run it:

python check.py
{'status': 'alive', 'uptime_seconds': 70, 'version': '1.0.0-rc.2'}
0.993 quickstart-demo.txt
1.0 ['demo']

The quickstart service has no authentication, so there’s no api_key here. To connect to a service that requires one, use Cortrix(base_url=..., api_key="your-cortrix-api-key").

Warning

If every call raises CortrixError with status code 502 while curl to the same address works, a system proxy is usually intercepting requests to your own machine. Bypass the proxy for local addresses and try again:

NO_PROXY=127.0.0.1,localhost python check.py

Client options

OptionPurpose
base_urlThe service address. Defaults to http://localhost:8420
api_keyAn API key. Optional
tenant_idA tenant identifier. Optional
timeoutThe request timeout
max_retriesThe maximum number of automatic retries
http_clientPass in your own httpx.Client
client_idSent as the X-Client-Id header to tell callers apart
trace_id_providerA function that returns a W3C traceparent, for distributed tracing

client.search() maps to POST /query. The first argument can be a single namespace, a list of namespaces, or ["*"] for all of them:

results = client.search(["contracts", "support_docs"], "refund policy", top_k=10)
ParameterDefaultPurpose
top_k10How many results to return
rerankTrueWhether to rerank
include_sourcesFalseWhether to return source information
filtersNoneFilter conditions

coverage_ratio, namespaces_succeeded, and namespaces_failed in results.meta tell you whether a cross-namespace query fully succeeded.

Upload documents

client.namespaces.create("contracts", display_name="Contracts")
task = client.documents.upload("contracts", "/path/to/contract.pdf")
print(task.task_id, task.status)

Uploads are processed asynchronously and return a task. Track it with client.documents.status() or client.documents.task_progress().

Async client

The async client mirrors the sync client exactly. Every resource method has an async counterpart:

import asyncio
from cortrix import AsyncCortrix

async def main():
    async with AsyncCortrix(base_url="http://127.0.0.1:8420") as client:
        return await client.search(["demo"], "semantic storage")

asyncio.run(main())

Resources

ResourceMethods
client.documentsupload, list, get, status, task_progress, cancel_task, delete
client.namespacescreate, list, get, update, delete, set_permission
client.search(...)Semantic query
client.memorysearch, log, list, create, update, delete
client.watchersadd, list, remove, events
client.systemhealth, version, namespace_stats, agent_llm_config
client.ops.gcstatus, run, restore, purge
client.import_database(...) In developmentStart a database import manually
client.tenants In developmentlist, get, invite, update_role, quota, create

Resources marked In development have no documentation yet.

Handle errors

Every exception derives from CortrixError and carries structured fields, so you can decide whether to retry or report:

from time import sleep
from cortrix import Cortrix, CortrixError, RateLimitError

client = Cortrix(base_url="http://127.0.0.1:8420")
try:
    client.documents.upload("docs", "report.pdf")
except RateLimitError as e:
    sleep((e.retry_after_ms or 1000) / 1000)
except CortrixError as e:
    if e.category == "transient" and e.retryable:
        ...  # retry
    elif e.category == "permanent":
        print(e.error_code, e.structured_data)
    else:
        raise

The SDK retries automatically using the server’s hints. To decide whether to retry, it looks at the retryable field first and then at the HTTP status code. For the wait time it uses retry_after_ms, then the Retry-After header, then exponential backoff. Adjust the number of attempts with max_retries.

Operations

Runtime and maintenance operations live under client.ops:

status = client.ops.gc.status()
client.ops.gc.restore(["doc_abc"])
Caution

client.ops.gc.run() and client.ops.gc.purge() are destructive. purge() deletes data permanently and can’t be undone.

Next steps

3.4 - Framework adapters

Use Cortrix from LangChain, Claude Tools, and OpenAI function calling.

On this page you’ll install cortrix-skills, call its tools directly, and turn them into tool definitions that Claude, OpenAI, or LangChain understand.

cortrix-skills provides a CortrixToolKit with 29 methods that map one-to-one to the MCP server’s regular tools, with the same names and semantics. Three adapters turn the toolkit into each framework’s native tool format, so you don’t write tool glue by hand. Admin tools are out of scope for this package.

Prerequisites

  • A running Cortrix service. See the Quickstart.
  • Python 3.9 or later, in a virtual environment.

Install

Install the package from PyPI. It brings in the Python SDK as a dependency:

pip install cortrix-skills
pip list | grep -E '^cortrix'
cortrix                   1.0.0rc2
cortrix-skills            1.0.0rc2

The framework SDKs are optional dependencies. Building Claude or OpenAI tool definitions needs no framework SDK at all, because the definitions are plain JSON. Install a framework’s package when you need it, for example pip install anthropic.

Call the tools directly

skills_check.py
from cortrix_skills import CortrixToolKit
from cortrix_skills.adapters import as_claude_tools, as_openai_functions

with CortrixToolKit(base_url="http://127.0.0.1:8420", default_namespace="demo") as kit:
    result = kit.cortrix_query(
        query="What does semantic storage keep close to the agents that need it?",
        top_k=3,
    )
    print(type(result).__name__, str(result)[:80])

    claude_tools = as_claude_tools(kit)
    print(len(claude_tools), claude_tools[0]["name"], sorted(claude_tools[0].keys()))
    print(len(as_openai_functions(kit)))
dict {'results': [{'child_id': '01M409ADX4M34WZD0EWVRYEMQJ', 'parent_id': '', 'co
29 cortrix_health ['description', 'input_schema', 'name']
29

CortrixToolKit is lazy: it makes no network request until you call a method.

ParameterDefaultDescription
base_url—Required unless you pass client
api_keyNoneA Cortrix API key
default_namespace"default"Used when a method doesn’t name a namespace
client—Pass in an existing cortrix.Cortrix client

Connect a framework

The three examples below come from cortrix-skills/README.md in the repository. They need a key for the matching LLM service, and the full round trip with a model hasn’t been tested for this page.

Claude Tools

from anthropic import Anthropic
from cortrix_skills import CortrixToolKit
from cortrix_skills.adapters import as_claude_tools
from cortrix_skills.adapters.claude import dispatch_claude_tool_use

kit = CortrixToolKit(base_url="http://127.0.0.1:8420", default_namespace="demo")
tools = as_claude_tools(kit)

client = Anthropic(api_key="your-anthropic-api-key")
resp = client.messages.create(
    model="claude-...", max_tokens=4096, tools=tools,
    messages=[{"role": "user", "content": "What does semantic storage keep close to agents?"}],
)
for block in resp.content:
    if block.type == "tool_use":
        tool_result = dispatch_claude_tool_use(kit, block)
        # append tool_result to the messages of the next messages.create(...) call

OpenAI function calling

from openai import OpenAI
from cortrix_skills import CortrixToolKit
from cortrix_skills.adapters import as_openai_functions
from cortrix_skills.adapters.openai import dispatch_openai_tool_call

kit = CortrixToolKit(base_url="http://127.0.0.1:8420", default_namespace="demo")
tools = as_openai_functions(kit)

client = OpenAI(api_key="your-openai-api-key")
resp = client.chat.completions.create(
    model="gpt-4o-mini", tools=tools,
    messages=[{"role": "user", "content": "What does semantic storage keep close to agents?"}],
)
for call in resp.choices[0].message.tool_calls or []:
    content = dispatch_openai_tool_call(kit, call)
    # content is a JSON string for a message with role "tool"

LangChain

pip install 'cortrix-skills[langchain]'
from cortrix_skills import CortrixToolKit
from cortrix_skills.adapters import as_langchain_tools

kit = CortrixToolKit(base_url="http://127.0.0.1:8420", default_namespace="demo")
tools = as_langchain_tools(kit)   # 29 StructuredTools

Error handling

Cortrix errors pass through unchanged from the Python SDK. This package adds no error codes of its own. Every error carries code, retryable, category, retry_after_ms, and structured_data, and each adapter surfaces them in its framework’s native shape:

FrameworkHow an error appears
LangChainA ToolException whose message is these fields as JSON
Claude ToolsA tool_result with is_error=True whose content is these fields as JSON
OpenAIThese fields as JSON, returned as the tool message content

An agent can use them to decide for itself whether to retry, wait, or report, without parsing free text.

Next steps

3.5 - Built-in Agent

Run the fixed-flow local chat service.

The built-in Agent is a FastAPI service that provides fixed-flow RAG chat over Cortrix storage. It queries cortrix-server through the public Python SDK and has no privileged channel:

Web UI chat -> Cortrix Agent (:8001) -> Python SDK -> cortrix-server (:8420)
                                    -> configured LLM provider
Note

The setup steps and interface details on this page come from cortrix-agent/README.md in the repository. The built-in Agent needs a working LLM service, and it hasn’t been tested for this page. The quickstart leaves the built-in Agent off by default.

Current scope

The built-in Agent has one mode: chat, a fixed RAG flow with no autonomous tool selection. It’s in preview.

Persisting configuration through PUT /config/agent_llm hasn’t been verified for this documentation.

Prerequisites

  • A running Cortrix service.
  • Python 3.
  • Credentials for an LLM service, for the agent_llm role.

Start the service

cd cortrix-agent
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
.venv/bin/uvicorn main:app --port 8001 --reload

Put your LLM service configuration in .env. Keep real keys only in ignored local files such as .env, and don’t commit them.

Health check

curl http://localhost:8001/health

The expected response shape:

{
  "status": "ready",
  "cortrix_server": "unknown",
  "llm_reachable": true
}

In v1.0.0-rc.2, cortrix_server is always "unknown": this endpoint doesn’t check the Cortrix server. Use the server’s own readiness endpoint for that. If llm_reachable is false, check the LLM service configuration.

Chat interface

POST /chat streams the answer over server-sent events:

curl -N -X POST 'http://localhost:8001/chat?explain=true' \
  -H 'Content-Type: application/json' \
  -H 'X-Cortrix-Namespace: default' \
  -d '{"message": "find privacy documents", "session_id": "s-001"}'
InputLocationNotes
messageRequest bodyThe user message
session_idRequest bodyAn optional session identifier
AuthorizationHeaderAn optional Bearer token, depending on the server’s authentication mode
X-Cortrix-Tenant-IdHeaderAn optional tenant identifier
X-Cortrix-NamespaceHeaderOptional. Names the namespace
explain=trueQuery parameterReturns extra explanation metadata
debug=trueQuery parameterReturns more detail on failure

Example SSE frames:

data: {"chunk": "Based on"}
data: {"chunk": " the retrieved documents..."}
data: {"meta": {"session_id": "s-001", "chunk_ids": [], "rag_status": "success"}}
data: [DONE]

Errors come back as structured SSE error events with a code, a message, retryability, a category, an optional retry delay, and structured data.

Other endpoints

EndpointPurpose
GET /sessions/{id}Returns the recent turns a session keeps in memory
GET /configReturns the current LLM configuration with the API key masked
GET /config/providersReturns the LLM provider catalog used by the configuration UI
PUT /config/agent_llmUpdates the LLM configuration. Persisting it isn’t a verified capability yet
GET /healthReturns service status, backend reachability, and LLM reachability

Next steps

3.6 - pgcortrix

Call Cortrix from PostgreSQL with SQL.
In development

In development. Not supported yet.

What to do instead

Call Cortrix from your application with the HTTP API or the Python SDK.

Next steps

4 - Deploy

Deploy, configure, and upgrade Cortrix.

For whoever runs Cortrix: deployment, configuration, models, and execution providers.

4.1 - Deploy with Docker Compose

Run Cortrix with the Compose file that ships in the repository, and manage its data.

The repository ships a Compose deployment. Here’s what it includes, how to check on it, where your data lives, and how to let other machines reach it.

If you haven’t started Cortrix yet, begin with the Quickstart.

Important

The bundled Compose deployment is built for local evaluation. It has no authentication and listens only on the loopback address by default. It isn’t an internet-facing production setup.

What’s included

ItemDetails
Compose filedeploy/docker-compose.yml
ImageBuilt from source with deploy/Dockerfile and tagged cortrix:quickstart
ServiceOne cortrix container running cortrix-server and the Web UI
Port127.0.0.1:8420, shared by the API and the Web UI
Volumecortrix-data, mounted at /data in the container
Execution providerCPU for both embedding and reranking
Off by defaultExternal LLM roles and the built-in Agent

The metrics port and the built-in Agent port aren’t published to the host.

Start and stop

CORTRIX_SOURCE_REVISION="$(git rev-parse HEAD)" \
  docker compose -f deploy/docker-compose.yml up --build --wait
docker compose -f deploy/docker-compose.yml down

down keeps the volume. On later starts you can drop --build to skip rebuilding the image.

Check status

docker compose -f deploy/docker-compose.yml ps
docker compose -f deploy/docker-compose.yml logs -f cortrix

Cortrix has three health endpoints:

EndpointWhat it tells you
/api/v1/system/health/liveWhether the process is alive
/api/v1/system/health/readyWhether the API, the models, and the demo data are all ready
/api/v1/healthA summary of each component
curl -fsS http://127.0.0.1:8420/api/v1/health
{
  "components": {
    "config": "ok",
    "logging": "ok",
    "namespace_manager": "ok",
    "parser": "disabled"
  },
  "llm_enabled": false,
  "status": "healthy",
  "version": "1.0.0-rc.2"
}

The container’s health check allows a 30-minute start period so the first start has time to download the models.

Web UI

The Web UI shares a port with the API. Once the service is up, open http://127.0.0.1:8420/ in your browser.

Where your data lives

All persistent data is in the cortrix-data volume: model files, databases, the vector index, and uploaded files. Docker prefixes the volume name with the Compose project name, so by default it’s deploy_cortrix-data.

docker volume inspect deploy_cortrix-data
Caution

docker compose down --volumes deletes this volume, along with all of your data and the downloaded models.

Let other machines connect

By default, nothing outside the host can reach the service. To open it up on an isolated test network you control, set CORTRIX_PUBLISH_HOST when you start it, and preferably pick an uncommon port:

CORTRIX_PUBLISH_HOST=10.0.0.5 CORTRIX_HTTP_PORT=18420 \
  docker compose -f deploy/docker-compose.yml up -d

Any machine that can route to that address can then reach the Web UI and API at http://10.0.0.5:18420/.

Warning

This path has no authentication. Anyone who can reach the address gets full API access. Use it only on an isolated test network you control, never on a shared corporate network, a cloud network with other tenants, or anything internet-facing.

Setting only the port, without CORTRIX_PUBLISH_HOST, doesn’t widen what the service listens on.

Admin endpoints

Admin endpoints accept requests only from the loopback address. In a Docker deployment, a request from the host doesn’t look like loopback to the container, so it gets 403 CX_ERR_ADMIN_LOOPBACK_REQUIRED. When you need an admin endpoint, send the request from inside the container:

docker compose -f deploy/docker-compose.yml exec cortrix \
  curl -fsS http://127.0.0.1:8420/api/v1/admin/db-connections

Next steps

4.2 - Configuration

How the configuration file is organized, the environment variables for Docker, and how to configure LLMs by role.

Cortrix can be configured in two ways. This page explains both and walks through the settings you’re most likely to change: authentication, logging, and LLM roles. For every key, see the configuration reference.

Two ways to configure

MethodUse it whenTemplate
YAML configuration fileYou build from source and run cortrix-server directlyconfig.yaml.example
Environment variablesYou deploy with Dockerdeploy/.env.example

When a setting appears in both places, the environment variable wins.

Configuration file

When you run from source, copy the template into the build directory:

cp config.yaml.example build/config.yaml

Environment variables

For a Docker deployment, copy the template to .env and edit what you need:

cp deploy/.env.example deploy/.env

Common variables:

VariableValue in the templatePurpose
CORTRIX_DATA_DIR/dataThe data directory
CORTRIX_HTTP_PORT8420The HTTP port
CORTRIX_LOG_LEVELinfoThe log level
CORTRIX_PROFILEquickstartquickstart is the default and is what the bundled Compose file uses. full provisions the embedding model and fails startup if it’s missing. lite explicitly turns off the embedding model and the parsers, and is for development only
CORTRIX_EMBEDDING_EXECUTION_PROVIDERautoThe execution provider for embedding
CORTRIX_RERANKER_EXECUTION_PROVIDERautoThe execution provider for reranking
CORTRIX_WEB_UI_ENABLEDtrueWhether the Web UI is on
CORTRIX_AGENT_ENABLEDtrueWhether the built-in Agent is on
Note

The deploy/docker-compose.yml used by the quickstart doesn’t need a .env file, and it keeps LLMs and the built-in Agent off. It reads only three variables from the environment or from deploy/.env: CORTRIX_PUBLISH_HOST, CORTRIX_HTTP_PORT, and CORTRIX_SOURCE_REVISION. Other settings in the file don’t reach the container.

Server

config.yaml
server:
  host: "127.0.0.1"
  port: 8420
  thread_count: 4

host defaults to the loopback address. Turn on authentication before you bind to a non-loopback address, or the server refuses to start.

There’s one exception, which the bundled Compose file relies on. Inside a container, the server can bind the container interface without authentication when CORTRIX_SERVER_ALLOW_UNAUTHENTICATED_CONTAINER_BIND is true, as long as the host port is published only to loopback.

Authentication

config.yaml
auth:
  enabled: false

Running without authentication is accepted only when the server binds to the loopback address. With authentication on, the configuration looks like this:

config.yaml
auth:
  enabled: true
  api_keys:
    - key_hash: "<SHA-256 of your key>"
      tenant_id: "default_tenant"  # must be an existing tenant; CE creates default_tenant
      permissions: 7           # READ=1, WRITE=2, ADMIN=4; 7 is all of them
      expires_at: 0            # 0 never expires

key_hash is the SHA-256 of the key. The configuration file never holds the key itself:

echo -n 'your-key' | shasum -a 256 | cut -d' ' -f1

Logging

config.yaml
log:
  level: "info"      # trace / debug / info / warn / error / critical / off
  format: "text"     # text for development, json for log collection
  output: "stdout"   # stdout / stderr / a file path

LLM roles

Cortrix splits its use of LLMs into five independent roles. You configure each role separately, and a feature stays off until its role is configured.

RoleUsed for
semantic_llmQuery-side semantic processing such as intent classification
vision_llmRefining image recognition after OCR. The model must accept image input
agent_llmChat in the built-in Agent
doc_summary_llmGenerating document summaries at ingest time
enricher_llmEnriching content at ingest time

None of these roles has anything to do with the local embedding and reranking models the quickstart uses. With no LLM role configured, embedding and reranking work as usual.

Every role takes the same four fields. A role counts as configured only when provider, api_key, and model are all set:

config.yaml
semantic_llm:
  provider: "openai"
  api_key: "your-api-key"
  model: "gpt-4o-mini"
  base_url: "https://api.openai.com/v1"

provider can be openai, glm, claude, ollama, deepseek, or mock.

Roles use two different protocols

RoleCalled byProtocol
agent_llmThe built-in Agent (Python)Each provider’s native protocol
The other fourcortrix-server (C++)OpenAI-compatible only. Requests go to {base_url}/chat/completions

That difference matters when you pick a provider. Take Claude as an example:

  • For agent_llm, connect directly and don’t set base_url:

    config.yaml
    agent_llm:
      provider: "claude"
      api_key: "your-api-key"
      model: "claude-haiku-4-5-20251001"
  • For the other four roles, go through an OpenAI-compatible proxy gateway and point base_url at it:

    config.yaml
    enricher_llm:
      provider: "claude"
      api_key: "your-api-key"
      model: "claude-haiku-4-5-20251001"
      base_url: "https://your-openai-compatible-proxy.example.com/v1"

OpenAI, GLM, DeepSeek, and a local OpenAI-compatible gateway work directly in every role.

Caution

Use placeholder values in documentation and examples. Keep real keys only in ignored local configuration files, and never commit them.

Next steps

4.3 - Models and ONNX

Where the bundled models come from, how they’re downloaded, and how their integrity is checked.

Cortrix runs two local models. Here’s where they come from, how they’re verified at startup, and where the files live.

Models

A Docker deployment downloads two families of local neural models into the cortrix-data volume. They aren’t baked into the image.

ModelRoleDownload sizePinned sourceUpstream and license
BGE-M3Embedding585,562,194 bytesonnx-community/bge-m3-ONNX@25b9af8BAAI/bge-m3@5617a9f, MIT
bge-reranker-v2-m3Reranking587,809,994 bytesonnx-community/bge-reranker-v2-m3-ONNX@6f5ff65BAAI/bge-reranker-v2-m3@953dc6f, Apache-2.0

The onnx-community repositories are format-conversion sources for the BAAI upstream revisions listed above. Cortrix doesn’t claim authorship of these models.

These models are independent of any LLM configuration. With no LLM role configured, embedding and reranking work as usual.

Model manifest

deploy/model-manifest.tsv is the authoritative, machine-readable record of model identity. For every model and tokenizer file it records:

  • The repository, revision, and file path
  • The expected byte size and SHA-256
  • The upstream repository, upstream revision, and upstream license

The manifest lists four files:

ComponentInstalled at
embedding_modelbge-m3/model.onnx
embedding_tokenizerbge-m3/tokenizer.json
reranker_modelbge-reranker-v2-m3/model.onnx
reranker_tokenizerbge-reranker-v2-m3/tokenizer.json

Download and verification at startup

On the first start, the container downloads the manifest’s files into /data/models. The downloader:

  1. Fetches the exact revision and path in the manifest.
  2. Rejects symbolic links.
  3. Checks the byte size and SHA-256.
  4. Installs each file atomically.

If anything doesn’t match, or a download fails, the container doesn’t report ready. Readiness also requires both models to finish loading and the demo data to finish importing. The quickstart never falls back silently to a stub embedder or reranker.

Later starts reuse the models already in the volume.

Start without access to Hugging Face

The first start downloads the model files from Hugging Face. On a machine that can’t reach it, copy the files in before the first start. The downloader verifies every file it finds in /data/models against the manifest and downloads only what is missing or doesn’t match, so a complete, valid copy means nothing is downloaded.

  1. On a machine where the quickstart has already started once, copy the model directory out of the container. The container can be stopped. Make sure ./models doesn’t exist yet, or the files land one level too deep:

    docker cp "$(docker compose -f deploy/docker-compose.yml ps -aq cortrix)":/data/models ./models

    The models directory holds bge-m3/, bge-reranker-v2-m3/, and MANIFEST.tsv, about 1.17 GB in total.

  2. Move the models directory to the machine that has no access.

  3. On that machine, create the container without starting it, copy the directory in, hand the files to the user the service runs as, and then start:

    docker compose -f deploy/docker-compose.yml create
    docker cp ./models/. "$(docker compose -f deploy/docker-compose.yml ps -aq cortrix)":/data/models/
    docker compose -f deploy/docker-compose.yml run --rm --no-deps --user root \
      --entrypoint chown cortrix -R cortrix:cortrix /data/models
    docker compose -f deploy/docker-compose.yml up --wait

    docker cp creates the copied files as root, and the service runs as cortrix. Without the chown, the service can read the models but can never replace one, so the container would exit at start the first time a file fails verification or a later release pins a different model revision.

The log shows that the cached files were verified and nothing was downloaded:

[provision] verifying pinned embedding and reranker assets
[models] verified cached embedding_model
[models] verified cached embedding_tokenizer
[models] verified cached reranker_model
[models] verified cached reranker_tokenizer
[models] all pinned embedding and reranker assets verified

A copied file that fails the size or SHA-256 check isn’t used. The downloader tries to fetch it again, and without network access it can’t download a replacement, so the container exits without starting the service. Copy the directory again from a machine where the quickstart reports ready.

Note

Building the image still needs network access, for the base images and the build dependencies. This section covers only the model download at first start.

Remove the cached models

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

This deletes the whole volume, including your data, not just the models.

Model settings when you run from source

When you run from source, the configuration file sets the model paths:

config.yaml
embedding:
  model_path: "./models/bge-m3/model.onnx"
  tokenizer_path: "./models/bge-m3/tokenizer.json"
  dimension: 1024
  max_seq_length: 512

reranker:
  model_dir: "./models/bge-reranker-v2-m3"
  • dimension is fixed at 1024 and can’t be changed.
  • An empty embedding.model_path is the only explicit stub mode. If the path is set but the model is missing or invalid, the server fails to start instead of degrading to a stub.
  • An empty reranker.model_dir explicitly selects the stub reranker. If the path is set, the model and tokenizer must be valid.

What the quickstart doesn’t include

The Docker quickstart covers only text files, BGE-M3 embedding, and bge-reranker-v2-m3 reranking. It doesn’t install or validate PDF, DOCX, images, OCR, query-complexity routing, external LLM roles, or the built-in Agent. Those are separate features. Check Compatibility and status before you rely on them.

Upgrade ONNX Runtime

The repository pins the ONNX Runtime version. The steps and verification requirements for upgrading it are written for maintainers. See ONNX Runtime upgrade and rollback.

Next steps

4.4 - Performance tuning

The settings that affect query latency, recall, and ingestion speed, and how to measure them on your own data.

A handful of settings affect Cortrix’s performance. Learn which stage each one acts on and how to measure its effect on your own data.

Important

Which way to turn a setting depends on your task and your data. The numbers on this page only illustrate direction. Measure on your own data before you change a default.

Measure first

Every query response includes the latency the server measured:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespaces": ["demo"], "query": "semantic storage", "top_k": 5}' \
  http://127.0.0.1:8420/api/v1/query
{
  "meta": {
    "coverage_ratio": 1.0,
    "latency_ms": 242,
    "namespaces_succeeded": ["demo"]
  }
}

Change one variable at a time, repeat the same set of queries several times, and compare the median meta.latency_ms. Check result quality too: faster isn’t the same as better.

Add ?explain=true to see which retrieval paths a query used. See Query and rerank.

Settings at a glance

SettingWhereDefaultAffects
rerankQuery requesttrueQuery latency and result ordering
top_kQuery request10How many results come back, and the candidate pool size
retrieval.candidate_multiplierConfiguration file3Candidate pool size
retrieval.max_candidatesConfiguration file50The candidate pool ceiling, and so the recall ceiling
embedding.execution_providerConfiguration fileautoWhere embedding runs
reranker.execution_providerConfiguration fileautoWhere reranking runs
server.thread_countConfiguration file4The server’s worker threads
spc.worker_countConfiguration file2How many documents are processed in parallel
spc.embedding_batch_sizeConfiguration file1Blocks embedded per batch
spc.onnx_intra_threadsConfiguration file4Intra-op threads for ONNX inference
spc.onnx_inter_threadsConfiguration file1Parallel ONNX inferences

The configuration file defaults come from config.yaml.example in the repository.

Queries

Reranking

Reranking is the single switch with the biggest effect on query latency. When it’s on, Cortrix scores each retrieved candidate with the cross-encoder model bge-reranker-v2-m3.

As a rough illustration, here is one measurement taken while writing this page. It isn’t a published benchmark, and it isn’t in the repository. On the quickstart service, with 3 short documents and CPU inference in Docker on an Apple silicon Mac, the median over 8 queries per setting was:

SettingMedian latency_ms
rerank: true242
rerank: false52

The measurements published in the repository show that on the Quora corpus (522,931 documents, a 32-core CPU, no GPU, serial queries), mean query latency goes from 1.7 seconds without reranking to 19.0 seconds with it.

Whether reranking is worth that cost depends on the kind of task:

Kind of taskExamplesRecommendation
Questions and answersDocumentation search, finding solutions in support tickets, grounding a RAG answerLeave it on
Finding identical or duplicate itemsDuplicate-question detectionTurn it off

In the published measurements, the three question-answering datasets (SciFact, NFCorpus, FiQA) gained 0.013 to 0.059 nDCG@10 with reranking on, while duplicate-question detection (Quora) dropped from 0.5003 to 0.2031. The reranker optimizes for “relevant,” and that kind of task is looking for “the same.”

For neighboring cases such as duplicate tickets, similar products, or “find similar” features, the same problem is a hypothesis, not a measurement. Test it on your own data.

To turn reranking off, set "rerank": false on each query.

Warning

Only the rerank flag on the query request takes effect today. The namespace-level reranker_config is accepted, but the query path doesn’t read it yet. See cortrix/cortrix#75. For a workload that shouldn’t be reranked, every request needs to pass "rerank": false explicitly.

For the measurement conditions and full data, see When to rerank and Benchmark evidence.

Candidate pool size

Cortrix fetches more candidates than top_k, then ranks and truncates. The number of candidates is:

candidate_k = min(top_k × candidate_multiplier × oversample, max_candidates)
  • A larger top_k means more candidates and more content returned.
  • max_candidates is a hard ceiling. On a large corpus, relevant documents can rank below 50, so raising max_candidates is the only way to lift the recall ceiling.
config.yaml
retrieval:
  candidate_multiplier: 3
  max_candidates: 50

You can also override these with the CORTRIX_RETRIEVAL_CANDIDATE_MULTIPLIER and CORTRIX_RETRIEVAL_MAX_CANDIDATES environment variables.

Query scope

List only the namespaces you actually need in namespaces. ["*"] queries every namespace you have access to, up to 100.

Time limits

A query request has no time budget of its own on this release. A query over several namespaces has two default wait limits in the step that collects the namespaces’ results: that step waits up to 5 seconds for each namespace in turn, counted from when it reaches that namespace, and stops waiting altogether 30 seconds after it started. A namespace it stops waiting for is listed among the failed namespaces with CX_ERR_NS_TIMEOUT, and the results from the other namespaces still come back.

These limits bound waiting, not work. A namespace can take longer than 5 seconds and still succeed when the collection reaches it later. The 30 seconds are not an end-to-end limit for the request: waiting for a free worker, RAG-Fusion and reranking come on top. The work of a namespace the collection stopped waiting for is not cancelled. A query over a single namespace has no wait limit.

Execution providers

The embedding model and the reranker each have an execution_provider setting. The values are auto, cpu, coreml, and cuda:

config.yaml
embedding:
  execution_provider: "auto"

reranker:
  execution_provider: "auto"

The matching environment variables are CORTRIX_EMBEDDING_EXECUTION_PROVIDER and CORTRIX_RERANKER_EXECUTION_PROVIDER. The quickstart pins both to cpu.

The readiness check shows which execution provider is actually in use:

curl -fsS http://127.0.0.1:8420/api/v1/system/health/ready
{
  "embedding_execution_provider": {
    "active_ep": "cpu",
    "configured_ep": "cpu",
    "fallback": false,
    "status": "ok"
  }
}

active_ep is the provider in use. A fallback of true means the configured provider wasn’t available and Cortrix fell back.

Using an NVIDIA GPU on Linux needs a separate image. See NVIDIA CUDA. The CUDA document in the repository is a deployment guide and doesn’t include performance data.

Ingestion

After upload, a document is parsed, chunked, and embedded. These settings control how much of that pipeline runs in parallel:

config.yaml
spc:
  worker_count: 2
  chunk_size: 512
  chunk_overlap: 50
  embedding_batch_size: 1
  onnx_intra_threads: 4
  onnx_inter_threads: 1
SettingPurpose
worker_countThreads processing documents in parallel. 2 to 4 is recommended
embedding_batch_sizeBlocks sent to the embedding model per batch
onnx_intra_threadsThreads used inside a single ONNX inference
onnx_inter_threadsONNX inferences that run in parallel
chunk_sizeThe target number of tokens per text block. Smaller blocks mean more blocks per document

These are configuration-file keys. They have no environment-variable override.

The readiness check reports the current queue depth and worker count under spc_pipeline:

{ "spc_pipeline": { "queue_depth": 0, "status": "ok", "workers": 2 } }

Server

config.yaml
server:
  thread_count: 4
  • server.thread_count is the number of worker threads handling requests. The recommended value is your CPU core count. You can override it with CORTRIX_SERVER_THREADS.

What these numbers do and don’t tell you

The measurements published in the repository cover retrieval quality at top_k=10 and mean latency under serial queries. They say nothing about production latency or capacity under concurrency, or about end-to-end answer quality.

This page doesn’t recommend values for thread counts, batch size, or execution providers, because the repository has no published controlled measurements for them. Measure those on your own hardware and data, using the method above, before you settle on values.

Next steps

4.5 - NVIDIA CUDA

Run embedding and reranking on an NVIDIA GPU on Linux.

Build and run the Cortrix CUDA image, then confirm that the models are really running on the GPU.

The default deploy/Dockerfile and deploy/docker-compose.yml are a CPU deployment. CUDA is turned on only when you build deploy/Dockerfile.cuda and layer deploy/docker-compose.cuda.yml on top.

Note

This page is adapted from the CUDA execution provider runbook and hasn’t been tested on a GPU machine. It’s a deployment guide and contains no performance data. Complete the verification steps on your target machine before you treat CUDA as verified.

Prerequisites

  • A Linux x86_64 host and container architecture.
  • An NVIDIA GPU and a compatible driver.
  • Docker, Docker Compose, and NVIDIA Container Toolkit configured for Docker.

The image runtime is CUDA 11.8 and cuDNN 8 on Ubuntu 22.04, with the repository-pinned ONNX Runtime 1.17.1 GPU build.

Host driver requirements:

Host NVIDIA driverNotes
>= 520.61.05The required baseline, and the recommended version for deployment
>= 450.80.02 and < 520.61.05NVIDIA documents compatibility in this range, with limitations. Cortrix doesn’t treat this range as validated
< 450.80.02Below the compatibility floor for CUDA 11.8. Don’t use it

Check the host before you build:

uname -m
nvidia-smi
nvidia-smi --query-gpu=name,uuid,driver_version --format=csv,noheader
docker version
docker compose version

uname -m must print x86_64, and nvidia-smi must list the GPU you intend to use.

Execution provider values

Embedding and reranking each choose an execution provider independently, from the same set of values:

ValueBehavior in the CUDA image
autoTry CUDA first. If it fails, record the reason and create a fresh CPU-only session
cpuUse the CPU without trying CUDA
cudaRequire CUDA. A failure aborts startup, with no CPU fallback
coremlFor builds on Apple platforms. Not available in the Linux CUDA image

Environment variables take precedence over the YAML configuration. Values aren’t case-sensitive, but lowercase is recommended.

Steps

Run every command from the root of the repository.

Prepare the environment file

cp deploy/.env.example deploy/.env

At a minimum, confirm these settings:

deploy/.env
CORTRIX_PROFILE=full
CORTRIX_EMBEDDING_EXECUTION_PROVIDER=auto
CORTRIX_RERANKER_EXECUTION_PROVIDER=auto
NVIDIA_VISIBLE_DEVICES=all
NVIDIA_DRIVER_CAPABILITIES=compute,utility

The CUDA override file passes these values into the container. When the profile is full, the Quick Start demo data isn’t loaded.

To use only one GPU, set NVIDIA_VISIBLE_DEVICES to its index or UUID. Cortrix needs only the compute and utility capabilities.

Build the image

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  build cortrix

The build is restricted to linux/amd64, and model files aren’t baked into the image.

Start the stack

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  up -d

Follow the startup log until the service is healthy:

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  logs -f cortrix

Verify

Don’t conclude that CUDA is in use from the image name or from GPU visibility alone. Check each of these.

Check that the container sees the GPU

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  exec cortrix nvidia-smi -L

Only the GPUs selected by NVIDIA_VISIBLE_DEVICES should be listed.

Check the runtime libraries

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  exec cortrix sh -c \
  'out=$(ldd /usr/local/lib/libonnxruntime_providers_cuda.so) && printf "%s\n" "$out" && ! printf "%s\n" "$out" | grep -q "not found"'

This command succeeds only when there are no missing dependencies.

Check the active execution provider

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

Look at components.embedding_execution_provider and components.reranker_execution_provider:

SituationWhat you see
CUDA is workingactive_ep is cuda
auto fell back to the CPUThe service is still ready, but fallback is true, active_ep is cpu, and preferred_ep is cuda
The explicit setting and reality don’t matchThe service isn’t ready, and policy_mismatch is true
No model is configuredmodel_configured is false and active_ep is stub

Check the metrics

The metrics port, 9091, is open only inside the container, so query it from there:

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  exec -T cortrix sh -c \
  'curl -fsS http://127.0.0.1:9091/metrics | grep -E "cortrix_onnx_build_info|embedding_(configured|active)_ep|reranker_(configured|active)_ep"'

A CUDA build includes this line:

cortrix_onnx_build_info{runtime_flavor="cuda"} 1

Require the GPU

A typical CUDA deployment keeps both components on auto. If you’d rather have startup fail than fall back to the CPU when GPU initialization fails, change that component to cuda and recreate the service:

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  up -d --force-recreate cortrix

Roll back to CPU

To switch back to the default CPU image and keep the data volume:

docker compose \
  -f deploy/docker-compose.yml \
  -f deploy/docker-compose.cuda.yml \
  down
docker compose -f deploy/docker-compose.yml up -d --build
Caution

Don’t add --volumes to down unless you really mean to delete your data.

To keep the CUDA image and just use the CPU for now, set both execution provider variables to cpu and recreate the service.

Troubleshooting

SymptomWhat to do
Docker reports that no GPU driver is availableConfirm nvidia-smi works on the host, and that NVIDIA Container Toolkit is installed and configured for Docker
The container is rejected before the entrypoint runsCheck the Docker daemon log for an NVIDIA_REQUIRE_CUDA or driver-version constraint error, and upgrade the host driver. Don’t set NVIDIA_DISABLE_REQUIRE=true to bypass the check
The pre-flight check can’t see a GPUCheck the value of NVIDIA_VISIBLE_DEVICES, and that NVIDIA_DRIVER_CAPABILITIES includes compute,utility
ldd reports CUDA or cuDNN libraries as not foundRebuild from deploy/Dockerfile.cuda and confirm the runtime stage is the CUDA 11.8 and cuDNN 8 image

Next steps

4.6 - Security boundaries

Where Cortrix stands today on authentication, network exposure, and logging, and how to report a vulnerability.

Read this before you deploy Cortrix anywhere beyond your own machine. It covers what Cortrix can and can’t guarantee about security today.

Important

Cortrix is in pre-release. Tenant isolation, access control, and log redaction are in development. API key permissions are off by default: Cortrix checks them only with authentication on. API key configuration exists, but its behavior hasn’t been verified for this documentation. See Compatibility and status. Until these are available, deploy Cortrix only on a network you control.

Default protections

The bundled Compose deployment is configured this way in v1.0.0-rc.2:

  • It listens only on the loopback address. The Compose deployment publishes the API at 127.0.0.1:8420, so other machines can’t reach it.
  • Admin endpoints accept loopback requests only. An admin request from a non-loopback address gets 403 CX_ERR_ADMIN_LOOPBACK_REQUIRED.
  • The metrics port isn’t published. It’s reachable only from inside the container.
  • External LLMs are off by default. The quickstart sends no documents or queries to any external LLM service.

The configuration template also states that running without authentication is accepted only when the server binds to the loopback address, and that authentication must be on before the server binds to a non-loopback address.

With authentication off

The bundled configuration ships with authentication off. In that mode every request is treated as an admin of the default tenant: it can read and write every namespace, call the tenant, member, and maintenance endpoints, and restore or purge deleted documents. The server accepts this only on the loopback address or a container-internal bind published only to loopback, so anyone who can reach that port has full access.

What not to do

  • Don’t expose an unauthenticated service to a network you don’t control. Access opened with CORTRIX_PUBLISH_HOST has no authentication at all, and is only for an isolated test network you control.
  • Don’t use a local run with authentication off to prove that access control works. With authentication off, denial behavior for RBAC, tenant isolation, ACLs, and quotas can’t be demonstrated.
  • Don’t assume logs are redacted. Startup and runtime logs can contain sensitive content. Check them yourself before you collect or share them.
  • Don’t put keys in files that get committed. Keep real API keys only in ignored local configuration.

Authentication schemes

Cortrix authenticates requests with an API key, sent in the X-API-Key header. The configuration file stores an API key as its SHA-256 hash. To set one up, see Configuration.

Before production

At a minimum, verify these in your target environment:

  • Authentication mode and credential handling
  • Tenant isolation and RBAC behavior
  • Namespace ACLs and quotas
  • Logging and redaction
  • Data persistence and backup strategy
  • Deployment topology and resource limits

Treat anything you haven’t verified as not ready.

Report a vulnerability

Report suspected vulnerabilities privately to security@cortrix.ai. Don’t open a public issue for an unpatched vulnerability, credentials, customer data, or details of exploitable infrastructure.

Include:

  • The affected 40-character commit hash
  • The impact
  • A minimal reproduction
  • Sanitized evidence

Don’t include secrets unless the security response team explicitly asks for them and gives you a secure way to send them.

The team acknowledges receipt within 5 business days. An acknowledgment means the report has been received and routed. It isn’t a promise that analysis, a fix, or a release will be finished in that time.

Don’t disclose the vulnerability publicly before a fix is available or before a disclosure date both sides agree on.

Until the first stable release, security support covers only the latest commit on the default branch.

Next steps

4.7 - Upgrade

Upgrade from v1.0.0-rc.1 to v1.0.0-rc.2.

Before you move from v1.0.0-rc.1 to v1.0.0-rc.2, here’s what to check first, what to verify afterward, and how to roll back.

Important

RC2 is a new pre-release. Back up your persistent data and validate RC2 against a copy before you change an existing environment.

Before you upgrade

  • Read Compatibility and status and confirm the current status of the capabilities you depend on.
  • Record your existing source revision, configuration, model files, database path, and rollback procedure.
  • In an isolated environment, rerun your API, SDK, MCP, deployment, and persistence smoke tests against the exact RC2 tag.
  • Keep treating your source documents as authoritative until you’ve verified indexing, query behavior, deletion, and rollback.

Changes to verify

Task lifecycle and persistent data

RC2 changes a lot in the asynchronous task lifecycle. Verify task submission, terminal states, resubmission, cancellation races, cleanup scheduling after a restart, namespace-scoped task identity, and repeated or same-content batch uploads.

There’s no new SQL migration file to apply by hand between v1.0.0-rc.1 and RC2. Startup still creates or adjusts indexes and task state, though, so this is no substitute for a backup or for an upgrade test against a copy.

Query and reranking

  • When the reranker doesn’t suit your task, pass rerank=false on each request.
  • Don’t rely on the namespace-level reranker setting to turn reranking off. The query path doesn’t read it yet.

See Performance tuning.

MCP

  • The local MCP server supports both the modern stdio discovery path and the legacy initialization handshake.
  • Session and trace identity are passed through to the Cortrix server.
  • Verify client and server API compatibility before you replace an existing MCP environment. Local stdio is still the only public transport.

Deployment

  • Docker Compose still listens only on the loopback address by default.
  • Publishing to a LAN address is an explicit opt-in, meant only for isolated test networks.
  • After upgrading, rerun the readiness check and the reranked query from the Quickstart.

License change

Cortrix-authored RC2 material is licensed under Apache-2.0. Release objects from the historical v1.0.0-rc.1 remain under AGPL-3.0-only, and third-party material keeps its own license. Before you redistribute a mixed or modified package, review LICENSE, NOTICE.md, and CONTRIBUTING.md in the repository.

Reading the benchmarks

  • The RC2 retrieval evidence is the pinned four-corpus CPU measurement bundle. See Benchmark evidence.
  • Don’t compare the 2,000-query Quora subset with a result over the full query set.
  • Don’t read the published CPU latency as production capacity under concurrency.

Roll back

  1. Stop the RC2 environment.
  2. Restore the RC1 configuration and data backup you recorded.
  3. Check out the immutable v1.0.0-rc.1 tag.
Warning

Don’t reuse a database that RC2 has opened unless you’ve run a rollback test on that same copy and confirmed it’s compatible.

Next steps

5 - Concepts

Understand Cortrix’s architecture, data flow, and interfaces.

These pages explain why Cortrix works the way it does. They don’t contain steps to follow.

5.1 - Architecture overview

The parts that make up Cortrix and how they relate.

Cortrix is one server with several ways to reach it. Knowing how the parts fit together explains why the steps on other pages look the way they do.

One server, several access paths

At the center of Cortrix is a single process, cortrix-server. It’s written in C++, exposes an HTTP API, and contains all of the ingestion, storage, and retrieval logic. Everything else is a client of that API.

flowchart TB
  subgraph clients[Access paths]
    MCP[MCP server]
    SDK[Python SDK]
    SKILLS[Framework adapters]
    AGENT[Built-in Agent]
    PG[pgcortrix]
    UI[Web UI]
  end
  subgraph server[cortrix-server]
    API[HTTP API]
    INGEST[Ingestion pipeline]
    QUERY[Query pipeline]
    MEMORY[Memory]
    STORE[Storage]
  end
  MCP --> API
  SDK --> API
  SKILLS --> SDK
  AGENT --> SDK
  PG --> API
  UI --> API
  API --> INGEST
  API --> QUERY
  API --> MEMORY
  INGEST --> STORE
  QUERY --> STORE
  MEMORY --> STORE

Two things follow directly from this shape:

  • Every access path has the same reach. MCP tools, SDK methods, and SQL functions all end up calling the same HTTP endpoints, and none of them has a privileged channel. Even the built-in Agent reaches the server only through the public Python SDK.
  • There’s one contract. api/openapi.yaml is the authoritative definition of the HTTP API, and every other access path follows it.

Inside the server

Ingestion pipeline

Once a document enters Cortrix, it’s parsed, chunked, embedded, and indexed in the background. This is an asynchronous queue with persisted tasks: the upload request returns quickly, and you check progress through the task API.

The repository calls this pipeline SPC, short for Semantic Processing Chain. The readiness check reports its queue depth and worker count under spc_pipeline.

Query pipeline

At query time, several retrieval paths run in parallel. Their results are fused and then, optionally, reranked:

  • Vector search: looks up BGE-M3 dense vectors in a persistent HNSW index.
  • Full-text search: built on SQLite FTS5.
  • Sparse retrieval: uses sparse vectors produced by the same BGE-M3 model.
  • Fusion: merges the paths’ results into one list by rank.
  • Reranking: scores each candidate with a cross-encoder model. It’s on by default.

A cross-namespace query fans the request out to each namespace, then merges and de-duplicates the results.

Storage

Each namespace has its own data:

WhatHow it’s stored
The vector indexA persistent HNSW index with snapshots and a write-ahead log
Metadata, the full-text index, and tasksSQLite
The original uploaded filesFile storage

A single write touches the vector index, the database, and file storage. A write coordinator makes sure all three succeed or none of them takes effect.

Every namespace is loaded when the server starts or when it’s created, and it stays loaded until it’s deleted.

Local models

Embedding and reranking use two local ONNX models, run on your machine by ONNX Runtime on CPU, CoreML, or CUDA. They need no external service.

LLMs are a different matter. They’re optional, they’re configured per role, and only features such as enrichment, document summaries, memory extraction, and built-in Agent chat use them. With no LLM configured, ingestion and retrieval work as usual.

How the repository maps to components

DirectoryComponentLanguage
src/, include/cortrix-serverC++17
api/The OpenAPI specYAML
cortrix-mcp/MCP serverPython
sdk/python/Python SDKPython
cortrix-skills/Framework adaptersPython
cortrix-agent/Built-in AgentPython
sql-extensions/pgcortrix/PostgreSQL extensionSQL, Python
web/Web UITypeScript
deploy/Deployment files—

What this page doesn’t cover

The sections above describe how the code is put together, not the status of each part. To see whether a capability is in preview or in development, see Compatibility and status.

Next steps

5.2 - Data flow

What happens to a document between upload and retrieval.

Follow a document from the moment you upload it to the moment it shows up in a query result, then see how a query runs.

Writing

flowchart LR
  UP[Upload] --> TASK[Create task]
  TASK --> PARSE[Parse]
  PARSE --> CHUNK[Chunk]
  CHUNK --> EMBED[Embed]
  EMBED --> INDEX[Index]
  INDEX --> READY[ready]

1. Upload

A document comes in one of three ways: a file upload, an inline upload, or a watcher that noticed a new file. Whichever way it arrives, it becomes a background processing task.

Cortrix recognizes duplicates by content hash, so uploading the same content again doesn’t reprocess it.

2. Parse

A parser turns the file into text. Plain text is used as it is. PDF, Word, and images need the matching parsers and OCR, which are optional components and aren’t turned on in the quickstart.

3. Chunk

The text is split into blocks. By default each block targets 512 tokens, and neighboring blocks overlap by 50 tokens to keep context continuous. Blocks are the units that get retrieved later.

4. Embed

The BGE-M3 model turns each block into a 1024-dimension vector. This happens on your machine, and nothing is sent anywhere else.

5. Index

The vectors go into the vector index, the text goes into the full-text index, and the metadata goes into the database. These writes complete as a unit.

When that’s done, the document’s status becomes ready and queries can find it.

Why uploads are asynchronous

Parsing and embedding take time, and more of it for larger documents. Running them in the background lets the upload request return right away, and the caller checks progress with a task identifier.

It also means that a successful upload request only tells you the task was accepted. Whether processing succeeded is something you learn from the task progress or the document status.

Querying

flowchart LR
  Q[Query] --> EMBEDQ[Embed the query]
  EMBEDQ --> DENSE[Vector search]
  Q --> FTS[Full-text search]
  DENSE --> FUSE[Fuse]
  FTS --> FUSE
  FUSE --> RERANK[Rerank]
  RERANK --> OUT[Results]

1. Retrieve along several paths

The query text is embedded and used to find semantically similar blocks in the vector index. At the same time, the full-text index is searched by keyword. Each path returns its own set of candidates.

With ?explain=true you can see which paths a query actually used, for example "rrf_path_counts": {"dense": 1, "fts5": 1}.

2. Fuse

The candidates from each path are merged into one list by rank. The score in a result is this fused score.

3. The candidate pool

More candidates move on to the next step than top_k asks for. The number comes from top_k, the candidate multiplier, and the candidate ceiling together. Fetching more and truncating later gives the reranker room to choose.

4. Rerank

The reranker scores the query against each candidate to produce a rerank_score. The results are reordered by that score and cut down to the top top_k.

Reranking happens before the candidates are truncated. So with reranking on, a candidate that was ranked first can drop out of the results entirely rather than just moving down. That’s one reason reranking hurts tasks that are looking for identical items. See Performance tuning.

5. Across namespaces

When you query several namespaces, the request is sent to each one, and the results are merged and de-duplicated. One namespace failing doesn’t fail the whole query: the parts that succeeded come back as usual, and the failure is recorded in meta.namespaces_failed.

Deleting

Deleting a document happens in stages:

  1. Soft delete: the document is marked deleted and disappears from query results right away, but the data is still there and can be restored during the retention period.
  2. Hard delete: once the retention period passes, garbage collection removes the document’s records.
  3. File cleanup: after a further waiting period, the original file is physically deleted.

The default retention period is 30 days, and the wait before file cleanup is 90 days.

Memory

A memory you write explicitly is saved as it is. Editing a memory doesn’t change the original record. It creates a new record and marks the old one invalidated. Deleting a memory also only marks it invalidated. Memories are always kept, so their history can be traced.

Next steps

5.3 - Interfaces

The conventions behind Cortrix’s agent-facing interfaces and structured errors.

Cortrix is agent-native, and that shows up as a set of conventions that run through every interface.

What agent-native means for an interface

When a call fails, a person can read the error message, look something up, and try a different approach. An agent needs information it can act on directly: can this error be retried, how long should it wait, is the result complete, and what should happen next.

Cortrix’s interfaces are designed for that second need. The principle is that every API is designed for programs and agents first: errors are structured, states are enumerable, and degraded paths still return data instead of failing outright.

Convention 1: errors are structured

Every error carries code, retryable, category, and retry_after_ms. An agent never needs to parse the message with a regular expression:

{
  "error": {
    "code": "CX_ERR_DEPRECATED_FIELD",
    "message": "Field 'namespace' is deprecated, use 'namespaces' array instead",
    "retryable": false,
    "category": "permanent",
    "structured_data": { "deprecated_field": "namespace", "use_instead": "namespaces" }
  }
}

structured_data holds machine-readable details about the error. The example above tells the caller exactly which field to use instead.

See Error codes.

Convention 2: partial failure still returns data

In a cross-namespace query, one failing namespace doesn’t fail the whole request. The parts that succeeded come back as usual, and meta says how much was covered, what failed, and why:

{
  "meta": {
    "coverage_ratio": 0.5,
    "namespaces_succeeded": ["guide"],
    "namespaces_failed": [
      { "namespace": "nope", "error_code": "CX_ERR_INDEX_CORRUPT", "retryable": false, "category": "permanent" }
    ]
  }
}

An agent can use the results it has and then decide whether to retry the part that failed. Batch document submission works the same way.

The cost is that HTTP 200 no longer means “everything succeeded.” Callers need to check meta.

Convention 3: responses say what to do next

The progress of an asynchronous task carries an agent_decision_hint that says what to do next:

ValueMeaning
done_fetch_docProcessing finished. You can read the document
inspect_error_codeProcessing failed. Look at the error code

Convention 4: endpoints describe themselves

The OpenAPI spec annotates every endpoint with agent-facing metadata that can be read before the call:

MetadataThe question it answers
Side-effect categoryIs this call read-only, a write, or destructive?
Retryability and retry strategyCan it be retried after a failure, and how?
Authorization scopeWhat permission does it need?
Rate limitHow often can it be called?

An agent can use this to check with the user before it runs a destructive operation. For the full list of fields, see Error codes.

Convention 5: calls can be traced

The MCP server attaches session, trace, and caller identifiers to every request. The SDK sends a caller identifier when you set client_id, and a trace identifier when you give it a trace_id_provider. The server adopts those identifiers when it records traces, and you can query them later by session:

curl -fsS http://127.0.0.1:8420/api/v1/traces/<session_id>

When several agents work together, this lets you reconstruct what each one did.

Convention 6: every access path means the same thing

MCP tools, framework adapter methods, and HTTP endpoints share names and semantics. The framework adapters’ 29 methods map one-to-one to the MCP server’s regular tools. What you learn on one access path carries over to the others.

Between the spec and the implementation

These conventions are design goals. In v1.0.0-rc.2 there are still places where the implementation and the spec disagree. Testing for this documentation ran into several and recorded them:

  • Some error codes don’t use the unified CX_ERR_ prefix.
  • The memory edit and delete endpoints require parameters that differ from the OpenAPI definition.
  • The watcher events endpoint exists in the spec but returns 404.

So when you integrate, go by the retryable and category in the actual response, and rerun your own smoke tests after each upgrade.

Next steps

6 - Reference

Exact details of the HTTP API, MCP tools, configuration keys, and error codes.

Use this section when you need to look up exact behavior.

6.1 - HTTP API

The HTTP API reference, generated from the OpenAPI spec.

This reference is rendered from a filtered copy of api/openapi.yaml. The copy leaves out operations that this build doesn’t serve. An endpoint that appears in the spec isn’t necessarily available yet. For the status of each capability, see Compatibility and status.

OpenAPI specification — /docs/openapi/openapi.yaml

6.2 - MCP tools

Every tool the MCP server provides, with its parameters.

cortrix-mcp provides 31 tools in v1.0.0-rc.2. The tool names and parameters come from the tool list returned by a running MCP server.

A * after a parameter name means it’s required. A tool that isn’t given a namespace uses the default namespace set by the CORTRIX_NAMESPACE environment variable.

For installation and setup, see MCP server.

Note

Tools marked In development have no documentation yet.

Health and namespaces

ToolWhat it doesParameters
cortrix_healthChecks that the Cortrix service is running and reachable—
cortrix_list_namespacesLists the namespaces you have access tolimit, offset
cortrix_create_namespaceCreates a namespacename*

Query

ToolWhat it doesParameters
cortrix_queryRuns a semantic query over one or more namespacesquery*, top_k, namespaces, rerank
cortrix_cross_ns_queryQueries across several namespacesquery*, namespaces*, top_k, rerank
cortrix_query_explainRuns a query and returns an explanation of the path it tookquery*, top_k, namespaces, rerank

For cortrix_query, top_k defaults to 5 and rerank defaults to true.

Documents

ToolWhat it doesParameters
cortrix_uploadUploads document content for asynchronous processing and returns a taskcontent*, namespace, filename, metadata
cortrix_async_uploadUploads a larger document asynchronously and returns a taskcontent*, namespace, filename, metadata
cortrix_batch_submitSubmits up to 100 documents to one namespace at oncenamespace*, documents*, async_, on_duplicate
cortrix_list_documentsLists the documents in a namespacenamespace, limit, offset
cortrix_document_statusShows a document’s processing status and detailsdoc_id*, namespace
cortrix_task_statusShows the progress of an asynchronous upload tasktask_id*
cortrix_cancel_taskCancels an asynchronous upload tasktask_id*

Directory watchers

ToolWhat it doesParameters
cortrix_add_watcherAdds a watcher that imports the files in a directory automaticallydata_dir*, namespace, recursive
cortrix_list_watchersLists all watchers—

Memory

ToolWhat it doesParameters
cortrix_memory_createCreates a memorynamespace*, content*, memory_type*, metadata
cortrix_memory_listLists memoriesnamespace, memory_type, include_invalidated, limit, offset
cortrix_memory_editEdits a memory’s content or metadatamemory_id*, namespace, content, metadata
cortrix_memory_invalidateSoft-deletes a memorymemory_id*, namespace, reason
cortrix_memory_searchRuns a semantic search over conversation memoryquery*, namespace, top_k
cortrix_memory_search_filterSearches memory filtered by memory typequery*, memory_type*, namespace, top_k
cortrix_memory_opt_outOpts a session out of memory, or revokes the opt-outsession_id*, opt_out, namespace, reason
cortrix_memory_get_auditQueries the memory audit recordsmemory_id, namespace, limit

These tools are In development:

ToolWhat it doesParameters
cortrix_memory_extractExtracts memories from a conversation in one callmessages*, namespace
cortrix_memory_extract_triggerTriggers memory extraction for a session manuallynamespace, session_id
cortrix_memory_revoke_factRevokes an automatically extracted factmemory_id*, namespace

Interactions and the operation log

ToolWhat it doesParameters
cortrix_log_interactionSaves a conversation turn: the user’s question and the assistant’s answersession_id*, query_text*, response_text*, namespace
cortrix_list_interactionsLists a user’s interactionsnamespace*, user_id*, filter, limit, offset
cortrix_list_operationsQueries the operation loguser_id, namespace, action, action_in, start_time, end_time, limit, offset, sort_order

Admin

Admin tools require the server to accept the caller as an admin.

ToolWhat it doesParameters
cortrix_admin_db_credential_registerRegisters a database connection credentialname, dsn, expire_days, connection_ref, description
cortrix_admin_db_import_runStarts a database importconnection_ref*, namespace*, table, filter, sql

These two tools are In development.

Responses and errors

Every tool returns two layers, data and meta. For the response schema and the adapter’s own error codes, see MCP server.

6.3 - Configuration reference

Every key in config.yaml, with its default.

Every key in the configuration file is listed here. Defaults come from config.yaml.example in the v1.0.0-rc.2 repository.

For how to configure Cortrix and for common scenarios, see Configuration. When a key also has an environment variable, the environment variable wins.

server

KeyDefaultDescription
host"127.0.0.1"The address to listen on. Binding to a non-loopback address requires authentication to be on
port8420The HTTP port
thread_count4Worker threads. The recommended value is your CPU core count. Environment variable: CORTRIX_SERVER_THREADS

auth

KeyDefaultDescription
enabledfalseWhether API key authentication is on. With it off, only a loopback bind is accepted
api_keys[].key_hash—The SHA-256 of the key
api_keys[].tenant_id—The tenant the key belongs to
api_keys[].permissions—Permission bits: READ=1, WRITE=2, ADMIN=4. 7 is all of them
api_keys[].expires_at0Expiry time. 0 never expires

log

KeyDefaultDescription
level"info"trace, debug, info, warn, error, critical, or off
format"text"text or json
output"stdout"stdout, stderr, or a file path

namespace

KeyDefaultDescription
data_dir"./build/data"The data root, holding databases, the vector index, and files. A relative path is resolved from the directory of the cortrix-server binary

embedding

KeyDefaultDescription
model_path"./models/bge-m3/model.onnx"The embedding model path. Leave it empty to select the stub explicitly
tokenizer_path"./models/bge-m3/tokenizer.json"The tokenizer path
dimension1024The vector dimension. Fixed at 1024 for bge-m3 and can’t be changed
max_seq_length512The maximum tokens per encode
execution_provider"auto"auto, cpu, coreml, or cuda. Environment variable: CORTRIX_EMBEDDING_EXECUTION_PROVIDER

reranker

KeyDefaultDescription
model_dir"./models/bge-reranker-v2-m3"The reranker model directory. Leave it empty to select the stub explicitly. Environment variable: CORTRIX_RERANKER_MODEL_DIR
execution_provider"auto"auto, cpu, coreml, or cuda. Environment variable: CORTRIX_RERANKER_EXECUTION_PROVIDER

query_complexity

KeyDefaultDescription
model_dir"./models/query-complexity"The directory of the query-complexity classifier. If the model is absent, a heuristic is used instead. Environment variable: CORTRIX_QUERY_COMPLEXITY_MODEL_DIR

retrieval

KeyDefaultDescription
candidate_multiplier3How many times top_k the candidate pool is, at least 1. Environment variable: CORTRIX_RETRIEVAL_CANDIDATE_MULTIPLIER
max_candidates50The hard ceiling on the candidate pool, at least 1. Environment variable: CORTRIX_RETRIEVAL_MAX_CANDIDATES

See Performance tuning.

spc

The Semantic Processing Chain (SPC), the document processing pipeline. It supports PDF, DOCX, TXT, MD, CSV, JSON, and images (through OCR).

KeyDefaultDescription
worker_count2Threads processing in parallel. 2 to 4 is recommended
chunk_size512The target number of tokens per text block
chunk_overlap50Tokens shared between neighboring blocks
embedding_batch_size1Blocks embedded per batch
onnx_intra_threads4Intra-op threads for ONNX inference
onnx_inter_threads1Parallel ONNX inferences
python_bin"./scripts/ocr_venv/bin/python3.12"The Python used by the parsing scripts
parse_pdf_script"./scripts/parse_pdf.py"The PDF parsing script
parse_word_script"./scripts/parse_word.py"The Word parsing script
ocr_script"./scripts/run_ocr.py"The OCR script
parser_timeout_s120Document parsing timeout, in seconds
ocr_timeout_s3600OCR timeout, in seconds

LLM roles

The five roles semantic_llm, vision_llm, agent_llm, doc_summary_llm, and enricher_llm each have their own section with the same fields:

KeyDescription
provideropenai, glm, claude, ollama, deepseek, or mock
api_keyThe provider’s API key
modelThe provider’s model identifier
base_urlThe API address

A role counts as configured only when provider, api_key, and model are all set. See Configuration.

watch_dir

KeyDefaultDescription
data_dir""The absolute path of a local directory to watch. Empty turns it off
namespace_name"local"The namespace files are imported into. It’s created if it doesn’t exist
watch_enabledtrueWhen false, existing files are imported but later changes aren’t watched

To manage watchers through the API, see Watch a directory.

memory

KeyDefaultDescription
default_ttl_seconds0How long memory is kept. 0 keeps it forever
inject_recent_turns5How many recent turns to include when injecting context
inject_max_tokens2000The token ceiling for injected context

rag_fusion

KeyDefaultDescription
default_enabledfalseThe global default for whether it’s on
default_variant_count3How many query variants to generate
default_rrf_k60The rank-fusion constant
default_timeout_ms5000The timeout for the LLM to generate variants
llm_prompt_template_zh"default-zh"The Chinese prompt template
llm_prompt_template_en"default-en"The English prompt template

RAG-Fusion is off by default and runs only when an LLM role is configured. The configuration template notes that the server doesn’t read the keys in this section yet, so the built-in defaults are what’s actually used.

gc

Garbage collection runs in three stages: soft delete, hard delete, and file cleanup.

KeyDefaultDescription
enabledtrueWhether the background garbage collection thread runs
soft_delete_retention_days30Days a soft-deleted item is kept, during which it can be restored
blob_gc_retention_days90Days a file is kept after hard delete before it’s physically removed
scan_interval_hours24The interval between background scans
max_purge_per_run10000The most files cleaned up in one run
max_run_duration_minutes5The longest a single run can take
dry_runfalseScan without deleting, for testing and inspection
immediate_purge_enabledfalseTurns on the immediate-purge API. Leave it false

Environment variables for Docker

See Configuration.

6.4 - Error codes

The structure of an error response, the error categories, and common error codes.

Cortrix error responses are designed for programs and agents. Whether to retry, how long to wait, and what kind of error it is each have a dedicated field, so you never need to parse the message text.

Error response structure

{
  "error": {
    "code": "CX_ERR_DEPRECATED_FIELD",
    "message": "Field 'namespace' is deprecated, use 'namespaces' array instead",
    "retryable": false,
    "category": "permanent",
    "retry_after_ms": null,
    "structured_data": {
      "deprecated_field": "namespace",
      "use_instead": "namespaces"
    }
  }
}
FieldTypeDescription
codestringThe error code
messagestringA description for people. Don’t parse it in code. The structured details are in structured_data
retryablebooleanWhether a retry is worthwhile
categorystringThe error category. See the next table
retry_after_msinteger or nullThe suggested wait before a retry, in milliseconds
structured_dataobjectStructured data about this error, for programs to use
request_idstringA server-generated request identifier for finding the request in logs. Some error responses include it

Error categories

categoryMeaningWhat to do
authAn authentication or permission problemDon’t retry. Check your credentials or permissions
quotaA quota was exceededSlow down, or wait and try again
transientA temporary failureWait for retry_after_ms, then retry
timeoutA timeoutWait for retry_after_ms, then retry
permanentSomething is wrong with the request itselfDon’t retry it unchanged. Fix the request

Decide whether to retry

  1. Look at retryable first. If it’s false, don’t retry.
  2. For the wait time, use retry_after_ms, then the Retry-After header (in seconds), then exponential backoff.

The Python SDK has this logic built in. See Python SDK.

Partial success

Some operations return HTTP 200 even when part of the work failed. The details are in the response’s meta, and every failure carries the same structured fields:

OperationWhere the failures are
Cross-namespace querymeta.namespaces_failed[]
Batch document submitmeta.failed[]

A query can also succeed with degraded results, reported in meta.warnings with the same code and category fields and, when applicable, retry_after_ms. See Check for degraded results for the warning codes and what to do.

When an asynchronous task fails, the failure appears in the task progress as error_code and error_msg, not in the response to the request that submitted it.

So don’t judge whether an operation fully succeeded from the HTTP status code alone.

How error codes are named

The spec requires every error code to use the CX_ERR_ prefix, which lets you filter Cortrix errors in logs and monitoring.

Note

In testing, some errors in v1.0.0-rc.2 used generic codes without the prefix, such as INVALID_ARGUMENT and NOT_FOUND. When you handle errors, go by retryable and category, and don’t assume every code starts with CX_ERR_.

Common error codes

These are the high-frequency codes registered in the spec, with the suggested way to handle each:

Error codeRetryableCategoryTypical causeWhat to do
CX_ERR_NAMESPACE_NOT_FOUNDNopermanentThe namespace name is misspelled, or the namespace was deletedConfirm the name with GET /namespaces, or create the namespace
CX_ERR_NS_UNAUTHORIZEDNoauthThe API key has no access to this namespaceRead the namespaces you can’t access from structured_data.unauthorized_namespaces and query only the ones you can
CX_ERR_NS_TIMEOUTYestimeoutA query on one namespace timed outUse the partial results you got, and optionally retry just that namespace
CX_ERR_RATE_LIMITYestransientThe rate limit was exceeded. The v1.0.0-rc.2 server doesn’t emit this codeWait for retry_after_ms and retry, or lower your request rate
CX_ERR_AUTH_INVALID_API_KEYNoauthThe API key is invalid or revokedUse a different API key
CX_ERR_INDEX_CORRUPTNopermanentThe vector index is unavailableUse the partial results and notify whoever operates the service

These are the error codes that came up in testing for this documentation:

Error codeHTTP statusWhen it appears
CX_ERR_DEPRECATED_FIELD400A query request used the singular namespace
CX_ERR_NS_NOT_FOUND404A file was uploaded to a namespace that doesn’t exist
CX_ERR_ADMIN_LOOPBACK_REQUIRED403An admin endpoint was called from a non-loopback address
CX_ERR_DISK_FULL507A file was uploaded while the data disk was at least 90% full. See Troubleshooting
CX_ERR_SPC_PROCESS_FAILED—An asynchronous processing task failed. It appears in the task progress

For the MCP adapter’s own error codes, see MCP server.

Agent hints in the OpenAPI spec

The OpenAPI spec annotates every endpoint with a set of x-cortrix-* extension fields, so an agent knows what kind of endpoint it’s dealing with before it calls it:

FieldMeaning
x-cortrix-retryableWhether this endpoint can usually be retried
x-cortrix-retry-strategyThe suggested way to retry: exponential_backoff, linear, no_retry, or immediate
x-cortrix-side-effectsThe side-effect category: none, read_only, write, or destructive
x-cortrix-auth-requiredWhether authentication is required
x-cortrix-auth-scopeThe required scope: ns:read, ns:write, tenant:admin, or ops:admin
x-cortrix-rate-limitThe rate limit, as count/period/scope
x-cortrix-typical-latencyEstimated P50 and P99 latency

These fields are design annotations in the spec, not measured results.

Next steps

6.5 - Glossary

The terms used in the Cortrix documentation.

These are the terms the Cortrix documentation uses. Each concept has exactly one name.

Product and positioning

TermDefinition
access pathA way for an agent or application to use Cortrix: the HTTP API, MCP, the Python SDK, framework adapters, or the built-in Agent
Agent-nativeDesigned around agent data workflows: semantic processing, memory, and traceability are concerns of the shared storage layer
built-in AgentThe fixed-flow chat service that ships in the repository
framework adapterThe cortrix-skills package, which turns Cortrix tools into each agent framework’s native format
Quick StartThe path that starts Cortrix locally with Docker and runs a first query
semantic storageA storage layer that connects information with the context an application needs to use it

Data model

TermDefinition
blockThe smallest searchable unit, derived from a document or a memory record
documentSource material uploaded to Cortrix
eventA memory type. It decays over time
factA memory type. It doesn’t decay over time
interactionOne conversation turn: the user’s question and the assistant’s answer
memoryStructured long-term information. Its type is fact, preference, or event
metadataKey-value information attached to a document, block, or memory
namespaceA logical collection boundary for documents, blocks, memory, and queries. It isn’t an authentication or tenant-security boundary
preferenceA memory type. It doesn’t decay over time
sessionA set of conversation turns grouped together
sourceThe original document a block belongs to

Ingestion

TermDefinition
batch submitSubmitting several documents in one request
chunkingSplitting text into blocks
database importImporting the rows of a database table or query into a namespace
embeddingTurning text into a vector
enrichmentUsing an LLM to add entities and summaries to ingested content
file uploadUploading one file as multipart. It returns the document identifier right away
ingestionEverything that happens to a document between upload and being searchable
inline uploadSubmitting text content directly in a JSON request body. Processing is asynchronous
parsingTurning a file into text
Semantic Processing Chain (SPC)The ingestion pipeline: parsing, chunking, enrichment, embedding, and indexing
taskOne asynchronous processing job. You can check its progress and cancel it
watcherTracks a directory and imports new files in it automatically

Retrieval

TermDefinition
candidate poolThe set of candidates fetched before reranking and truncation. It’s larger than top_k
coverage ratioThe share of requested namespaces that were queried successfully
cross-namespace queryQuerying several namespaces at once and merging the results
dense retrievalLooking up semantically similar content in the vector index
full-text searchLooking up content by keyword
fusionMerging the results of several retrieval paths into one list by rank
hybrid searchUsing several retrieval paths together and fusing their results
partial successReturning the parts that succeeded when some sub-operations fail, with the failures described in meta
queryA retrieval request over one or more namespaces
rerank scoreThe relevance score given by the reranker model
rerankingScoring each candidate with a cross-encoder model and reordering them
sparse retrievalLooking up content with sparse vectors

Memory operations

TermDefinition
invalidationMarking a memory as no longer valid while keeping the record
memory extractionExtracting memories from conversations automatically
soft deleteMarking something deleted while keeping it restorable or traceable, without physically removing it

Deployment and runtime

TermDefinition
admin endpointA management interface that accepts loopback requests only
execution providerThe backend that runs a model: CPU, CoreML, or CUDA
garbage collectionThe background process that removes deleted data in stages
LLM roleOne use of an LLM, configured separately. There are five: semantic_llm, vision_llm, agent_llm, doc_summary_llm, and enricher_llm
local modelThe embedding and reranking models that run on your machine and need no external service
loopback addressA network address reachable only from the same machine
model manifestThe file that records each model file’s source, size, and checksum
readiness checkThe health check that confirms the API, the models, and the data are all available
volumeThe Docker storage that holds persistent data

Interfaces

TermDefinition
authenticationConfirming who the caller is
error categoryThe classification of an error: auth, quota, transient, timeout, or permanent
structured errorAn error response that carries code, retryable, category, and retry_after_ms
tenantOne unit of isolation in the multi-tenant model
toolA callable operation that the MCP server or the framework adapters offer to an agent
traceThe record a call leaves on the server, which can be queried by session

Status labels

TermDefinition
In developmentPresent in part or being built. Not supported yet
PreviewAvailable and documented. Cortrix is in pre-release, so verify it in your own environment before production use

7 - Resources

Status, adoption boundaries, troubleshooting, and contributing.

Before you make a production, security, benchmark, or integration decision, read Compatibility and status.

7.1 - Compatibility and status

The current status of every capability.

Check here for the status of each Cortrix capability before you make a production, security, benchmark, or integration decision.

Important

Cortrix is in pre-release. The current version is v1.0.0-rc.2. Nothing in this documentation is a production-readiness commitment yet. Verify it in your own environment before you use it in production.

What each status means

StatusMeaning
PreviewAvailable and documented. Verify it in your own environment before production use
Off by defaultImplemented, but not active in the shipped configuration, where authentication is off. Turn on authentication to use it, and read what happens while it’s off
In developmentPresent in part or being built. Not supported yet. Don’t rely on it

Current status

Preview

CapabilityDocumentation
Docker quickstartQuickstart
Namespaces, document upload, and processingUpload documents
Query, cross-namespace query, and rerankingQuery and rerank
Writing, listing, editing, and deleting memories. Semantic search over explicit memories doesn’t return results in v1.0.0-rc.2Work with memory
Correcting a memory by hand: invalidate, restore, and the audit trailWork with memory
Directory watchersWatch a directory
The HTTP API and the OpenAPI specHTTP API
MCP server (local stdio)MCP server
Python SDKPython SDK
Framework adaptersFramework adapters
Fixed-flow chat in the built-in AgentBuilt-in Agent
The NVIDIA CUDA execution provider on LinuxNVIDIA CUDA
OCR and document parsers—

Off by default

These work only after you turn on authentication.

CapabilityWith authentication off
API key permissions (read, write, admin)Every request has all three

In development

  • Tenants, members, and access control
  • Tenant isolation
  • Roles (RBAC). Access is decided by an API key’s permissions
  • Quotas. Quota values can be read and updated, but requests aren’t checked against them
  • Memory extraction, including automatic handling of contradicting memories
  • pgcortrix
  • Database import
  • Log redaction

Using a preview capability

An endpoint that appears in the OpenAPI spec is part of the documented API surface. That doesn’t mean it has been verified in every runtime. When you write client code:

  • Take request and response shapes from the OpenAPI spec. This documentation notes where tested behavior differs from the spec.
  • Pin the version of your target server, and rerun your smoke tests after you upgrade Cortrix.

Authentication and security

API key permissions are off by default: Cortrix checks them only with authentication on, and with it off anyone who can reach the server’s port acts as an admin. Tenant isolation and access control are in development, and API key authentication itself hasn’t been verified for this documentation. Deploy Cortrix only on a network you control. See Security boundaries.

A namespace is a logical query scope. It isn’t an authentication or tenant-security boundary.

Benchmarks

The published benchmark numbers measure retrieval quality at top_k=10. They say nothing about end-to-end answer quality, production latency or capacity under concurrency, security or compliance, how Cortrix ranks against other products, or business outcomes. For the measurement conditions and data, see Benchmark evidence.

Before production

At a minimum, verify these in your target environment:

  • Data persistence and backup strategy
  • Deployment topology and resource limits
  • Network exposure
  • Compatibility of the API, SDK, and MCP server with your target build
  • The actual behavior of every preview capability you depend on

7.2 - Stack fit

How Cortrix relates to your existing stack: keep, add, replace, or unknown.

When you bring Cortrix into an existing stack, these decision cards show what you keep, what you add, and what you still need to verify yourself.

The cards aren’t replacement guarantees or product rankings. Each card proves only the boundary it states.

Vocabulary

TermMeaning
keepThe existing component or source of truth stays in place
addCortrix is introduced alongside the existing component
replaceA tested substitution exists for the stated boundary
unknownThe evidence isn’t sufficient to choose yet
not_supportedThe current evidence explicitly excludes the path

PostgreSQL with pgcortrix

Note

pgcortrix is in development and not supported yet. This card records what the evidence does and doesn’t establish. It isn’t a recommendation to adopt it now.

Decision fieldWhat the evidence supports
Existing stackPostgreSQL 13 through 17 with plpython3u, plus a separately running Cortrix service
Decisionkeep PostgreSQL as the business-data system. add the pgcortrix SQL-to-HTTP bridge and Cortrix. replace isn’t claimed
Tested identityCortrix 4a6299ca86c7bec21ed7b8989a729a198fe5a42a, with the standalone SQL-contract and helper tests under sql-extensions/pgcortrix/tests/. The repository marks live PostgreSQL load and pg_regress integration as not yet validated
Data movementExplicit SQL functions submit selected content to Cortrix over HTTP. Change data capture, automatic table mirroring, and two-way sync aren’t proven
Who owns syncThe application or operator owns selection, submission, resubmission, deletion, and consistency checks
Query pathPostgreSQL SQL function → plpython3u helper → Cortrix HTTP API → rows returned to SQL
Failure domainExtension installation, PL/Python availability, endpoint policy, network transport, Cortrix health, asynchronous indexing, and query execution are separate failure points
Security responsibilityA PostgreSQL superuser installs the extension. Operators own the endpoint setting, API key handling, Cortrix authentication, namespace permissions, network policy, and tenant boundaries. Security validation on a live PostgreSQL hasn’t been done yet
Exit and rollbackStop calling the SQL functions and remove the extension following PostgreSQL procedures. The source data in PostgreSQL remains authoritative. Namespaces and submitted copies in Cortrix need a separate cleanup decision
EvidenceThe pgcortrix README, SQL contract tests, helper tests, and SQL and helper seam tests

Boundary: this card supports evaluating the bridge locally as an addition. It doesn’t establish compatibility with managed PostgreSQL, live migration, automatic synchronization, production hardening, or a replacement for PostgreSQL.

See pgcortrix.

BGE-M3 embedding plus reranking

Decision fieldWhat the evidence supports
Existing stackAn application with source documents and an existing retrieval path. Compatibility with any named third-party vector database is unknown
Decisionkeep the original source documents and the application’s ownership of them. add Cortrix as a retrieval service. Whether an existing vector database can be replaced is unknown until a test against that specific stack proves data, query, and rollback parity
Data movementSource documents are ingested into Cortrix and indexed with BGE-M3. The measured profile reranks with bge-reranker-v2-m3. This creates a copy and an index managed by Cortrix
Who owns syncThe application or operator owns the initial ingest, propagating updates and deletes, draining tasks, and mapping source-document identity
Query pathApplication → Cortrix /api/v1/query → vector retrieval → reranking → mapping back to source documents. The measured profile sets rerank=true and rag_fusion=false, with LLM stages off
Tested identityBenchmark bundle commit 4b94390c1d5f7be95065e7483362ec7f93774ed7, Cortrix 79a4eb17c62521338d1ac47a9749e6230e87e69b, and public runner 9490520c24a96ed97b80073ed3ebab096b80550b. Full-corpus SciFact, NFCorpus, and FiQA with every judged test query, plus full-corpus Quora with a deterministic 2,000-query subset
Failure domainModel availability, the execution providers for embedding and reranking, ingest tasks, Cortrix storage and indexing, source mapping, and the calling application are separate failure points
Security responsibilityOperators own Cortrix authentication, namespace permissions, model provenance, network exposure, source-data policy, and deletion verification. The benchmark doesn’t prove tenant isolation or production security
Exit and rollbackKeep the original corpus and the previous query path until acceptance. Stop routing queries to Cortrix and delete the test namespaces explicitly. Exporting to a third-party index and zero-downtime cutover aren’t claimed
EvidenceThe pinned bundle README, its manifest, and the per-cell scorecards in the same bundle

Boundary: the measurements this card refers to cover retrieval quality at top_k=10 only. See Benchmark evidence.

Next steps

7.3 - Benchmark evidence

The retrieval-quality measurements that have been published, and what they apply to.

Cortrix has published one set of retrieval-quality measurements. Here are the conditions they were taken under, and what the numbers do and don’t tell you.

Measurement bundle

The measurements accepted for public use are the pinned four-corpus CPU measurement bundle, which holds results for 16 retrieval configurations.

Measurement conditions

ItemDetails
HardwareA 32-core Xeon Silver 4110 with 192 GB of RAM and no GPU
Modelsbge-m3 embedding and bge-reranker-v2-m3 reranking, both ONNX fp32 on CPU
Query shapeSerial, one query at a time, top_k=10
ScoringnDCG@10 and Recall@10 after de-duplicating by doc_id
CorpusDocumentsQueries
SciFact5,183300
NFCorpus3,633323
FiQA57,638648
Quora522,931The first 2,000 of 10,000 judged queries

SciFact, NFCorpus, and FiQA use every judged test query.

Results

The table shows nDCG@10:

DatasetTaskDense onlyWith cross-encoder reranking
SciFactScientific claim verification0.59420.6184
NFCorpusNutrition and medical QA0.29910.3121
FiQAFinancial forum QA0.25400.3125
QuoraDuplicate-question detection0.50030.2031

The three question-answering datasets gain 0.013 to 0.059 with reranking on. Quora loses 0.297.

Reranking helps question-answering tasks and hurts duplicate-detection tasks. For why, and what to do about it, see Performance tuning.

Comparability

  • The two Quora configurations query the same 8 namespaces, so the rerank flag is the only variable. This is the bundle’s only strictly controlled comparison.
  • The SciFact, NFCorpus, and FiQA configurations use independently ingested namespaces. Small differences between them fall within the variation floor the bundle discloses, roughly 0.001 to 0.003 nDCG.

What these numbers don’t show

The bundle measures retrieval quality at top_k=10. It isn’t evidence of:

  • End-to-end answer quality
  • Production latency or capacity under concurrency
  • Security or compliance properties
  • How Cortrix ranks against other products
  • Business outcomes

The latency figures quoted in this documentation are means under serial queries and don’t represent behavior under concurrent load.

Important

Act on the direction these measurements show, not on the absolute values. Verify that direction on your own corpus before you choose.

Next steps

7.4 - Troubleshooting

Common problems, what causes them, and how to fix them.

Common problems are listed here by symptom. Most entries come from testing v1.0.0-rc.2 on one macOS machine while this documentation was written, so some of them aren’t described anywhere else in the repository.

Startup

docker: 'compose' is not a docker command

The Docker Compose plugin isn’t installed. If you have the standalone version, replace docker compose with docker-compose in each command.

The first start takes a long time to return

The first start builds the image from source and downloads about 1.17 GB of models, and --wait blocks until the service is ready. To watch progress:

docker compose -f deploy/docker-compose.yml logs -f cortrix

The container’s health check allows a 30-minute start period. If a model download hits a missing file or a size or checksum mismatch, the service doesn’t report ready, and the log says why.

The model download fails because the machine can’t reach Hugging Face

Copy the model files in before the first start. See Start without access to Hugging Face.

The service never becomes ready and the log says demo upload returned HTTP 507

Cortrix stops accepting writes when the disk that holds its data is at least 90% full. The quickstart then can’t import its demo document, so the service never reports ready. The log has one line about it:

ERROR: QuickStart bootstrap: demo upload returned HTTP 507

The disk monitor logs its own line the first time it samples, which is worth grepping for as well because it names the stage and the measured percentage:

[2026-01-01 00:00:00.000] [warning] [tid:1] [disk] Disk stage crit at 97.2%

With JSON logging the same text appears in the message field. The stable part to search for is Disk stage.

The readiness response shows the disk at the crit stage:

curl -sS http://127.0.0.1:8420/api/v1/system/health/ready
"disk": { "stage": "crit", "status": "not_ready" }

At the critical stage Cortrix rejects document uploads and new processing tasks, but creating a namespace still succeeds — which is why the quickstart gets as far as the upload before it fails.

A file upload in this state returns 507 with the measured usage:

{
  "error": {
    "category": "permanent",
    "code": "CX_ERR_DISK_FULL",
    "message": "Disk usage critical (>= crit threshold). Operations rejected.",
    "retry_after_ms": null,
    "retryable": false,
    "structured_data": {
      "crit_threshold": 0.9,
      "data_path": "/data",
      "disk_usage_ratio": 0.9723306231355636,
      "free_bytes": 1745616896,
      "warn_threshold": 0.8
    }
  }
}

The disk in question is the one behind the cortrix-data volume. With Docker Desktop, Colima, or a similar tool, that is the virtual machine’s disk, not your computer’s, and it fills up with images, build cache, and other volumes. Check it from inside the container:

docker compose -f deploy/docker-compose.yml exec cortrix df -h /data

Free space on that disk, or give the virtual machine a larger one. docker system df shows what is using it.

Once there is space, the disk component recovers on its own at the next check, which happens every 30 seconds, and no restart is needed for that. A restart is only needed here because the demo import already failed, and the quickstart imports it at startup:

docker compose -f deploy/docker-compose.yml restart cortrix

At 80% the stage is warn and writes still work, which is why the readiness example in the Quickstart can show warn with status ok.

Why df -h can disagree with the reported percentage

Cortrix measures usage against the filesystem’s total size and the space actually available to it. df -h computes its Use% a little differently, and on a filesystem that keeps blocks in reserve it can read a percentage point or so lower. If the two disagree, disk_usage_ratio in the 507 body is the figure the threshold is applied to — that is the number to compare against crit_threshold, not the one from df.

Port 8420 is in use

Start on a different port:

CORTRIX_HTTP_PORT=18420 docker compose -f deploy/docker-compose.yml up --wait

Then replace 8420 with the new port in every command.

Installation

pip install cortrix-mcp reports “No matching distribution found”

cortrix-mcp requires Python 3.10 or later. With an older interpreter, pip can’t find a version it can install. Check the version, and create the virtual environment with a newer Python:

python3 --version
python3.12 -m venv .venv

cortrix and cortrix-skills need Python 3.9 or later.

Calling the API

Every Python SDK call returns 502

The SDK raises CortrixError with status code 502 and no response body, while curl to the same address works.

A system proxy is usually intercepting requests to your own machine. Bypass the proxy for local addresses:

NO_PROXY=127.0.0.1,localhost python your_script.py

A query returns 400 CX_ERR_DEPRECATED_FIELD

The query request used the singular namespace. Use the plural array instead:

{ "namespaces": ["demo"], "query": "..." }

An admin endpoint returns 403 CX_ERR_ADMIN_LOOPBACK_REQUIRED

Admin endpoints accept requests only from the loopback address. In a Docker deployment, a request from the host doesn’t look like loopback to the container. Send the request from inside the container:

docker compose -f deploy/docker-compose.yml exec cortrix \
  curl -fsS http://127.0.0.1:8420/api/v1/admin/<endpoint>

This error code is in the server code but not in the error list of the OpenAPI spec.

A query returns HTTP 200 but the results are incomplete

A cross-namespace query still returns 200 when some namespaces fail. Check meta.coverage_ratio and meta.namespaces_failed in the response.

A namespace that doesn’t exist shows up in namespaces_failed with the error code CX_ERR_INDEX_CORRUPT. When you see that, first check that the namespace name is spelled correctly:

curl -fsS http://127.0.0.1:8420/api/v1/namespaces

Ingestion

An upload returns 202 but the document never appears

An inline upload (POST /api/v1/documents) is asynchronous. An accepted request doesn’t mean processing succeeded. Check the task progress with the task_id you got back:

curl -fsS http://127.0.0.1:8420/api/v1/documents/tasks/<task_id>/progress

A non-null error_code means processing failed. A common cause is a namespace that doesn’t exist: an inline upload doesn’t check for that when you submit.

A file upload returns 404 CX_ERR_NS_NOT_FOUND

The target namespace doesn’t exist. Create it first:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"name": "your-namespace"}' \
  http://127.0.0.1:8420/api/v1/namespaces

Uploading again returns skipped

This is expected. Cortrix recognizes duplicate files by content hash. When the content hasn’t changed, it skips reprocessing and returns the original doc_id.

A watcher isn’t importing files

The watched path must be one the Cortrix server process can reach. When Cortrix runs in Docker, that means a path inside the container. Mount a host directory into the container before you watch it.

Memory

Editing or deleting a memory returns 400 ns is required

  • To edit, add ns to the request body.
  • To delete, add ns as a query parameter.

This is tested behavior that differs from the OpenAPI spec, which declares no ns parameter for deletion.

See Work with memory.

MCP

Claude Code doesn’t show the Cortrix tools

Claude Code asks you to approve an MCP server added with --scope project before using it. Check its status:

claude mcp get cortrix

If the status is Pending approval, start claude and approve it.

The MCP server fails to start because cortrix-mcp can’t be found

cortrix-mcp is installed in a virtual environment, and an MCP client doesn’t necessarily start it with that environment’s PATH. Change command in the configuration to an absolute path, for example /path/to/.venv/bin/cortrix-mcp.

GPU

For problems with a CUDA deployment, see NVIDIA CUDA.

Report a problem

If this page doesn’t cover your problem, report it in GitHub Issues. Include the version, your environment, steps to reproduce, and the request_id from the error response.

7.5 - Release notes

The scope, main changes, and known issues of v1.0.0-rc.2.

Here’s a summary of v1.0.0-rc.2. For every change with its issue and pull request, see the change-by-change release notes.

Cortrix v1.0.0-rc.2 is a pre-release for local evaluation and integration testing. It isn’t a production-readiness claim. Before you upgrade from RC1, read Upgrade and Compatibility and status.

Highlights

  • License change: Cortrix-authored RC2 material is available under the Apache License 2.0. The historical v1.0.0-rc.1 release remains under AGPL-3.0-only.
  • More reliable asynchronous ingestion: task identity is scoped to the namespace, and terminal-state transitions, cancellation races, cleanup scheduling, and retry de-duplication are all stronger.
  • Reranking can be turned off per request: for duplicate detection and similar-item lookups, set rerank=false on the query.
  • MCP works with modern and legacy clients: the local MCP server supports the modern stdio discovery path while keeping the legacy initialization handshake, and it passes session and trace identity to the Cortrix server.
  • Hardening in several places: parser output handling, sparse-vector decoding, configuration validation, memory-scope validation, and operation-log error reporting.
  • Deployment defaults are unchanged: Docker Compose still listens only on the loopback address by default, with a new explicit publish-address option for isolated test networks.

FiQA retrieval accuracy

With the non-LLM cross-encoder reranking configuration, the RC2 benchmark results on FiQA are higher than the July baseline:

MetricJuly resultAugust resultRelative change
nDCG@100.25260.3125+23.7%
Recall@100.36350.4523+24.4%

These are retrieval-accuracy measurements, not server performance measurements. The two runs differ in build, configuration, and execution environment, so the comparison doesn’t isolate the improvement to any single code change.

For the scope and limits of the measurements, see Benchmark evidence.

Compatibility notes

  • Setting rerank=false on an individual query is the verified way to turn reranking off. The namespace-level reranker_config.enabled isn’t wired into the query path yet.
  • Local stdio is the current public MCP transport.

Known issues

IssueTracking
Enrichment backfill still has open follow-ups in scheduling and transport retries#62, #78
HyPE LLM-call metrics aren’t connected to the production enrichment path yet#69
The LAN publish-address option doesn’t yet give you a complete authenticated setup without editing configuration by hand#71
Ingestion into a single namespace is constrained by serialized durability and index updates#73
Cross-encoder reranking is on by default, even for tasks where turning it off is the better choice#75
Uploading a changed version of a file, or changing a watched file, can leave the previous version’s passages in query results; the issue lists workarounds#157
The server can crash with a segmentation fault while it exits, for example after a start that can’t bind its port while document tasks are queued; make sure the port is free before you start it#196
A failed task’s progress always reports retryable_if_fail: true, even when resubmitting it will fail the same way; cap your retries#199

Release artifacts

GitHub provides source archives for the tag automatically. RC2 doesn’t promise a separately published container image or prebuilt binary unless the GitHub pre-release page explicitly attaches one. To use Cortrix, build it from source. See the Quickstart.

Full changelog

Next steps

7.6 - Contributing

How to report a problem, set up a development environment, and submit a change.

You can take part in Cortrix in several ways. Here’s a summary, along with the workflow for landing a change. The full rules are in CONTRIBUTING.md in the repository.

Ways to contribute

What you want to doWhere to go
Report a bugThe bug report form. Include steps to reproduce, expected and actual behavior, and your environment
Propose a feature or integrationThe feature and integration form. Use it to confirm scope before you open a large pull request
Improve the docsThe documentation form, or send a focused documentation pull request
Report a security vulnerabilityDon’t open a public issue. See Security boundaries

Licensing and certification

Cortrix doesn’t require a Contributor License Agreement (CLA). Contributions are accepted under the Apache License 2.0, and every new commit must carry a Signed-off-by line certifying the Developer Certificate of Origin 1.1 (DCO).

Add -s when you commit:

git commit -s

To add it to an existing local commit:

git commit --amend --signoff --no-edit

If a contribution has several commits, sign off every one. Contributors keep the copyright in their contributions.

Repository layout

  • cortrix/
    • src/The C++ server implementation
    • include/cortrix/Public C++ headers
    • api/The OpenAPI spec, components, paths, and examples
    • sdk/python/The Python SDK
    • sql-extensions/pgcortrix, the PostgreSQL extension
    • cortrix-mcp/The MCP server
    • cortrix-skills/Framework adapters
    • cortrix-agent/The built-in Agent
    • web/The Web UI
    • deploy/Compose files, Dockerfiles, and configuration
    • tests/C++ tests
    • docs/Documentation

Code comments and names carry short identifiers from the project’s design tracking. The repository’s Feature Index explains them.

Set up a development environment

If you only want to run Cortrix, the Quickstart is all you need. The source build below is for contributors who are changing Cortrix itself.

Prerequisites

ItemRequirement
Operating systemmacOS (arm64 or x86_64) or Linux (x86_64)
CompilerC++17 support: Clang 14 or later, or GCC 10 or later
CMake3.27 or later
OpenSSLInstalled through your system package manager
Python3.9 or later, for the SDK and the MCP server

CMake fetches every C++ dependency automatically.

Build the server

git clone https://github.com/cortrix/cortrix
cd cortrix
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel

./cortrix-server --config ../deploy/cortrix.yaml

For faster iteration, you can build without ONNX. Embedding then uses a stub that produces random vectors:

cmake -DCMAKE_BUILD_TYPE=Release -DCORTRIX_USE_ONNX=OFF ..

Python SDK

cd sdk/python
pip install -e ".[dev]"
pytest

Run the tests

Run the C++ tests with ctest from the build/ directory:

cd build
ctest --output-on-failure

You can also run a single suite directly: ./cortrix_unit_tests, ./cortrix_integration_tests, ./cortrix_security_tests, or ./cortrix_stability_tests.

Coding standards

  • Use C++17, in the cortrix::<module> namespace, and match the style of the surrounding code.
  • Use English only in source: comments, log messages, identifiers, and error strings.
  • A new endpoint must return the structured error fields (code, retryable, category, retry_after_ms) and carry the relevant x-cortrix-* hints in the OpenAPI spec.
  • Error codes follow the CX_ERR_* naming convention.

Version number

The VERSION file at the root of the repository is the only place the version is edited by hand. After you change it, synchronize the other locations with the script:

python3 scripts/sync_version.py
python3 scripts/sync_version.py --check

Don’t edit a derived version field on its own. CI runs the check command and rejects version drift.

Pull request workflow

  1. For anything non-trivial, open an issue first.
  2. Branch from the intended base with a short-lived name such as feat/<topic>, fix/<topic>, or docs/<topic>.
  3. Keep each pull request to one logical change.
  4. Add tests for new behavior and keep existing tests passing.
  5. If you change the API, update both api/openapi.yaml and the affected docs.
  6. Sign off every commit under the DCO.
  7. Run the full test suite locally before you push.
  8. Open the pull request against main and describe what changed, why, and how you tested it.

Branches

BranchPurpose
mainThe only integration branch for ongoing development. It doesn’t identify any published version
release/1.0The stabilization and maintenance line for the 1.0 family

Published versions are identified by immutable tags and GitHub Releases. A fix normally lands on main first and then reaches the release line through a separate backport/1.0-* pull request. Delete a pull request’s remote branch once it’s merged or closed.

Code of conduct

Participation is governed by the code of conduct in the repository (CODE_OF_CONDUCT.md). Send conduct reports privately to devrel@cortrix.ai, not through a public issue.

Next steps