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

At a glance

How it runs
Agent plugin / skillMCP serverCLI
Works with
Universal · cross-platformCodex · Claude Code
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
Python 3.11+ (standalone use)uv / uvxShell / CLILocal filesystemMCP Server
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.

  1. 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
  2. Engineers accumulating durable project facts (e.g. 'staging deploys use blue-green') recalled per-project in new sessions
  3. Users who value auditability and want to inspect provenance, importance, currency and supersession of every memory in Obsidian
  4. People migrating Claude Code's auto-memory into a shared vault via cairn import claude-memory with source provenance retained
  5. 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 -g
  • uv tool install agentcairn
  • uvx --version
  • uvx 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@agentcairn

Codex:

codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Or agent-assisted setup (skills.sh workflow):

npx skills add ccf/agentcairn --skill agentcairn-setup -g

Standalone install requires Python 3.11+:

uv tool install agentcairn

The 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 ~/agentcairn

Import Claude Code native memory:

cairn import claude-memory            # preview; writes nothing
cairn import claude-memory --apply    # import this repository

Maintenance commands:

cairn reindex ~/agentcairn            # rebuild the disposable cache
cairn savings                         # local context-efficiency estimate
cairn link --vault ~/agentcairn       # write deterministic related: neighbors

Configuration 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?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Good
89/ 100 5-point scale 4.5 / 5
Trust 24/29
Reliability 12/14
Adaptability 18/18
Convention 16/18
Effectiveness 13/13
Verifiability 6/8
Why each dimension lost points
Trust24 / 29 · 4.1/5

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).

Reliability12 / 14 · 4.3/5

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).

Adaptability18 / 18 · 5.0/5

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.

Convention16 / 18 · 4.4/5

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).

Effectiveness13 / 13 · 5.0/5

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.

Verifiability6 / 8 · 3.8/5

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).

Risks and how to mitigate them
  • 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`.
Evidence confidence: Low Reviewed Nov 21, 2026 Reviewed revision bb66c80ba2ae
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/agentcairn.svg)](https://followagents.com/en/agents/agentcairn)
<a href="https://followagents.com/en/agents/agentcairn"><img src="https://followagents.com/badge/agentcairn.svg" alt="FARS review"></a>

FAQ

Does data leave my machine?
Not by default: FastEmbed runs locally, the MCP server uses stdio, and there is no daemon or telemetry. Only when you explicitly enable a cloud embedder (Voyage, OpenAI-compatible) or the Anthropic judge does redacted text go to that provider.
Will deleting or rebuilding the index lose data?
No. DuckDB is a derived cache; the Markdown vault is canonical. A failed rebuild preserves the last good cache, and durable files remain untouched.
Does it cost money?
The software is free (Apache-2.0) and the default local embeddings require no API keys. Optional cloud features (Voyage/OpenAI-compatible embeddings, Anthropic judge) use your own keys and may cost money.
Which agents are supported, and is behavior identical?
Claude Code, Codex, Cursor, OpenCode, Hermes Agent, Antigravity, VS Code (Copilot), Claude Desktop and any MCP host are supported, but ambient memory differs: Claude Code/Codex/OpenCode/Hermes get full recall and capture; Cursor/Antigravity only sweep; generic MCP hosts are host-dependent.
What happens if I hand-edit the Markdown notes?
Markdown is canonical, so hand edits are honored on the next reconciled read; history is non-lossy — superseded and expired notes are demoted and remain inspectable rather than deleted.
Is AgentCairn open source?
Yes. The source code is on GitHub (ccf/agentcairn) under the Apache-2.0 licence.
Is AgentCairn safe to use?
FollowAgents' FARS review (Nov 21, 2026) scored AgentCairn 24/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is AgentCairn still maintained?
Yes. The latest commit on GitHub is from 2026-11-19, within the last 30 days.
Who makes AgentCairn?
AgentCairn is published on GitHub by the account ccf. FollowAgents has not verified which person or company is behind that account.
What is AgentCairn's official website?
The project's GitHub repository lists https://agentcairn.dev as its website. That link is set by the repository owner; the source code itself is on GitHub (ccf/agentcairn).
Was this page helpful?
View on GitHub ↗ Install ↓

Host ecosystems

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts