AgentCairn
Long-term, cross-project memory for AI coding agents, with your own Obsidian vault as the source of truth — daemonless, no opaque databases, no telemetry.
- Source repo
- ccf/agentcairn
- Stars
- ★ 78
- Last updated
- 1d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 89/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers using multiple coding agents (e.g. Claude Code and Codex) who want them to share one memory vault instead of isolated per-tool memories
- Not a fit if
- Teams wanting a hosted or cloud-synced memory service
- Users treating the vault as encrypted, access-controlled storage
- Teams needing identical ambient memory on every host — Cursor and Antigravity only get sweep capture
- Website
- agentcairn.dev ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-19
- Source review
- 89/100 · Good
What does this agent do, and when should you use it?
AgentCairn is an Apache-2.0 open-source project that gives coding agents (Claude Code, Codex, Cursor, OpenCode, Hermes Agent and others) one durable, shared memory. It captures context via host hooks and writes it as human-readable Markdown notes with frontmatter and [[wikilinks]] — that vault is canonical — while a DuckDB index serves only as a disposable, rebuildable retrieval cache. Recall is exposed through an MCP server and the cairn CLI, fusing BM25 with semantic vectors via Reciprocal Rank Fusion and optional reranking, using local FastEmbed nomic-embed-text-v1.5 by default. There is no daemon, no external database and no telemetry, and the companion agentcairn-obsidian plugin lets you inspect provenance, currency, importance and supersession directly in Obsidian. The project is beta; standalone use requires Python 3.11+.
Capture: host hooks (Claude Code SessionEnd/PreCompact, Codex SessionEnd) collect context immediately, with cairn sweep reading supported transcript stores as an out-of-band backstop; writes are credential-redacted, deduplicated, importance-gated and distilled. Remember: an MCP tool atomically writes a Markdown note and updates the DuckDB index under one writer lock, so saves are immediately recallable. Reconcile: the first read transactionally syncs the index with Markdown, preserving the last good cache on failed rebuilds. Recall: BM25 and semantic vectors are fused with Reciprocal Rank Fusion, optionally reranked, with a visible BM25 fallback and diagnostics on model failure. Results carry project, validity status and permalinks; valid_from, valid_until and superseded_by keep old evidence visible but demoted. A one-way cairn import claude-memory command imports Claude Code's MEMORY.md into the shared vault with provenance.
- Developers using multiple coding agents (e.g. Claude Code and Codex) who want them to share one memory vault instead of isolated per-tool memories
- Engineers accumulating durable project facts (e.g. 'staging deploys use blue-green') recalled per-project in new sessions
- Users who value auditability and want to inspect provenance, importance, currency and supersession of every memory in Obsidian
- People migrating Claude Code's auto-memory into a shared vault via cairn import claude-memory with source provenance retained
- Teams watching context cost: recall returns only relevant chunks (benchmarks show LongMemEval-S full history averages ~136.5K tokens vs ~2,207 recalled)
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npx skills add ccf/agentcairn --skill agentcairn-setup -guv tool install agentcairnuvx --versionuvx agentcairn
- Config files
~/.agentcairn/config.toml- Runtime
- Python 3.11+
How do you install or deploy this agent?
Fastest path is a first-class plugin. Install uv first (ensure uvx --version works). Claude Code:
claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairnCodex:
codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairnOr agent-assisted setup (skills.sh workflow):
npx skills add ccf/agentcairn --skill agentcairn-setup -gStandalone install requires Python 3.11+:
uv tool install agentcairnThe default vault is ~/agentcairn, created on first use; the first local run downloads and warms the configured embedding/reranking models.
How do you use this agent?
Prove the loop first: tell the agent 'Remember this durable fact: staging deploys use blue-green.', then 'Recall the staging deploy strategy.' — you should get the fact plus a memory permalink. Standalone CLI usage:
cairn init ~/agentcairn
cairn sweep --vault ~/agentcairn
cairn recall "how did we fix the auth bug?" --vault ~/agentcairn
cairn doctor --vault ~/agentcairnImport Claude Code native memory:
cairn import claude-memory # preview; writes nothing
cairn import claude-memory --apply # import this repositoryMaintenance commands:
cairn reindex ~/agentcairn # rebuild the disposable cache
cairn savings # local context-efficiency estimate
cairn link --vault ~/agentcairn # write deterministic related: neighborsConfiguration lives in ~/.agentcairn/config.toml with auto_recall, auto_recall_k and auto_recall_scope (default "project"; cross-project requires an explicit opt-in to "all"). Run the MCP server on demand with uvx agentcairn.
What are this agent's strengths and limitations?
- Markdown is canonical and the DuckDB index is disposable — memory is fully user-owned, hand-editable and inspectable, with no opaque database
- One vault crosses Claude Code, Codex, Cursor, OpenCode, Hermes and other hosts, avoiding isolated per-tool memories
- Local by default: FastEmbed embeddings, stdio MCP, no daemon, no telemetry, credential-pattern redaction, and vault files locked to 0600/0700
- Ships a revision-pinned LongMemEval-S + LoCoMo benchmark harness plus dogfood data (417 recalls averaged 262× smaller than full-vault loading), so the evidence is reproducible
- The project is beta; standalone use needs Python 3.11+ and the first local model load can be slow
- Ambient behavior varies by host: Cursor and Antigravity only get out-of-band sweep capture, with no per-turn recall
- The vault is plaintext by design, not encrypted storage; redaction covers recognized patterns only, so unknown secrets and hand edits are the user's responsibility
- Opting into cloud features (Voyage, OpenAI-compatible embeddings, Anthropic judge) sends redacted text off-machine and may incur latency or API cost
- Managed scheduling targets only macOS launchd and Linux user crontab; other platforms need your own scheduler
How does this agent compare with similar options?
The README positions the project as a local-first alternative that does not hide memory behind a hosted database or admin console, and defines an import relationship with Claude Code's native MEMORY.md memory, but does not name specific competing products.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AgentCairn This agent | 89 · Good | Agent plugin / skillFree | ★ 78 | 1d ago | Python | Codex · Claude Code |
| Ruflo Agent Harness | 48 · Major gaps | CLIFree + model costs | ★ 82k | today | TypeScript | Codex · Claude Code · OpenAI API |
| Emulo | 76 · Good | Agent plugin / skillFree + model costs | ★ 306 | 1mo ago | HTML | Codex · Claude Code |
| XERJ | 65 · Some gaps | CLIFree | ★ 19k | 1d ago | Rust | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Strong evidence: READ_ONLY DuckDB for MCP, single-writer lock, symlinks escaping the vault root rejected, vault files 0600/0700; installs are preview-first (no-arg preview writes nothing, --print, --apply gated imports, skill requires approval before writing test memories), redaction before plaintext writes, cloud embedder/judge is explicit opt-in egress with no telemetry, and provenance (project/harness/permalink) is stored in frontmatter. Deductions: redaction is self-described best-effort and plaintext storage leans on file mode as the only access control (sensitive data 2); a Trivy workflow and a documented load-bearing mcp<2.0.0 pin exist but no vulnerability-response record is visible (dependency security 2); host-config writes are backup-first and merge-preserving, but full removal/uninstall completeness cannot be confirmed from the packet (external effects 2, rollback 2 — .bak backups, rebuildable index and schedule uninstall exist, while MCP-config removal is marked out of scope in the v1 plan).
Code shows a graded degradation ladder: visible BM25 fallback on model/provider failure, VaultBusyError exits EX_TEMPFAIL(75), startup reconcile distinguishes writer_busy/reader_busy/reconcile_failed with freshness status in results; malformed configs are not clobbered and unknown keys warn once. Deduction: CLAUDE.md records 0.10.1 (2026-06-13) while README cites 0.24.2 — documentation snapshots drift (2 rather than 3).
Audience, host matrix (including Cursor/Antigravity sweep-only differences), platform boundaries (macOS launchd / Linux crontab, Shared-GID caveats, Python 3.11+, first-model-load latency), precise skill trigger conditions, and capability limits (beta, retrieval evidence limited to conversational memory) are all concretely documented; weakest environments are explicitly scoped, no deduction.
Clear information architecture (vault as truth, disposable index), install notes covering plugin/CLI/uvx paths including the `uvx cairn` wrong-package warning, locked naming decisions, an unusually honest limits section, complete Apache-2.0 with visible SPDX practice. Deductions: examples and screenshots but no FAQ (2); CHANGELOG is referenced in the release ritual but the file is not shown in the packet (2); single named maintainer with unverified publisher identity and personal-process governance (2).
High output usability: recall results carry permalinks, project labels, validity status and freshness metadata; marginal value is backed by retrieval ablations (BM25 → RRF → reranker) and context-reduction tables, explicitly framed as retrieval recall rather than QA accuracy or billed savings; cost/benefit quantified with the token heuristic disclosed, no deduction.
Benchmarks are described as revision-pinned with CI running the offline regression, and CLAUDE.md forbids single headline benchmark claims; specs, plans, code and tests corroborate on install, config and writer semantics; fact/inference separation is excellent ('Read the numbers honestly'). Deductions: the dogfood snapshot (417 recalls, 136.6M tokens) is unreproducible self-report (claim traceability 2); all benchmark numbers are self-measured without independent third-party comparison (2).
- The vault is plaintext Markdown; redaction is pattern-based and self-described best-effort — unknown credential formats and hand edits are unredacted, and file mode is the only access control. Be careful on shared machines and cautious with vault_group_writable.
- Enabling cloud embeddings or the Anthropic judge sends redacted note chunks and queries off-machine; this is explicit egress to evaluate yourself.
- cairn install modifies host MCP configs (backed up as .bak), but v1 ships no uninstall/remove command; rollback means restoring backups by hand.
- Self-reported performance numbers (dogfood snapshot and benchmark tables) are not independently validated, and token counts use a ~4-chars/token heuristic — not billed cost.
- Publisher identity is unverified by the FollowAgents enterprise registry; this is a single-maintainer beta where release cadence depends on one person.
- Do not run `uvx cairn` — that resolves a different package; use `uvx --from agentcairn cairn`.
FAQ
Does data leave my machine?
Will deleting or rebuilding the index lose data?
Does it cost money?
Which agents are supported, and is behavior identical?
What happens if I hand-edit the Markdown notes?
Is AgentCairn open source?
Is AgentCairn safe to use?
Is AgentCairn still maintained?
Who makes AgentCairn?
What is AgentCairn's official website?
Thanks — we use this to improve the page.