AgentCairn
为 AI 编码代理提供跨项目长期记忆:以你自己的 Obsidian Markdown 库为唯一事实来源,本地运行、无守护进程、无遥测。
- Star 数
- ★ 78
- 最近更新
- 1 天前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 89/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 免费,无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 使用多个编码代理(如 Claude Code 与 Codex)的开发者,希望它们共享同一个记忆库而不是各自孤立存储
- 不适合
- 需要团队托管记忆服务或云端备份的用户
- 把记忆当作加密存储、依赖强访问控制的场景
- 需要跨所有编辑器一致环境记忆(部分主机仅靠 sweep 捕获)的团队
- 官网
- agentcairn.dev ↗ 来自 GitHub 仓库设置
- 维护状态
- 近 30 天有提交最近提交 2026-11-19
- 源码审查
- 89/100 · 表现良好
这个 Agent 能做什么,适合哪些场景?
AgentCairn 是一个 Apache-2.0 开源项目,为 Claude Code、Codex、Cursor、OpenCode、Hermes Agent 等编码代理提供统一的长期记忆。它把代理捕获的持久上下文写入人类可读的 Markdown 笔记(含 frontmatter 和 [[wikilinks]]),这些文件即规范记忆;DuckDB 只是一个可随时删除重建的检索缓存。召回通过 MCP server 或 cairn CLI 完成,采用 BM25 与语义向量融合(RRF)并可选用重排序模型,默认使用本地 FastEmbed 的 nomic-embed-text-v1.5,无需守护进程或外部数据库,也没有遥测。项目处于 beta 阶段,独立使用需 Python 3.11+,配套的 agentcairn-obsidian 插件让你在 Obsidian 中直接审阅记忆的来源、时效与被取代关系。
捕获:通过主机钩子(如 Claude Code 的 SessionEnd/PreCompact、Codex 的 SessionEnd)即时采集上下文,cairn sweep 作为带外兜底读取受支持的会话记录;写入前进行凭据识别脱敏、去重、重要性过滤和蒸馏。记忆(remember):在一个写锁下原子地写入 Markdown 笔记并更新 DuckDB 索引,保证成功保存即可被召回。协调(reconcile):首次读取时事务性同步索引与 Markdown,重建失败时保留上一个可用缓存。召回(recall):BM25 + 语义向量经 Reciprocal Rank Fusion 融合,可选用重排序;模型故障时可见地回退到 BM25 并输出诊断。结果附带项目、有效性状态和 permalink;时间字段 valid_from/valid_until/superseded_by 让旧证据可见且被降级而非删除。还可通过 cairn import claude-memory 单向导入 Claude Code 的 MEMORY.md 记忆。
- 使用多个编码代理(如 Claude Code 与 Codex)的开发者,希望它们共享同一个记忆库而不是各自孤立存储
- 希望长期积累项目事实(如『staging 部署采用蓝绿发布』)并在新会话中自动按项目召回的工程师
- 重视可审计性的用户:希望在 Obsidian 中直接查看每条记忆的来源、重要性、时效与被取代关系
- 需要把 Claude Code 自动记忆迁移到共享库的人,可用 cairn import claude-memory 导入并保留来源标注
- 关注上下文成本的团队:召回只返回相关片段(基准显示 LongMemEval-S 全量历史平均约 13.7 万 token,召回平均约 2207 token)
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
npx skills add ccf/agentcairn --skill agentcairn-setup -guv tool install agentcairnuvx --versionuvx agentcairn
- 配置文件
~/.agentcairn/config.toml- 运行环境
- Python 3.11+
如何安装或部署这个 Agent?
最快路径是官方插件。需先安装 uv(确保 uvx --version 可用)。Claude Code:
claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairnCodex:
codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn或使用代理辅助安装(skills.sh 工作流):
npx skills add ccf/agentcairn --skill agentcairn-setup -g独立安装需要 Python 3.11+:
uv tool install agentcairn默认库为 ~/agentcairn,首次使用时自动创建;首次本地运行会下载并预热配置的嵌入/重排序模型。
如何使用这个 Agent?
先验证完整回路:对代理说『Remember this durable fact: staging deploys use blue-green.』,再说『Recall the staging deploy strategy.』,应返回该事实和记忆 permalink。CLI 独立使用:
cairn init ~/agentcairn
cairn sweep --vault ~/agentcairn
cairn recall "how did we fix the auth bug?" --vault ~/agentcairn
cairn doctor --vault ~/agentcairn导入 Claude Code 原生记忆:
cairn import claude-memory # 预览,不写入
cairn import claude-memory --apply # 实际导入维护命令:
cairn reindex ~/agentcairn # 重建可丢弃缓存
cairn savings # 本地上下文效率估算
cairn link --vault ~/agentcairn # 写入确定性 related: 邻居配置位于 ~/.agentcairn/config.toml,可设置 auto_recall、auto_recall_k、auto_recall_scope(默认 "project",跨项目需显式 opt-in 为 "all")。MCP 按需运行:uvx agentcairn。
这个 Agent 有哪些优点和局限?
- Markdown 是规范记忆、DuckDB 索引可随时删除重建,记忆完全归属用户且可手工编辑,无黑盒数据库
- 一个库跨 Claude Code、Codex、Cursor、OpenCode、Hermes 等主机共享,避免按工具孤立记忆
- 默认全本地:FastEmbed 本地嵌入、MCP 走 stdio、无守护进程、无遥测,且凭据识别脱敏、文件权限 0600/0700
- 有修订固定的 LongMemEval-S + LoMo 基准与 dogfood 数据(417 次召回平均比全库小 262 倍),证据可复现
- 项目处于 beta,独立使用需 Python 3.11+,首次本地模型加载可能耗时
- 环境记忆能力因主机而异:Cursor 和 Antigravity 仅有带外 sweep 捕获,无逐轮召回
- 库是明文设计而非加密存储,脱敏只覆盖已知模式,未知模式与手工编辑的安全由用户负责
- 启用可选云嵌入(Voyage、OpenAI 兼容)或 Anthropic 评估器时,脱敏后的文本会离开本机,可能产生延迟或 API 成本
- 调度自动化仅针对 macOS launchd 和 Linux 用户 crontab,其他系统需自备调度器
这个 Agent 与同类方案有什么区别?
README 将其定位为『不像托管数据库或管理控制台那样隐藏记忆』的本地方案,并与 Claude Code 自带的原生记忆(MEMORY.md)形成导入关系,但没有点名具体竞品进行对比。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| AgentCairn 当前 | 89 · 表现良好 | Agent 插件 / 技能免费 | ★ 78 | 1 天前 | Python | Codex · Claude Code |
| Ruflo 智能体编排平台 | 48 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 82k | 今天 | TypeScript | Codex · Claude Code · OpenAI API |
| Emulo | 76 · 表现良好 | Agent 插件 / 技能免费 + 模型费 | ★ 306 | 1 个月前 | HTML | Codex · Claude Code |
| XERJ | 65 · 存在缺口 | 命令行工具免费 | ★ 19k | 1 天前 | Rust | Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
证据充分:MCP 以 READ_ONLY 打开 DuckDB、唯一写入者锁、拒绝逃逸 vault 根的符号链接、vault 文件 0600/0700;安装全部 preview-first(cairn install 默认只预览、--print 不落盘、import 需显式 --apply、技能明确要求用户批准才写测试记忆),凭证遮蔽先于写入,云端嵌入/评审为显式选择加入且声明无遥测,出处(project/harness/permalink)写入 frontmatter。扣分点:redaction 自述 best-effort、明文存储依赖文件权限作唯一访问控制(敏感数据处理 2);Trivy 扫描与依赖上界(mcp<2.0.0 注释)有体现但未见漏洞处置记录(依赖安全 2);写入宿主 MCP 配置虽备份优先、合并保真,但未见的 remove/uninstall 完整性不可确认(外部影响 2、回滚 2——.bak 备份、可重建索引、schedule uninstall 存在,但 MCP 配置移除在计划中标为 out of scope)。
代码显示清晰分级降级:模型/提供商失败可见回退 BM25、VaultBusyError 以 EX_TEMPFAIL(75) 退出、startup reconcile 区分 writer_busy/reader_busy/reconcile_failed 并带 freshness 状态返回;malformed 配置不 clobber、警告一次。扣分点:CLAUDE.md 记 0.10.1(2026-06-13)而 README 引 0.24.2,两份文档快照不同步,存在内部一致性漂移(2 而非 3)。
受众(多宿主编码代理用户)、宿主矩阵(含 Cursor/Antigravity 依赖 sweep 的差异)、平台边界(macOS launchd / Linux cron、Shared-GID 说明、Python 3.11+、首载模型耗时)、技能触发描述('Use when…' 带具体条件)与能力边界(beta、检索证据限于会话记忆)都有具体文本支撑,环境适配最弱处也有明确交代,无扣分。
信息架构清晰(vault 为真源、index 可弃)、安装说明覆盖插件/CLI/uvx 各路径并警告 `uvx cairn` 是另一个包、命名决策锁定、限制章节诚实详尽、Apache-2.0 齐备且 SPDX 实践可见。扣分点:README 有示例与截图但无 FAQ(2);CHANGELOG 仅在发布仪式中被引用、文件未在包内出现(2);维护者是单人且发布者身份未经企业注册表验证,治理/更新路径依赖个人(2)。
输出可用性高:召回结果带 permalink、project 标注、validity 状态与 freshness 元数据;边际价值有检索消融基准(BM25→RRF→rerank)与上下文缩减表支撑,且明确说明这是检索召回而非问答准确率、非计费成本节省;成本收益(每 vault 全量加载 vs 局部召回)量化并诚实标注启发式近似,无扣分。
基准仓自述 revision-pinned 且 CI 跑离线基准回归、CLAUDE.md 明令不做单一头条数字对比;规格/计划/代码/测试在 install、config、写者语义上互相印证;事实与推断分离出色('Read the numbers honestly' 章节)。扣分点:dogfood 快照(417 次召回、136.6M tokens)不可复现且为自报(claim traceability 2);基准数字均为自我测量、未与第三方独立结果对照(2)。
- Vault 为明文 Markdown,凭证遮蔽仅为模式匹配且自认 best-effort:未知格式的密钥、手工编辑内容不会被遮蔽,文件权限是唯一访问控制;共享机器上须谨慎,慎用 vault_group_writable。
- 启用云端嵌入或 Anthropic 评审后,遮蔽后的笔记内容与查询会离开本机,属于显式数据出境,需自行评估。
- cairn install 会修改各宿主 MCP 配置(备份为 .bak),但 v1 未提供卸载/移除命令;回滚需手工恢复备份。
- 自报性能数字(含 dogfood 快照与基准表)未经第三方验证,且 token 计数用 ~4 字符/token 启发式,不是计费成本。
- 发布者身份未经 FollowAgents 企业注册表验证,项目为单人维护的 beta,升级与响应速度取决于个人。
- 不要运行 `uvx cairn`,那是另一个同名包;应使用 `uvx --from agentcairn cairn`。
常见问题
数据会离开我的机器吗?
删除或重建索引会丢数据吗?
付费吗?
支持哪些代理,能力一致吗?
我编辑了 Markdown 笔记会怎样?
AgentCairn 官网是什么?
AgentCairn 开源吗?
AgentCairn 安全吗?
AgentCairn 还在维护吗?
AgentCairn 是谁开发的?
谢谢反馈,我们会据此改进页面。