agentcairn

A cairn marks a trail for whoever comes next.agentcairndoes 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.

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 about262× smallerthan loading the full vault each time—an estimated136.6M tokens of full-vault context avoidedin aggregate. Token counts use approximately four characters per token. This is not billed-token savings, and agentcairn sends no telemetry.

claude plugin marketplace add ccf/agentcairn claude plugin install agentcairn@agentcairn

Claude Code gets per-turn project-scoped recall, session/compaction capture, and the/agentcairn:recall,/agentcairn:remember,/agentcairn:memory,/agentcairn:savings, and/agentcairn:ingestcommands.

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

Codex gets the bundled MCP tools and memory skill, live-verified SessionStart recall, and SessionEnd capture withcairn sweepas the out-of-band backstop.

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

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~/agentcairnand is created on first use. A new empty vault has nothing useful to recall yet, so prove the whole loop explicitly:

You → Remember this durable fact: staging deploys use blue-green. Agent → written and indexed You → Recall the staging deploy strategy. Agent → staging deploys use blue-green. ↳ <memory permalink>

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

- Capture:host hooks improve immediacy;cairn sweepreads 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.
- Recall:BM25 and semantic vectors are fused with Reciprocal Rank Fusion, then optionally reranked. Model/provider failures visibly fall back to BM25 with diagnostics instead of returning incompatible vectors.
- Remember:the MCP tool atomically writes a Markdown note and updates the index under one writer lock, making a successful save immediately recallable.

The plugin is the easiest route, but agentcairn is also a standalone CLI and on-demand MCP server. Standalone installs require Python 3.11+.

uv tool install agentcairn cairn init ~/agentcairn cairn sweep --vault ~/agentcairn cairn recall "how did we fix the auth bug?" --vault ~/agentcairn cairn doctor --vault ~/agentcairn

Bring Claude Code's memory with you

Claude Code's auto-memory can seed the shared vault without changing its source files. The command previews only the current repository by default; add--applyto write the redacted notes and refresh the index.

cairn import claude-memory # preview; writes nothing cairn import claude-memory --apply # import this repository cairn import claude-memory --project ../other --apply

The one-way import readsMEMORY.mdand its topic Markdown files—neverCLAUDE.mdor.claude/rules/. Imported notes retain Claude Code, project, and source-file provenance. When a source changes, the prior version remains inspectable but is superseded; when one disappears, its imported version expires. A small.agentcairn/native-memory/registry preserves that lifecycle without indexing source content twice. Use--source <dir>for a custom, managed, or session-overridden Claude memory directory, or--no-reindexwhen batching imports.

uvx agentcairn # MCP server uvx --from agentcairn cairn recall "..." # CLI; plain uvx cairn is a different package

cairn schedule install --vault ~/agentcairn # launchd on macOS / user crontab on Linux cairn schedule status cairn link --vault ~/agentcairn # write deterministic related: neighbors cairn reindex ~/agentcairn # rebuild the disposable cache cairn savings # local context-efficiency estimate cairn index-status --vault ~/agentcairn

On other operating systems, runcairn sweepfrom your scheduler of choice.

Settings live in~/.agentcairn/config.toml; precedence is CLI flag → environment → config file → default.

auto_recall = true auto_recall_k = 3 auto_recall_scope = "project" # use "all" only as an explicit cross-project opt-in

Localnomic-embed-text-v1.5embeddings are the default. Voyage, OpenAI-compatible embeddings, and the Anthropic durability judge are opt-in. With a cloud provider enabled, remaining secret-redacted note chunks and queries leave the machine; changing the embedding model re-embeds the vault and may incur real latency or API cost.

Context returned at the defaultk=10is much smaller than the complete indexed history:

- The vault is plaintext by design, not encrypted storage.AgentCairn redacts recognized credential patterns before its automated body/title/tag writes; unknown patterns and hand edits remain your responsibility.
- Cloud features are explicit egress.The default stays local. Opting into a cloud embedder or LLM judge sends the remaining redacted text to that provider.
- The project is beta.Standalone use requires Python 3.11+, and the first local model load can take time. The published retrieval evidence is strongest for conversational memory, not a universal code-search claim.
- Ambient behavior varies by host.The matrix above is intentional: Cursor and Antigravity rely on sweep capture; generic MCP hosts may expose tools without lifecycle hooks.
- Automation is platform-specific.Managed scheduling targets macOS launchd and Linux user crontab; use your own scheduler elsewhere.

uv sync uv run pre-commit install uv run pytest uv run ruff format . uv run ruff check --fix . uv run pre-commit run --all-files

Run the offline benchmark regression without API keys:

Agents Remember is a Drift-aware repository memory for coding agents in complex codebases. Captures what code can't say on its own! Retrieves memory by path, semantic search, and relationship (code-graph).

Self-hosted MCP server giving AI agents persistent memory — Markdown source of truth, hybrid BM25+embedding search, typed graph relations.

mem0-mcp-server — exposes Mem0 persistent semantic memory as an MCP HTTP server; supports add/search/read/update/delete operations and semantic search for agent memory.

Local-first second brain for Claude. Saves notes as Markdown and recalls them across sessions with offline semantic search, no cloud and no API keys.

Long-term memory system for AI agents with semantic search, context management, and multi-format storage.

A self-hosted, secure, feature-rich memory system for AI agents and assistants. Provides intelligent fact extraction and deduplication, with an artifact store for detailed content.

Local-first MCP memory server with no external dependency, source citations and OKF/Markdown KB.

Personal knowledge twin with semantic search. Store voice notes, documents, URLs, principles, and skills from any AI chat, then retrieve them with inline provenance citations. Hosted, multi-tenant, with per-user bearer-token auth and full data isolation.

Local-first MCP server for searching private Obsidian vaults with hybrid full-text, fuzzy, semantic, and wikilink graph retrieval.