cairn

Verifiable codebase memory for AI agents — a structural graph + compass + wiki + tribal memory, all local, all traceable to source.

cairn parses your repos with tree-sitter into a resolution-labeled structural graph (14 languages), fuses it with code-grounded tribal memory, compass, and wiki, and serves all of it through one MCP server (22 tools) + a cairn CLI. The product is a verification contract: every exact edge is actually resolved, every symbol in a synthesized doc is graph-verified by a deterministic critic, and the LLM never sits in the query path.

Contents

• Get Started
• Language Support
• Why cairn?
• Key Features
• How It Works
• Measured Results
• CLI Reference
• MCP Tools
• Configuration
• Supported Platforms & Agents
• Documentation
• Troubleshooting
• Development
• Dependency Licenses
• Status · License

Get Started

1. Install the CLI

pip install cairn-intel

Already installed? cairn upgrade updates in place (detects uv tool / pipx / pip; --check previews without changing anything).

2. Wire up your agent(s)

cairn install-agents

Detects which AI clients you have (Claude Code, Cursor, ZCode, Droid, Claude Desktop, opencode, agy, kilo, omp), shows what's already wired, and prompts for scope: workspace (per-project ./.claude/, ./.cursor/ …) or global (~/.claude/ — every project inherits it). Non-interactive: cairn install-agents --yes --scope global. Manual wiring is one JSON block (stdio — or point clients that support SSE at http://127.0.0.1:9876/sse after cairn serve start, which is what install-agents does by default):

{ "mcpServers": { "cairn": { "command": "cairn", "args": ["serve"] } } }

3. Build the graph

cairn build          # parse the workspace, resolve edges (first run; ~4s on cairn itself)

4. No more syncing

cairn update         # incremental reindex — only what changed since the last build

With the optional [watch] extra, a running cairn serve watches the workspace and reindexes edits within a ~2s debounce window — no restart, no manual update. Pending files carry a staleness banner on results until the update lands.

Uninstall — cairn uninstall removes agent wiring, hooks, and the graph store; --dry-run previews the scope; cairn uninstall-agents only removes client configs.

Language Support

Fourteen languages, one uniform contract: definitions, call edges (labeled exact / ambiguous / unresolved), references, and inheritance wherever the grammar carries them. .h headers are sniffed to Objective-C / C++ / C.

Not indexed (yet): Vue / Svelte single-file components, CSS, HTML. SCIP coexistence is opt-in per language via cairn.json — without an index, tree-sitter alone carries the language. Details: docs/indexing.md.

Why cairn?

A code graph alone is commoditized — several tools index symbols and call edges. Generic agent memory is ungrounded — it lets an LLM silently rewrite what it "remembers." cairn is the narrow intersection: a structural graph fused with code-grounded memory, where every output is traceable to source and every synthesized doc is fact-checked before it lands.

Three promises cairn can machine-check — and does, in CI, on cairn's own code:

1. Every exact edge is actually resolved. The resolver pins each edge to one definition before labeling it exact (target_id IS NOT NULL); an invariant test guards this on every build.
2. Every symbol in a compass / wiki / memory doc exists in the graph. A deterministic critic fact-checks every LLM-synthesized doc against the graph before it is written; hallucinated references are rejected or flagged.
3. Every answer is re-derivable from local data. cairn never calls an LLM in the query path — the LLM stays on a task queue behind the critic gate, so outputs are verifiable, not probabilistic.

Resolution labels are the evidence for promise #1. Every code graph can tell you "who calls this." cairn tells you whether to trust the answer: exact (pinned to one definition — trusted), ambiguous (multiple candidates; the resolver declined to guess), unresolved (external / stdlib). Graph tools default to precise mode — only exact edges — so blast radius is never inflated by name collisions:

cairn impact invoke              # precise (default): real callers only — ground truth
cairn impact invoke --fuzzy      # candidate list (name matches), each labelled unverified

Measured on this repo: 82% of fuzzy results for common names are name-collision noise that precise mode excludes. An empty precise result means "no resolvable callers," not "unused" — retry with --fuzzy before concluding a symbol is dead. And explore surfaces ambiguous dispatch hops — polymorphism that grep fundamentally cannot see.

