npm package: @misterhuydo/cairn-mcp
Description: MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.
Latest version: 1.7.1

# 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

```bash
npm install -g @misterhuydo/cairn-mcp
```

**Requirements:** Node.js >= 22.15.0

---

## Setup

```bash
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

```bash
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 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 |
| `cairn_resume` | Restore last session + re-index only changed files |
| `cairn_search` | Find classes, functions, components by name or concept |
| `cairn_describe` | Summarize what a folder or module does |
| `cairn_outline` | Structural outline + 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