Platform · 2. CoreCrux
This chapter is reference. It documents what CoreCrux is, exactly which capabilities live in it rather than in the free Crux Daemon, what its contracts look like from outside, what it guarantees, and what it declines to guarantee.
CoreCrux is closed source and is not something you install from a package manager. If you are a developer looking for something to run on your laptop, you want the Crux Daemon, and 2.3 tells you exactly what you get and what you do not.
2.0 In plain English
CoreCrux is the engine underneath the hosted service. You do not call it and you cannot install it; when you use Crux Engine, this is what is doing the retrieval and holding the history. It is documented here because you are entitled to know what your data sits on, and because the boundary between it and the free daemon is a commercial fact that you should be able to see rather than discover.
It is not a database, and framing it as one leads people to the wrong conclusions immediately. It has no SQL, no arbitrary updates and no foreign keys, and it will lose any comparison written on those terms. The closer comparison is a ledger: writes are appended in order and sealed rather than edited in place, so the history is the record and past states are reached by replaying rather than by remembering. Retrieval and projections are built on top of that.
Why build a separate engine rather than scale up the daemon? Because three things get much harder once you are holding other people's corpora on shared hardware, and each of them is a whole subsystem. Answers have to remain traceable to the exact bytes that produced them months later, after the corpus has moved on. Recall has to survive vocabulary mismatch, so lexical, dense-vector and graph lanes are run together and fused rather than betting on any one of them. And deletion has to be real deletion, surviving a rebuild from the beginning of the history, which is a substantially harder problem than removing a row.
You will read this chapter to answer procurement-shaped questions rather than integration-shaped ones. §2.3 is the honest capability split, which is the section to read if you want to know what you are paying for. §2.7 carries measured results with the corpus they were measured on, because a benchmark number without its corpus is not a result. §2.9 states what it does not promise.
The thing people get wrong is assuming the free daemon is CoreCrux with features switched off. It is not: they are separate codebases that deliberately share a family of contracts, which is why a client written against the daemon keeps working when pointed at CoreCrux. There is no licence key that turns one into the other. The second misreading is subtler: everything in this chapter is described behaviourally, in terms of what it does and what it guarantees, never how it does it. That omission is deliberate, and where you cannot find a mechanism it is because it has been withheld, not because it is unimportant.
2.1 What CoreCrux is
CoreCrux is CueCrux's proprietary, GPU-accelerated retrieval and event-storage engine.
It holds an append-only, sealed-and-hashed event spine that records every knowledge write and every decision as an ordered, replayable event. On top of that spine it serves multi-tenant hybrid retrieval, lexical, dense-vector and graph lanes fused into one ranked result, with per-tenant isolation, durable right-to-erasure, and receipts a third party can verify offline.
It is a retrieval and evidence engine, not a general-purpose database. It has no SQL, no arbitrary updates and no foreign keys, and it will lose any comparison framed that way. The write model is append; the read model is retrieval and projection.
The three things it is built not to lose
Retrieval systems that are good enough for a demonstration lose three things at scale.
Provenance under audit. Answers must be traceable to the exact bytes that produced them, months later, after the corpus has moved on. The spine is append-only and hash-sealed, so reconstructing a past state is a replay rather than a reconstruction from memory.
Recall that survives vocabulary mismatch. Pure keyword search fails on paraphrase. Pure vector search fails on rare proper nouns and exact identifiers. CoreCrux runs both, plus graph and entity lanes, and fuses the ranked lists.
Deletion that is actually deletion. A right-to-erasure request against a live multi-tenant index has to remove data from memory, from the durable projection snapshot, and from the sealed on-disk segments, and it has to survive a rebuild from the beginning of the spine. CoreCrux splits that into a fast online step and an audited offline step, both receipted.
2.2 Why it is separate from the Community Edition
The Crux Daemon Community Edition is deliberately a local-first, single-machine, CPU-only memory daemon for one developer's agents. CoreCrux is the server-side, GPU-resident, multi-tenant, shardable engine that carries corpora at scale and the operational surface that comes with running someone else's data on your hardware, sharding, replication, hibernation, offline bulk build, physical erasure.
They are not two tiers of one binary. They are two codebases that share a family of contracts, the receipt format, the pointer-first response contract, the /v1/query/* route shapes, so that a consumer written against the Community Edition keeps working when it is pointed at CoreCrux.
| Crux Daemon (Community Edition) | CoreCrux | |
|---|---|---|
| Availability | Open source | Proprietary, closed |
| Licence | Apache License, Version 2.0 | All rights reserved |
| Runs on | The developer's own machine. No account, no API keys. | An operator-run server with an NVIDIA GPU |
| Listeners | HTTP on localhost:14800, MCP on :14801, gRPC on :4007 | An HTTP control and query listener plus a separate gRPC data plane, both operator-configured |
| Posture | Local-first. Nothing leaves the machine. | Multi-tenant service |
One-line rule. If it is about one person's machine and one person's memory, it is the Community Edition. If it is about many tenants' corpora on someone's server hardware, it is CoreCrux.
A naming trap worth knowing. Both codebases build binaries and crates with overlapping corecrux names, because the shared names are the contract components. In these chapters, "the Crux Daemon" always means the Community Edition and "the CoreCrux engine" always means the private one. Any other document that writes the bare binary name without saying which daemon it means is ambiguous, and you should assume nothing from it.
2.3 The capability split, in full
Read "Crux Daemon" as ships in the Community Edition, and "CoreCrux" as ships in the private engine. A reader should be able to finish this table knowing exactly which side of the line every capability sits on.
| Capability | Crux Daemon | CoreCrux |
|---|---|---|
| Append-only event spine, sealed segments, hash chain | Yes | Yes |
| CROWN receipts, Ed25519-signed and offline-verifiable | Yes | Yes |
| Deterministic replay and replay digest | Yes | Yes |
| Store integrity verification | Yes | Yes, plus a stricter mode that recomputes sealed-segment hashes and cross-checks the manifest |
| Versioned fact store with confidence and freshness decay | Yes | No: a different model, based on projections rather than facts |
| MCP server, agent tool surface, agent passports, pack export | Yes | No |
| Work board, kanban and plan projection | Yes | No |
| Lexical retrieval | Yes | Yes |
| Graph and entity-expansion retrieval | Yes | Yes |
| Budget-first retrieval, returning metadata before content | Yes | No, budgeting is a Community Edition and consumer-side concern |
| Dense vector retrieval | Bring-your-own, optional, never required | Yes: first-class, with server-side embedding |
| Multi-lane fusion with per-tenant configurable lane weights | No | Yes |
| Cross-encoder reranking, including a confidence-gated mode | No | Yes |
| GPU acceleration of the read and scan path | No, CPU-only by design | Yes |
| Direct NVMe-to-GPU transfer, bypassing host RAM | No | Yes |
| Multi-tenant isolation enforced by token claim | No, single-user | Yes |
| Sharding and shard-map routing | No | Yes |
| Replication and follower reads | No | Yes |
| Idle-tenant hibernation and on-demand rehydration | No | Yes |
| Durable tenant erasure | Scoped forget, with a dry-run | Yes: full tenant-level, two-step, receipted |
| Offline bulk corpus build and atomic attach | No | Yes |
| Analytics plane covering retrieval volume, contradiction rate and cost budget | No | Yes |
Note the two rows that read "Yes" on the left and "No" on the right, because they surprise people: the agent tool surface and the versioned fact store are Community Edition capabilities. CoreCrux is the substrate, not the agent-facing product.
2.4 Position in the architecture
agents / SDKs / apps
|
v
Crux Engine -------------> CoreCrux engine
(hosted plane: answers, (HTTP control + query plane,
synthesis, receipt separate gRPC data plane)
assembly) |
+--> embedding service (external)
+--> local NVMe (sealed segments + companions)What calls it. In production the caller is Crux Engine. It posts retrieval queries and reads the ranked results; a separate hydration path fetches prose content for the winning results. Operational tooling probes the health endpoints. Nothing in the public web tier talks to CoreCrux directly.
What it depends on. An NVIDIA GPU with a current driver and CUDA runtime; local NVMe for the data directory; an external embedding service for dense-vector embedding, configured as a single endpoint. That is the whole external dependency set. There is no relational database, no message broker and no external vector database in the serving path.
The plane split, as an architectural rule. Only the CoreCrux daemon terminates the data plane. Any control plane written in another language is admin-only: it may publish shard maps and drive an operator interface, but it never proxies append or read traffic and never parses event frames. That is why there is no request-forwarding layer sitting in front of the index in this architecture, and why a control-plane outage does not take reads down.
Relationship to the Crux Daemon. Peers on a shared contract, not layers. A consumer can target either. The Community Edition is what a developer installs; CoreCrux is what an operator deploys.
2.5 The external contract surface
All HTTP is JSON. Errors are RFC 7807 application/problem+json, with type URIs under https://errors.cuecrux.com/.
2.5.1 Consumer-facing endpoints
| Method and path | Purpose | Scope |
|---|---|---|
POST /v1/query/text-search | Primary hybrid retrieval | query:read |
POST /v1/query/text-search/escalate | Second-pass retrieval when a first result is weak | query:read |
POST /v1/query/answer | Planned, multi-step answer construction | query:read |
POST /v1/query/fetch-content | Hydrate full content for pointer-shaped results | query:read |
POST /v1/query/graph-expand | Expand a result set along the entity graph | query:read |
GET /v1/graph/ego, /v1/graph/path, /v1/graph/resolve, /v1/graph/stats | Link-graph read API | query:read |
POST /v1/query/time-range, /v1/query/temporal/diff, /period, /trend | Temporal queries over the spine | query:read |
GET /v1/receipts/{id}, /{id}/signature, /{id}/verification | Receipt fetch and verification | receipts:read |
GET /v1/replay/exports/receipts, /answers, /actions, /streams | Replay and export bundles | exports:read |
GET /v1/projections/entity/current-state, /history, /timeline, /sessions, /sequence, /count | Materialised entity views | query:read |
GET /v1/analytics/counts, /retrieval-volume, /query-patterns, /citation-trend, /contradiction-rate, /cost-budget, /meta | Usage and quality analytics | admin:read |
GET /healthz, GET /readyz, GET /metrics | Liveness, readiness, Prometheus | unauthenticated |
An operator with a support contract also gets an administrative surface covering tenant erasure, shard-map publication, projection status and rebuild, replication status, per-tenant lane configuration and boost configuration, and an operations log. The three erasure routes are documented in 2.6.5 because erasure is a customer right and its contract has to be legible to the person exercising it. The remainder of the admin surface is documented to operators, not on this page.
2.5.2 Request shape for retrieval
POST /v1/query/text-search requires tenant_id (a non-empty string) and query (a string).
Optional: limit, defaulting to 10; a scoring profile selector; and reference_date in YYYY-MM-DD form, which anchors relative-date resolution to your clock rather than the engine's. If your users ask about "last month", send reference_date.
The request also accepts a set of caller-supplied routing hints for a well-informed client that wants to shortcut the engine's own classification: a query-class hint with a confidence, an entity-type hint, an anchor-entity override, a hypothetical-answer text for hypothesis-expanded search, and per-request lane and rerank-sensitivity overrides where the deployment enables them. Every optional field is inert when absent, the engine falls back to its own resolution, and unknown fields are ignored. The field-level schema for the hints is supplied with the versioned API reference to integrators, because the hint set moves with the lane configuration of a given deployment.
An empty tenant_id is rejected with 400. It does not fall through to a cross-tenant scan. That is worth stating explicitly, because "empty string means everything" is exactly the class of bug this refusal exists to prevent.
2.5.3 Response shape
Two negotiated contracts.
CRC-v1, the default. A pointer-first envelope. Results carry identity, ranking and token-cost metadata; content is hydrated in tiers, pointer, then summary, then full, so a caller pays for text only when it wants it. The canonical schema is published as crc-v1.schema.json and ships with a conformance validator, so you can check your client against the contract rather than against a running server.
Legacy full payload. Opted into with the header Accept-Contract: legacy, the values v0, none and off are also accepted, as is the query parameter ?contract=legacy. Byte-identical to the pre-CRC-v1 shape, with a top-level results[] array. It exists so that receipts written against the old shape stay stable.
Both shapes may carry additive observation blocks: an agent_decision object with per-lane attribution and a fused confidence, read_pointers, and receipt_refs. These are additive by contract, a client that ignores them is unaffected by their arrival.
2.5.4 Auth model
Four modes, set per deployment.
| Mode | Credential | Use |
|---|---|---|
jwt_hs256 | Authorization: Bearer <JWT>, HS256 shared secret | Production default |
jwt_jwks | Authorization: Bearer <JWT>, verified against JWKS or OIDC discovery | Production, federated identity |
dev_scopes | An X-Corecrux-Scopes header, or a bearer token read as a scope list | Local development only |
off | None | Local development only |
Scopes are read from the token's scope, scopes, scp or permissions claims. The vocabulary is query:read, query:write, receipts:read, exports:read, replication:write, admin:read and admin:write.
Tenant binding is the part that matters. Under a JWT mode a token carries a tenant_id claim, and every tenant-scoped handler binds the request to it. A token for tenant A cannot read or mutate tenant B, including through the batch erase endpoint, where a batch is rejected wholesale if any member tenant fails the check. There is no partial-success path that quietly does most of what you asked.
A token with tenant_id set to * is a global operations token and spans all tenants by design. That is what replication and cross-tenant operations use.
Under off and dev_scopes the tenant claim is forced to "any", so isolation is not enforced at all. This is stated as loudly as the guarantee it suspends. The daemon refuses to bind those modes to a non-loopback address, and prints a security warning if an operator overrides that refusal. If you are evaluating this engine, confirm which auth mode the deployment you are testing is running in before you draw any conclusion about isolation from its behaviour.
2.5.5 Error codes
| Status | Meaning |
|---|---|
400 | Malformed request, or an empty tenant_id |
401 | Missing or invalid credential |
403 | Valid scope but the wrong tenant, or a per-tenant token attempting a global operation |
404 | Unknown receipt or artefact |
501 | A plane that is disabled in this deployment |
503 | From /readyz, when a dependency check fails |
5xx | Returned as application/problem+json |
2.5.6 The gRPC data plane
The data plane is gRPC: append, batched stream reads, replay sessions, and raw frame reads for replication.
Raw frame reads require a globally scoped admin:read token. A per-tenant token attempting one gets PermissionDenied. Raw frames cross tenant boundaries by construction, so the credential that reads them has to be one that legitimately spans tenants.
2.6 Capabilities, described behaviourally
2.6.1 Hybrid retrieval
A query fans out across several independent retrieval lanes, each producing its own ranked candidate list, and the lists are combined by rank fusion into a single ordering. The lane family covers lexical keyword scoring, dense vector similarity, learned sparse expansion that bridges vocabulary gaps without dense vectors' cost, hypothesis expansion where the caller supplies a hypothetical answer that is embedded and searched as an additional lane, graph and entity expansion, structural lanes that exploit a document's own index structure and navigation tree, and a per-tenant domain-vernacular lane that adapts to a tenant's own phrasing.
Which lanes are live is a per-tenant configuration, not a global setting. An operator sets lane weights per tenant through the administrative surface, and callers may additionally override lanes per request where the deployment enables it. Lane participation and contribution are reported back on the response, so a consumer can see which lanes produced its answer.
Every new lane goes through the same three-stage rollout: off, then shadow, then active. In shadow a lane runs on every query and emits diagnostics but does not touch ranking; promotion to active requires a shadow report over a minimum soak window. Rollback is a per-tenant configuration change, immediate, with no restart and no index rebuild. The on-disk artefacts stay in place and resume serving when the lane is re-enabled.
"Fused by rank" is the whole published description of the mechanism. The fusion function, its constants, per-lane normalisation, confidence computation, tie-breaking, the default weight vector, and which lanes a deployment starts with are not published.
2.6.2 Reranking
A cross-encoder rerank stage can reorder the fused list. It is off by default and enabled per deployment, so do not assume a result you are looking at has been reranked.
There is also a confidence-gated mode: when the fused result's confidence falls below a threshold, settable per tenant or per request, the rerank fires even if it is otherwise off. Low confidence is treated as a trigger to spend more compute rather than as a reason to return a weak answer.
A date-aware rerank resolves relative time expressions against the reference_date you supplied.
2.6.3 Dense lanes and the embedder
CoreCrux does not host an embedding model. It calls an external embedding service at a configured endpoint, and it uses the same endpoint for both stored-document embedding and query embedding, so the two vector spaces align by construction rather than by convention.
Dense artefacts can be built two ways: online at seal time, or offline on a separate build node and then attached. The embedder can be pinned to a specific pool backend when a run has to be reproducible.
The consequence, stated as a limit rather than left implicit: if the embedding service is unreachable, dense lanes degrade. Lexical and graph lanes continue serving.
2.6.4 Tenant isolation
Tenancy is a first-class dimension, not a filter applied late in the query. Each tenant's data is namespaced through the routing key, and every tenant-scoped handler binds the request to the caller's token claim.
A tenant can additionally be siloed, moved out of shared segments into segments that contain only that tenant's data. Siloing is both an isolation posture in its own right and the precondition for physical erasure.
2.6.5 Durable tenant erasure
Two operations, deliberately separate. Erasure here is tenant-scoped, not receipt-scoped. Receipt-scoped forgetting with a dry-run is the Community Edition's fact-store model and is a different thing; do not carry it across.
Step one, online. POST /v1/admin/forget-tenant?tenant_id=... requires admin:write and is tenant-bound. It is synchronous. Across every shard on every device it removes the tenant's rows from the in-memory materialised state, flushes the projection snapshot so the removal survives a restart, clears the tenant's configuration overlay, and writes a durable tombstone per shard so that a rebuild from the beginning of the spine skips the tenant's frames rather than resurrecting them.
The response reports, per shard, how many rows were removed and whether that shard's tombstone was written, plus whether the snapshot flush succeeded, and a top-level complete flag that is true only if the flush and every tombstone succeeded. A partial erasure reports itself as partial. A tenant-erasure control event is recorded with the acting identity, so the erasure is itself part of the audit record.
A batched variant, POST /v1/admin/forget-tenants with a body of {"tenant_ids": [...]}, does the same for many tenants with a single snapshot flush instead of one per tenant. That is the corpus-scale path.
Step two, offline. Physical deletion of the tenant's sealed segments and companion files, with the manifest rewritten. This runs with the daemon stopped, because rewriting manifests underneath live readers is unsafe. It aborts if the tenant is co-mingled in any segment, so the tenant has to be siloed first. It defaults to a dry run that prints a plan and changes nothing until an explicit write flag is given, and it emits an erase receipt to a path the operator names.
POST /v1/admin/erase-tenant is the authenticated, tenant-bound initiator of step two. It returns the exact offline procedure rather than performing it, so the intent is attributable even though the act is manual.
The honest scope of erasure: it covers the live data directory. Operator backups, replicas, snapshots and any copies made downstream are the operator's responsibility and are outside the engine's control. An erasure guarantee that claimed otherwise would be a guarantee about someone else's filesystem.
2.6.6 Tombstone-aware rebuild
Materialised state can be rebuilt from the spine at any time. That is what makes an append-only design usable rather than merely principled.
A naive rebuild would replay a forgotten tenant's frames straight back into memory. The durable tombstones written during the online erasure step are consulted by the rebuild, so erased tenants stay erased across a rebuild from the beginning of the spine.
Companion artefacts are rebuilt by a control-CLI command that can be scoped to a single shard or a single segment, and that has a dry-run mode which only detects staleness.
2.6.7 Idle-tenant hibernation
In a large multi-tenant deployment most tenants are idle at any given instant while their materialised state still occupies resident memory. CoreCrux tracks per-tenant activity and, after a configurable idle period, spills an idle tenant's state to disk and releases the memory.
Note the subject carefully: hibernation operates on idle tenants' materialised projection state. It does not hibernate segments. Any description that says cold segments hibernate is describing something that does not exist.
The feature is off by default, leaving the idle threshold unset means zero behaviour change, and a list of tenants can be excluded from hibernation entirely.
Rehydration is automatic and synchronous on the query path: a query for a sleeping tenant wakes it before it is served. Restore is insert-if-absent, so anything written while a tenant slept wins over the sleeping copy. Spill files are checksummed, and a spill file that fails its checksum is left untouched on disk while the live copy is put back into memory, the engine never destroys the only verifiable copy of something. On restart, spill files are inventoried rather than loaded, since loading them would defeat the purpose, and a restored tenant's file is renamed rather than deleted so that a crash between rehydration and the next snapshot cannot lose data.
The customer-visible property: idle tenants cost approximately zero resident memory, and the first query after idling pays a wake cost measured in well under a second.
2.6.8 Offline bulk ingest
For corpora at the millions-of-events scale, ingest is decoupled from the serving daemon entirely.
You produce a line-delimited JSON payload with deterministic identifiers. Each line carries tenant_id, stream_type, stream_id, an ascending seq, an event_id, and either payload or payload_b64, with optional timestamps and content type.
A build node then builds sealed, pre-compacted segments plus their companion indexes, optionally runs the dense embedding pass against an embedder, and finally attaches the finished tenant directory to the serving daemon. Attach is a file copy plus an atomic manifest swap: gated, count-verified, receipted, and reversible via a detach that produces a rollback plan.
The serving daemon never runs the append, seal and compact loop for a bulk load. It only ever loads finished segments. That is what keeps a large import from competing with live queries.
2.6.9 Sharding and routing
Routing is deterministic. The tuple of tenant, stream type and stream id hashes onto a 64-bit ring, and an immutable, versioned shard map assigns explicit hash ranges to shards, each with a leader and optional followers.
The map is content-addressed with a BLAKE3 digest over its canonical bytes and chains to its predecessor, so a routing change is itself an auditable versioned artefact rather than a configuration edit nobody can reconstruct afterwards.
Shards carry a state, active, draining or retired, so a shard can be drained without a stop-the-world migration. The offline build tool reproduces the same routing, which is why a bulk-built tenant lands on the same shards as a live-ingested one.
2.6.10 Replication
Followers stream raw frames over the gRPC data plane using a globally scoped credential. Replication health and readiness are exposed on the administrative surface. Deployments run at replication factor 1, or at 2 or more.
2.6.11 Analytics
An analytics plane reports retrieval volume, query patterns, citation trend, contradiction rate and cost budget per tenant. This is the operator's view of how a corpus is actually being used, and it is scoped to admin:read.
2.6.12 Scale characteristics
CoreCrux is built to carry corpora at the tens-of-millions-of-chunks scale on a single GPU node, with sharding and replication available above that. Treat that as a design and operational characteristic rather than a benchmarked figure, the numbers this page will stand behind are in 2.7, and that is not one of them.
2.7 Measured results, and their corpora
House rule: a number carries its corpus and the revision it was measured at, or it is not quoted. Not softened, not hedged, dropped. Three results are published below, each with its corpus, its date, the shape of the workload, and its provenance stated exactly.
One caveat that applies to all three, and that you should weigh before relying on any of them. CoreCrux is a closed system, so a revision identifier here is an attestation, not something you can independently check, unlike the Crux Daemon claims elsewhere in this documentation, where every citation links to a line of source you can read. Treat these as we would treat a vendor's figures: useful, dated, specific enough to argue with, and weaker evidence than anything you can verify yourself. If you are evaluating us, ask for the run record.
| Result | Corpus | Date | Revision |
|---|---|---|---|
| Retrieval quality (2.7.1) | LME-40 | 2026-05-29 | 89d965f (CoreCrux PR #82) |
| Substrate coverage (2.7.2) | LME-M | see section | run record; no revision recorded |
| Integration throughput (2.7.3) | see section | 2026-03-10 | run record; no revision recorded |
Two of the three carry no revision in their run record. That is a defect in how those runs were recorded, and it is stated here rather than papered over: you should discount them accordingly. They are retained because the corpus and workload are named and the comparison is internally consistent; a reader who wants only fully-provenanced numbers should use the first row and ignore the other two.
None of these is a service level. They are measurements of dated runs on stated hardware. There is no latency, throughput or availability commitment attached to any of them, and you should not design a capacity plan around a figure you did not measure on your own deployment.
2.7.1 Retrieval quality: LongMemEval, 40-problem cohort, 2026-05-29
Corpus: LME-40, a 40-problem mixed cohort drawn from LongMemEval, comprising 20 LME-S robust-failure problems and the first 20 LME-M problems, run as paired tenants: one freshly ingested, one on the earlier baseline ingest. 80 probes. Same endpoint, same question and same anchor on both sides of each pair.
| Metric | Baseline ingest | Fresh ingest | Delta |
|---|---|---|---|
| Recall@1 | 60 % | 78 % | +18 pp |
| MRR | 0.717 | 0.806 | +0.089 |
| Recall@10 | 88 % | 88 % | no change |
Read the third row as carefully as the first two. Recall@10 ties. The whole of the improvement is in where the right evidence lands in the ranking, not in whether it is retrieved at all. If your application shows a user ten results, this result predicts no change for you.
The lift decomposes, and publishing the decomposition matters because it stops the whole gain being attributed to one thing:
| Contribution | Recall@1 | Basis |
|---|---|---|
| Clean ingest base alone | 47 % to 80 %, +33 pp | The 15 tenant pairs on which the additional lane did not participate |
| The additional retrieval lane | 68 % to 76 %, +8 pp | The 25 tenant pairs on which it did |
Most of the gain is corpus hygiene. A smaller, real gain is the additional lane. Anyone quoting +18 pp as the effect of a retrieval feature is quoting it wrong.
2.7.2 Where the lane does not help: LongMemEval-M, 2026-05-29
Corpus: LME-M, all 500 tenants scanned.
Substrate coverage on the LME-M baseline cohort is approximately 4.3 %, roughly 450 of about 10,500 items. That is below the level the additional lane needs in order to contribute at all.
This is a negative result and it is published for the same reason the positive one is: the lift in 2.7.1 is conditional on the substrate being present, and on a corpus where it is not present the lane does nothing. A feature that only works when its precondition holds is a normal engineering fact. A feature sold without its precondition is not.
2.7.3 Integration throughput and latency: 2026-03-10
A production integration benchmark of the hosted answer path with CoreCrux as the authoritative store, measured against the same path running on the previous relational-only configuration. Workload: 50 connections over 60 seconds.
Hardware class, as recorded with the run: an application node with a high-core desktop-class CPU and 192 GB RAM, and a GPU node with an RTX 4000 SFF Ada 20 GB, driver 570 and CUDA 12.8, on a private network at sub-millisecond latency.
| Measurement | Relational-only | CoreCrux authoritative | Delta |
|---|---|---|---|
| Answer throughput | 8,197 req/s | 8,017 req/s | −2.2 % |
| Answer latency P50 | 5 ms | 5 ms | unchanged |
| Answer latency P99 | 12 ms | 12 ms | unchanged |
| Retrieval warm P95 | 8.91 ms | 9.67 ms | +8.5 % |
Under stress, at 200 connections: 7,393 req/s, P50 25 ms, P99 48 ms, zero errors.
The honest reading: moving the authoritative store to CoreCrux cost about 2 % of answer throughput and about 8.5 % of warm retrieval latency at P95, and bought the guarantees in 2.8. It was not free and this page does not pretend it was.
2.7.4 Corpus glossary
Use these names whenever you quote one of our numbers back at us.
| Name | What it is |
|---|---|
| LME-S | LongMemEval small. Roughly 250 events per problem, chat-history shaped. |
| LME-M | LongMemEval medium. Roughly 2,500 events per problem. |
| LME-40 | The 40-problem mixed cohort, 20 LME-S robust-failure problems plus the first 20 LME-M, run as paired fresh-ingest and baseline-ingest tenants. |
LME-S, LME-M and LME-40 give materially different numbers. A recall figure quoted without saying which of the three it came from is not a claim we will stand behind, including when we are the ones who said it.
2.8 What it guarantees
Append-only. Nothing is edited in place. State changes are appended in a monotonic order, sealed segments are hash-sealed, and each seal commits to the seals before it. An offline verifier can walk the chain and prove that nothing was inserted, reordered or rewritten.
Deterministic replay. Replaying the same events reproduces the same bytes, not a plausible re-run. Replay digests are computable independently.
Independent verifiability. Receipts are Ed25519-signed, with the signature bound to both the receipt id and the payload hash. Verification runs offline, with no network access and no trust in the service. Conformance vectors keep client verifiers checked against the core implementation.
Durability of erasure across restart and rebuild. The online erasure step flushes durably and writes tombstones, and a rebuild from the beginning of the spine honours them.
Tenant isolation under a JWT auth mode. Enforced per handler on the token's tenant claim, with no batch back door.
Integrity verification on demand. The control CLI checks frame integrity, and a strict mode additionally recomputes sealed-segment hashes and cross-checks them against the manifest.
Attach atomicity. A bulk attach is count-verified, receipted and reversible.
Readiness honesty. If the direct NVMe-to-GPU transfer path is configured but not genuinely engaged, or is running in a compatibility fallback, /readyz stays at 503 by design rather than serving a silently degraded path. Readiness also gates on free space on the data partition.
Configuration safety by default. New retrieval lanes ship off. Hibernation ships off. Enabling anything is an explicit, per-tenant act, and disabling it again is immediate and non-destructive.
2.9 What it does not promise
It is not a general-purpose database. No arbitrary updates, no SQL, no foreign keys. If you need a transactional system of record for mutable rows, this is not it, and pointing it at that job will go badly.
Erasure does not reach outside the data directory. Operator backups, snapshots, replicas and downstream copies are the operator's responsibility.
Materialised state is eventually consistent with the spine. Projections are asynchronous views. The spine is the authority. Consistency is monitored, not assumed.
Physical erasure requires downtime for that node, and requires the tenant to be siloed first.
Under off and dev_scopes auth there is no tenant isolation at all. This is a development-only posture and the daemon actively refuses to expose it on a network interface.
Dense retrieval depends on an external embedding service. If the embedder is unreachable, dense lanes degrade while lexical and graph lanes continue.
No GPU, no CoreCrux. There is no CPU-only production mode of this product. That product is the Community Edition.
It is not a validated multi-node story yet. Sharding and replication exist, and multi-node and multi-GPU validation is tracked as ongoing operational work. Ask for the currently-validated shape rather than the roadmap shape, and expect to be given the former.
There is no latency or availability SLA. As with the hosted plane, any service level has to be a commercial agreement, not an inference from a benchmark table.
2.10 Operational shape
Deployment model. Customer-hosted on the customer's own hardware, or CueCrux-hosted on dedicated hardware. One daemon per GPU node; data lives on that node's local NVMe. Configuration is entirely environment-driven. There is no phone-home and no licence server in the serving path.
Hardware. An NVIDIA GPU with a current driver and CUDA runtime, plus local NVMe. The reference production node class is an RTX 4000 SFF Ada 20 GB with driver 570 and CUDA 12.8.
For the highest-throughput IO mode, direct NVMe-to-GPU transfer that bypasses host RAM, the host must be native Linux with the GPUDirect Storage kernel components installed and functional. WSL2 does not provide these, and the daemon will correctly refuse to report ready in that mode rather than falling back silently. A conventional IO mode runs without those components.
Data residency and air-gap. All customer data stays in the data directory on the node. The engine's only outbound network dependency in the serving path is the embedding service, and that service is itself self-hostable, so a fully air-gapped deployment is achievable by co-locating the embedder. There is no external vector database, no managed control plane and no telemetry requirement. OpenTelemetry export exists and is the operator's choice, not a condition of running the product.
Deploy discipline. Deployments go through a wrapper that refuses to build from an uncommitted tree, snapshots the currently-running binary before overwriting it, tags the source commit with the resulting binary hash and a UTC timestamp, restarts, and polls readiness. Every running binary therefore maps deterministically back to a commit. A companion audit tool compares the running binary's hash against the most recent deploy tag and exits non-zero on drift; it is designed to run on a timer and be paged on. Rollback is restoring the pre-deploy binary snapshot.
Backup and erasure. Backup is a filesystem-level backup of the data directory plus the manifest. The integrity of a restored copy is checkable with the strict store-verification mode. Erasure is the two-step online-tombstone then offline-physical-erase flow in 2.6.5, both steps receipted.
Day-2 runbooks ship with the product and cover GPU memory pressure, compaction backlog, disk capacity, long-soak validation, storage-readiness failures, replication health, multi-node rollout gates, and audit-pack production.
Observability. GET /healthz returns build version, build commit and compatibility metadata. GET /readyz returns 200 only when every dependency check passes, and 503 with the failing checks otherwise. GET /metrics is Prometheus text including a build-info gauge. This trio is a contractual integration surface, not an implementation detail, and it is safe to build alerting on.
2.11 Claims corrected from earlier published copy
| Claim that was published | Correction |
|---|---|
| "Cold segments hibernate to near-zero memory and rehydrate on demand" | Wrong subject. Hibernation operates on idle tenants' materialised projection state, not on segments. See 2.6.7. |
| "Erasure is receipt-scoped: the record is removed and the manifest rewritten" | Conflates two products. Receipt-scoped forgetting is the Community Edition fact-store model. CoreCrux erasure is tenant-scoped and two-step: an online projection tombstone, then an offline physical segment erase that requires the tenant to be siloed first. The manifest is rewritten only in the offline step. See 2.6.5. |
| "Answers come from fused lanes: lexical (BM25) and dense" | Understated. Several complementary lanes, lexical, dense-vector, sparse, graph and structural, are fused into one ranking. See 2.6.1. |
| "Dense retrieval is inert here and lives in a separate engine against an external vector database" | No longer true. Dense is a first-class native lane with a server-side embedder integration and offline dense build tooling. |
| A component map naming four separate services as the readers, writers, auditors and monitors of this engine | Stale topology. Those components were retired or never shipped. The live consumer is Crux Engine; see 2.4. |
| "GPU-accelerated segment logs that can handle extremely high write throughput" | An unquantified superlative with no corpus. Withdrawn in favour of 2.7. |
| "Our database" | A positioning error. CoreCrux is a retrieval and evidence engine and 2.9 explicitly disclaims being a general-purpose database. |
2.12 Grounding, and what is deliberately absent
CoreCrux is a closed system. This chapter carries no source links, because internal paths are precisely what must not be published. Every claim above is grounded on an endpoint, a request or response field, a header, a scope, a status code, or an observable behaviour you can provoke on a deployment you have access to.
Deliberately absent, permanently: on-disk artefact and index format names; posting-list, term-dictionary, quantisation and approximate-nearest-neighbour internals; the fusion function and its constants; per-lane normalisation and confidence computation; default lane weights and which lanes a deployment starts with; scoring thresholds; GPU kernel and memory-layout detail; the environment-variable and feature-flag surface; internal module, crate and function names; and the addresses of specific machines.
Present and staying present, because they are contracts: endpoint paths, request and response field names, auth modes, scope names, header semantics, status codes, the bulk-ingest payload format, and the health, readiness and metrics trio.
Next: 1. Crux Engine for the hosted plane that reads this substrate, 3. FeatureCrux for the internal control plane, and 4. How they fit together for what stays yours in each deployment shape.