Honest trade-offs

• Semantic retrieval is opt-in and mid-band. On the hand-verified ground truth, pooled recall/MRR sit at 0.4174 / 0.2862 — below the 0.50 / 0.33 shipping targets, which is exactly why the semantic stack is an extra, not the default path; the structural tools carry the precision story.
• The [semantic] extra is heavy. Real embeddings pull sentence-transformers (+ torch on Linux); a one-time ~836 MB model download lives in ~/.cairn/lib/ (scoped per Python version). The default install is torch-free and network-free. Alternative with no download at all: point CAIRN_EMBED_BACKEND at a local OpenAI-compatible embeddings server (oMLX, Ollama, LM Studio) — same bge-m3 vectors, zero torch footprint (configuration.md).
• Synthesized docs need an LLM pass. Compass/wiki generation runs through the task queue (cairn task) with the critic gate — deterministic, but it won't happen purely locally without any model access.

Key Features

• Surgical context — explore(query) returns matching symbols' verbatim source, the call paths between them, and a blast-radius summary in one round trip. The recommended first call for agents.
• Trust-labeled blast radius — precise mode follows only resolved edges; --fuzzy gives an explicitly-labelled candidate list for auditing and dead-code hunts.
• Cross-repo reach — cross_repo_deps(repo) maps who consumes your public API across registered repos; impact_analysis reports consumer reach.
• Code-grounded memory — decisions / patterns / mistakes / workarounds, symbol-keyed, recalled alongside graph results; promotion and decay lifecycles keep it honest.
• Docs as first-class knowledge — cairn knowledge ingest stages markdown / PDF / DOCX (repo doc-trees or fed files) through a reviewable dry-run manifest before anything lands in the store; classification, redaction, and collision-safe identities included.
• Always fresh — incremental cairn update (git-diff-driven), optional live watch with staleness banners, and cairn doctor's 11 health checks gating CI.
• 100% local — one SQLite store under ~/.cairn; no network calls, no telemetry egress (OTLP export is opt-in and best-effort).
• Agent-first surfaces — the same store backs 22 MCP tools and the CLI; cairn install-agents wires every detected client in one command.
• Local dashboard — cairn dashboard opens a loopback web console at 127.0.0.1:8765: interactive graph with symbol search, recorded tool-call history and token usage (MCP + CLI, mode-labeled estimates), session chains, health/memory panels, a global workspace selector in the topbar (every view follows the selection), a Ctrl/Cmd+K command palette (views, workspaces, symbol search), repo-scoped wiki navigation (grouped catalog with filters and search, breadcrumbs, in-page TOCs, prev/next, graph cross-links), knowledge views over the ingested docs (/knowledge catalog with family/status/tag filters, per-doc detail with supersede chain, relationship panel, and linked code refs, and a /knowledge/graph relationship canvas whose legend chips filter edges in place), a collapsible grouped sidebar, a dark/light theme whose flip re-colors the live graph canvas in place (no reload; canvas physics respects prefers-reduced-motion), CSV/JSON export of any filtered view, an Embeddings status view (probe health, fallback state, per-knob config sources) with the degradation banner, and a Settings page that persists embedding-backend configuration to ~/.cairn/config.json.

How It Works

The query path is deterministic: tree-sitter parsing → SQLite graph → FTS5/BM25 fused with vectors (RRF, always on when embeddings exist) and a confidence-gated optional rerank → labeled results. The LLM only ever runs off-path, generating compass/wiki/memory candidates that the deterministic critic verifies symbol-by-symbol against the graph.

Deep dives with diagrams: architecture · indexing · retrieval · knowledge & memory.

Measured Results

Agent effort vs a grep-and-read baseline (cairn bench --suite agent; deterministic arms, no LLM, reproducible in CI — 300-file corpus, 6 task shapes, medians):

Depth-3 blast radius is the extreme: 2 tool calls and 712 tokens vs 303 calls and 429,600 tokens — grep must read every name-collision hit; precise edges don't.

