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 和语义向量通过倒数排名融合进行融合，然后可选地进行重排序。模型/提供商的失败会明显地回退到 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/ 注册表保留了该生命周期，而无需对源内容进行两次索引。对于自定义、托管或会话覆盖的 Claude 记忆目录，请使用 --source <dir>，或在批量导入时使用 --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 下返回的上下文比完整的索引历史小得多：

诚实地解读这些数字：

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

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

隐私和限制

• 保险库本质上是明文设计，而非加密存储。 AgentCairn 在自动写入正文/标题/标签之前，会编辑掉识别出的凭据模式；未知模式及手动编辑的内容仍需您自行负责。
• 云端功能属于显式数据出口。 默认保持本地运行。若选择启用云端嵌入器或 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 许可证 2.0 — 宽松型许可证，包含明确的专利授权。版权所有 © 2026 Charles C. Figueiredo。