ccf/agentcairn

Your Markdown vault is canonical. DuckDB is the replaceable retrieval cache.
Website ·
PyPI ·
Obsidian companion ·
Benchmarks
A cairn marks a trail for whoever comes next. **agentcairn** does that for coding agents: it captures durable context from the tools you use, stores it as inspectable Markdown with provenance, and recalls only the most relevant pieces when another agent needs them.
Proof you can inspect
The memory is not hidden behind an admin console or a hosted database. The separate agentcairn-obsidian companion reads the same Markdown files as the agents and exposes provenance, currency, importance, supersession, and related: links.
A real agentcairn vault in Obsidian. The list is a view over the files—not a second memory store.
> **Dogfood snapshot · 2026-07-15.** Across 417 local recalls, the maintainer's vault returned context about 262× smaller than loading the full vault each time—an estimated 136.6M tokens of full-vault context avoided in aggregate. Token counts use approximately four characters per token. This is not billed-token savings, and agentcairn sends no telemetry.
Install
The shortest path is a first-class plugin. It bundles the MCP server, the memory skill, and the host-specific ambient hooks—no separate agentcairn package install. The plugin launches through uvx, so install uv first if uvx --version is not already available.
Claude Code
Claude Code gets per-turn project-scoped recall, session/compaction capture, and the /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings, and /agentcairn:ingest commands.
Codex
Codex gets the bundled MCP tools and memory skill, live-verified SessionStart recall, and SessionEnd capture with cairn sweep as the out-of-band backstop.
Agent-assisted setup
Already use skills.sh or a find-skills workflow? Install the public setup assistant:
Then ask your agent: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.
This installs setup guidance only—not the AgentCairn runtime, MCP server, plugin, or hooks. The assistant delegates those changes to AgentCairn's preview-first native installer and verifies the resulting integration. The Claude Code and Codex plugin commands above remain the shortest path.
The default vault is ~/agentcairn and is created on first use. A new empty vault has nothing useful to recall yet, so prove the whole loop explicitly:
remember writes the Markdown note and index entry together, so immediate recall is part of the contract. The first local run may download and warm the configured embedding/reranking models.
The contract
| Promise | What it means in practice |
|---|---|
| **Markdown is canonical** | Notes, frontmatter, and [[wikilinks]] are the durable memory. Edit a fact by hand; the next reconciled read honors it. |
| **The index is disposable** | DuckDB is a derived cache. Deleting or rebuilding it does not delete the Markdown vault. |
| **One vault crosses agents** | Supported hosts share the same configured vault instead of building isolated memories per tool. |
| **History is non-lossy** | Derived notes do not silently erase stored notes; superseded and expired facts remain inspectable and are demoted rather than hidden. |
| **Every result has context** | Project, validity status, and permalinks travel with recall so an agent can distinguish current local evidence from cross-project history. |
How it works
- **Capture:** host hooks improve immediacy; cairn sweep reads supported transcript stores out-of-band as the durable backstop. AgentCairn redacts recognized credentials, deduplicates, importance-gates, and distills before its automated plaintext writes.
- **Reconcile:** the first read transactionally brings the vault-scoped index in sync with Markdown. A failed rebuild preserves the last good cache and the durable files remain untouched.