Query latency (cairn bench --suite perf, p95): find_definition 0.03 ms · get_callers 0.06 ms · impact_analysis 0.11 ms · search_symbols 6.25 ms · semantic_search 201.67 ms (with embeddings) · explore 513.73 ms. First-semantic_search latency after boot warm-up: 15.5 s cold → 232.6 ms warm.

Self-demo — cairn indexes its own source in ~4s (~1,900 symbols / ~11,500 edges), and CI re-runs the build + resolution invariant on every push (tests/test_self_demo.py), so the dogfood cannot silently rot. Reproduce:

git clone https://github.com/tanlnm512/cairn && cd cairn
cairn build
cairn def build_graph               # -> src/cairn/graph/builder.py
cairn impact build_graph            # -> real transitive callers (non-empty)
sqlite3 "$(cairn config --db)" \
  "SELECT COUNT(*) FROM edges WHERE resolution='exact' AND target_id IS NULL"   # -> 0

Run the suites yourself: cairn bench --help and cairn eval --help.

CLI Reference

cairn --help (or cairn <group> --help) is authoritative. The essentials:

Deep reference: docs/cli-reference.md.

MCP Tools

22 tools across four layers — same store as the CLI:

Per-tool shapes and examples: docs/mcp-tools.md.

Configuration

The default install is dependency-light and network-free. Opt in with extras:

Also: CAIRN_HOME (store location, default ~/.cairn), CAIRN_TELEMETRY=off (master kill switch). Full reference: docs/configuration.md.

Supported Platforms & Agents

• Platforms — anywhere Python ≥ 3.10 runs; CI tests 3.10–3.14 (macOS + Linux; make ci-local replicates CI in a clean Linux container).
• Agents — Claude Code, Cursor, ZCode, Droid, Claude Desktop, opencode, agy, kilo, omp — wired by cairn install-agents, or any MCP client via the manual JSON block above.

Documentation

Full index: docs/README.md. The short map:

Visual overviews (standalone HTML) live in docs/diagrams/: system architecture, the C4 model, indexing, retrieval, and doc-ingestion pipelines. Contribution and release procedures: docs/review-checklist.md · docs/release-checklist.md.

Troubleshooting

• cairn doctor — 11 health checks with PASS/WARN/FAIL each; non-zero exit means an active degradation (agents can gate on it).
• cairn report — redacted diagnostic bundle for bug reports; it never uploads anything.
• Empty impact / get_callers on a symbol you know is used → it's precise mode: retry --fuzzy / fuzzy=True; the name-matches list is labelled.
• cairn update did nothing on a fresh clone → that's correct (clean tree, no diff); run cairn build first.

Development

pip install -e ".[dev]"   # full review gate: pytest, ruff, mypy, bandit,
                            # pip-audit, pre-commit, commitizen
                            # (compiles the vendored Kotlin grammar — needs a C toolchain)
pytest -m core            # fast <3s smoke subset (one test per core function)
pytest                    # full suite (default gate + infra tier; CI splits them)
pytest -m infra           # bench/dataset/soak tier alone (CI runs it on main pushes)
make ci-local             # clean-room CI replication in a Linux container

pytest -m core includes the cairn-on-cairn self-demo: cairn indexes its own source in an isolated temp DB and asserts the core queries return correct results for known symbols — and that the resolution invariant holds on the verifier's own code. Releases are cut by tagging vX.Y.Z (tag-triggered workflow; see docs/release-checklist.md). Contributions follow docs/review-checklist.md.

Dependency Licenses

MIT-licensed; dependencies are all permissive (MIT, BSD, Apache-2.0, MPL-2.0, PSF) — see NOTICE. The optional [semantic] extra resolves torch (+ NVIDIA CUDA components on Linux, under their own licenses) at install time; the BAAI/bge-m3 embedding model (MIT) downloads on demand to ~/.cairn/lib/cp<version>/ and is not redistributed with cairn.

Status

Beta — pre-1.0 (v0.18.0). Public surfaces (CLI flags, MCP tool shapes, knowledge-file layout) may still shift before 1.0. Feedback welcome via GitHub issues.

License

MIT — © 2025–2026 Tan Le