Cairn MCP

Persistent polyglot knowledge graph for Claude Code. Index once, query forever.

Claude is stateless — every session starts cold. Cairn fixes this by indexing your project into a local SQLite knowledge graph and wiring into Claude Code via hooks, so file compression, checkpointing, and session restore all happen automatically in the background.

Install

npm install -g @misterhuydo/cairn-mcp

Requirements: Node.js >= 22.15.0

Setup

cairn install

That's it. One command registers the MCP server in ~/.claude.json and installs all hooks globally. Works on macOS, Linux, and Windows.

Restart Claude Code once after running this — required for the MCP server to load.

Project-only hooks (no MCP registration): cairn install-hooks or cairn install-hooks --global

Upgrade

npm install -g @misterhuydo/cairn-mcp

No need to re-run cairn install — hooks and MCP config carry over between versions.

What the hooks do

| Hook | Trigger | Effect | |---|---|---| | PreToolUse[Read] | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline with line numbers to save tokens | | PreToolUse[Edit] | Every file edit | Blocks Edit if Claude only saw compressed content — requires a full re-read first | | Stop | End of every response | Session auto-saved to .cairn/session.json | | UserPromptSubmit | First message of a new session | Fresh project: Claude prompted to run cairn_maintain. Returning session: Claude prompted to run cairn_resume |

First use

Just open Claude Code from your project root and start working. The UserPromptSubmit hook handles everything:

• Fresh project — hook tells Claude to run cairn_maintain, index is built automatically
• Returning session — hook tells Claude to run cairn_resume, prior context is restored

No manual steps. The index lives in .cairn/index.db inside your project — like a .git folder, just cd to the root and everything works.

Tools

| Tool | What it does | |---|---| | cairn_maintain | Full index of the current project. Suggests adding .cairn/ to .gitignore if not already present | | cairn_resume | Restore last session + re-index only changed files | | cairn_search | Find classes, functions, components by name or concept — results include file path and line number | | cairn_describe | Summarize what a folder or module does | | cairn_outline | Structural outline with line numbers per symbol + heuristic issue detection. On large federated projects returns a per-service summary; use repo param to drill into one service | | cairn_code_graph | Dependency health — instability, cycles, load-bearing modules | | cairn_security | Scan for XSS, SQLi, hardcoded secrets, weak crypto, and more | | cairn_todos | Scan codebase for TODO/FIXME/HACK comments, add manual items, resolve and list them | | cairn_bundle | Minified source snapshot (auto-handled by hooks) | | cairn_checkpoint | Save session state (auto-handled by hooks) | | cairn_minify | Minify a single file on demand (fallback when hooks are not installed) | | cairn_switch | Switch active project root mid-session (use for maintenance on a sibling service) | | cairn_memo | Save a preference, decision, or discovery to the project's persistent memory | | cairn_employ_memory | Recall stored memories explicitly (call only when asked) |

Multi-service / monorepo support

Cairn understands workspace structures where multiple services or packages live under a common parent folder.

How it works:

• Each service has its own .cairn/index.db — it is the authoritative index for that service
• When cairn_maintain runs at the parent folder, it skips files already covered by a sub-project and instead federates all sub-indexes via SQLite ATTACH — no duplication
• When a session opens inside a subfolder (e.g. elprint-component-service/), Cairn automatically discovers and mounts siblings:
  1. If the parent folder has a .cairn/index.db (already initialized) → uses its registry
  2. Otherwise → scans the parent directory for any sibling folders that already have a .cairn/index.db

The result: every service session has full cross-service visibility for search, outline, and bundle — no manual setup required.

Drilling into a service from a federated session:

cairn_outline { repo: "elprint-component-service" }   → outline one service
cairn_search  { query: "PartRepository" }             → searches all services

When you need to re-index a sibling service:

cairn_switch  { path: "/path/to/elprint-project-service" }
cairn_maintain
cairn_switch  { path: "/path/to/elprint-component-service" }

cairn_switch is the explicit escape hatch for maintenance — it changes the active project root so cairn_maintain and cairn_checkpoint target the right service.

TODO tracking

cairn_todos scans every file Cairn indexes for TODO, FIXME, HACK, XXX, and NOTE comments and stores them in the project database. Manual items you add yourself are never overwritten by a scan.

cairn_todos { action: "list" }                          → all todos (open + done)
cairn_todos { action: "list", status: "open" }          → open only
cairn_todos { action: "list", source: "manual" }        → items you added yourself
cairn_todos { action: "add", text: "...", kind: "FIXME" } → add a manual item
cairn_todos { action: "resolve", id: 42 }               → mark done
cairn_todos { action: "scan" }                          → re-scan without full maintain

Stats are included automatically in cairn_maintain (todos_found) and cairn_resume (open_todos), so you always know the backlog at a glance.

Supported languages

| Language | What Cairn extracts | |---|---| | Java | packages, classes, interfaces, enums, records, methods | | TypeScript / JavaScript | classes, interfaces, functions, types, enums | | Vue | components, composables, script block symbols | | Python | classes, functions, decorators | | SQL | tables, views, stored procedures | | XML / HTML | bean ids, component names | | Config (YAML, properties, .env) | top-level keys | | Markdown | headings | | Build files (pom.xml, package.json, build.gradle) | dependencies |

License

MIT