Skip to content

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

Return to the regular view of this page.

Resources

Status, adoption boundaries, troubleshooting, and contributing.

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

1 - Compatibility and status

The current status of every capability.

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

Important

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

What each status means

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

Current status

Preview

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

Off by default

These work only after you turn on authentication.

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

In development

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

Using a preview capability

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

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

Authentication and security

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

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

Benchmarks

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

Before production

At a minimum, verify these in your target environment:

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

2 - Stack fit

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

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

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

Vocabulary

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

PostgreSQL with pgcortrix

Note

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

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

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

See pgcortrix.

BGE-M3 embedding plus reranking

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

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

Next steps

3 - Benchmark evidence

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

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

Measurement bundle

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

Measurement conditions

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

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

Results

The table shows nDCG@10:

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

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

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

Comparability

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

What these numbers don’t show

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

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

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

Important

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

Next steps

4 - Troubleshooting

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

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

Startup

docker: 'compose' is not a docker command

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

The first start takes a long time to return

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

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

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

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

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

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

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

ERROR: QuickStart bootstrap: demo upload returned HTTP 507

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

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

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

The readiness response shows the disk at the crit stage:

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

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

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

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

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

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

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

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

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

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

Why df -h can disagree with the reported percentage

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

Port 8420 is in use

Start on a different port:

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

Then replace 8420 with the new port in every command.

Installation

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

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

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

cortrix and cortrix-skills need Python 3.9 or later.

Calling the API

Every Python SDK call returns 502

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

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

NO_PROXY=127.0.0.1,localhost python your_script.py

A query returns 400 CX_ERR_DEPRECATED_FIELD

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

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

An admin endpoint returns 403 CX_ERR_ADMIN_LOOPBACK_REQUIRED

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

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

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

A query returns HTTP 200 but the results are incomplete

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

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

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

Ingestion

An upload returns 202 but the document never appears

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

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

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

A file upload returns 404 CX_ERR_NS_NOT_FOUND

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

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

Uploading again returns skipped

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

A watcher isn’t importing files

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

Memory

Editing or deleting a memory returns 400 ns is required

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

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

See Work with memory.

MCP

Claude Code doesn’t show the Cortrix tools

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

claude mcp get cortrix

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

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

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

GPU

For problems with a CUDA deployment, see NVIDIA CUDA.

Report a problem

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

5 - Release notes

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

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

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

Highlights

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

FiQA retrieval accuracy

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

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

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

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

Compatibility notes

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

Known issues

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

Release artifacts

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

Full changelog

Next steps

6 - Contributing

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

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

Ways to contribute

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

Licensing and certification

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

Add -s when you commit:

git commit -s

To add it to an existing local commit:

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

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

Repository layout

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

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

Set up a development environment

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

Prerequisites

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

CMake fetches every C++ dependency automatically.

Build the server

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

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

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

cmake -DCMAKE_BUILD_TYPE=Release -DCORTRIX_USE_ONNX=OFF ..

Python SDK

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

Run the tests

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

cd build
ctest --output-on-failure

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

Coding standards

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

Version number

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

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

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

Pull request workflow

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

Branches

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

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

Code of conduct

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

Next steps