---

---

Calyx is a database whose native record is the association-constellation: one input measured through many frozen embedders ("lenses"), fused, differentiated by the information each one adds, and anchored to real outcomes. It finds the small grounding kernel that explains a whole dataset, guards generated content against drift and out-of-distribution answers, keeps a tamper-evident ledger of how every answer was produced, and gets faster the more you use it.

A calyx is the whorl of sepals that holds a flower together at its base — the grounded structure from which a constellation of petals opens. That is exactly what this database is: a grounded base (kernel + provenance) that holds a constellation of vectors and lets it bloom into search, naming, and answers.

---

🧩 Calyx is a base, not a finished product

Calyx is a template. It computes associations — it measures one input through many lenses, fuses them, finds the grounding kernel, guards every answer, and records provenance. But the moment an association means something specific — something you can infer, recognize, or act on — that recognition-and-trigger logic is code you write for your data. Every Calyx database holds different data, forms different associations, and unlocks different meanings; what happens the instant a meaning is recognized is custom to each project.

That is by design, and it is why Calyx will always be a base rather than a shrink-wrapped product. You don't ship the template — you refactor it into your specific use case, exactly like starting a product from a frontend template instead of a blank page. Beginning from the Calyx base, you are already very far along: the hard, reusable machinery (constellations, kernel, guard, ledger) is built and grounded for you. What remains is the part only you can write — the meaning your data unlocks, and what your system does when it sees it.

---

✨ Why Calyx

Every time you build a serious retrieval or intelligence system, you end up gluing the same machinery together by hand: a vector store for semantics, a keyword index for lexical match, a graph database for relationships, a pile of bespoke code to combine embedders, more code to measure whether a new embedder actually helps, and still nothing that tells you when your AI's answer has wandered outside what your data can support.

Calyx bakes that machinery once, into the storage engine.

[!NOTE] A vector database is a one-lens Calyx: a single embedder plus nearest-neighbor search. Calyx is built for the case where one signal is never enough.

---

🌟 The core idea: constellations

A traditional database stores a row. A vector database stores a point. Calyx stores a constellation: one input, measured through many independent lenses (embedders and feature extractors), each producing its own typed slot-vector — kept separate, never flattened into one opaque blob.

Calyx is organized around four verbs — the calculus of association:

Three principles make the results trustworthy:

• Grounding is mandatory. Every claim is measured against real, anchored outcomes. Ungrounded results are explicitly tagged provisional rather than presented as fact.
• Keep slots separate (no-flatten). Signals stay typed and independent end-to-end, so you can always see which lens drove a result.
• Fail closed. Unknown lens, shape mismatch, uncalibrated guard, missing data → a structured error, never a silent wrong answer.

---

🚀 Build from source

[!IMPORTANT] Calyx is a Rust workspace (edition 2024, toolchain 1.95). It builds CPU-only by default; the GPU backend is an opt-in feature.

Prerequisites

• Rust 1.95 (via rustup; the pinned toolchain is in rust-toolchain.toml)
• A C toolchain (required by native numeric/runtime dependencies)
• Optional, for GPU acceleration: an NVIDIA sm_120-class GPU and CUDA 13.3

Build & test

git clone https://github.com/ChrisRoyse/Calyx.git
cd Calyx

# CPU build (portable, uses SIMD math)
cargo build --release --workspace

# Run the test suite
cargo test --workspace

# Optional: build with the CUDA backend
cargo build --release --workspace --features cuda

[!NOTE] The polished public CLI and the agent-facing MCP server are in active development. A dedicated usage guide will ship alongside them — see Project status.

---

🧭 Architecture

Calyx is not a service mesh. It is an embedded engine — a stack of focused Rust crates — with three thin entry points on top: a CLI (calyx), a daemon (calyxd), and an MCP server (calyx-mcp).

Every subsystem is named for an instrument of celestial navigation: a lens is a sighting instrument, the kernel is the guiding star, and search is navigation.

---

🧠 The intelligence layer

What makes Calyx more than a fast multi-index search engine is the layer that turns retrieval into grounded intelligence.

⭐ Lodestar — the grounding kernel

Most datasets are mostly redundant. Lodestar discovers the small set of records — the kernel — that actually carries the structure of the whole corpus, scoring candidates by how central and how grounded they are. The kernel then doubles as a fast index and as an answer path: route a query through the kernel first, then walk its edges to an answer.

🛡️ Ward — the no-hallucination guard

Ward is a fail-closed boundary around what your data can support. Each required slot is scored independently against a calibrated threshold — there is no single averaged gate that a strong score on one slot can sneak past. Anything outside the trusted region is refused, quarantined, or recorded as a new region to learn — never waved through. Thresholds are set by conformal calibration to a target false-accept rate, so the guard's strictness is a number you choose, not a guess.

📜 Ledger — provenance you can verify

Every measurement, kernel, guard verdict, and answer is appended to a hash-chained ledger. Each entry seals the one before it, so any tampering is detectable; periodic checkpoints can be cryptographically signed; and a single command can re-verify the entire chain. You can always answer the question "how was this produced, and has anything changed since?"

♨️ Anneal — a database that improves with use

Anneal continuously tunes the engine — index parameters, quantization levels, fusion weights — but safely: every change is gated against quality tripwires and shadow-tested before it goes live, and anything that regresses recall, latency, or guard accuracy is automatically reverted. Optimization that can only make things better, and is always reversible.

🔮 Oracle — grounded consequence prediction

Oracle predicts the grounded consequences of an action by mining recurrence patterns in your data, builds a branching "butterfly" tree of likely downstream effects, and can even walk backward from an outcome to its likely causes. Crucially, it has an honesty gate: when the available signals can't support a confident prediction, Oracle returns insufficient with the specific deficits — instead of fabricating an answer.

---

🗄️ One core, every paradigm

Because everything is built on one ordered, transactional storage core, Calyx can serve the role of many database shapes at once:

The search-shaped paradigms collapse into the association engine; the storage-shaped ones are the general data layer beneath it. One engine, one transaction, one source of truth.

---

🗺️ Project status

[!WARNING] Calyx is pre-1.0 software under active development. The on-disk format and public interfaces may change before a stable release.

The core engine — storage, math, the lens registry, multi-signal search, the association and information layers, the grounding kernel, the guard, the ledger, self-optimization, and the first oracle capabilities — is built and working.

Actively expanding toward 1.0:

• A richer public CLI and a populated MCP toolset so agents can drive the full engine directly.
• Scale-out vector indexing (on-disk graph and centroid-partitioned indexes) for very large vaults.
• Server & deployment polish for running calyxd as a managed service.
• Broader validation of the oracle and guard against public benchmark corpora.

[!NOTE] The dream. Calyx's north star is a grounded substrate for planetary-scale intelligence: hold the world's data un-flattened, measure it through many diverse lenses, derive the associations between distant domains, and surface ranked, provenance-backed, validatable hypotheses — never ungrounded answers. Two levers maximize what it can discover: corpus breadth and lens diversity. In a world where any answer is cheap to generate, the scarce resource is grounded verification — knowing what is true and being able to trace it to its sources — and that is exactly what Calyx is built to provide. The white paper lays out the full path, including why this workload's natural long-term home is neuromorphic, in-memory hardware. That vision is aspirational and Calyx is pre-1.0; the honesty gate that underpins it is already built.

---

📄 License

Calyx is source-available under the Business Source License 1.1 (BSL) — the same model used by databases like CockroachDB, MariaDB, and Couchbase.

Each released version automatically converts to the open-source Apache License 2.0 four years after its release. For a commercial license, please open an issue. See LICENSE for the binding terms.

---