\n\n## Quick Start\n\n```bash\npip install citadeldb\n```\n\n```python\nimport citadeldb\n\ndb = citadeldb.connect(\"memory.cdl\", key=\"your-passphrase\", region_keys=True)\nmem = db.memory()\nmem.create_encrypted_region(\"chat\", citadeldb.MockEmbedder(dim=64))\n\nmem.remember(\"chat\", {\"kind\": \"fact\", \"text\": \"Alice's cat is named Mochi\"})\nberlin = mem.remember(\"chat\", {\"kind\": \"fact\", \"text\": \"Alice lives in Berlin\"})\n\nfor hit in mem.recall(\"chat\", text=\"where does Alice live?\", k=2):\n print(f\"{hit.score:.3f} {hit.text}\")\n# 0.850 Alice lives in Berlin\n# 0.200 Alice's cat is named Mochi\n\n# Forgetting destroys the atom's key, so the ciphertext is unrecoverable.\nreceipt = mem.forget(\"chat\", [berlin])\nprint(receipt.cryptographic_erasure, receipt.algorithm)\n# True AES-256-KW(RFC3394)\n```\n\n`MockEmbedder` needs no download and is enough to try the API. For real recall\nquality use `CandleEmbedder` with a local e5-large, which is the benchmark setup.\n\n### Memory (Rust)\n\nUses the `citadeldb` and `citadeldb-mem` crates (enable `citadeldb-mem`'s `candle-embed` feature). `e5_large` loads the recommended local embedder, and adding a `CrossEncoder` reranker gives the best recall (the benchmark config). Other presets (`bge_large`, `bge_small`, ...) or a custom `Embedder` work too.\n\n```rust\nuse std::sync::Arc;\nuse citadel::DatabaseBuilder;\nuse citadel_mem::{AtomInput, CandleEmbedder, CrossEncoder, MemoryEngine, RecallQuery, RerankStrategy};\n\n// Encrypted store (per-atom keys enable cryptographic forgetting)\nlet db = DatabaseBuilder::new(\"memory.db\")\n .passphrase(b\"secret\")\n .enable_region_keys(true)\n .create()?;\nlet mem = MemoryEngine::open(Arc::new(db))?;\n\n// Local embedder (e5-large) + cross-encoder reranker = the best-recall setup\nlet embedder = Arc::new(CandleEmbedder::e5_large(\"/path/to/e5-large\")?);\nmem.create_encrypted_region(\"chat\", embedder)?;\nmem.set_reranker(\n Arc::new(CrossEncoder::ms_marco_minilm_l6(\"/path/to/ms-marco-minilm\")?),\n RerankStrategy::default(),\n);\n\n// Remember raw turns (no LLM)\nmem.remember(\"chat\", AtomInput::new(\"fact\", \"Alice's cat is named Mochi\"))?;\nlet berlin = mem.remember(\"chat\", AtomInput::new(\"fact\", \"Alice lives in Berlin\"))?;\n\n// Recall by relevance\nfor hit in mem.recall(\"chat\", RecallQuery::by_text(\"where does Alice live?\", 5))? {\n println!(\"{:.3} {}\", hit.score, hit.text);\n}\n\n// Cryptographic forgetting: destroy the atom's key\nmem.forget_atom(\"chat\", berlin)?;\n```\n\n### SQL and key-value\n\nUses the `citadeldb` and `citadeldb-sql` crates - or try SQL with no install in the [live playground](https://citadeldb.dev/demo/).\n\n```rust\nuse citadel::DatabaseBuilder;\nuse citadel_sql::Connection;\n\nlet db = DatabaseBuilder::new(\"my.db\")\n .passphrase(b\"secret\")\n .create()?;\n\nlet conn = Connection::open(&db)?;\nconn.execute(\"CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);\")?;\nconn.execute(\"INSERT INTO users (id, name) VALUES (1, 'Alice');\")?;\nlet result = conn.query(\"SELECT * FROM users;\")?;\n\n// Key-value API\nlet mut wtx = db.begin_write()?;\nwtx.insert(b\"key\", b\"value\")?;\nwtx.commit()?;\n\nlet mut rtx = db.begin_read();\nassert_eq!(rtx.get(b\"key\")?.unwrap(), b\"value\");\n\n// Named tables\nlet mut wtx = db.begin_write()?;\nwtx.create_table(b\"sessions\")?;\nwtx.table_insert(b\"sessions\", b\"token-abc\", b\"user-42\")?;\nwtx.commit()?;\n\n// In-memory (no file I/O - useful for testing and WASM)\nlet mem_db = DatabaseBuilder::new(\"\")\n .passphrase(b\"secret\")\n .create_in_memory()?;\n```\n\n### CLI\n\n```bash\ncitadel --create my.db\n\ncitadel> CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);\ncitadel> INSERT INTO users (id, name) VALUES (1, 'Alice'), (2, 'Bob');\ncitadel> SELECT * FROM users;\n+----+-------+\n| id | name |\n+----+-------+\n| 1 | Alice |\n| 2 | Bob |\n+----+-------+\n\ncitadel> .backup mydb.bak\ncitadel> .verify\ncitadel> .upgrade\ncitadel> .stats\ncitadel> .audit verify\ncitadel> .rekey\ncitadel> .compact clean.db\ncitadel> .dump users\n\n# P2P sync\ncitadel> .keygen\ncitadel> .listen 4248 # Terminal A\ncitadel> .sync 127.0.0.1:4248 # Terminal B\n```\n\n### Agent frameworks\n\nEach package implements that framework's own storage interface, so existing code keeps\nworking and only the constructor changes. Deleting through any of them destroys the\nrecord's key, not just its row, and search is ranked recall rather than a `LIKE`.\n\n| Framework | Package | Implements |\n|---|---|---|\n| [LangGraph](packaging/citadeldb-langgraph) | [`citadeldb-langgraph`](https://pypi.org/project/citadeldb-langgraph/) | `BaseStore` |\n| [CrewAI](packaging/citadeldb-crewai) | [`citadeldb-crewai`](https://pypi.org/project/citadeldb-crewai/) | `StorageBackend` |\n| [OpenAI Agents SDK](packaging/citadeldb-openai-agents) | [`citadeldb-openai-agents`](https://pypi.org/project/citadeldb-openai-agents/) | `Session` |\n| [Google ADK](packaging/citadeldb-google-adk) | [`citadeldb-google-adk`](https://pypi.org/project/citadeldb-google-adk/) | `BaseMemoryService` |\n| [LlamaIndex](packaging/citadeldb-llamaindex) | [`citadeldb-llamaindex`](https://pypi.org/project/citadeldb-llamaindex/) | `BasePydanticVectorStore` |\n| [LangChain](packaging/citadeldb-langchain) | [`citadeldb-langchain`](https://pypi.org/project/citadeldb-langchain/) | `VectorStore`, `BaseChatMessageHistory` |\n| [Haystack](packaging/citadeldb-haystack) | [`citadeldb-haystack`](https://pypi.org/project/citadeldb-haystack/) | `DocumentStore` |\n| [Microsoft Agent Framework](packaging/citadeldb-ms-agent-framework) | [`citadeldb-ms-agent-framework`](https://pypi.org/project/citadeldb-ms-agent-framework/) | `HistoryProvider`, `ContextProvider` |\n| [Strands Agents](packaging/citadeldb-strands-agents) | [`citadeldb-strands-agents`](https://pypi.org/project/citadeldb-strands-agents/) | `SessionRepository` |\n\n```bash\npip install citadeldb-langgraph\n```\n\n```python\nimport citadeldb\nfrom citadeldb_langgraph import CitadelStore\n\nstore = CitadelStore(\n \"agent.cdl\",\n key=\"your-passphrase\",\n embedder=citadeldb.MockEmbedder(dim=64), # replace with your production model\n)\nstore.put((\"users\", \"alice\"), \"prefs\", {\"theme\": \"dark\"})\nstore.search((\"users\",)) # every namespace under users/\nstore.forget_namespace((\"users\", \"alice\")) # cryptographic erasure, returns a count\n```\n\nOne database serves every adapter on the thread that opened it, so a graph's long-term\nstore and its session transcripts can share one encrypted file. See [`packaging/`](packaging/) for each\npackage's own README.\n\n### MCP\n\nServe an encrypted memory region to Claude Desktop or any MCP client. `citadeldb-mcp` is\npublished to PyPI and listed in the official [MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=dev.citadeldb/mcp)\nas `dev.citadeldb/mcp`. Run it without installing through `uvx`.\n\nFor the recommended semantic-recall setup, pull the embedder and cross-encoder reranker once:\n\n```console\nuvx citadeldb-mcp pull e5-large\nuvx citadeldb-mcp pull ms-marco-minilm\n```\n\nThe pull commands do not need a vault key. Before starting the server, set `CITADEL_KEY`\nto the vault passphrase: use `export CITADEL_KEY=\"your-passphrase\"` on macOS/Linux or\n`$env:CITADEL_KEY = \"your-passphrase\"` in PowerShell. Then run:\n\n```console\nuvx citadeldb-mcp --db memory.cdl --embedder e5-large --reranker ms-marco-minilm\n```\n\n`--db`, `--embedder`, and `CITADEL_KEY` are required when serving. The reranker is optional,\nbut `e5-large` with `ms-marco-minilm` is the recommended highest-recall configuration used\nfor the memory benchmarks. `--embedder mock` is a keyword-only option, not a semantic\nembedder.\n\nTo install the executable instead, run `pip install citadeldb-mcp` or\n`cargo install citadeldb-mcp`. Pull the same models with `citadeldb-mcp pull e5-large` and\n`citadeldb-mcp pull ms-marco-minilm`, then add it to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"citadel\": {\n \"command\": \"citadeldb-mcp\",\n \"args\": [\n \"--db\", \"/absolute/path/to/memory.cdl\",\n \"--embedder\", \"e5-large\",\n \"--reranker\", \"ms-marco-minilm\"\n ],\n \"env\": { \"CITADEL_KEY\": \"your-passphrase\" }\n }\n }\n}\n```\n\n## Memory benchmarks\n\nCitadel is scored on the LoCoMo and LongMemEval long-term-memory benchmarks. Execution speed against unencrypted SQLite across 58 head-to-head benchmarks is under [Speed benchmarks](#speed-benchmarks).\n\n**LoCoMo** - `gpt-4o-mini` reader and judge (the 2025 paper-comparison protocol), mean of 3 runs:\n\n| Metric | Score |\n|---|---|\n| Overall | 87.2% +/- 0.3 |\n| Full context at the same reader (no retrieval) | 72.9% |\n\nRetrieval is identical across the three runs; the spread is reader and judge\nnondeterminism. A manual audit estimates that ~6.4% of LoCoMo answer keys are erroneous,\nso raw accuracy should be interpreted with that annotation noise in mind.\n\nMemory is built with no LLM - raw turns only, indexed and recalled deterministically.\n\n**LongMemEval_S** ([arXiv 2410.10813](https://arxiv.org/abs/2410.10813)) full-haystack split (~40-50 sessions/question), gpt-4o reader, official CoT prompt and `gpt-4o-2024-08-06` judge:\n\n| Metric | Score |\n|---|---|\n| Overall | 86.2% |\n| Task-averaged | 86.8% |\n| Abstention | 80.0% |\n\nFull-haystack stresses retrieval against distractors (not the oracle reader ceiling). Protocol and per-type results in [citadel-membench](https://github.com/yp3y5akh0v/citadel/blob/HEAD/crates/citadel-membench/RESULTS.md).\n\n## Encrypted memory engine\n\nThe same encrypted pages that hold SQL tables also hold memory. Three crates make up\nthe memory engine:\n\n- **[citadeldb-vector](https://github.com/yp3y5akh0v/citadel/tree/HEAD/crates/citadel-vector)** - a `VECTOR(N)` SQL type, distance operators (`<->` L2, `<#>` inner, `<=>` cosine), and a [PRISM](https://github.com/yp3y5akh0v/prism)-backed filtered ANN index that reads through the encrypted page store.\n- **[citadeldb-mem](https://github.com/yp3y5akh0v/citadel/tree/HEAD/crates/citadel-mem)** - the memory engine (regions, atoms, edges) with hybrid recall and **cryptographic forgetting**: an atom or region is erased by destroying its key, at whole-store, per-region, and per-atom granularity.\n- **[citadeldb-mcp](https://github.com/yp3y5akh0v/citadel/tree/HEAD/crates/citadel-mcp)** - a Model Context Protocol server exposing a Citadel memory region (encrypted by default) to any MCP client (Claude Desktop, IDEs) as recall/remember/link/evolve/forget/verify tools.\n\n### Zero-LLM memory path\n\ncitadeldb-mem uses no LLM at ingest or retrieval: it stores raw conversation content\nand recalls with embeddings, BM25 keyword matching, and a cross-encoder reranker.\nRemembering costs zero tokens, recall is deterministic, and the conversation is never\nsent to an LLM to build or search the memory. The readers and judges above are separate\nLLMs - gpt-4o-mini for LoCoMo, gpt-4o for LongMemEval. Protocol and a comparison with\npublished systems are in\n[citadel-membench](https://github.com/yp3y5akh0v/citadel/blob/HEAD/crates/citadel-membench/RESULTS.md).\n\n## Agent runtime\n\n- **[citadeldb-llm](https://github.com/yp3y5akh0v/citadel/tree/HEAD/crates/citadel-llm)** - the provider-neutral LLM client layer (Claude, OpenAI, Ollama, Gemini) behind one factory, with canonical request hashing and a non-secret client request identity.\n- **[citadeldb-ai](https://github.com/yp3y5akh0v/citadel/tree/HEAD/crates/citadel-ai)** - an autonomous agent runtime (ReAct + Reflexion, tool registry, budget caps, pluggable LLM backends) that uses citadeldb-mem for persistence.\n\n## Features\n\n- **Encrypted at rest** - AES-256-CTR + HMAC-SHA256 per page, verified before decryption\n- **SQL** - JOINs, subqueries, CTEs (recursive + WITH-DML), UNION/INTERSECT/EXCEPT, window functions, views, materialized views, triggers, TEMP tables, generated columns (STORED + VIRTUAL), constraints, full FK actions, UPSERT, RETURNING, JSON/JSONB (14 Postgres operators + SQL/JSON path language), full-text search, prepared statements with plan caching, and a queryable system catalog. Full list under [SQL](#sql)\n- **ACID** - Copy-on-Write B+ tree, shadow paging, no WAL. Snapshot isolation with concurrent readers\n- **Authenticated commit slots** - the commit metadata (table roots, catalog) carries its own HMAC; older files migrate one-way via `.upgrade`\n- **P2P sync** - Merkle-based table diffing over Noise-encrypted channels with PSK auth\n- **CLI** - SQL shell with tab completion, syntax highlighting, 27 dot-commands (.backup, .verify, .upgrade, .rekey, .sync, .dump, ...)\n- **3-tier key hierarchy** - Passphrase -> Argon2id -> Master Key -> AES-KW -> REK -> HKDF -> DEK + MAC\n- **Cryptographic forgetting** - Erase data by destroying its key, not by overwriting: whole-store, and per-region / per-atom via [citadeldb-mem](https://github.com/yp3y5akh0v/citadel/tree/HEAD/crates/citadel-mem). A forgotten region or atom is unrecoverable\n- **FIPS-oriented at-rest profile** - PBKDF2-HMAC-SHA256 + AES-256-CTR for database storage; not a claim of whole-product validation\n- **Audit log** - HMAC-SHA256 chained within files and across retained v2 generations; retained-history verification detects record edits and broken retained links, but there is no external anti-rollback anchor\n- **Hot backup** - Consistent snapshots via MVCC, no write blocking\n- **Overflow pages** - Large values handled transparently, no size limits\n- **Cross-platform** - Windows, Linux, macOS. Python, C FFI, and WebAssembly bindings\n- **Thousands of tests** - Unit, integration, and torture tests across 21 crates\n\n## Speed benchmarks\n\nSingle-threaded, durability off (pure engine overhead). Most benchmarks run on 100K rows of `(id INTEGER PK, name TEXT, age INTEGER)`; per-benchmark queries and schemas are in Methodology. Ratio = SQLite / Citadel time (higher is faster). Two-run medians.\n\n### Execution speed\n\nEvery iteration computes its result: writes, and reads whose parameters rotate per iteration or whose shape re-executes against the storage engine.\n\n```\nBenchmark Citadel SQLite Ratio\n----------------------------------------------------------\ncorrelated_scalar 12.8 us 19.8 ms 1,549x\nfull_outer_join 14.1 us 21.8 ms 1,540x\nview_filter 21.6 us 1.83 ms 85x\nfilter 23.2 us 1.84 ms 80x\njoin_param 1.55 us 34.8 us 22x\njoin 14.2 us 97.7 us 6.89x\nunion 28 us 150 us 5.35x\ndelete_returning 48.8 us 171 us 3.50x\nupdate_returning 46.6 us 150 us 3.23x\ninsert_returning 61.1 us 174 us 2.84x\ntruncate 20.8 us 58.7 us 2.83x\nfts_match 2.91 ms 8.03 ms 2.76x\njson_extract 12.2 ms 32.7 ms 2.68x\nsort_paginate_pk 5.62 us 14.7 us 2.61x\nupsert_returning 67.2 us 175 us 2.61x\nwindow_agg 29.5 ms 76.5 ms 2.59x\nupsert_dedup 13 us 32.8 us 2.52x\nfts_phrase 4.19 ms 9.73 ms 2.32x\nsavepoint_create 349 ns 748 ns 2.14x\nwindow_rank 63.4 ms 130 ms 2.05x\ninsert_select 543 us 1.1 ms 2.03x\ndelete 35 us 69.9 us 2.00x\nscan 4.97 ms 9.54 ms 1.92x\nsavepoint_rollback 1.28 ms 2.28 ms 1.78x\nwide_proj_2col 501 us 842 us 1.68x\nupsert_mixed 35.5 us 59.1 us 1.66x\nsavepoint_nested 197 us 326 us 1.66x\nwide_proj_full 4.59 ms 7.53 ms 1.64x\nupdate 17.9 us 28.3 us 1.58x\nwide_proj_pk 319 us 480 us 1.51x\nupsert_counter 35.8 us 53.7 us 1.50x\ninsert 35.4 us 51.9 us 1.47x\nupsert_all_new 35.6 us 51.4 us 1.44x\ncovered_count 257 us 359 us 1.40x\nwith_dml 80.5 us 107 us 1.34x\nfk_cascade_delete_only 63.5 us 80.7 us 1.27x\ninsert_gen_virtual 48.5 us 55 us 1.13x\nwide_proj_3col 1.11 ms 1.23 ms 1.11x\ninsert_gen_stored 51.3 us 56.2 us 1.10x\ncovered_range 67.7 us 74.4 us 1.10x\nfk_cascade 80.7 us 87.3 us 1.08x\nupdate_gen_propagate 44.6 us 45.2 us 1.01x\n```\n\n42 execution benchmarks. Citadel is faster on all 42. Geometric mean speedup: ~3.4x.\n\n### Memoized repeat-reads\n\nDeterministic read-only statements re-executed with identical parameters against unchanged data are served from a generation-keyed result cache. Any commit invalidates the cache, and the first execution after a write recomputes at execution speed. SQLite has no result cache and re-executes every query.\n\n```\nBenchmark Citadel SQLite Ratio\n----------------------------------------------------------\ncorrelated_in 103 ns 1.97 s 19,208,388x\nfts_rank 219 ns 42.5 ms 194,338x\ncorrelated_exists 102 ns 6.89 ms 67,712x\njsonb_contains 1.09 us 27.7 ms 25,273x\nsort_nocase 213 ns 3.31 ms 15,532x\ncte 668 ns 6.13 ms 9,179x\nsort 312 ns 2.76 ms 8,853x\ngroup_by 1.27 us 10.7 ms 8,411x\nsum 468 ns 1.97 ms 4,214x\ndistinct 1.11 us 4.08 ms 3,675x\nrecursive_cte 105 ns 122 us 1,165x\npartial_index_point 103 ns 12.6 us 122x\nview_point 121 ns 12.7 us 105x\npoint 121 ns 12.5 us 104x\ncount 457 ns 21.6 us 47x\nselect_gen_virtual 1.05 us 18.1 us 17x\n```\n\n16 memoized benchmarks. Geometric mean speedup: ~3,700x.\n\n### Citadel-only (no direct SQLite equivalent)\n\nFixed-parameter reads; every benchmark except `json_table` is served from the result cache on repeat execution.\n\n```\nBenchmark Citadel\n-------------------------------\njson_table 9.25 ms\nlateral 1.46 us\ndate_sort 1.10 us\ndate_extract 473 ns\ndate_groupby 242 ns\ndate_range_scan 102 ns\ndate_arith 100 ns\n```\n\n### Index speedups (citadel-internal)\n\nRotating probes; both arms measure execution speed.\n\n```\nBenchmark Without index With index Speedup\n---------------------------------------------------------------\njson_gin 4.70 ms 3.49 us 1,347x\nfts_index 1.37 s 2.98 ms 461x\n```\n\n\nMethodology\n\nH2H benchmarks:\n\n- **correlated_in** - `SELECT COUNT(*) FROM t WHERE id IN (SELECT id FROM ref_table WHERE ref_table.val = t.age)`\n- **full_outer_join** - `SELECT a.id, b.data FROM a FULL OUTER JOIN b ON a.id = b.a_id`\n- **count** - `SELECT COUNT(*) FROM t`\n- **correlated_scalar** - `SELECT a.id, (SELECT COUNT(*) FROM b WHERE b.a_id = a.id) FROM a`\n- **point** - `SELECT * FROM t WHERE id = 50000`\n- **group_by** - `SELECT age, COUNT(*) FROM t GROUP BY age`\n- **partial_index_point** - `SELECT * FROM t WHERE email = ? AND deleted_at IS NULL`\n- **cte** - `WITH filtered AS (SELECT ... WHERE age < 50) SELECT age, COUNT(*) FROM filtered GROUP BY age`\n- **view_point** - `SELECT * FROM v WHERE id = 50000`\n- **truncate** - `TRUNCATE TABLE t`\n- **insert_returning** - `INSERT INTO t (id, val) VALUES (...) RETURNING id, val`\n- **upsert_returning** - `INSERT ... ON CONFLICT (id) DO UPDATE SET c = c + 1 RETURNING c`\n- **view_filter** - `SELECT * FROM v WHERE age = 42`\n- **filter** - `SELECT * FROM t WHERE age = 42`\n- **window_agg** - `SELECT SUM(age) OVER (ORDER BY id ROWS 50 PRECEDING) FROM t`\n- **jsonb_contains** - `SELECT id FROM users WHERE data @> '{\"role\":\"admin\"}'::jsonb`\n- **savepoint_create** - `BEGIN; SAVEPOINT sp; RELEASE sp; COMMIT`\n- **sort** - `SELECT * FROM t ORDER BY age LIMIT 10`\n- **upsert_counter** - `INSERT ... ON CONFLICT (id) DO UPDATE SET c = c + 1`\n- **window_rank** - `SELECT ROW_NUMBER() OVER (PARTITION BY age ORDER BY id) FROM t`\n- **delete_returning** - `DELETE ... WHERE id = ? RETURNING id, val`\n- **upsert_dedup** - `INSERT ... ON CONFLICT (id) DO NOTHING`\n- **json_extract** - `SELECT data ->> 'name' FROM users`\n- **delete** - `DELETE FROM t WHERE id = ?`\n- **update** - `UPDATE t SET age = age + 1 WHERE id BETWEEN 10000 AND 10099`\n- **covered_range** - `SELECT age, id FROM t WHERE age = ?` on an indexed column, parameter rotating per iteration\n- **covered_count** - `SELECT COUNT(*) FROM t WHERE age >= ?` on an indexed column, parameter rotating per iteration\n- **sort_paginate_pk** - `SELECT id, name FROM t WHERE id > ? ORDER BY id LIMIT 20`, parameter advancing per iteration\n- **join_param** - `SELECT a.val, b.data FROM a JOIN b ON b.a_id = a.id WHERE a.id = ?`, parameter rotating per iteration\n- **correlated_exists** - `SELECT COUNT(*) FROM t WHERE EXISTS (SELECT 1 FROM ref_table WHERE ref_table.id = t.id)`\n- **savepoint_nested** - `BEGIN; SAVEPOINT sp1; ... ; RELEASE/ROLLBACK TO sp1; COMMIT`\n- **with_dml** - `WITH d AS (DELETE FROM src RETURNING *) INSERT INTO archive SELECT * FROM d`\n- **distinct** - `SELECT DISTINCT age FROM t`\n- **insert_select** - `INSERT INTO sink SELECT id, val FROM a`\n- **savepoint_rollback** - `BEGIN; INSERT 1K rows; SAVEPOINT sp; INSERT 10K rows; ROLLBACK TO sp; COMMIT`\n- **update_returning** - `UPDATE t SET c = c + ? WHERE id = ? RETURNING c`\n- **insert** - `INSERT INTO t (id, val) VALUES (?, ?)`\n- **scan** - `SELECT * FROM t`\n- **wide_proj_pk** - `SELECT id FROM wide` (24-column table: 3 INT keys, 8 INT, 12 TEXT; 10K rows)\n- **wide_proj_2col** - `SELECT id, k1 FROM wide`\n- **wide_proj_3col** - `SELECT id, k1, t1 FROM wide`\n- **wide_proj_full** - `SELECT * FROM wide`\n- **sort_nocase** - `SELECT name FROM t ORDER BY name COLLATE NOCASE LIMIT 10`\n- **sum** - `SELECT SUM(age) FROM t`\n- **insert_gen_virtual** - `INSERT INTO t (id, a, b) VALUES (?, ?, ?)`\n- **union** - `SELECT id, val FROM a UNION ALL SELECT id, data FROM b`\n- **select_gen_virtual** - `SELECT id, s FROM t WHERE s > ?`\n- **update_gen_propagate** - `UPDATE t SET a = a + ? WHERE id = ?`\n- **upsert_mixed** - `INSERT ... ON CONFLICT (id) DO UPDATE SET c = c + 1`\n- **upsert_all_new** - `INSERT ... ON CONFLICT (id) DO NOTHING`\n- **recursive_cte** - `WITH RECURSIVE seq(x) AS (SELECT 1 UNION ALL SELECT x+1 FROM seq WHERE x < 1000) SELECT SUM(x) FROM seq`\n- **insert_gen_stored** - `INSERT INTO t (id, a, b) VALUES (?, ?, ?)`\n- **fk_cascade** - `DELETE FROM parent WHERE id = ?`\n- **fk_cascade_delete_only** - `DELETE FROM parent WHERE id = ?` (no index on child)\n- **join** - `SELECT a.id, b.data FROM a INNER JOIN b ON a.id = b.a_id`\n- **fts_match** - `SELECT id FROM docs WHERE body @@ to_tsquery('rust & database')`\n- **fts_phrase** - `SELECT id FROM docs WHERE body @@ phraseto_tsquery('rust database')`\n- **fts_rank** - `SELECT id, ts_rank(body, to_tsquery('rust & database')) FROM docs WHERE body @@ ... ORDER BY r DESC LIMIT 10`\n\nCitadel-only benchmarks:\n\n- **date_extract** - `SELECT AVG(EXTRACT(HOUR FROM ts)) FROM events`\n- **date_groupby** - `SELECT DATE_TRUNC('month', ts), COUNT(*) FROM events GROUP BY 1`\n- **json_table** - `SELECT a, b, c FROM JSON_TABLE(j, '$[*]' COLUMNS (a INT PATH '$.a', b TEXT PATH '$.b', c INT PATH '$.c'))`\n- **lateral** - `SELECT c.id, p.name FROM c, LATERAL (SELECT name FROM p WHERE p.cat_id = c.id ORDER BY price DESC LIMIT 1) p`\n- **date_range_scan** - `SELECT COUNT(*) FROM events WHERE d BETWEEN DATE '2024-02-01' AND DATE '2024-03-31'`\n- **date_arith** - `SELECT COUNT(*) FROM events WHERE ts + INTERVAL '1 day' > TIMESTAMP '2024-06-01 00:00:00'`\n- **date_sort** - `SELECT id FROM events ORDER BY ts LIMIT 100`\n\nIndex speedups (same query, with vs without the index):\n\n- **json_gin** - `SELECT id FROM users WHERE data @> '{\"role\":\"admin\"}'::jsonb`; index `CREATE INDEX ... USING gin (data)`\n- **fts_index** - `SELECT id FROM docs WHERE body @@ to_tsquery(...)`; index `CREATE INDEX ... USING fts (body)` (`body` is a `TSVECTOR` column)\n\nSQLite config: `journal_mode=OFF, synchronous=OFF, cache_size=8192` (~32 MB).\nCitadel config: `SyncMode::Off, cache_size=4096` (~32 MB).\n\nReproduce with `cargo bench -p citadeldb-sql --bench h2h_bench`\n\n\n\n## SQL\n\n**Statements** - CREATE/DROP TABLE (incl. `TEMP`), ALTER TABLE (ADD/DROP/RENAME COLUMN, RENAME TABLE, DISABLE/ENABLE TRIGGER), CREATE/DROP INDEX (incl. partial `WHERE`, expression keys, `CONCURRENTLY`), CREATE/DROP VIEW, CREATE/DROP MATERIALIZED VIEW (with `REFRESH [CONCURRENTLY]`), CREATE/DROP TRIGGER (BEFORE/AFTER/INSTEAD OF, FOR EACH ROW/STATEMENT, `REFERENCING NEW/OLD TABLE`, `WHEN`, `UPDATE OF cols`), INSERT (VALUES, SELECT, ON CONFLICT DO NOTHING/DO UPDATE, ON CONSTRAINT), SELECT, UPDATE, DELETE, TRUNCATE TABLE, RETURNING (with `OLD`/`NEW`), BEGIN [READ ONLY | READ WRITE]/COMMIT/ROLLBACK, SAVEPOINT/RELEASE/ROLLBACK TO, SET [LOCAL] TIME ZONE, EXPLAIN, REFRESH MATERIALIZED VIEW\n\n**Constraints** - PRIMARY KEY, NOT NULL, UNIQUE, DEFAULT, CHECK (column + table level), FOREIGN KEY with full referential actions (`ON DELETE` / `ON UPDATE` `CASCADE` / `SET NULL` / `SET DEFAULT` / `RESTRICT` / `NO ACTION`), GENERATED ALWAYS AS (...) STORED|VIRTUAL\n\n**Types** - INTEGER, REAL, TEXT, BLOB, BOOLEAN, DATE, TIME, TIMESTAMP (WITH TIME ZONE), INTERVAL, JSON, JSONB, TSVECTOR, TSQUERY, ARRAY\n\n**JSON / JSONB** - Postgres operators plus SQL/JSON path functions and the SQL:2023 item methods `.bigint()`, `.decimal()`, `.integer()`, `.number()`, `.string()`, `.boolean()`, `.date()`, `.time()`, `.time_tz()`, `.timestamp()`, and `.timestamp_tz()`. Time-zone-dependent evaluation uses the connection's transactional `SET [LOCAL] TIME ZONE` context.\n\n**Clauses** - JOINs (INNER, LEFT, RIGHT, CROSS, FULL OUTER, LATERAL), subqueries (scalar, IN, EXISTS, correlated), CTEs (`WITH` / `WITH RECURSIVE` / WITH-DML: `WITH x AS (INSERT/UPDATE/DELETE ... [RETURNING *]) SELECT ...`), UNION/INTERSECT/EXCEPT [ALL], CASE, BETWEEN, LIKE, DISTINCT, `ANY` / `ALL` (subquery + array forms), GROUP BY/HAVING, ORDER BY, LIMIT/OFFSET\n\n**Window functions** - ROW_NUMBER, RANK, DENSE_RANK, NTILE, LAG, LEAD, FIRST_VALUE, LAST_VALUE, SUM/COUNT/AVG/MIN/MAX OVER with PARTITION BY, ORDER BY, ROWS/RANGE frames\n\n**Views** - CREATE/DROP VIEW, OR REPLACE, IF NOT EXISTS/IF EXISTS, column aliases, nested views\n\n**Materialized views** - `CREATE MATERIALIZED VIEW [IF NOT EXISTS] name AS SELECT ...`, `REFRESH MATERIALIZED VIEW [CONCURRENTLY] name` (`CONCURRENTLY` does a diff-merge - DELETE removed rows, UPDATE changed rows, INSERT new rows - instead of TRUNCATE+repopulate), `DROP MATERIALIZED VIEW [CASCADE]`, full backing-table semantics (indexes, joins, planner sees a real table), `pg_matviews` introspection\n\n**Triggers** - `CREATE TRIGGER name {BEFORE|AFTER|INSTEAD OF} {INSERT|UPDATE [OF cols]|DELETE} ON table FOR EACH {ROW|STATEMENT} [REFERENCING NEW TABLE AS new_t OLD TABLE AS old_t] [WHEN (expr)] BEGIN ... END`. INSTEAD OF triggers make views writable. Transition tables work as virtual tables in trigger bodies. `ALTER TABLE ... DISABLE/ENABLE TRIGGER [name|ALL]`. PG-faithful name-order firing. Introspection via `information_schema.triggers` and `SHOW TRIGGERS [ON table]`.\n\n**TEMP tables** - `CREATE TEMP TABLE ...` lives in a per-connection in-memory database, dropped on disconnect. Full DDL/DML/index/constraint/trigger parity with persistent tables.\n\n**Functions** - COUNT, SUM, AVG, MIN, MAX, LENGTH, UPPER, LOWER, SUBSTR/SUBSTRING, TRIM/LTRIM/RTRIM, REPLACE, INSTR, CONCAT, HEX, ABS, ROUND, CEIL/CEILING, FLOOR, SIGN, SQRT, RANDOM, COALESCE, NULLIF, CAST, TYPEOF, IIF\n\n**Date/Time Functions** - NOW, CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME, LOCALTIMESTAMP, LOCALTIME, CLOCK_TIMESTAMP, EXTRACT, DATE_PART, DATE_TRUNC, DATE_BIN, AGE, MAKE_DATE, MAKE_TIME, MAKE_TIMESTAMP, MAKE_INTERVAL, JUSTIFY_DAYS, JUSTIFY_HOURS, JUSTIFY_INTERVAL, ISFINITE, DATE, TIME, DATETIME, STRFTIME, JULIANDAY, UNIXEPOCH, TIMEDIFF, AT TIME ZONE. Supports `INTERVAL '1 year 2 months'`, `DATE '2024-01-15'`, `TIMESTAMP '2024-01-15 12:30:00Z'`, `infinity`/`-infinity` sentinels, BC dates, full IANA zone parsing (jiff), PG-normalized INTERVAL comparison.\n\n**Full-text search** - `tsvector` / `tsquery` types, `to_tsvector` / `to_tsquery` / `plainto_tsquery` / `phraseto_tsquery` / `websearch_to_tsquery` builders, `@@` match operator, `ts_rank` / `ts_rank_cd` ranking with weighted positions (A/B/C/D), prefix matching (`term:*`), phrase distance (``), inverted indexes via `CREATE INDEX ... USING fts` for ~461x speedup over sequential scan\n\n**System catalog** - `information_schema.tables`, `information_schema.columns`, `information_schema.key_column_usage`, `information_schema.table_constraints`, `information_schema.triggers`, `pg_timezone_names`, `pg_timezone_abbrevs`, `pg_matviews` (virtual tables, queryable). `SHOW TRIGGERS [ON table]` and `SHOW MATERIALIZED VIEWS` shorthands for the corresponding catalog queries.\n\n**Prepared statements** - `$1, $2, ...` positional parameters with LRU statement cache plus snapshot-tagged plan caching for joins and compound queries (cache invalidates only on commit, never per-call)\n\n**Multi-statement scripts** - `Connection::execute_script(sql)` runs `;`-separated statements in one call, returning per-statement outcomes with partial-success preserved. WASM: `db.run(sql)` returns `[{type, ...}, ...]`.\n\n**UPSERT** - `INSERT ... ON CONFLICT (cols) DO NOTHING` / `DO UPDATE SET col = excluded.col ... WHERE ...` and `ON CONFLICT ON CONSTRAINT idx_name`. `excluded.*` refers to the proposed row; bare `col` refers to the existing row. Single-descent storage primitive: on the canonical `DO UPDATE SET counter = counter + 1` pattern, Citadel is ~1.5x faster than SQLite.\n\n## Security\n\n**No plaintext on disk.** Every page is encrypted before writing and authenticated before reading.\n\n**Separate key file.** Encryption keys live in `{dbname}.citadel-keys`, not inside the database. The passphrase derives a master key in memory via Argon2id (or PBKDF2 in the FIPS-oriented at-rest profile) and never touches disk.\n\n**Key backup.** Export an encrypted key backup with a separate recovery passphrase. Restore access without re-encrypting the entire database.\n\n**Instant rekey.** Changing the passphrase re-wraps the root encryption key. No page re-encryption - instant regardless of database size.\n\n**Encrypted sync.** Noise protocol (`NNpsk0_25519_ChaChaPoly_BLAKE2s`) with a 256-bit pre-shared key. Ephemeral Curve25519 keys per session for forward secrecy.\n\n## Architecture\n\n```\nAgent layer:\n+---------------------------------------------+\n| citadel-ai | Agent runtime (ReAct + Reflexion)\n+---------------------------------------------+\n| citadel-llm | LLM client layer: Claude, OpenAI, Ollama, Gemini\n+---------------------------------------------+\n\nMemory layer:\n+---------------------------------------------+\n| citadel-mcp | MCP server: memory tools for any MCP client\n+---------------------------------------------+\n| citadel-mem | Memory engine: regions, atoms, recall, erasure\n+---------------------------------------------+\n| citadel-vector | VECTOR(N) type + PRISM filtered ANN index\n+---------------------------------------------+\n\nEncrypted database engine:\n+----------------------+----------------------+\n| citadel-cli | citadel-python | CLI, Python wheel\n+----------------------+----------------------+\n| citadel-ffi | citadel-wasm | C FFI, WebAssembly\n+----------------------+----------------------+\n| citadel-sql | SQL parser, planner, executor\n+---------------------------------------------+\n| citadel | Database API, builder, sync\n+-------------+--------------+----------------+\n| citadel-txn | citadel-sync | citadel-crypto | Transactions, replication, keys\n+-------------+--------------+----------------+\n| citadel-buffer | citadel-page | Buffer pool (SIEVE), page codec\n+----------------------------+----------------+\n| citadel-io | File I/O, fsync, io_uring\n+---------------------------------------------+\n| citadel-core | Types, errors, constants\n+---------------------------------------------+\n```\n\n### Page Layout (8,208 bytes)\n\n```\n+----------+--------------------+----------+\n| IV 16B | Ciphertext 8160B | MAC 32B |\n+----------+--------------------+----------+\n```\n\nFresh random IV per page. HMAC verified before decryption.\n\n### Commit Protocol\n\nShadow paging with a god byte - one byte selects the active commit slot. Atomic commits without WAL:\n\n1. Write dirty pages to new locations (CoW)\n2. Compute Merkle hashes bottom-up\n3. Update the inactive commit slot\n4. Flip the god byte\n\n### Integrity Boundary\n\nWhat the at-rest integrity machinery does and does not guarantee against an attacker with file access:\n\n- **Per-page HMAC** binds `(epoch, page_id, IV, ciphertext)`. Any modification of a page's bytes is detected before decryption. It does **not** bind the commit generation: a page image validly written in the past for the same `(page_id, epoch)` verifies forever.\n- **Commit slots** have two accepted formats. V1 slots carry a truncated HMAC-SHA256 over every field except the MAC itself; legacy slots carry only a keyless checksum over a prefix. Checksum-valid legacy slots remain readable only while no V1 requirement is recorded. Once both physical slots are valid V1 and the vault records that one-way requirement, any checksum-valid legacy slot is rejected as downgrade evidence, and writers refuse to create one.\n- **Rollback to an older genuine state** is outside this boundary. An earlier authenticated slot plus its matching pages can pass the data-file checks; an older internally consistent snapshot of all local vault state, including the data, key, and retained audit files, also passes local authentication. Detecting freshness requires an external anchor - for example, store the latest commit's `txn_id` and Merkle root outside the attacker's reach and compare them after opening.\n\n## Language Bindings\n\n### C / C++\n\nStatic or dynamic library with auto-generated `citadel.h` (cbindgen). Exported entry points are panic-safe.\n\n```c\n#include \"citadel.h\"\n\nCitadelDb *db = NULL;\ncitadel_create(\"my.db\", (const uint8_t*)\"secret\", 6, NULL, &db);\n\nCitadelWriteTxn *wtx = NULL;\ncitadel_write_begin(db, &wtx);\ncitadel_write_put(wtx, (const uint8_t*)\"key\", 3, (const uint8_t*)\"val\", 3, NULL);\ncitadel_write_commit(wtx);\n\nCitadelSqlConn *conn = NULL;\ncitadel_sql_open(db, &conn);\nCitadelSqlResult *result = NULL;\ncitadel_sql_execute(conn, \"SELECT * FROM users;\", &result);\n\ncitadel_close(db);\n```\n\n### WebAssembly\n\nInstall with `npm install @citadeldb/wasm`.\n\n```js\nimport init, { CitadelDb } from \"@citadeldb/wasm\";\n\nawait init();\n\nconst db = new CitadelDb(\"secret\");\ndb.execute(\"CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT);\");\ndb.execute(\"INSERT INTO t (id, name) VALUES (1, 'Alice');\");\n\nconst result = db.query(\"SELECT * FROM t;\");\n// { columns: [\"id\", \"name\"], rows: [[1, \"Alice\"]] }\n\ndb.put(new Uint8Array([1, 2, 3]), new Uint8Array([4, 5, 6]));\n```\n\nBuild the npm package: `bash scripts/publish-wasm.sh`\n\n### Python\n\nOne importable wheel with the full engine (SQL, vectors, memory, agent runtime) and bundled type stubs.\n\n```\npip install citadeldb\n```\n\n```python\nimport citadeldb\n\ndb = citadeldb.connect(\"my.db\", key=\"secret\", create=True)\ndb.execute(\"CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)\")\ndb.execute(\"INSERT INTO t VALUES (1, 'Alice')\")\ndb.query(\"SELECT * FROM t\").to_dicts()\n# [{'id': 1, 'name': 'Alice'}]\n```\n\n## Building\n\nRust 1.95+.\n\n```bash\ngit clone https://github.com/yp3y5akh0v/citadel.git\ncd citadel\ncargo build --release\n```\n\n### Feature Flags\n\n| Flag | Description |\n|------|-------------|\n| `audit-log` | HMAC-SHA256-chained audit log (default: on); no external anti-rollback anchor |\n| `fips` | At-rest PBKDF2 + AES-256-CTR profile; not whole-product validation |\n| `io-uring` | Linux io_uring async I/O |\n\n## License\n\n[Apache-2.0](https://github.com/yp3y5akh0v/citadel/blob/HEAD/LICENSE-APACHE)\n",
"bytes": 38353,
"sha": "da3d7e797a40b34241a32a9c397a7228c0afa23ded331786cf4b79a311cad7ae",
"repo_slug": "yp3y5akh0v/citadel",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_dev_citadeldb_mcp_1e4a1f21/readme"
}
![\"Citadel\"](\"https://raw.githubusercontent.com/yp3y5akh0v/citadel/HEAD/.github/banner.png\")
\n![\"npm\"](\"https://img.shields.io/npm/v/@citadeldb/wasm\")
![\"PyPI](\"https://img.shields.io/pypi/v/citadeldb?label=pypi%20citadeldb\")
![\"PyPI](\"https://img.shields.io/pypi/v/citadeldb-mcp?label=pypi%20citadeldb-mcp\")
![\"MCP](\"https://img.shields.io/badge/MCP-dev.citadeldb%2Fmcp-blue\"){kind=icon}
![\"CI\"](\"https://github.com/yp3y5akh0v/citadel/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"LoCoMo](\"https://img.shields.io/badge/LoCoMo%20(gpt--4o--mini)-87.2%25-success\"){kind=icon}
![\"LongMemEval-S](\"https://img.shields.io/badge/LongMemEval--S%20(gpt--4o)-86.2%25-success\"){kind=icon}
![\"License\"](\"https://img.shields.io/badge/license-Apache--2.0-blue\"){kind=icon}