Metadata-Version: 2.4
Name: citadeldb-mcp
Version: 1.11.0
Summary: Model Context Protocol server for Citadel: encrypted memory as MCP tools
Home-Page: https://citadeldb.dev
Author: Yuriy Peysakhov
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://citadeldb.dev
Project-URL: Repository, https://github.com/yp3y5akh0v/citadel

# citadeldb-mcp

mcp-name: dev.citadeldb/mcp

Model Context Protocol (MCP) server for the
[Citadel](https://github.com/yp3y5akh0v/citadel) encrypted memory engine. Gives any MCP client
(Claude Desktop, an IDE, an agent) persistent, encrypted memory.

Memory lives in a local [`citadeldb-mem`](https://crates.io/crates/citadeldb-mem) region:
AES-256 encrypted at rest, per-atom sealed and HMAC-authenticated, recalled through a hybrid
vector + keyword + recency + importance fusion over a [PRISM](https://github.com/yp3y5akh0v/prism) approximate nearest-neighbor index,
connected by a typed edge graph, and forgotten by **destroying keys** (cryptographic erasure).

## Install

Run it with no install:

```sh
uvx citadeldb-mcp --db memory.cdl
```

Or install the command with `pip install citadeldb-mcp` or `cargo install citadeldb-mcp`,
then wire it into Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "citadel": {
      "command": "citadeldb-mcp",
      "args": ["--db", "memory.cdl", "--embedder", "bge-large"],
      "env": { "CITADEL_KEY": "your-passphrase" }
    }
  }
}
```

Omit `--embedder` for keyword-only recall, or run `citadeldb-mcp pull bge-large` first for
semantic recall (models are never downloaded automatically; see below).

Tools (over a synchronous, hand-rolled JSON-RPC 2.0 stdio transport):

- `mem_recall` - hybrid retrieval (vector + keyword + recency + importance); filter by kind/payload, expand along the memory graph, override fusion weights, and optionally attach provenance (`derived_from`), per-hit integrity verdicts (`attest`), and `resource_link`s to each hit
- `mem_fetch` - deterministic listing of a kind (no embedding)
- `mem_edges` - typed graph introspection
- `mem_profile` - what the memory knows about a query: recall plus its graph neighborhood
- `mem_summarize` - per-kind digest of a region
- `mem_verify` - re-authenticate atoms off disk: per-atom integrity verdict (authentic / tampered / key_erased / missing / plaintext_unattested)
- `mem_remember` / `mem_remember_batch` - store atoms with payload, importance, TTL, immutability
- `mem_update` - replace a stored atom's payload in place (preserves id, edges, and embedding)
- `mem_link` - connect atoms with a typed edge
- `mem_evolve` - recompute an atom's neighbor links and score
- `mem_evict` - selective forgetting by policy (cryptographic erasure on encrypted regions)
- `mem_forget` - forget atoms by id and return a verifiable **erasure receipt** (cryptographic erasure on encrypted regions; skips immutable atoms unless forced)

The `citadeldb-mcp` binary reads the passphrase from `CITADEL_KEY` and serves one region
(encrypted by default); only protocol messages go to stdout, diagnostics to stderr.

Recall is keyword-only (a mock embedder) until you opt into a real semantic model. The
(CPU) Candle embedder is compiled into the default build, but models are fetched only on
explicit request, never automatically:

```sh
citadeldb-mcp pull bge-large                       # one-time download to ~/.citadel/models
citadeldb-mcp --db memory.cdl --embedder bge-large
```

Pull names: `bge-small`, `bge-base`, `bge-large`, `minilm`, `e5-large`. Or point `--model-dir`
at a local model directory for a fully offline setup, and build with `--features cuda-embed` to
run the model on an NVIDIA GPU.

For better recall ordering, add a cross-encoder reranker (off by default, also explicit):

```sh
citadeldb-mcp pull ms-marco-minilm
citadeldb-mcp --db memory.cdl --embedder bge-large --reranker ms-marco-minilm
```

This crate is part of the Citadel workspace.

## License

MIT OR Apache-2.0

