v2.2.0

Local-first encrypted memory for AI agents.

What's changed

• Citadel Studio - Native desktop application for encrypted-vault inspection, SQL editing and query plans, memory verification and erasure, vector visualization, and SQLite schema import.
• Memory operations - Adds profiles, read budgets, exact-ID retrieval, region-scoped graph operations, edge removal, dependent erasure, paginated summaries, and atomic batch writes with idempotency keys.
• MMR recall - Adds maximal marginal relevance over stored vectors for cosine regions, with Rust, Python, and LangChain support.
• MCP - Adds stateless discovery, per-request protocol metadata, result-type and cache metadata, request cancellation, rate limiting, and bounded stdio transport for MCP 2026-07-28.
• Framework adapters - Corrects LangGraph relevance scores and Strands redaction handling, and adopts the 2.2 memory APIs across all nine adapters.
• Transaction storage - Prevents excessive file growth while read transactions remain open across sustained writes.
• SQL execution - Corrects REAL-column predicates with integer literals and rejects truncated row headers and invalid scalar lengths.

Upgrading

• Custom Rust and Python embedders must implement embed_with_cancel; rerankers must implement rerank_with_cancel. Asymmetric query embedders use embed_queries_with_cancel.
• Memory APIs rename the stored importance value from score to importance, including Python atom dictionaries, MCP schemas, evolution results, summary avg_importance, Rust with_importance, and LowImportance/low_importance. Hits expose stored importance and confidence separately from optional query-specific relevance, distance, and graph_depth; AtomHit.score is removed.
• Rust graph callers must use region-scoped methods such as link_in_region and fetch_edges_in_region; Python link and fetch_edges require a region.
• Memory summaries are paginated. Python and MCP callers follow next_after_kind; Rust summarize() returns the first page, and callers continue with summarize_page and SummaryQuery::with_after_kind. Payload updates report whether the payload changed.
• Public memory structs gained fields, and the citadel_core::Error, MemError, and EmbedError enums gained variants. Update affected struct literals and exhaustive matches.
• Upgrade citadeldb and installed citadeldb-* adapters together; the 2.2 adapter releases require citadeldb>=2.2,<3.
• LangChain similarity search and MMR candidate selection now use vector similarity only instead of fused memory ranking; result ordering may change.
• MCP mem_remember_batch requires a distinct nonempty idempotency_key for every atom and returns results: [{id, inserted}] instead of ids. mem_update returns {id, changed} instead of {status, id}.
• MCP supports initialize-based 2025-11-25 and 2025-06-18. Those clients must send protocolVersion, capabilities, and clientInfo, followed by notifications/initialized before other requests. MCP 2026-07-28 clients must include protocol metadata on every request; one stdio connection cannot mix the two modes.
• MCP tool calls are rate-limited. mem_forget with force: true and mem_evict with policy: "purge_region" require --allow-protected-memory-erasure and confirm_region exactly matching the configured region.
• Rust citadel_mcp::ServeConfig literals require the new allow_protected_memory_erasure and tool_rate_limit_per_minute fields.

Downloads

Platform	CLI	FFI	Studio
Linux x86_64	citadel-v2.2.0-x86_64-unknown-linux-musl.tar.gz	citadel-ffi-v2.2.0-x86_64-unknown-linux-gnu.tar.gz	citadel-studio-v2.2.0-x86_64-unknown-linux-gnu.AppImage
Linux aarch64	citadel-v2.2.0-aarch64-unknown-linux-gnu.tar.gz	citadel-ffi-v2.2.0-aarch64-unknown-linux-gnu.tar.gz	-
macOS x86_64	citadel-v2.2.0-x86_64-apple-darwin.tar.gz	citadel-ffi-v2.2.0-x86_64-apple-darwin.tar.gz	citadel-studio-v2.2.0-x86_64-apple-darwin.dmg
macOS aarch64	citadel-v2.2.0-aarch64-apple-darwin.tar.gz	citadel-ffi-v2.2.0-aarch64-apple-darwin.tar.gz	citadel-studio-v2.2.0-aarch64-apple-darwin.dmg
Windows x86_64	citadel-v2.2.0-x86_64-pc-windows-msvc.zip	citadel-ffi-v2.2.0-x86_64-pc-windows-msvc.zip	citadel-studio-v2.2.0-x86_64-pc-windows-msvc.msi

FIPS-oriented at-rest-profile artifacts use the citadel-fips- / citadel-ffi-fips- prefixes. These artifacts are not a claim of whole-product FIPS validation.

Each package has a .sha256 checksum. The Windows Studio executable and MSI are unsigned. The macOS app is ad-hoc signed and unnotarized, and the DMG is unsigned; Windows SmartScreen or macOS Gatekeeper may warn.

Verification

One build-provenance attestation covers the 24 downloadable packages and installers. After downloading a package, verify its digest and origin with GitHub CLI:

gh attestation verify \
  citadel-v2.2.0-x86_64-unknown-linux-musl.tar.gz \
  --repo yp3y5akh0v/citadel \
  --signer-workflow yp3y5akh0v/citadel/.github/workflows/release.yml \
  --signer-digest 3761bb9cec11d0fd1881b019b779884862ca627d \
  --source-ref refs/tags/v2.2.0 \
  --source-digest 3761bb9cec11d0fd1881b019b779884862ca627d \
  --deny-self-hosted-runners

View the v2.2.0 build-provenance attestation.

Install

cargo install citadeldb-cli

uvx citadeldb-mcp pull e5-large
uvx citadeldb-mcp pull ms-marco-minilm

CITADEL_KEY="your-passphrase" uvx citadeldb-mcp \
  --db /absolute/path/memory.cdl \
  --embedder e5-large \
  --reranker ms-marco-minilm

pip install citadeldb

pip install citadeldb-langgraph
pip install citadeldb-crewai
pip install citadeldb-langchain
pip install citadeldb-llamaindex
pip install citadeldb-haystack
pip install citadeldb-google-adk
pip install citadeldb-openai-agents
pip install citadeldb-strands-agents
pip install citadeldb-ms-agent-framework

npm install @citadeldb/wasm