Local-first memory for AI agents
Most agent memory makes a database the source of truth. We made it your files.
agentcairn inverts the stack: human-readable Markdown with [[wikilinks]] is the truth, and a rebuildable DuckDB index gives your agent fast hybrid retrieval. Hand-edit a fact in Obsidian and the agent picks it up.
$ claude plugin marketplace add ccf/agentcairn
$ claude plugin install agentcairn@agentcairn Vault ยท source of truth
--- tags: [auth, fix] --- Fixed login by rotating [[jwt-secret]] during [[deploy]].
Index ยท disposable cache
MCP ยท recall
cairn recall "how did we fix login?"
Rotated the jwt-secret during deploy.
โณ auth-fix.md
The inversion
Most systems make the database the truth. We made it your files.
Mem0 and Zep keep your memory in a cloud database. Letta and agentmemory keep it in a database too, and treat files โ if any โ as a one-way export. agentcairn is the only one where the Markdown vault is the source of truth.
So your memory survives a model upgrade, a corrupted index, a schema change โ even uninstalling the tool. There is nothing to lose, because the truth was never trapped in the database.
Six differentiators
Obsidian Vault is the source of truth
Human-readable Markdown with frontmatter and [[wikilinks]]. Edit it by hand; the index honors your edits.
The index is disposable
DuckDB is a rebuildable cache. cairn reindex restores everything โ zero data loss.
Non-lossy by construction
The full note is always retained. Distillation only adds derived notes that link back.
Redaction before every write
Secrets scrubbed (regex + entropy + URL-cred) before body, title, or tags reach the vault.
A free, deterministic graph
Your [[wikilinks]] are the graph โ no LLM extraction, no hallucinated entities.
Daemonless, zero external DB
One embedded DuckDB does vector + BM25 + graph. No server, no Neo4j/Postgres/Qdrant.
How it works
Capture reads your agent's session transcripts out-of-band, then redacts โ dedups โ importance-gates โ distills into the vault. Retrieval fuses BM25 + vectors with RRF, with an optional cross-encoder reranker. The vault and the index reconcile on spawn; the MCP server exposes remember ยท recall ยท search ยท build_context ยท recent.
Survives uninstall
Delete the index. Reindex. Everything's back.
The index is a cache. The proof is destructive: remove it, rebuild it, lose nothing โ because the truth was never in the database.
Benchmarks measured
Retrieval โ LoCoMo
| arm | r@5 | r@10 | MRR |
|---|---|---|---|
| BM25 only | 0.527 | 0.604 | 0.459 |
| vector only | 0.536 | 0.637 | 0.433 |
| hybrid (RRF) | 0.562 | 0.648 | 0.477 |
| hybrid + reranker | 0.662 | 0.735 | 0.608 |
LoCoMo retrieval, turn-level macro-avg, FastEmbed nomic-embed-text-v1.5 (the default).
Retrieval โ LongMemEval-S
| arm | session r@5 | session MRR | turn r@5 |
|---|---|---|---|
| BM25 only | 0.920 | 0.918 | 0.680 |
| vector only | 0.936 | 0.916 | 0.507 |
| hybrid (RRF) | 0.954 | 0.938 | 0.640 |
| hybrid + reranker | 0.969 | 0.963 | 0.788 |
LongMemEval-S, full 500-instance set. Full turn r@10/MRR in the README.
Context efficiency
| dataset | haystack | recalled | reduction |
|---|---|---|---|
| LoCoMo | 25,646 tok | 529 tok | 51.1ร |
| LongMemEval-S | 136,552 tok | 2,207 tok | 64.7ร |
Context the default config recalls vs the full history. Estimate (~4 chars/tok).
- No single headline number โ these are relative ablation signals.
- graph-boost is inert on chat corpora (no native wikilink graph); it's for real vaults.
- QA-accuracy numbers use an Anthropic judge, not GPT-4o โ not comparable to published leaderboards.
Quickstart
# Claude Code plugin (recommended) claude plugin marketplace add ccf/agentcairn claude plugin install agentcairn@agentcairn # ...or use it directly โ MCP server + CLI, any host uvx agentcairn # on-demand MCP server cairn install cursor # wire the server into another host cairn recall "how did we fix auth?" # hybrid recall cairn savings # context recall has saved you cairn doctor # health-check the index
Use it in any MCP host
First-class in Claude Code. Portable everywhere else.
Claude Code gets the full plugin โ ambient recall at session start, capture at session end, a memory skill, and slash commands. Every other MCP host gets the same recall/search/remember tools via the portable server; cairn install wires it in non-destructively (your other servers are preserved, the original backed up to <config>.bak). One global ~/agentcairn vault, shared across every host.
| host | support | set up with | ambient |
|---|---|---|---|
| Claude Code | First-class plugin | claude plugin install agentcairn@agentcairn | โ |
| Cursor | MCP server | cairn install cursor | โ |
| Claude Desktop | MCP server | cairn install claude-desktop | โ |
| VS Code (Copilot) | MCP server | cairn install vscode | โ |
| Gemini CLI | MCP server | cairn install gemini | โ |
| Antigravity | MCP server | cairn install antigravity | โ |
| Codex CLI | MCP server | cairn install codex | โ |
cairn install # detect installed hosts + preview (writes nothing) cairn install cursor # configure one host cairn install --all # configure every detected host cairn install codex --print # just print the snippet, change nothing
Most hosts take a JSON mcpServers entry (VS Code uses its servers key); Codex takes a TOML table (comments and other servers preserved). Writes are non-destructive, idempotent, and backup-first. Ambient capture (auto recall-at-start, capture-at-end) is Claude-Code-only today.
Trust & security
Redaction before write
regex + entropy + URL-credential
Localhost-only MCP
READ_ONLY queries, no exposed ports
No telemetry
nothing phones home
Index outside the vault
the .duckdb cache is never synced