This is the multi-page printable view of this section. .
Resources
- 1: Compatibility and status
- 2: Stack fit
- 3: Benchmark evidence
- 4: Troubleshooting
- 5: Release notes
- 6: Contributing
Before you make a production, security, benchmark, or integration decision, read Compatibility and status.
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
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
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
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.
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
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.