This is the multi-page printable view of this section. .
Documentation
- 1: Get started
- 1.1: Overview
- 1.2: Quickstart
- 1.3: Install with an AI agent
- 1.4: Core concepts
- 2: Guides
- 2.1: Upload documents
- 2.2: Query and rerank
- 2.3: Work with memory
- 2.4: Watch a directory
- 2.5: Import from a database
- 3: Integrations
- 3.1: Choose an access path
- 3.2: MCP server
- 3.3: Python SDK
- 3.4: Framework adapters
- 3.5: Built-in Agent
- 3.6: pgcortrix
- 4: Deploy
- 4.1: Deploy with Docker Compose
- 4.2: Configuration
- 4.3: Models and ONNX
- 4.4: Performance tuning
- 4.5: NVIDIA CUDA
- 4.6: Security boundaries
- 4.7: Upgrade
- 5: Concepts
- 5.1: Architecture overview
- 5.2: Data flow
- 5.3: Interfaces
- 6: Reference
- 6.1: HTTP API
- 6.2: MCP tools
- 6.3: Configuration reference
- 6.4: Error codes
- 6.5: Glossary
- 7: Resources
- 7.1: Compatibility and status
- 7.2: Stack fit
- 7.3: Benchmark evidence
- 7.4: Troubleshooting
- 7.5: Release notes
- 7.6: Contributing
New to Cortrix? Start with Get started. If Cortrix is already running, jump to the task you have in mind.
1 - Get started
Go from a machine with only Git and Docker to a local Cortrix you can query.
1.1 - Overview
Cortrix is open source semantic storage built for AI agents. It’s agent-native storage for retrieval, memory, and API-driven AI applications.
It provides a semantic storage server with namespaces, documents, blocks, hybrid search, memory APIs, and agent-oriented access paths. It’s designed for agents and applications that need a programmable retrieval layer rather than a one-off vector database wrapper.
Cortrix is in active pre-release. The current version is v1.0.0-rc.2. Interfaces and features are at different levels of maturity, and authentication, authorization, and production readiness are not established. See Compatibility and status.
What is semantic storage?
Semantic storage connects information with the context an application needs to use it. Cortrix does this through retrieval, memory records, and links back to sources.
That maps to three needs in agent work:
| Need | What it means |
|---|---|
| Agent workflows | An agent needs to read source material, use tools, and keep track of what happened |
| Context for a task | A useful answer needs relevant material at the right moment. Storage keeps that material available, and retrieval decides which passages belong in the prompt |
| Memory across tasks | Some experience is worth carrying into the next task. Storage preserves it, but the system still needs to check whether an old observation applies |
Design
- Agent-native: designed around agent data workflows. Semantic processing, memory, and traceability are shared storage concerns rather than scattered integration code.
- Semantic storage: documents are parsed, chunked, embedded, and indexed in a shared semantic layer, so agent workflows can query meaning and source context together.
- Built to fit existing stacks: works with your existing databases, tools, and agent workflows while giving retrieval, memory, and audit a shared semantic layer.
Building blocks
| Building block | What it covers |
|---|---|
| Semantic Processing Chain (SPC) | Parsing, OCR fallback, chunking, enrichment, embedding, and indexing |
| Hybrid query and reranker | Vector search, BM25, rank fusion, and reranking |
| AI interaction memory | Memory APIs and typed memory records |
| Agent observability | Session, trace, and agent identity |
| Source-level traceability | Inspectable source context across chunks, documents, and turns |
| Namespaces and cross-namespace query | Logical query scope for projects and workflows |
| Local embedding | ONNX Runtime and BGE-M3 |
| Access paths | HTTP, MCP, the Python SDK, framework adapters, data import, and PostgreSQL |
A namespace is a logical query scope. It is not an authentication, authorization, access-control, or tenant-security boundary.
Components in the repository
| Component | Location | Role |
|---|---|---|
cortrix-server | src/ | The C++ backend and HTTP API |
| OpenAPI spec | api/openapi.yaml | The public HTTP API contract |
| MCP server | cortrix-mcp/ | An MCP server for IDE and agent clients |
| Python SDK | sdk/python/ | The Python client |
| Built-in Agent | cortrix-agent/ | A fixed-flow RAG chat service |
| Web UI | web/ | The local web interface |
Access paths
| Path | Best for |
|---|---|
| HTTP API | Your own services, or direct calls from an agent |
| MCP server | IDE agents and MCP-compatible clients |
| Python SDK | Python applications and RAG pipelines |
| Built-in Agent | Local fixed-flow chat over Cortrix storage |
To pick one, see Choose an access path.
Current status
Cortrix is in pre-release. To see whether a capability is in preview or in development, see Compatibility and status.
License
Cortrix Core is licensed under Apache-2.0. That applies to v1.0.0-rc.2 and later. The historical v1.0.0-rc.1 release remains under AGPL-3.0-only. Third-party material keeps its own license.
Next steps
- Quickstart: start Cortrix with Docker and run your first query.
- Install with an AI agent: hand setup and verification to an AI agent.
- Core concepts: learn about namespaces, documents, blocks, queries, and memory.
1.2 - Quickstart
In this quickstart you’ll start Cortrix v1.0.0-rc.2 on your machine with Docker and run a reranked query against the bundled demo document. The whole path uses real local embedding and reranking models, and you don’t need a key for any LLM service.
If you’d rather have an AI agent run these steps, see Install with an AI agent.
Prerequisites
- Git
- Docker with Docker Compose
curl- Enough disk space for the image, the build cache, and about 1.17 GB of model files
You don’t need a .env file, an LLM provider key, model tooling on the host, or any manual model download or conversion.
Steps
Clone and start
The first start builds the image from source and downloads the model files into the cortrix-data volume (its full name in Docker is deploy_cortrix-data). Later starts reuse that volume.
The command returns only when the service is ready. It ends with:
How long the first start takes depends on your machine and network. On an Apple silicon Mac with 5 CPUs assigned to Docker, the image build took about 6 minutes and the model download took under a minute.
If you see docker: unknown command: docker compose, the Compose plugin isn’t installed. If you have the standalone version, replace docker compose with docker-compose in each command.
Check readiness
status should be ready, and every component’s status should be ok:
Compose reports the service healthy only once the API, the embedding model, the reranker model, and the demo document are all ready. If a model download hits a missing file, a size or checksum mismatch, a symbolic link, or a download error, it fails outright rather than starting with incomplete models.
Run a reranked query
The response should include content from quickstart-demo.txt and a numeric rerank_score. Here is a real response, with metadata shortened:
Identifiers, latency, and scores will differ on your machine.
Stop or reset
To stop the service and keep your data and the downloaded models:
To remove the data and models as well:
--volumes deletes the cortrix-data volume. The next start downloads about 1.17 GB of models again.
What this path verifies
The quickstart:
- Builds the local Docker image from the checked-out source.
- Downloads pinned versions of the BGE-M3 embedding model and the bge-reranker-v2-m3 reranker.
- Publishes only the API, at
127.0.0.1:8420. The metrics port and the built-in Agent port aren’t published. - Keeps every external LLM role and the built-in Agent turned off.
- Sends a query with a plural
namespacesarray andrerank=true, and gets back source-backed demo content with numeric rerank scores.
It does not cover PDF, DOCX, images, OCR, authentication, internet-facing deployment, or retrieval-quality benchmarks, and it doesn’t establish production readiness.
The quickstart service has no authentication. By default Compose publishes it only on the host’s loopback address, so other machines can’t reach it. Don’t treat it as an internet-facing deployment.
Model provenance and integrity
deploy/model-manifest.tsv in the repository pins the repository, revision, path, expected size, SHA-256, upstream repository, upstream revision, and upstream license for every downloaded file.
| Purpose | Model | Source |
|---|---|---|
| Embedding | onnx-community/bge-m3-ONNX | Derived from BAAI/bge-m3 |
| Reranking | onnx-community/bge-reranker-v2-m3-ONNX | Derived from BAAI/bge-reranker-v2-m3 |
At startup, Cortrix downloads each manifest entry, verifies its size and SHA-256, and installs it atomically. If anything doesn’t match, the service doesn’t report ready.
Next steps
- Core concepts: understand the namespace, blocks, and query you just used.
- Choose an access path: connect to the running service through MCP or the Python SDK.
- Compatibility and status: see the current status of every capability.
1.3 - Install with an AI agent
On this page you’ll get a task brief you can hand to a terminal-capable AI agent. The agent installs Cortrix v1.0.0-rc.2 on your machine, verifies it, and returns a structured report.
This path runs the same loopback-only Docker flow as the Quickstart. It’s a local first-value setup, not an internet-facing, cloud, security, or production deployment procedure.
Prerequisites
The AI agent needs to be able to use your local filesystem, Git, Docker, Docker Compose, and curl. It can be a coding assistant or a broader agent runtime. Whether it qualifies depends on those capabilities. This page doesn’t claim that every version or configuration of any particular product has been validated.
Contract identity
Both the release tag and the full commit it resolves to must be recorded. A checkout of the mutable main branch doesn’t satisfy this contract.
What the agent may do
- Inspect local prerequisites: Git, Docker, Docker Compose,
curl, disk, network, and ports. - Create one new installation directory.
- Clone the declared repository and check out the declared release.
- Build and start the documented Docker Compose stack.
- Download the pinned model files that stack needs.
- Call the readiness and query endpoints on the loopback address.
- Leave the verified local service running.
- Report the files, containers, volumes, and commands it used.
What the agent must not do
- Modify, reset, delete, or reuse an existing Cortrix checkout.
- Use
sudoor install system-level dependencies without separate approval from you. - Request, read, store, or invent keys for LLM, cloud, GitHub, or any other service.
- Change firewall, DNS, proxy, VPN, or system security settings.
- Publish Cortrix on
0.0.0.0or any non-loopback address. - Turn off ONNX, embedding, reranking, model checksums, readiness, or source verification to make the run pass.
- Delete existing Docker images, containers, caches, or volumes.
- Run
docker compose down --volumesunless you explicitly ask for it. - Describe this contract as a production deployment or as production readiness.
Copyable agent task
Give your AI agent this brief exactly as written. It’s contract text, so don’t reword it:
Required execution path
The agent must create a new cortrix directory under a parent directory you approve. If cortrix already exists there, it must stop rather than overwrite or reuse it.
The first start downloads about 1.17 GB of pinned model files and can take several minutes. No .env file, provider key, host-side model tooling, manual model download or conversion, or separate bootstrap command is required.
Required verification
Readiness:
A source-backed reranked query:
The result must contain content from quickstart-demo.txt and a numeric rerank_score. A process that exits successfully without those two assertions is still a failed contract.
Required final report
PASS requires all of these: the exact repository and release, the 40-character commit that the tag resolves to, a loopback-only bind, readiness, source content, numeric rerank scores, external LLM roles left off, and a running service.
Failure behavior
The agent must stop and return FAIL when:
- A prerequisite is missing.
- The target directory already exists.
- The tag or commit doesn’t match what was expected.
- The API port is in use.
- The Docker build, a download, an integrity check, startup, or readiness fails.
- The query fails or lacks the required source content.
rerank_scoreis absent or isn’t numeric.- The service binds beyond the loopback address.
- Finishing the task would require a prohibited action.
The report must preserve the original error and name the next decision you need to make. The agent must not quietly switch to a different build profile or to weaker verification.
Stop or reset
After you’ve reviewed the report, you can ask the agent to stop the service:
Removing the cached models and local data is a separate, destructive decision that’s yours to make:
The agent must not run the cleanup command with --volumes unless you explicitly ask for it.
What this path doesn’t verify
An agent-assisted install doesn’t verify every HTTP API, parser, the built-in Agent, MCP, the SDK, authentication, tenants, security, benchmarks, or production behavior. Before you expand the deployment, read Compatibility and status and Choose an access path.
Next steps
- Quickstart: run the same flow yourself.
- Choose an access path
- Compatibility and status
1.4 - Core concepts
You’ll keep running into six concepts when you use Cortrix. Here’s what each one means and how they relate.
How the concepts relate
flowchart LR
NS[Namespace] --> DOC[Document]
DOC --> BLK[Block]
NS --> MEM[Memory]
MEM --> BLK
Q[Query] --> BLKDocuments and memories both belong to a namespace. Documents and memory records produce blocks, and blocks are what a query searches.
Namespace
A namespace is a logical collection boundary for documents, blocks, memory, and queries. You name a namespace when you write, and you list one or more namespaces when you query.
Document
A document is source material you upload to Cortrix. It can be parsed and indexed.
Block
A block is the smallest searchable unit, derived from a document or a memory record. Query results are blocks, along with the source each one came from.
Query
A query is a retrieval request over one or more namespaces. The request names its scope with a plural namespaces array:
The deprecated singular namespace field is rejected on query requests. Other endpoints may still use a singular namespace field where their OpenAPI definition requires it.
Memory
Memory is structured long-term information, captured from interactions or written explicitly through the API.
Agent surface
An agent surface is a programmatic path that lets an agent use Cortrix: the HTTP API, MCP, the Python SDK, or the built-in Agent service.
Local models and LLM roles
These two are easy to mix up:
- Local neural models: the quickstart uses two local ONNX models. BGE-M3 handles embedding and bge-reranker-v2-m3 handles reranking. They run on your machine’s CPU and send nothing to an external service.
- LLM roles:
semantic_llm,vision_llm,agent_llm,doc_summary_llm, andenricher_llmare separate, optional capabilities. You configure them only when you’re testing a feature that uses them.
So LLM_ENABLED=false doesn’t mean embedding or reranking is off.
Next steps
2 - Guides
Each guide covers one task, with commands you can copy and the output to expect.
2.1 - Upload documents
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.
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 upload | Inline upload | |
|---|---|---|
| Endpoint | POST /api/v1/namespaces/{ns}/documents | POST /api/v1/documents |
| Request body | multipart/form-data | JSON |
| Best for | Uploading a file, including binary files | Text your program already has in memory |
| Returns | A doc_id right away | A task_id; processing is asynchronous |
| If the namespace doesn’t exist | 404 right away | The 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
Upload a file
First create a text file:
Upload it as multipart. file is required. title and metadata (a JSON string) are optional:
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:
Upload inline content
namespace and content are required. filename and metadata are optional:
The service returns HTTP 202 and a task:
Check task progress
Look up the task with the task_id from the previous step:
A status of completed with error_code set to null means processing succeeded. meta.agent_decision_hint tells an agent what to do next.
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
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:
Delete a document
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:
Next steps
- Query and rerank: query the documents you just uploaded.
- Python SDK: do the same thing with
client.documents.upload(). - HTTP API reference
2.2 - Query and rerank
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
guidenamespace from Upload documents.
Run a query
Every query goes through one endpoint, POST /api/v1/query. query and namespaces are required:
The response has two parts, meta and results. Only the key fields of results are shown here:
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
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | Required | The query text |
namespaces | string array | Required | The namespaces to search |
top_k | integer | 10 | How many results to return. The minimum is 1 |
rerank | boolean | true | Whether to reorder candidates with the reranker model |
include_sources | boolean | — | When true, results include source information |
filter | object | — | Filter conditions |
For the full request shape, see the HTTP API reference.
Use the plural namespaces array. A singular namespace is rejected:
Read the results
Each result is a block:
| Field | Meaning |
|---|---|
content | The block’s text |
namespace | The namespace the block belongs to |
metadata.source_path | The original filename of the source document |
rerank_score | The relevance score from the reranker model |
score | The 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:
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:
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:
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:
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 | When it appears | reason | category | retry_after_ms | What to do |
|---|---|---|---|---|---|
CX_WARN_RERANK_DISABLED | The request sets "rerank": false. Ordering uses the fused retrieval score instead of the reranker model. | rerank_disabled | permanent | — | 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_DEGRADED | The 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_degraded | transient | 1000 | Results 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_DEGRADED | The 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_degraded | transient | 5000 | Results 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:
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
- Work with memory
- Python SDK: run the same query with
client.search(). - HTTP API reference
2.3 - Work with memory
On this page you’ll write memories explicitly through the API, then list, edit, and delete them.
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:
Memory types
| Type | Meaning |
|---|---|
fact | A fact |
preference | A preference |
event | An 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:
A memory written this way is an explicit memory. It isn’t validated by an LLM.
List memories
Query parameters:
| Parameter | Description |
|---|---|
namespace | Required |
memory_type | List only one type: fact, preference, or event |
include_invalidated | When true, also return invalidated memories. The default is false |
limit, offset | Paging |
Edit a memory
An edit doesn’t overwrite the original. Cortrix creates a new memory and marks the old one invalidated:
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:
Invalidated memories don’t appear in the list by default. Add include_invalidated=true to see them:
Sessions
A memory session groups a set of conversation turns. namespace is required when you create one:
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
| Capability | Status |
|---|---|
| Automatic memory extraction from conversations | In development. Not supported yet |
| Automatic handling of contradicting memories | In 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
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:
Create the namespace that receives the files:
Add a watcher
path and target_namespaces are required. recursive defaults to true, which includes subdirectories:
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:
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:
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:
Remove a watcher, along with all of its namespace subscriptions:
A successful removal returns HTTP 204.
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
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
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
Cortrix has four access paths. This page helps you pick the one that fits your situation.
How to choose
| Your situation | Choose |
|---|---|
| You need precise control over requests, retries, authentication, and deployment, or you’re not using Python | HTTP API |
| You want an agent in your IDE, or another MCP-compatible client, to call Cortrix | MCP server |
| You’re writing a Python application, a RAG pipeline, or a test script | Python SDK |
| You want local fixed-flow chat over what’s in Cortrix, without wiring up an agent framework | Built-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:
Run a 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
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.
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:
This gives you the cortrix-mcp command, which is the entry point for the MCP stdio server. Confirm the install:
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:
| Variable | Purpose | Default |
|---|---|---|
CORTRIX_URL | The address of cortrix-server | http://127.0.0.1:8420 |
CORTRIX_NAMESPACE | The default namespace | default |
CORTRIX_API_KEY | A Bearer token or API key for the target server | Empty |
CORTRIX_MCP_ADMIN | Turns on admin tools when the server accepts the caller as an admin | false |
CORTRIX_MCP_TIMEOUT | HTTP timeout, in seconds | 30 |
CORTRIX_AGENT_ID | The 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 default | cortrix-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:
This creates .mcp.json in the current directory:
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.
.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:
Cline
Add this to cline_mcp_settings.json in your VS Code user directory:
Verify
Once connected, ask the agent to call cortrix_health. The result’s meta.category should be success:
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:
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:
Keep them on in a session that also edits code: Claude Code reads a file before it edits it.
Tools
| Group | Tools |
|---|---|
| Core | cortrix_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 |
| Extended | cortrix_cross_ns_query, cortrix_async_upload, cortrix_memory_search_filter, cortrix_memory_extract_trigger |
| Tasks and explain | cortrix_memory_extract, cortrix_task_status, cortrix_cancel_task, cortrix_query_explain |
| Memory and operations | cortrix_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 |
| Admin | cortrix_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 code | Retryable | Category | Suggested wait (ms) |
|---|---|---|---|
CX_ERR_MCP_BACKEND_TIMEOUT | Yes | transient | 1000 |
CX_ERR_MCP_BACKEND_UNAVAILABLE | Yes | transient | 5000 |
CX_ERR_MCP_SCHEMA_VALIDATION_FAIL | No | permanent | — |
CX_ERR_MCP_TOOL_NOT_FOUND | No | permanent | — |
CX_ERR_MCP_AUTH_MISSING | No | auth | — |
CX_ERR_MCP_ADMIN_REQUIRED | No | auth | — |
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:
Protocol compatibility
- The modern protocol
2026-07-28, throughserver/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
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:
Confirm the installed version:
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:
Run it:
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").
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:
Client options
| Option | Purpose |
|---|---|
base_url | The service address. Defaults to http://localhost:8420 |
api_key | An API key. Optional |
tenant_id | A tenant identifier. Optional |
timeout | The request timeout |
max_retries | The maximum number of automatic retries |
http_client | Pass in your own httpx.Client |
client_id | Sent as the X-Client-Id header to tell callers apart |
trace_id_provider | A function that returns a W3C traceparent, for distributed tracing |
Query
client.search() maps to POST /query. The first argument can be a single namespace, a list of namespaces, or ["*"] for all of them:
| Parameter | Default | Purpose |
|---|---|---|
top_k | 10 | How many results to return |
rerank | True | Whether to rerank |
include_sources | False | Whether to return source information |
filters | None | Filter conditions |
coverage_ratio, namespaces_succeeded, and namespaces_failed in results.meta tell you whether a cross-namespace query fully succeeded.
Upload documents
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:
Resources
| Resource | Methods |
|---|---|
client.documents | upload, list, get, status, task_progress, cancel_task, delete |
client.namespaces | create, list, get, update, delete, set_permission |
client.search(...) | Semantic query |
client.memory | search, log, list, create, update, delete |
client.watchers | add, list, remove, events |
client.system | health, version, namespace_stats, agent_llm_config |
client.ops.gc | status, run, restore, purge |
client.import_database(...) In development | Start a database import manually |
client.tenants In development | list, 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:
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:
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
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:
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
CortrixToolKit is lazy: it makes no network request until you call a method.
| Parameter | Default | Description |
|---|---|---|
base_url | — | Required unless you pass client |
api_key | None | A 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
OpenAI function calling
LangChain
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:
| Framework | How an error appears |
|---|---|
| LangChain | A ToolException whose message is these fields as JSON |
| Claude Tools | A tool_result with is_error=True whose content is these fields as JSON |
| OpenAI | These 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
- MCP server: the full list of tools.
- Python SDK
3.5 - Built-in Agent
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:
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_llmrole.
Start the service
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
The expected response shape:
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:
| Input | Location | Notes |
|---|---|---|
message | Request body | The user message |
session_id | Request body | An optional session identifier |
Authorization | Header | An optional Bearer token, depending on the server’s authentication mode |
X-Cortrix-Tenant-Id | Header | An optional tenant identifier |
X-Cortrix-Namespace | Header | Optional. Names the namespace |
explain=true | Query parameter | Returns extra explanation metadata |
debug=true | Query parameter | Returns more detail on failure |
Example SSE frames:
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
| Endpoint | Purpose |
|---|---|
GET /sessions/{id} | Returns the recent turns a session keeps in memory |
GET /config | Returns the current LLM configuration with the API key masked |
GET /config/providers | Returns the LLM provider catalog used by the configuration UI |
PUT /config/agent_llm | Updates the LLM configuration. Persisting it isn’t a verified capability yet |
GET /health | Returns service status, backend reachability, and LLM reachability |
Next steps
- Choose an access path
- Configuration: configure LLMs by role.
- Compatibility and status
3.6 - pgcortrix
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
For whoever runs Cortrix: deployment, configuration, models, and execution providers.
4.1 - Deploy with Docker Compose
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.
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
| Item | Details |
|---|---|
| Compose file | deploy/docker-compose.yml |
| Image | Built from source with deploy/Dockerfile and tagged cortrix:quickstart |
| Service | One cortrix container running cortrix-server and the Web UI |
| Port | 127.0.0.1:8420, shared by the API and the Web UI |
| Volume | cortrix-data, mounted at /data in the container |
| Execution provider | CPU for both embedding and reranking |
| Off by default | External 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
down keeps the volume. On later starts you can drop --build to skip rebuilding the image.
Check status
Cortrix has three health endpoints:
| Endpoint | What it tells you |
|---|---|
/api/v1/system/health/live | Whether the process is alive |
/api/v1/system/health/ready | Whether the API, the models, and the demo data are all ready |
/api/v1/health | A summary of each component |
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 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:
Any machine that can route to that address can then reach the Web UI and API at http://10.0.0.5:18420/.
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:
Next steps
4.2 - Configuration
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
| Method | Use it when | Template |
|---|---|---|
| YAML configuration file | You build from source and run cortrix-server directly | config.yaml.example |
| Environment variables | You deploy with Docker | deploy/.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:
Environment variables
For a Docker deployment, copy the template to .env and edit what you need:
Common variables:
| Variable | Value in the template | Purpose |
|---|---|---|
CORTRIX_DATA_DIR | /data | The data directory |
CORTRIX_HTTP_PORT | 8420 | The HTTP port |
CORTRIX_LOG_LEVEL | info | The log level |
CORTRIX_PROFILE | quickstart | quickstart 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_PROVIDER | auto | The execution provider for embedding |
CORTRIX_RERANKER_EXECUTION_PROVIDER | auto | The execution provider for reranking |
CORTRIX_WEB_UI_ENABLED | true | Whether the Web UI is on |
CORTRIX_AGENT_ENABLED | true | Whether the built-in Agent is on |
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
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
Running without authentication is accepted only when the server binds to the loopback address. With authentication on, the configuration looks like this:
key_hash is the SHA-256 of the key. The configuration file never holds the key itself:
Logging
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.
| Role | Used for |
|---|---|
semantic_llm | Query-side semantic processing such as intent classification |
vision_llm | Refining image recognition after OCR. The model must accept image input |
agent_llm | Chat in the built-in Agent |
doc_summary_llm | Generating document summaries at ingest time |
enricher_llm | Enriching 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:
provider can be openai, glm, claude, ollama, deepseek, or mock.
Roles use two different protocols
| Role | Called by | Protocol |
|---|---|---|
agent_llm | The built-in Agent (Python) | Each provider’s native protocol |
| The other four | cortrix-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 setbase_url:config.yamlFor the other four roles, go through an OpenAI-compatible proxy gateway and point
base_urlat it:config.yaml
OpenAI, GLM, DeepSeek, and a local OpenAI-compatible gateway work directly in every role.
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
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.
| Model | Role | Download size | Pinned source | Upstream and license |
|---|---|---|---|---|
| BGE-M3 | Embedding | 585,562,194 bytes | onnx-community/bge-m3-ONNX@25b9af8 | BAAI/bge-m3@5617a9f, MIT |
| bge-reranker-v2-m3 | Reranking | 587,809,994 bytes | onnx-community/bge-reranker-v2-m3-ONNX@6f5ff65 | BAAI/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:
| Component | Installed at |
|---|---|
embedding_model | bge-m3/model.onnx |
embedding_tokenizer | bge-m3/tokenizer.json |
reranker_model | bge-reranker-v2-m3/model.onnx |
reranker_tokenizer | bge-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:
- Fetches the exact revision and path in the manifest.
- Rejects symbolic links.
- Checks the byte size and SHA-256.
- 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.
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
./modelsdoesn’t exist yet, or the files land one level too deep:The
modelsdirectory holdsbge-m3/,bge-reranker-v2-m3/, andMANIFEST.tsv, about 1.17 GB in total.Move the
modelsdirectory to the machine that has no access.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 cpcreates the copied files as root, and the service runs ascortrix. Without thechown, 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:
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.
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
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:
dimensionis fixed at 1024 and can’t be changed.- An empty
embedding.model_pathis 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_direxplicitly 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
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.
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:
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
| Setting | Where | Default | Affects |
|---|---|---|---|
rerank | Query request | true | Query latency and result ordering |
top_k | Query request | 10 | How many results come back, and the candidate pool size |
retrieval.candidate_multiplier | Configuration file | 3 | Candidate pool size |
retrieval.max_candidates | Configuration file | 50 | The candidate pool ceiling, and so the recall ceiling |
embedding.execution_provider | Configuration file | auto | Where embedding runs |
reranker.execution_provider | Configuration file | auto | Where reranking runs |
server.thread_count | Configuration file | 4 | The server’s worker threads |
spc.worker_count | Configuration file | 2 | How many documents are processed in parallel |
spc.embedding_batch_size | Configuration file | 1 | Blocks embedded per batch |
spc.onnx_intra_threads | Configuration file | 4 | Intra-op threads for ONNX inference |
spc.onnx_inter_threads | Configuration file | 1 | Parallel 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:
| Setting | Median latency_ms |
|---|---|
rerank: true | 242 |
rerank: false | 52 |
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 task | Examples | Recommendation |
|---|---|---|
| Questions and answers | Documentation search, finding solutions in support tickets, grounding a RAG answer | Leave it on |
| Finding identical or duplicate items | Duplicate-question detection | Turn 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.
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:
- A larger
top_kmeans more candidates and more content returned. max_candidatesis a hard ceiling. On a large corpus, relevant documents can rank below 50, so raisingmax_candidatesis the only way to lift the recall ceiling.
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:
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:
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:
| Setting | Purpose |
|---|---|
worker_count | Threads processing documents in parallel. 2 to 4 is recommended |
embedding_batch_size | Blocks sent to the embedding model per batch |
onnx_intra_threads | Threads used inside a single ONNX inference |
onnx_inter_threads | ONNX inferences that run in parallel |
chunk_size | The 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:
Server
server.thread_countis the number of worker threads handling requests. The recommended value is your CPU core count. You can override it withCORTRIX_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
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.
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 driver | Notes |
|---|---|
>= 520.61.05 | The required baseline, and the recommended version for deployment |
>= 450.80.02 and < 520.61.05 | NVIDIA documents compatibility in this range, with limitations. Cortrix doesn’t treat this range as validated |
< 450.80.02 | Below the compatibility floor for CUDA 11.8. Don’t use it |
Check the host before you build:
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:
| Value | Behavior in the CUDA image |
|---|---|
auto | Try CUDA first. If it fails, record the reason and create a fresh CPU-only session |
cpu | Use the CPU without trying CUDA |
cuda | Require CUDA. A failure aborts startup, with no CPU fallback |
coreml | For 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
At a minimum, confirm these settings:
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
The build is restricted to linux/amd64, and model files aren’t baked into the image.
Start the stack
Follow the startup log until the service is healthy:
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
Only the GPUs selected by NVIDIA_VISIBLE_DEVICES should be listed.
Check the runtime libraries
This command succeeds only when there are no missing dependencies.
Check the active execution provider
Look at components.embedding_execution_provider and components.reranker_execution_provider:
| Situation | What you see |
|---|---|
| CUDA is working | active_ep is cuda |
auto fell back to the CPU | The service is still ready, but fallback is true, active_ep is cpu, and preferred_ep is cuda |
| The explicit setting and reality don’t match | The service isn’t ready, and policy_mismatch is true |
| No model is configured | model_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:
A CUDA build includes this line:
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:
Roll back to CPU
To switch back to the default CPU image and keep the data volume:
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
| Symptom | What to do |
|---|---|
| Docker reports that no GPU driver is available | Confirm nvidia-smi works on the host, and that NVIDIA Container Toolkit is installed and configured for Docker |
| The container is rejected before the entrypoint runs | Check 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 GPU | Check the value of NVIDIA_VISIBLE_DEVICES, and that NVIDIA_DRIVER_CAPABILITIES includes compute,utility |
ldd reports CUDA or cuDNN libraries as not found | Rebuild from deploy/Dockerfile.cuda and confirm the runtime stage is the CUDA 11.8 and cuDNN 8 image |
Next steps
4.6 - Security boundaries
Read this before you deploy Cortrix anywhere beyond your own machine. It covers what Cortrix can and can’t guarantee about security today.
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_HOSThas 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
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.
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=falseon 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
- Stop the RC2 environment.
- Restore the RC1 configuration and data backup you recorded.
- Check out the immutable
v1.0.0-rc.1tag.
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
These pages explain why Cortrix works the way it does. They don’t contain steps to follow.
5.1 - Architecture overview
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 --> STORETwo 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.yamlis 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:
| What | How it’s stored |
|---|---|
| The vector index | A persistent HNSW index with snapshots and a write-ahead log |
| Metadata, the full-text index, and tasks | SQLite |
| The original uploaded files | File 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
| Directory | Component | Language |
|---|---|---|
src/, include/ | cortrix-server | C++17 |
api/ | The OpenAPI spec | YAML |
cortrix-mcp/ | MCP server | Python |
sdk/python/ | Python SDK | Python |
cortrix-skills/ | Framework adapters | Python |
cortrix-agent/ | Built-in Agent | Python |
sql-extensions/pgcortrix/ | PostgreSQL extension | SQL, Python |
web/ | Web UI | TypeScript |
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
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:
- 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.
- Hard delete: once the retention period passes, garbage collection removes the document’s records.
- 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
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:
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:
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:
| Value | Meaning |
|---|---|
done_fetch_doc | Processing finished. You can read the document |
inspect_error_code | Processing 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:
| Metadata | The question it answers |
|---|---|
| Side-effect category | Is this call read-only, a write, or destructive? |
| Retryability and retry strategy | Can it be retried after a failure, and how? |
| Authorization scope | What permission does it need? |
| Rate limit | How 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:
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
Use this section when you need to look up exact behavior.
6.1 - HTTP API
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
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.
Tools marked In development have no documentation yet.
Health and namespaces
| Tool | What it does | Parameters |
|---|---|---|
cortrix_health | Checks that the Cortrix service is running and reachable | — |
cortrix_list_namespaces | Lists the namespaces you have access to | limit, offset |
cortrix_create_namespace | Creates a namespace | name* |
Query
| Tool | What it does | Parameters |
|---|---|---|
cortrix_query | Runs a semantic query over one or more namespaces | query*, top_k, namespaces, rerank |
cortrix_cross_ns_query | Queries across several namespaces | query*, namespaces*, top_k, rerank |
cortrix_query_explain | Runs a query and returns an explanation of the path it took | query*, top_k, namespaces, rerank |
For cortrix_query, top_k defaults to 5 and rerank defaults to true.
Documents
| Tool | What it does | Parameters |
|---|---|---|
cortrix_upload | Uploads document content for asynchronous processing and returns a task | content*, namespace, filename, metadata |
cortrix_async_upload | Uploads a larger document asynchronously and returns a task | content*, namespace, filename, metadata |
cortrix_batch_submit | Submits up to 100 documents to one namespace at once | namespace*, documents*, async_, on_duplicate |
cortrix_list_documents | Lists the documents in a namespace | namespace, limit, offset |
cortrix_document_status | Shows a document’s processing status and details | doc_id*, namespace |
cortrix_task_status | Shows the progress of an asynchronous upload task | task_id* |
cortrix_cancel_task | Cancels an asynchronous upload task | task_id* |
Directory watchers
| Tool | What it does | Parameters |
|---|---|---|
cortrix_add_watcher | Adds a watcher that imports the files in a directory automatically | data_dir*, namespace, recursive |
cortrix_list_watchers | Lists all watchers | — |
Memory
| Tool | What it does | Parameters |
|---|---|---|
cortrix_memory_create | Creates a memory | namespace*, content*, memory_type*, metadata |
cortrix_memory_list | Lists memories | namespace, memory_type, include_invalidated, limit, offset |
cortrix_memory_edit | Edits a memory’s content or metadata | memory_id*, namespace, content, metadata |
cortrix_memory_invalidate | Soft-deletes a memory | memory_id*, namespace, reason |
cortrix_memory_search | Runs a semantic search over conversation memory | query*, namespace, top_k |
cortrix_memory_search_filter | Searches memory filtered by memory type | query*, memory_type*, namespace, top_k |
cortrix_memory_opt_out | Opts a session out of memory, or revokes the opt-out | session_id*, opt_out, namespace, reason |
cortrix_memory_get_audit | Queries the memory audit records | memory_id, namespace, limit |
These tools are In development:
| Tool | What it does | Parameters |
|---|---|---|
cortrix_memory_extract | Extracts memories from a conversation in one call | messages*, namespace |
cortrix_memory_extract_trigger | Triggers memory extraction for a session manually | namespace, session_id |
cortrix_memory_revoke_fact | Revokes an automatically extracted fact | memory_id*, namespace |
Interactions and the operation log
| Tool | What it does | Parameters |
|---|---|---|
cortrix_log_interaction | Saves a conversation turn: the user’s question and the assistant’s answer | session_id*, query_text*, response_text*, namespace |
cortrix_list_interactions | Lists a user’s interactions | namespace*, user_id*, filter, limit, offset |
cortrix_list_operations | Queries the operation log | user_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.
| Tool | What it does | Parameters |
|---|---|---|
cortrix_admin_db_credential_register | Registers a database connection credential | name, dsn, expire_days, connection_ref, description |
cortrix_admin_db_import_run | Starts a database import | connection_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 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
| Key | Default | Description |
|---|---|---|
host | "127.0.0.1" | The address to listen on. Binding to a non-loopback address requires authentication to be on |
port | 8420 | The HTTP port |
thread_count | 4 | Worker threads. The recommended value is your CPU core count. Environment variable: CORTRIX_SERVER_THREADS |
auth
| Key | Default | Description |
|---|---|---|
enabled | false | Whether 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_at | 0 | Expiry time. 0 never expires |
log
| Key | Default | Description |
|---|---|---|
level | "info" | trace, debug, info, warn, error, critical, or off |
format | "text" | text or json |
output | "stdout" | stdout, stderr, or a file path |
namespace
| Key | Default | Description |
|---|---|---|
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
| Key | Default | Description |
|---|---|---|
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 |
dimension | 1024 | The vector dimension. Fixed at 1024 for bge-m3 and can’t be changed |
max_seq_length | 512 | The maximum tokens per encode |
execution_provider | "auto" | auto, cpu, coreml, or cuda. Environment variable: CORTRIX_EMBEDDING_EXECUTION_PROVIDER |
reranker
| Key | Default | Description |
|---|---|---|
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
| Key | Default | Description |
|---|---|---|
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
| Key | Default | Description |
|---|---|---|
candidate_multiplier | 3 | How many times top_k the candidate pool is, at least 1. Environment variable: CORTRIX_RETRIEVAL_CANDIDATE_MULTIPLIER |
max_candidates | 50 | The 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).
| Key | Default | Description |
|---|---|---|
worker_count | 2 | Threads processing in parallel. 2 to 4 is recommended |
chunk_size | 512 | The target number of tokens per text block |
chunk_overlap | 50 | Tokens shared between neighboring blocks |
embedding_batch_size | 1 | Blocks embedded per batch |
onnx_intra_threads | 4 | Intra-op threads for ONNX inference |
onnx_inter_threads | 1 | Parallel 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_s | 120 | Document parsing timeout, in seconds |
ocr_timeout_s | 3600 | OCR 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:
| Key | Description |
|---|---|
provider | openai, glm, claude, ollama, deepseek, or mock |
api_key | The provider’s API key |
model | The provider’s model identifier |
base_url | The API address |
A role counts as configured only when provider, api_key, and model are all set. See Configuration.
watch_dir
| Key | Default | Description |
|---|---|---|
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_enabled | true | When false, existing files are imported but later changes aren’t watched |
To manage watchers through the API, see Watch a directory.
memory
| Key | Default | Description |
|---|---|---|
default_ttl_seconds | 0 | How long memory is kept. 0 keeps it forever |
inject_recent_turns | 5 | How many recent turns to include when injecting context |
inject_max_tokens | 2000 | The token ceiling for injected context |
rag_fusion
| Key | Default | Description |
|---|---|---|
default_enabled | false | The global default for whether it’s on |
default_variant_count | 3 | How many query variants to generate |
default_rrf_k | 60 | The rank-fusion constant |
default_timeout_ms | 5000 | The 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.
| Key | Default | Description |
|---|---|---|
enabled | true | Whether the background garbage collection thread runs |
soft_delete_retention_days | 30 | Days a soft-deleted item is kept, during which it can be restored |
blob_gc_retention_days | 90 | Days a file is kept after hard delete before it’s physically removed |
scan_interval_hours | 24 | The interval between background scans |
max_purge_per_run | 10000 | The most files cleaned up in one run |
max_run_duration_minutes | 5 | The longest a single run can take |
dry_run | false | Scan without deleting, for testing and inspection |
immediate_purge_enabled | false | Turns on the immediate-purge API. Leave it false |
Environment variables for Docker
See Configuration.
6.4 - 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
| Field | Type | Description |
|---|---|---|
code | string | The error code |
message | string | A description for people. Don’t parse it in code. The structured details are in structured_data |
retryable | boolean | Whether a retry is worthwhile |
category | string | The error category. See the next table |
retry_after_ms | integer or null | The suggested wait before a retry, in milliseconds |
structured_data | object | Structured data about this error, for programs to use |
request_id | string | A server-generated request identifier for finding the request in logs. Some error responses include it |
Error categories
category | Meaning | What to do |
|---|---|---|
auth | An authentication or permission problem | Don’t retry. Check your credentials or permissions |
quota | A quota was exceeded | Slow down, or wait and try again |
transient | A temporary failure | Wait for retry_after_ms, then retry |
timeout | A timeout | Wait for retry_after_ms, then retry |
permanent | Something is wrong with the request itself | Don’t retry it unchanged. Fix the request |
Decide whether to retry
- Look at
retryablefirst. If it’sfalse, don’t retry. - For the wait time, use
retry_after_ms, then theRetry-Afterheader (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:
| Operation | Where the failures are |
|---|---|
| Cross-namespace query | meta.namespaces_failed[] |
| Batch document submit | meta.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.
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 code | Retryable | Category | Typical cause | What to do |
|---|---|---|---|---|
CX_ERR_NAMESPACE_NOT_FOUND | No | permanent | The namespace name is misspelled, or the namespace was deleted | Confirm the name with GET /namespaces, or create the namespace |
CX_ERR_NS_UNAUTHORIZED | No | auth | The API key has no access to this namespace | Read the namespaces you can’t access from structured_data.unauthorized_namespaces and query only the ones you can |
CX_ERR_NS_TIMEOUT | Yes | timeout | A query on one namespace timed out | Use the partial results you got, and optionally retry just that namespace |
CX_ERR_RATE_LIMIT | Yes | transient | The rate limit was exceeded. The v1.0.0-rc.2 server doesn’t emit this code | Wait for retry_after_ms and retry, or lower your request rate |
CX_ERR_AUTH_INVALID_API_KEY | No | auth | The API key is invalid or revoked | Use a different API key |
CX_ERR_INDEX_CORRUPT | No | permanent | The vector index is unavailable | Use the partial results and notify whoever operates the service |
These are the error codes that came up in testing for this documentation:
| Error code | HTTP status | When it appears |
|---|---|---|
CX_ERR_DEPRECATED_FIELD | 400 | A query request used the singular namespace |
CX_ERR_NS_NOT_FOUND | 404 | A file was uploaded to a namespace that doesn’t exist |
CX_ERR_ADMIN_LOOPBACK_REQUIRED | 403 | An admin endpoint was called from a non-loopback address |
CX_ERR_DISK_FULL | 507 | A 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:
| Field | Meaning |
|---|---|
x-cortrix-retryable | Whether this endpoint can usually be retried |
x-cortrix-retry-strategy | The suggested way to retry: exponential_backoff, linear, no_retry, or immediate |
x-cortrix-side-effects | The side-effect category: none, read_only, write, or destructive |
x-cortrix-auth-required | Whether authentication is required |
x-cortrix-auth-scope | The required scope: ns:read, ns:write, tenant:admin, or ops:admin |
x-cortrix-rate-limit | The rate limit, as count/period/scope |
x-cortrix-typical-latency | Estimated P50 and P99 latency |
These fields are design annotations in the spec, not measured results.
Next steps
6.5 - Glossary
These are the terms the Cortrix documentation uses. Each concept has exactly one name.
Product and positioning
| Term | Definition |
|---|---|
| access path | A way for an agent or application to use Cortrix: the HTTP API, MCP, the Python SDK, framework adapters, or the built-in Agent |
| Agent-native | Designed around agent data workflows: semantic processing, memory, and traceability are concerns of the shared storage layer |
| built-in Agent | The fixed-flow chat service that ships in the repository |
| framework adapter | The cortrix-skills package, which turns Cortrix tools into each agent framework’s native format |
| Quick Start | The path that starts Cortrix locally with Docker and runs a first query |
| semantic storage | A storage layer that connects information with the context an application needs to use it |
Data model
| Term | Definition |
|---|---|
| block | The smallest searchable unit, derived from a document or a memory record |
| document | Source material uploaded to Cortrix |
| event | A memory type. It decays over time |
| fact | A memory type. It doesn’t decay over time |
| interaction | One conversation turn: the user’s question and the assistant’s answer |
| memory | Structured long-term information. Its type is fact, preference, or event |
| metadata | Key-value information attached to a document, block, or memory |
| namespace | A logical collection boundary for documents, blocks, memory, and queries. It isn’t an authentication or tenant-security boundary |
| preference | A memory type. It doesn’t decay over time |
| session | A set of conversation turns grouped together |
| source | The original document a block belongs to |
Ingestion
| Term | Definition |
|---|---|
| batch submit | Submitting several documents in one request |
| chunking | Splitting text into blocks |
| database import | Importing the rows of a database table or query into a namespace |
| embedding | Turning text into a vector |
| enrichment | Using an LLM to add entities and summaries to ingested content |
| file upload | Uploading one file as multipart. It returns the document identifier right away |
| ingestion | Everything that happens to a document between upload and being searchable |
| inline upload | Submitting text content directly in a JSON request body. Processing is asynchronous |
| parsing | Turning a file into text |
| Semantic Processing Chain (SPC) | The ingestion pipeline: parsing, chunking, enrichment, embedding, and indexing |
| task | One asynchronous processing job. You can check its progress and cancel it |
| watcher | Tracks a directory and imports new files in it automatically |
Retrieval
| Term | Definition |
|---|---|
| candidate pool | The set of candidates fetched before reranking and truncation. It’s larger than top_k |
| coverage ratio | The share of requested namespaces that were queried successfully |
| cross-namespace query | Querying several namespaces at once and merging the results |
| dense retrieval | Looking up semantically similar content in the vector index |
| full-text search | Looking up content by keyword |
| fusion | Merging the results of several retrieval paths into one list by rank |
| hybrid search | Using several retrieval paths together and fusing their results |
| partial success | Returning the parts that succeeded when some sub-operations fail, with the failures described in meta |
| query | A retrieval request over one or more namespaces |
| rerank score | The relevance score given by the reranker model |
| reranking | Scoring each candidate with a cross-encoder model and reordering them |
| sparse retrieval | Looking up content with sparse vectors |
Memory operations
| Term | Definition |
|---|---|
| invalidation | Marking a memory as no longer valid while keeping the record |
| memory extraction | Extracting memories from conversations automatically |
| soft delete | Marking something deleted while keeping it restorable or traceable, without physically removing it |
Deployment and runtime
| Term | Definition |
|---|---|
| admin endpoint | A management interface that accepts loopback requests only |
| execution provider | The backend that runs a model: CPU, CoreML, or CUDA |
| garbage collection | The background process that removes deleted data in stages |
| LLM role | One use of an LLM, configured separately. There are five: semantic_llm, vision_llm, agent_llm, doc_summary_llm, and enricher_llm |
| local model | The embedding and reranking models that run on your machine and need no external service |
| loopback address | A network address reachable only from the same machine |
| model manifest | The file that records each model file’s source, size, and checksum |
| readiness check | The health check that confirms the API, the models, and the data are all available |
| volume | The Docker storage that holds persistent data |
Interfaces
| Term | Definition |
|---|---|
| authentication | Confirming who the caller is |
| error category | The classification of an error: auth, quota, transient, timeout, or permanent |
| structured error | An error response that carries code, retryable, category, and retry_after_ms |
| tenant | One unit of isolation in the multi-tenant model |
| tool | A callable operation that the MCP server or the framework adapters offer to an agent |
| trace | The record a call leaves on the server, which can be queried by session |
Status labels
| Term | Definition |
|---|---|
| In development | Present in part or being built. Not supported yet |
| Preview | Available and documented. Cortrix is in pre-release, so verify it in your own environment before production use |
7 - Resources
Before you make a production, security, benchmark, or integration decision, read Compatibility and status.
7.1 - Compatibility and status
Check here for the status of each Cortrix capability before you make a production, security, benchmark, or integration decision.
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
| Status | Meaning |
|---|---|
| Preview | Available and documented. Verify it in your own environment before production use |
| Off by default | Implemented, 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 development | Present in part or being built. Not supported yet. Don’t rely on it |
Current status
Preview
| Capability | Documentation |
|---|---|
| Docker quickstart | Quickstart |
| Namespaces, document upload, and processing | Upload documents |
| Query, cross-namespace query, and reranking | Query and rerank |
Writing, listing, editing, and deleting memories. Semantic search over explicit memories doesn’t return results in v1.0.0-rc.2 | Work with memory |
| Correcting a memory by hand: invalidate, restore, and the audit trail | Work with memory |
| Directory watchers | Watch a directory |
| The HTTP API and the OpenAPI spec | HTTP API |
| MCP server (local stdio) | MCP server |
| Python SDK | Python SDK |
| Framework adapters | Framework adapters |
| Fixed-flow chat in the built-in Agent | Built-in Agent |
| The NVIDIA CUDA execution provider on Linux | NVIDIA CUDA |
| OCR and document parsers | — |
Off by default
These work only after you turn on authentication.
| Capability | With 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
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
| Term | Meaning |
|---|---|
keep | The existing component or source of truth stays in place |
add | Cortrix is introduced alongside the existing component |
replace | A tested substitution exists for the stated boundary |
unknown | The evidence isn’t sufficient to choose yet |
not_supported | The current evidence explicitly excludes the path |
PostgreSQL with pgcortrix
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 field | What the evidence supports |
|---|---|
| Existing stack | PostgreSQL 13 through 17 with plpython3u, plus a separately running Cortrix service |
| Decision | keep PostgreSQL as the business-data system. add the pgcortrix SQL-to-HTTP bridge and Cortrix. replace isn’t claimed |
| Tested identity | Cortrix 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 movement | Explicit SQL functions submit selected content to Cortrix over HTTP. Change data capture, automatic table mirroring, and two-way sync aren’t proven |
| Who owns sync | The application or operator owns selection, submission, resubmission, deletion, and consistency checks |
| Query path | PostgreSQL SQL function → plpython3u helper → Cortrix HTTP API → rows returned to SQL |
| Failure domain | Extension installation, PL/Python availability, endpoint policy, network transport, Cortrix health, asynchronous indexing, and query execution are separate failure points |
| Security responsibility | A 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 rollback | Stop 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 |
| Evidence | The 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 field | What the evidence supports |
|---|---|
| Existing stack | An application with source documents and an existing retrieval path. Compatibility with any named third-party vector database is unknown |
| Decision | keep 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 movement | Source 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 sync | The application or operator owns the initial ingest, propagating updates and deletes, draining tasks, and mapping source-document identity |
| Query path | Application → 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 identity | Benchmark 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 domain | Model 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 responsibility | Operators 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 rollback | Keep 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 |
| Evidence | The 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
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.
| Item | Identity |
|---|---|
| The Cortrix commit measured | 79a4eb17c62521338d1ac47a9749e6230e87e69b |
| The public runner | 9490520c24a96ed97b80073ed3ebab096b80550b |
| The bundle commit | 4b94390c1d5f7be95065e7483362ec7f93774ed7 |
Measurement conditions
| Item | Details |
|---|---|
| Hardware | A 32-core Xeon Silver 4110 with 192 GB of RAM and no GPU |
| Models | bge-m3 embedding and bge-reranker-v2-m3 reranking, both ONNX fp32 on CPU |
| Query shape | Serial, one query at a time, top_k=10 |
| Scoring | nDCG@10 and Recall@10 after de-duplicating by doc_id |
| Corpus | Documents | Queries |
|---|---|---|
| SciFact | 5,183 | 300 |
| NFCorpus | 3,633 | 323 |
| FiQA | 57,638 | 648 |
| Quora | 522,931 | The first 2,000 of 10,000 judged queries |
SciFact, NFCorpus, and FiQA use every judged test query.
Results
The table shows nDCG@10:
| Dataset | Task | Dense only | With cross-encoder reranking |
|---|---|---|---|
| SciFact | Scientific claim verification | 0.5942 | 0.6184 |
| NFCorpus | Nutrition and medical QA | 0.2991 | 0.3121 |
| FiQA | Financial forum QA | 0.2540 | 0.3125 |
| Quora | Duplicate-question detection | 0.5003 | 0.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
rerankflag 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.
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 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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
A query returns 400 CX_ERR_DEPRECATED_FIELD
The query request used the singular namespace. Use the plural array instead:
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:
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:
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:
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:
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
nsto the request body. - To delete, add
nsas 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:
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
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.1release 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=falseon 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:
| Metric | July result | August result | Relative change |
|---|---|---|---|
| nDCG@10 | 0.2526 | 0.3125 | +23.7% |
| Recall@10 | 0.3635 | 0.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=falseon an individual query is the verified way to turn reranking off. The namespace-levelreranker_config.enabledisn’t wired into the query path yet. - Local stdio is the current public MCP transport.
Known issues
| Issue | Tracking |
|---|---|
| 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
- Change-by-change notes
- Commit comparison:
v1.0.0-rc.1...v1.0.0-rc.2
Next steps
7.6 - Contributing
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 do | Where to go |
|---|---|
| Report a bug | The bug report form. Include steps to reproduce, expected and actual behavior, and your environment |
| Propose a feature or integration | The feature and integration form. Use it to confirm scope before you open a large pull request |
| Improve the docs | The documentation form, or send a focused documentation pull request |
| Report a security vulnerability | Don’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:
To add it to an existing local commit:
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
| Item | Requirement |
|---|---|
| Operating system | macOS (arm64 or x86_64) or Linux (x86_64) |
| Compiler | C++17 support: Clang 14 or later, or GCC 10 or later |
| CMake | 3.27 or later |
| OpenSSL | Installed through your system package manager |
| Python | 3.9 or later, for the SDK and the MCP server |
CMake fetches every C++ dependency automatically.
Build the server
For faster iteration, you can build without ONNX. Embedding then uses a stub that produces random vectors:
Python SDK
Run the tests
Run the C++ tests with ctest from the build/ directory:
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 relevantx-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:
Don’t edit a derived version field on its own. CI runs the check command and rejects version drift.
Pull request workflow
- For anything non-trivial, open an issue first.
- Branch from the intended base with a short-lived name such as
feat/<topic>,fix/<topic>, ordocs/<topic>. - Keep each pull request to one logical change.
- Add tests for new behavior and keep existing tests passing.
- If you change the API, update both
api/openapi.yamland the affected docs. - Sign off every commit under the DCO.
- Run the full test suite locally before you push.
- Open the pull request against
mainand describe what changed, why, and how you tested it.
Branches
| Branch | Purpose |
|---|---|
main | The only integration branch for ongoing development. It doesn’t identify any published version |
release/1.0 | The 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.