About / The project

A single-author Rust project with no unencrypted mode.

An encrypted memory engine with hybrid recall and an MCP server, built on an embedded SQL/vector database. Citadel Studio provides a native interface for SQL, stored memory, and vault diagnostics.

01Principles
i.

The file format is always encrypted.

Page payloads use AES-256-CTR with HMAC-SHA256 authentication. There is no unencrypted storage mode. File headers and commit metadata are not hidden.

ii.

Crash-safety without a WAL.

Commits use shadow paging: modified pages are written to fresh locations before publishing a new commit slot. Durable commits flush the pages and commit metadata in order; recovery validates the retained slots.

iii.

Embedded means no server.

The database runs inside your application and needs no separate server. Network sync and the stdio MCP server are explicit integrations.

iv.

Memory is encrypted the same way.

The memory engine stores vectors, atoms, and edges through the encrypted database. Encrypted regions support per-atom and per-region key erasure with receipts. External backups, copied keys, and exported plaintext are outside that erasure.

v.

The benchmarks are reproducible.

The 59 head-to-head benchmarks against unencrypted SQLite live in crates/citadel-sql/benches/h2h_bench.rs. They compare engine overhead with durability disabled. Commands and measured results are in the README.

02Repo shape

A Cargo workspace of 22 crates, layered from the bytes on disk up to the SQL frontend, the memory engine, and the bindings. Thousands of unit, integration, and torture tests run across the workspace. 16 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-llm
Provider-neutral LLM client layer: Claude, OpenAI, Ollama, Gemini.
citadel-ai
Agent runtime: ReAct + Reflexion, budget caps.
citadel-mcp
MCP server exposing memory as 15 tools.
citadel-cli
REPL with 27 dot-commands, tab completion.
citadel-studio
Native SQL, stored-memory, and vault inspection client.
citadel-ffi
Panic-safe C ABI. 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.
03Specifications
Language
Rust 1.95+
stable toolchain
License
Apache-2.0
permissive
Workspace crates
22 / 16 published
see section 02
Tests
Workspace-wide
cargo test --workspace
Head-to-head
59 comparisons vs SQLite
durability off / methodology
Page size
8,208 B on disk
16 IV + 8,160 ct + 32 MAC
Cipher
AES-256-CTR
per-page HMAC-SHA256
MAC
HMAC-SHA256
per-page tag
KDF
Argon2id
PBKDF2 at-rest profile
Commit
Shadow paging / god-byte flip
no WAL
Isolation
Snapshot / CoW B+tree
single-writer MVCC
FFI surface
Panic-safe C ABI
citadel-ffi
MCP tools
15 over stdio
citadel-mcp
LoCoMo score
87.2% (3-run mean)
historical / encrypted
LongMemEval-S
86.2% (gpt-4o, full-haystack)
historical / single run
04Grounded in the source

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

core
Encrypted pages and key management in citadel-crypto; transactions and authenticated commit slots in citadel-txn; public database APIs in citadel.
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. Historical memory results and configurations are recorded by citadel-membench.
targets
Rust on crates.io, Python on PyPI, WebAssembly on npm, C ABI via citadel-ffi, the citadel CLI, and Citadel Studio. See downloads and build instructions.
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 / v2.5.0