Cortrix

Agent-native semantic storage for retrieval, memory, and API-driven AI applications.

Quickstart · Install with an AI Agent · Agent access · Compatibility · OpenAPI

Cortrix provides a local-first semantic storage server with namespaces, documents, blocks, hybrid search, memory APIs, and Agent-oriented access paths. It is designed for applications and Agents that need a programmable retrieval layer rather than a one-off vector database wrapper.

Architecture

The repository includes:

• cortrix-server: the C++ backend and HTTP API.
• api/openapi.yaml: the public OpenAPI contract.
• cortrix-mcp/: an MCP server for IDE and Agent clients.
• sdk/python/: the Python SDK.
• cortrix-agent/: the built-in fixed-flow RAG chat service.
• web/: the local Web UI.

Documentation Map

Start here:

• Quickstart: start Cortrix with Docker, check readiness, and run a source-backed reranked query.
• Install with an AI Agent: give a terminal-capable AI Agent a version-pinned local setup and verification contract.
• First-value SupportOps demo: run the deeper source-build verification path with versioned assertions, trace evidence, and zero-residual cleanup.
• Stack fit and adoption boundaries: review evidence-backed keep/add/replace/unknown decision cards.
• Agent access: choose between HTTP/OpenAPI, MCP, Python SDK, and the built-in Agent.
• Compatibility and known status: current public status for API, MCP, SDK, Agent, auth, tenant/RBAC, memory extraction, benchmarks, and security hardening.
• OpenAPI spec: endpoint paths, schemas, security schemes, and response contracts.
• MCP README: MCP server setup and tool reference.
• Python SDK README: Python client setup and resource model.
• Built-in Agent README: FastAPI Agent service and chat endpoints.
• Linux NVIDIA CUDA operations:
  separate image, provider policy, deployment, verification, and rollback.
• Security policy: security reporting path.
• Contributing: development workflow and contribution checklist.
• Maintainers: ownership, acknowledgment targets, and recusal rules.
• Code of Conduct: community standards and private reporting.

Current Status

Cortrix is in active pre-release development. The public documentation uses these status labels:

• Verified: directly supported by current code/spec evidence and exercised in the latest validation scope.
• Verification required: present in code, spec, or docs, but not yet confirmed enough for a public-readiness claim.
• Blocked: known broken, blocked, or not provable in the current runtime.
• Roadmap: planned or reserved for a later version.

High-signal current status:

See Compatibility and known status before making production, security, benchmark, or integration claims.

Quickstart

Run the local Docker Quick Start with real embedding and reranking:

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

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

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

You need Git, Docker, and Docker Compose. No .env file, LLM provider key, host-side model tooling, manual model download, model conversion, or separate bootstrap command is required. The first start downloads about 1.17 GB of pinned model assets and can take several minutes; later starts reuse the cached volume.

The Quick Start publishes only the loopback API at 127.0.0.1:8420 (publishing on an isolated test network is an explicit, unauthenticated opt-in — see Quick Start). It uses BGE-M3 embedding and bge-reranker-v2-m3 reranking on CPU, while external LLM roles and the built-in Agent remain disabled. For model provenance, checks, expected output, cleanup, and scope boundaries, see Quick Start. For the deeper source-build evidence workflow, see the First-value SupportOps demo.

If you are using a terminal-capable AI Agent, use the
Agent-assisted setup contract. It pins the release
and commit, limits the agent to the same loopback-only Docker path, and requires
a structured verification report.

API Reference

The canonical API contract is api/openapi.yaml.

The spec includes:

• local and cloud server URLs;
• API key and Bearer auth schemes;
• namespaces, documents, query, memory, watch, import, auth, admin, tenant, Agent, system, GC, and maintenance paths;
• request/response schemas and error schemas.

OpenAPI presence is not the same as runtime verification. If an endpoint is listed as Verification required or Blocked in Compatibility, use that status as the public claim boundary.

Agent Access

Cortrix exposes four access paths:

See Agent access for selection guidance and current support status.

Core Concepts

• Namespace: a logical collection boundary for documents, blocks, memory, and queries.
• Document: uploaded source material that can be parsed and indexed.
• Block: a searchable unit derived from a document or memory record.
• Query: a retrieval request over one or more namespaces.
• Memory: structured long-term information captured from interactions or explicit API calls.
• Agent surface: a programmatic path that lets an Agent use Cortrix through HTTP, MCP, SDK, or the built-in Agent service.

Configuration

The default local config template is config.yaml.example. Copy it into build/config.yaml before the first run:

cp config.yaml.example build/config.yaml

LLM-backed features are configured by role:

• semantic_llm: optional LLM-backed semantic processing. It is separate from the local ONNX embedding and cross-encoder reranker used by the primary Quick Start.
• vision_llm: OCR image enhancement.
• agent_llm: built-in Agent chat.
• doc_summary_llm: ingest-side summaries.
• enricher_llm: ingest enrichment.

Use placeholder values in documentation and real provider keys only in local ignored config files. Do not commit secrets.

Production And Security Notes

Cortrix is pre-release. Before using it outside local development, review:

• Compatibility and known status for blocked and review-required areas.
• Security policy for reporting.
• config.yaml.example for auth and API key configuration.
• deploy/ for deployment templates.

Do not assume production readiness for auth, tenant isolation, RBAC, quota enforcement, or memory extraction. Do not generalize the published retrieval-quality measurements to answer quality, latency, cost, security, or production performance.

Roadmap

Roadmap items are not current capabilities.

• Advanced autonomous Agent executors such as tool-use and plan-execute modes.
• Additional integration adapters beyond the currently documented surfaces.
• A remote MCP access path using stateless Streamable HTTP, with production-grade
  authentication, authorization, and deployment hardening. The current MCP
  capability is local stdio only.
• Production-readiness hardening for auth, tenant isolation, RBAC, quota, logging redaction, and deployment operations.
• Additional datasets and production-representative latency or cost measurements after separate methods and artifacts are accepted.

Community And Contribution

• GitHub Issues: bugs and feature requests.
• Issue templates: bugs, feature or integration proposals, and documentation reports.
• Security policy: security reports.
• Contributing: local development and pull requests.
• Code of Conduct: community standards and private conduct reports.
• Maintainers: ownership and acknowledgment targets.

License

Cortrix-authored material is licensed under AGPL-3.0-only; third-party material retains its own license. See NOTICE.md for copyright and exception boundaries and CONTRIBUTING.md for the no-CLA, DCO 1.1 contribution policy.