Citadel

Self-hosted memory for engineering teams and the agents working alongside them.

Your team already writes down everything worth knowing. It ends up scattered across commits, pull requests, Linear tickets, and coding sessions nobody can search a week later. New engineers ask questions that were answered in March. Coding agents start every task with no idea what your team already decided.

Citadel collects that material as it is produced and puts it behind one query interface, for people and for agents. It runs on your own infrastructure.

Status: in testing, not yet open

Citadel currently runs for two organisations, Masumi Network and Sokosumi Network, who are using it daily and finding the problems. It is not open for general use yet.

If you are interested, watch the repository and wait for the stable release. We would rather you adopt something that works than something that is still moving under you. We publish benchmark numbers as we go, including the parts that are not good yet, so you can judge readiness for yourself rather than taking our word for it.

A self-hosted path for individuals to try it is planned. It is not ready today.

Who it is being built for

Teams running coding agents get the most out of it. Claude Code, Cursor, and anything else speaking MCP query the same vault the engineers do, through a hosted endpoint. An agent that can look up why you dropped Postmark for Resend does not re-litigate it.

It also suits companies that cannot ship their context to a vendor. Apache-2.0, pip install, runs where you decide. One caveat worth stating plainly: document text is sent to an external model provider for enrichment and digests, so this is data you control the storage of, not data that never leaves the building.

And it is for anyone tired of filing things. Capture runs from git and editor hooks. Nobody tags anything.

How it works

Capture happens without you. A git pre-push hook and a Claude Code session hook snapshot work as it is produced, while GitHub activity, repository content, and Linear issues sync on a schedule.

You ask from wherever you already are: the CLI, the web interface, or MCP. Answers carry a link back to the commit, issue, or document behind them, and retrieved text is marked as untrusted context worth checking before you act on it.

Promotion is the deliberate part. Captured work lands in your own space, and reaching shared org memory takes an explicit step. That gate is what keeps the shared layer worth reading instead of turning it into everyone's scratch notes.

Quick start

npx skills add masumi-network/citadel --skill citadel
pipx install citadel-archive
citadel onboard      # token, hooks, MCP (project + Cursor/Codex/Claude/…), capture roots
citadel status       # connection, identity, local setup

No Python yet? curl -fsSL https://raw.githubusercontent.com/masumi-network/Citadel/main/install.sh | sh checks for 3.11+, asks before installing, then sets up pipx and the CLI.

Self-hosting the server:

uv sync --dev
cp .env.example .env
uv run uvicorn kb.server:app --reload --port 8000

Full walkthrough in docs/onboarding/teammate-rollout.md, deployment in docs/operations.md.

Connecting an agent

Agents need a URL and a token. citadel onboard writes project .mcp.json and, when those tools are detected, ~/.cursor/mcp.json, Codex, Claude user-scope, Gemini, and Windsurf:

{
  "mcpServers": {
    "citadel": {
      "type": "http",
      "url": "https://citadel.utxo.ag/mcp/",
      "headers": { "Authorization": "Bearer ${CITADEL_MCP_ACCESS_TOKEN}" }
    }
  }
}

Use one seat per human. Give each agent process a distinct seat-bound token. After the human signs in with a seat token, the Access page can mint a reader token for search-only work or a writer token for explicit ingest. Do not share one token across agent processes.

For headless setup, pass the token through the environment instead of argv:

export CITADEL_MCP_ACCESS_TOKEN=ctdl_...
citadel onboard --non-interactive --json   # also wires Cursor/Codex/Claude when detected
citadel status --json --check-search

Confirm that status reports the expected seat_slug and default_dataset: seat:<slug> before the agent starts work.

Twenty-two tools cover search, document fetch, ingest, contribution, and the admin surface. Core CLI commands speak --json. Setup per client and the tool reference are in docs/mcp/README.md.

Measured performance

We publish the numbers, including the ones that look bad.

Search runs at a 311 to 472 ms median depending on token role. A 69-question golden harness scores answer_recall@5 at 0.8974 over the 39 questions carrying validated answer spans.

Two limits belong next to that number. Roughly a third of stored documents are not reachable by search at all (#228), and the documents that are indexed were embedded only at the head, so text past roughly the first 1,500 characters is also unreachable (#227). Ranking also correlates poorly with query relevance. All three are open work, and no recall figure currently describes the whole corpus.

Full table, definitions, and how to reproduce: docs/performance.md.

Documentation

Contributing

Issues and pull requests welcome. Commits need a DCO sign-off (git commit -s, no CLA), PR titles follow Conventional Commits, and the CI gate check must pass. Python 3.11+.

Start with good first issue or read CONTRIBUTING.md.

Found a security issue? Do not open a public issue. Use private vulnerability reporting. See SECURITY.md.

License

Apache-2.0. See LICENSE.