AgentCairn

为 AI 编码代理提供跨项目长期记忆:以你自己的 Obsidian Markdown 库为唯一事实来源,本地运行、无守护进程、无遥测。

Star 数
★ 78
最近更新
1 天前
License
Apache-2.0
主语言
Python

30 秒速览

运行形态
Agent 插件 / 技能MCP 服务器命令行工具
可在哪里用
通用 · 跨平台Codex · Claude Code
费用
免费,无需付费服务
上手难度
低 · 几分钟可跑通
开始前需要
Python 3.11+(独立使用)uv / uvxShell / 命令行本地文件系统MCP Server
典型场景
使用多个编码代理(如 Claude Code 与 Codex)的开发者,希望它们共享同一个记忆库而不是各自孤立存储
不适合
  • 需要团队托管记忆服务或云端备份的用户
  • 把记忆当作加密存储、依赖强访问控制的场景
  • 需要跨所有编辑器一致环境记忆(部分主机仅靠 sweep 捕获)的团队
官网
agentcairn.dev ↗ 来自 GitHub 仓库设置
维护状态
近 30 天有提交最近提交 2026-11-19

这个 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 记忆。

  1. 使用多个编码代理(如 Claude Code 与 Codex)的开发者,希望它们共享同一个记忆库而不是各自孤立存储
  2. 希望长期积累项目事实(如『staging 部署采用蓝绿发布』)并在新会话中自动按项目召回的工程师
  3. 重视可审计性的用户:希望在 Obsidian 中直接查看每条记忆的来源、重要性、时效与被取代关系
  4. 需要把 Claude Code 自动记忆迁移到共享库的人,可用 cairn import claude-memory 导入并保留来源标注
  5. 关注上下文成本的团队:召回只返回相关片段(基准显示 LongMemEval-S 全量历史平均约 13.7 万 token,召回平均约 2207 token)

安装与配置要点

摘自下方的安装和使用说明,以项目 README 的最新说明为准。

安装 / 启动命令
  • npx skills add ccf/agentcairn --skill agentcairn-setup -g
  • uv tool install agentcairn
  • uvx --version
  • uvx agentcairn
配置文件
~/.agentcairn/config.toml
运行环境
Python 3.11+

如何安装或部署这个 Agent?

最快路径是官方插件。需先安装 uv(确保 uvx --version 可用)。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

或使用代理辅助安装(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?

FollowAgents 源码审查 · FARS-2.1
表现良好
89/ 100 五分制 4.5 / 5
信任安全 24/29
可靠稳定 12/14
适用触发 18/18
规范维护 16/18
有效结果 13/13
证据核验 6/8
查看各维度的扣分理由
信任安全24 / 29 · 4.1/5

证据充分: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)。

可靠稳定12 / 14 · 4.3/5

代码显示清晰分级降级:模型/提供商失败可见回退 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)。

适用触发18 / 18 · 5.0/5

受众(多宿主编码代理用户)、宿主矩阵(含 Cursor/Antigravity 依赖 sweep 的差异)、平台边界(macOS launchd / Linux cron、Shared-GID 说明、Python 3.11+、首载模型耗时)、技能触发描述('Use when…' 带具体条件)与能力边界(beta、检索证据限于会话记忆)都有具体文本支撑,环境适配最弱处也有明确交代,无扣分。

规范维护16 / 18 · 4.4/5

信息架构清晰(vault 为真源、index 可弃)、安装说明覆盖插件/CLI/uvx 各路径并警告 `uvx cairn` 是另一个包、命名决策锁定、限制章节诚实详尽、Apache-2.0 齐备且 SPDX 实践可见。扣分点:README 有示例与截图但无 FAQ(2);CHANGELOG 仅在发布仪式中被引用、文件未在包内出现(2);维护者是单人且发布者身份未经企业注册表验证,治理/更新路径依赖个人(2)。

有效结果13 / 13 · 5.0/5

输出可用性高:召回结果带 permalink、project 标注、validity 状态与 freshness 元数据;边际价值有检索消融基准(BM25→RRF→rerank)与上下文缩减表支撑,且明确说明这是检索召回而非问答准确率、非计费成本节省;成本收益(每 vault 全量加载 vs 局部召回)量化并诚实标注启发式近似,无扣分。

证据核验6 / 8 · 3.8/5

基准仓自述 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`。
证据充分度:低 评估于 2026年11月21日 审查版本 bb66c80ba2ae
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/agentcairn.svg?lang=zh)](https://followagents.com/zh/agents/agentcairn)
<a href="https://followagents.com/zh/agents/agentcairn"><img src="https://followagents.com/badge/agentcairn.svg?lang=zh" alt="FARS 评测"></a>

常见问题

数据会离开我的机器吗?
默认不会:FastEmbed 本地运行,MCP 用 stdio,无守护进程、无遥测。只有当你显式启用云嵌入(Voyage、OpenAI 兼容)或 Anthropic 评估器时,脱敏后的文本才会发送给该服务商。
删除或重建索引会丢数据吗?
不会。DuckDB 是派生缓存,Markdown 库才是规范记忆;重建失败时会保留上一个可用缓存,持久文件不受影响。
付费吗?
软件本身免费(Apache-2.0),默认本地嵌入无 API 费用。可选云功能(Voyage/OpenAI 兼容嵌入、Anthropic 评估器)需你自己的密钥并可能产生费用。
支持哪些代理,能力一致吗?
支持 Claude Code、Codex、Cursor、OpenCode、Hermes Agent、Antigravity、VS Code (Copilot)、Claude Desktop 及任意 MCP 主机,但环境记忆不一致:Claude Code/Codex/OpenCode/Hermes 有完整召回与捕获,Cursor/Antigravity 仅带外 sweep,通用 MCP 主机视宿主而定。
我编辑了 Markdown 笔记会怎样?
规范记忆就是 Markdown,手工编辑的事实会在下次协调读取时被采纳;历史是非丢失的,被取代或过期的笔记会降级保留、可审阅。
AgentCairn 官网是什么?
AgentCairn 的 GitHub 仓库填写的官网是 https://agentcairn.dev。这个链接由仓库作者设置;源码在 GitHub(ccf/agentcairn)。
AgentCairn 开源吗?
开源。源码在 GitHub(ccf/agentcairn),许可证是 Apache-2.0。
AgentCairn 安全吗?
FollowAgents 的 FARS 评审(2026年11月21日)给 AgentCairn 的“信任与安全”打了 24/29 分。评审检查的 8 项安全措施没有完全缺失的。
AgentCairn 还在维护吗?
在维护。GitHub 上最近一次提交是 2026-11-19,在最近 30 天内。
AgentCairn 是谁开发的?
AgentCairn 由 GitHub 账号 ccf 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

所属宿主生态

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念