agentcairn

在受支持的编码代理之间实现持久记忆。
你的 Markdown 仓库是权威来源。DuckDB 是可替换的检索缓存。

网站 · PyPI · Obsidian 伴侣 · 基准测试

石堆为后来者标记路径。agentcairn 为编码代理做到了这一点：它从你使用的工具中捕获持久上下文，将其存储为带有溯源的可检查 Markdown，并在另一个代理需要时仅召回最相关的片段。

可检查的证明

记忆并非隐藏在管理控制台或托管数据库之后。独立的 agentcairn-obsidian 伴侣读取与代理相同的 Markdown 文件，并暴露溯源、时效性、重要性、取代关系以及 related: 链接。

_{Obsidian 中的真实 agentcairn 仓库。列表是对文件的视图——而非第二个记忆存储。}

自用快照 · 2026-07-15。 在 417 次本地召回中，维护者的仓库返回的上下文比每次加载完整仓库少 262× smaller——估计总计减少 136.6M tokens of full-vault context avoided。Token 计数使用大约每四个字符一个 token 的估算。这不是计费 token 节省，且 agentcairn 不发送任何遥测数据。

安装

最短路径是使用一等插件。它捆绑了 MCP 服务器、记忆技能和主机特定的环境钩子——无需单独安装 agentcairn 包。插件通过 uvx 启动，因此如果 uvx --version 尚不可用，请先安装 uv。

Claude Code

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

Claude Code 获得每轮项目范围的召回、会话/压缩捕获，以及 /agentcairn:recall、/agentcairn:remember、/agentcairn:memory、/agentcairn:savings 和 /agentcairn:ingest 命令。

Codex

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

Codex 获得捆绑的 MCP 工具和记忆技能、实时验证的 SessionStart 召回，以及以 cairn sweep 作为带外后备的 SessionEnd 捕获。

代理辅助设置

已经在使用 skills.sh 或 find-skills 工作流？安装公开的设置助手：

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

然后询问你的代理：Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

这仅安装设置指南——而非 AgentCairn 运行时、MCP 服务器、插件或钩子。助手将这些更改委托给 AgentCairn 的预览优先原生安装器，并验证生成的集成。上述 Claude Code 和 Codex 插件命令仍是最短路径。

默认仓库位于 ~/agentcairn，并在首次使用时创建。新的空仓库还没有可召回的有用内容，因此请显式验证整个循环：

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>

remember 同时写入 Markdown 笔记和索引条目，因此即时召回是契约的一部分。首次本地运行可能会下载并预热配置的嵌入/重排序模型。

契约

工作原理

• 捕获： 主机钩子提高即时性；cairn sweep 带外读取受支持的转录存储作为持久后备。AgentCairn 在自动明文写入前会编辑已识别的凭据、去重、重要性门控和提炼。
• 协调： 首次读取以事务方式将仓库范围的索引与 Markdown 同步。失败的重建保留最后良好的缓存，持久文件不受影响。
• 召回： BM25 和语义向量通过 Reciprocal Rank Fusion 融合，然后可选地重排序。模型/提供者失败时，会以诊断信息可见地回退到 BM25，而非返回不兼容的向量。
• 记忆： MCP 工具在单个写入锁下原子地写入 Markdown 笔记并更新索引，使成功保存立即可召回。

为信任而设计

• 默认本地。 FastEmbed 在本地运行，MCP 服务器使用 stdio，无需守护进程或外部数据库，且无遥测。
• 清晰边界。 同步的仓库包含 Markdown；默认情况下，可重建的 .duckdb 索引保留在仓库之外。逃逸配置根目录的仓库符号链接会被拒绝。
• 时间感知修正。 valid_from、valid_until 和 superseded_by 使旧证据保持可见，同时让当前事实排名靠前。
• 确定性图。 [[wikilinks]] 和可选的 cairn link 邻居创建 Obsidian 原生图，无需让 LLM 发明实体。
• 项目感知召回。 当前项目默认被提升；跨项目结果仍可用并被标记。自动召回是项目范围的，除非你显式选择所有项目。

受支持的代理

每个主机解析同一配置的仓库。cairn install 预览检测到的主机而不写入。MCP 配置写入是备份优先的，并保留无关服务器；插件主机安装委托给主机自身的 CLI。

