About / The project

A single-author Rust project that treats encryption as load-bearing.

Not an option, not an extension, not a wrapper. A 20-crate Rust workspace: a full SQL engine, a key-value API, AES-256-CTR + HMAC encryption at the page level, shadow paging, an encrypted memory engine, and a reproducible benchmark suite against SQLite.

01Principles
i.

Encryption is load-bearing.

Every page is AES-256-CTR ciphertext with an HMAC-SHA256 tag. There is no unencrypted mode. You cannot disable it, forget to enable it, or ship a build without it. The file format itself refuses to exist in plaintext.

ii.

Crash-safety without a WAL.

Commits use shadow paging: modified pages are written to fresh locations, then a single-byte flip in the file header atomically publishes the new commit slot. No separate log to replay, no fsync storm, no partial-write window.

iii.

Embedded means no server.

Citadel is a library. There is no daemon, no listener, no network code path in the default build. Your application's process is the database, the same deployment model as SQLite, with crypto as a property of the file format.

iv.

Memory is encrypted the same way.

The memory engine, citadel-mem, stores vectors, atoms, and edges on the exact same encrypted pages. Forgetting is cryptographic: destroy an atom's or region's key and the ciphertext that remains is unrecoverable, with a verifiable erasure receipt.

v.

The benchmarks are reproducible.

The 50 head-to-head benchmarks against unencrypted SQLite live in citadeldb-sql/benches/h2h_bench.rs. Run them yourself with cargo bench. We publish what the bench output says, not a marketing average.

02Repo shape

A Cargo workspace of 20 crates, layered from the bytes on disk up to the SQL frontend, the memory engine, and the bindings. Each crate has its own tests; 5,200+ in total, with 100% pass on cargo test --workspace. 15 crates publish to crates.io, plus a citadeldb wheel to PyPI.

citadel-core
Shared types, errors, constants.
citadel-io
File I/O, fsync, file locking, io_uring on Linux.
citadel-page
Page format, serialization, checksums.
citadel-buffer
SIEVE buffer pool, encrypt/decrypt pipeline.
citadel-crypto
AES-256-CTR, HMAC-SHA256, Argon2id, key hierarchy.
citadel-txn
MVCC transactions, CoW B+ tree, shadow-paging commit.
citadel-sync
CRDT replication, Merkle diffing over Noise.
citadel
Database API, builder, umbrella crate.
citadel-sql
Parser, planner, executor. JOINs, CTEs, triggers, JSON/JSONB, FTS.
sql-json-path
SQL/JSON Path engine (forked from RisingWave Labs).
citadel-vector
VECTOR(N) type and PRISM filtered ANN index.
citadel-mem
Memory engine: regions, atoms, edges, traces.
citadel-ai
Agent runtime: ReAct + Reflexion, budget caps.
citadel-mcp
MCP server exposing memory as 13 tools.
citadel-cli
REPL with 26 dot-commands, tab completion.
citadel-ffi
37 C-ABI functions. cbindgen header.
citadel-wasm
WebAssembly build. @citadeldb/wasm on npm.
citadel-python
PyO3 bindings. citadeldb wheel on PyPI.
citadel-membench
LoCoMo long-memory benchmark harness.
citadel-swe
Mini-SWE agent benchmark harness.
03Facts, verified

Every number here is either in the README, in a source file, or returned by the test suite. No marketing approximations.

Language
Rust 1.75+
stable toolchain
License
MIT or Apache-2.0
dual
Workspace crates
20 / 15 published
see section 02
Tests
5,200+ / 100% pass
cargo test --workspace
Head-to-head wins
50 / 50 vs SQLite
geo mean ~2.8×
Page size
8,208 B on disk
16 IV + 8,160 ct + 32 MAC
Cipher
AES-256-CTR
ChaCha20 available
MAC
HMAC-SHA256
per-page tag
KDF
Argon2id
PBKDF2 in FIPS mode
Commit
Shadow paging / god-byte flip
no WAL
Isolation
Snapshot / CoW B+tree
single-writer MVCC
FFI surface
37 C-ABI functions
citadel-ffi
MCP tools
13 over stdio
citadel-mcp
LoCoMo score
85.5% (3-run mean)
encrypted / vs 95.1% recall ceiling
04Grounded in the source

Each capability below lives in the open-source tree. Here is where to find it:

core
Cipher, MAC, KDF, page size, shadow paging, 5,200+ tests, 50/50 head-to-head, 20 crates, 37 FFI functions, and 13 MCP tools, all grounded in the README and source tree.
sql
FULL OUTER + LATERAL joins, recursive and with-DML CTEs, UPSERT (ON CONFLICT), RETURNING, generated columns, JSON/JSONB with 14 PostgreSQL operators, triggers, materialized views, full-text search, partial / GIN indexes, native DATE/TIMESTAMP, and a VECTOR(N) type with an ANN index. Implemented in citadel-sql and citadel-vector.
memory
citadel-mem stores regions of typed atoms and edges with hybrid recall and cryptographic erasure; citadel-mcp serves it over the Model Context Protocol; the 85.5% LoCoMo score is measured by citadel-membench.
targets
Rust on crates.io, Python on PyPI, WebAssembly on npm, C ABI via citadel-ffi, and the citadel CLI.
playground
The Playground runs the actual engine compiled to WebAssembly. Your SQL executes in your browser against a real encrypted in-memory database; nothing is sent to a server.
05Maintainer
YP

Yuriy Peysakhov

Sole author / @yp3y5akh0v on GitHub
View repoPRs welcome

Citadel is a one-person project. If you want to contribute, the crate list in section 02 is a good map of where help is welcome - each crate is a self-contained area: parser extensions in citadel-sql, new code paths in citadel-crypto, recall tuning in citadel-mem, and more language bindings.

Encrypted by construction. Not by option.
citadel / v1.7.0