Skip to content

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

Return to the regular view of this page.

Concepts

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

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

1 - Architecture overview

The parts that make up Cortrix and how they relate.

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

One server, several access paths

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

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

Two things follow directly from this shape:

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

Inside the server

Ingestion pipeline

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

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

Query pipeline

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

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

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

Storage

Each namespace has its own data:

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

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

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

Local models

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

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

How the repository maps to components

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

What this page doesn’t cover

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

Next steps

2 - Data flow

What happens to a document between upload and retrieval.

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

Writing

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

1. Upload

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

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

2. Parse

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

3. Chunk

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

4. Embed

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

5. Index

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

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

Why uploads are asynchronous

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

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

Querying

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

1. Retrieve along several paths

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

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

2. Fuse

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

3. The candidate pool

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

4. Rerank

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

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

5. Across namespaces

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

Deleting

Deleting a document happens in stages:

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

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

Memory

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

Next steps

3 - Interfaces

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

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

What agent-native means for an interface

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

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

Convention 1: errors are structured

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

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

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

See Error codes.

Convention 2: partial failure still returns data

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

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

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

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

Convention 3: responses say what to do next

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

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

Convention 4: endpoints describe themselves

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

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

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

Convention 5: calls can be traced

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

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

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

Convention 6: every access path means the same thing

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

Between the spec and the implementation

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

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

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

Next steps