Codex SessionStart 已使用 agentcairn 0.24.2 / 插件 0.1.2 进行端到端实时验证。安装的 SessionEnd 命令分发和分离清扫通过精确处理程序探测；cairn sweep 仍是带外捕获后备。参见 OpenCode 集成 和 Hermes 集成 了解其原生生命周期细节。

直接使用

插件是最简单的途径，但 agentcairn 也是独立的 CLI 和按需 MCP 服务器。独立安装需要 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

随身携带 Claude Code 的记忆

Claude Code 的自动记忆可以播种共享仓库，而无需更改其源文件。该命令默认仅预览当前仓库；添加 --apply 以写入已编辑的笔记并刷新索引。

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

单向导入读取 MEMORY.md 及其主题 Markdown 文件——绝不读取 CLAUDE.md 或 .claude/rules/。导入的笔记保留 Claude Code、项目和源文件溯源。当源更改时，先前版本保持可检查但被取代；当源消失时，其导入版本过期。一个小型 .agentcairn/native-memory/ 注册表保留该生命周期，而不会对源内容进行两次索引。使用 --source <dir> 指定自定义、托管或会话覆盖的 Claude 记忆目录，或在批量导入时使用 --no-reindex。

偏好临时进程：

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

cairn config --init
cairn config

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

实测基准

仓库附带一个修订固定的、可复现的 LongMemEval-S + LoCoMo 测试框架。默认是本地 nomic-embed-text-v1.5 加交叉编码器重排序器。

在默认 k=10 下返回的上下文远小于完整索引历史：

诚实地解读这些数字：

• 检索召回不是 QA 准确率。这些表格比较的是受控检索臂，而非最终用户答案质量或其他产品的排行榜分数。
• Token 计数使用大约每四个字符一个 token 的启发式。缩减比较的是索引的干草堆与返回的块；这不是计费成本节省。
• 图增强在这些聊天语料上是惰性的，因为它们不包含原生 [[wikilink]] 图。它是为真实互链仓库设计的。
• 可选的 QA 评判器使用 Anthropic 而非论文中的 GPT-4o 设置，因此这些 QA 结果适用于相对消融——而非已发布排行榜比较。

完整指标、嵌入扫描、延迟测量、许可证、命令和注意事项位于 benchmarks/README.md。

隐私和限制

• 保险库默认是明文设计，而非加密存储。 AgentCairn 在自动写入正文/标题/标签前会识别并脱敏常见凭据模式；未知模式及手动编辑的内容由您自行负责。
• 保险库文件仅限所有者访问（0600/0700）。 由于保险库为明文且脱敏为尽力而为，文件权限实际上是其唯一的访问控制。共享组 ID 的环境（例如两个 Docker 容器属于同一组但 UID 不同）需要组访问权限，因此 vault_group_writable = true 会将新建的保险库笔记和目录放宽为 0660/0770。这是有意为之的选配项：在 macOS 上，每个本地用户的主组都是 staff，因此默认组可读会让机器上的其他账户看到您的记忆。该开关绝不会放宽保险库之外的任何内容——索引、账本、锁文件和 ~/.agentcairn/config.toml 保持私有。
• 云功能是显式外发。 默认保持本地运行。选择使用云嵌入器或 LLM 评判器会将剩余的脱敏文本发送给相应提供商。
• 项目处于测试阶段。 独立使用需要 Python 3.11 及以上版本，首次加载本地模型可能需要一些时间。已发布的检索证据最适用于对话记忆，而非通用代码搜索的声明。
• 环境行为因主机而异。 上述矩阵是有意设计的：Cursor 和 Antigravity 依赖扫描捕获；通用 MCP 主机可能暴露工具而无生命周期钩子。
• 自动化因平台而异。 托管调度面向 macOS launchd 和 Linux 用户 crontab；其他环境请使用您自己的调度器。

开发

agentcairn 仅使用 uv 进行依赖管理和工具链。

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

无需 API 密钥即可运行离线基准回归测试：

uv run pytest benchmarks/tests/

许可证

Apache License 2.0 — 宽松许可，附带明确的专利授权。版权所有 © 2026 Charles C. Figueiredo。