🪨 agentcairn
Local-first memory for AI agents — that you can actually read, edit, and own.
cairn /kɛən/ · noun — a stack of stones raised to mark a trail or a place worth remembering, left for whoever comes next.
agentcairn gives your coding agent durable, high-quality memory — but instead of locking it in an opaque database or a cloud service, your memories live as plain Markdown in an Obsidian vault you own. A fast, rebuildable DuckDB index sits on top for retrieval. Open your vault, read what the agent remembered, fix a wrong fact by hand, or drop in your own notes — and the agent picks it all up.
Why agentcairn is different
Most agent-memory systems make a database or cloud store the source of truth and treat files (if any) as a one-way export. agentcairn inverts that:
- 📂 Your vault is the source of truth — not an export. Memory is human-readable Markdown with frontmatter and
[[wikilinks]]. Edit it in Obsidian; the index honors your edits.
- ♻️ The index is disposable. DuckDB is a rebuildable cache (
cairn reindex). Your memory survives a model upgrade, a corrupted index, a schema change, or uninstalling the tool — zero data loss, because the truth is just files on disk.
- 🧠 Non-lossy by construction. The full note is always retained. Distillation only adds derived notes that link back to the source — it never silently drops facts it didn't think to extract at write time.
- 🔒 Redaction before every write. Secrets are scrubbed (regex + entropy + URL-credential detection) before anything — body, title, or tags — reaches the plaintext vault. We write files you can read, so we treat a leaked credential as the worst failure mode.
- 🕸️ A free, deterministic knowledge graph. Your
[[wikilinks]] and frontmatter are the graph — no LLM extraction, no hallucinated entities.
- 🪶 Daemonless, zero external DB. One embedded DuckDB file does semantic vector search, BM25 full-text, and graph traversal. No always-on server, no Neo4j/Postgres/Qdrant, no required cloud key — just a
cairn CLI and an on-demand MCP server.
- 🔍 Honestly measured. A reproducible LongMemEval-S + LoCoMo harness ships in
benchmarks/ — with real numbers, ablations, and explicit caveats instead of one cherry-picked headline (see below).
Install
The easiest way to use agentcairn is the Claude Code plugin — one install wires up the MCP server, ambient memory (recall at session start, capture at session end), a memory skill, and slash commands:
claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn
On install you pick a vault path (default ~/agentcairn); it's auto-created on the first session — no Obsidian setup required. From then on agentcairn surfaces relevant memory at the start of each session, distills each session into your vault, and gives you /agentcairn:recall, /remember, /memory, /savings, and /ingest. Nothing to pip-install — the plugin runs the published package via uvx.
Not on Claude Code? agentcairn is also a standalone MCP server + CLI for any host — see Using it directly.
How it works
flowchart LR
T["Session transcripts<br/>(out-of-band)"]
H["You · Obsidian<br/>(hand edits)"]
V["📂 Obsidian vault<br/>Markdown + frontmatter + wikilinks<br/><b>source of truth</b>"]
I["♻️ DuckDB index<br/>vector + BM25 + graph<br/><b>rebuildable cache</b>"]
M["MCP tools<br/>remember · recall · search · build_context · recent"]
T -- "redact → dedup → distill" --> V
H -- "edit" --> V
V -- "parse / reconcile-on-spawn" --> I
I -- "READ_ONLY hybrid recall" --> M
M -. "remember (redacted write)" .-> V
classDef truth fill:#eaf1ff,stroke:#317cff,color:#191919;
classDef cache fill:#f5f5f3,stroke:#999999,color:#191919;
class V truth
class I cache
