agentcairn MCP Server

官方

本地优先的智能体记忆：以纯Markdown格式的Obsidian仓库作为数据源，配合可重建的DuckDB索引实现BM25混合检索、向量检索与图结构召回。

GitHub
1

文档

🪨 agentcairn

CI Security PyPI Python License: Apache-2.0

面向 AI 代理的本地优先记忆——你可以真正阅读、编辑并拥有它。

cairn  /kɛən/  · 名词 — 一堆石头，用来标记一条小径或一个值得记住的地方，留给后来者。

agentcairn 为你的编程代理提供持久、高质量的记忆——但不同于将其锁在不透明的数据库或云服务中，你的记忆以纯 Markdown 形式存在于你拥有的 Obsidian 仓库中。 一个快速、可重建的 DuckDB 索引位于其上用于检索。打开你的仓库，阅读代理记住的内容，手动修正错误事实，或放入你自己的笔记——代理会全部拾取。

agentcairn 有何不同

大多数代理记忆系统将数据库或云存储作为事实来源，并将文件（如果有的话）视为单向导出。agentcairn 则反其道而行之：

  • 📂 你的仓库是事实来源——而非导出结果。 记忆是人类可读的 Markdown，带有 frontmatter 和 [[wikilinks]]。在 Obsidian 中编辑它；索引会尊重你的编辑。
  • ♻️ 索引是可丢弃的。 DuckDB 是一个可重建的缓存（cairn reindex）。你的记忆在模型升级、索引损坏、模式变更或卸载工具后依然存在——零数据丢失，因为事实只是磁盘上的文件。
  • 🧠 构建即非有损。 完整笔记始终保留。提炼只会添加链接回源头的派生笔记——它永远不会在写入时悄悄丢弃它认为不需要提取的事实。
  • 🔒 每次写入前进行编辑。 在任何内容——正文、标题或标签——到达明文仓库之前，密钥都会被清除（正则表达式 + 熵 + URL 凭据检测）。我们写入你可以阅读的文件，因此我们将凭据泄露视为最严重的失败模式。
  • 🕸️ 一个免费、确定性的知识图谱。 你的 [[wikilinks]] 和 frontmatter 就是图谱——无需 LLM 提取，没有幻觉实体。
  • 🪶 无守护进程，零外部数据库。 一个嵌入式 DuckDB 文件即可进行语义向量搜索、BM25 全文搜索和图遍历。无需始终在线的服务器，无需 Neo4j/Postgres/Qdrant，无需必需的云密钥——只需一个 cairn CLI 和一个按需 MCP 服务器。
  • 🔍 诚实的测量。 一个可复现的 LongMemEval-S + LoCoMo 测试工具随附在 benchmarks/ 中——包含真实数据、消融实验和明确的注意事项，而非一个精心挑选的标题数字（见下文）。

安装

使用 agentcairn 最简单的方式是插件，适用于 Claude Code 或 Codex——一次安装即可连接 MCP 服务器、环境记忆（会话开始时回忆，会话结束时捕获）、一个记忆技能以及斜杠命令（Claude Code）：

# Claude Code
claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

# Codex (from the Codex plugin marketplace)
codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

安装时你选择一个仓库路径（默认 ~/agentcairn）；它会在首次会话时自动创建——无需设置 Obsidian。从那时起，agentcairn 会在每个会话开始时呈现相关记忆，将每个会话提炼到你的仓库中，并为你提供 /agentcairn:recall、/remember、/memory、/savings 和 /ingest。无需 pip 安装——插件通过 uvx 运行已发布的包。

不在 Claude Code 或 Codex 上？agentcairn 也是一个独立的 MCP 服务器 + CLI，适用于任何主机——参见直接使用。

工作原理

flowchart LR
    T["Session transcripts<br/>(out-of-band)"]
    H["You · Obsidian<br/>(hand edits)"]
    V["📂 Obsidian vault<br/>Markdown + frontmatter + wikilinks<br/><b>source of truth</b>"]
    I["♻️ DuckDB index<br/>vector + BM25 + graph<br/><b>rebuildable cache</b>"]
    M["MCP tools<br/>remember · recall · search · build_context · recent"]

    T -- "redact → judge → distill → consolidate" --> V
    H -- "edit" --> V
    V -- "parse / reconcile-on-spawn" --> I
    I -- "READ_ONLY hybrid recall" --> M
    M -. "remember (redacted write)" .-> V

    classDef truth fill:#eaf1ff,stroke:#317cff,color:#191919;
    classDef cache fill:#f5f5f3,stroke:#999999,color:#191919;
    class V truth
    class I cache
  • 捕获 以带外方式读取你的代理工具会话记录（仅追加，已在磁盘上）——设计上具有鲁棒性，没有脆弱的实时钩子——然后进行编辑 → 去重 → 判断（语义持久性；通过 CAIRN_JUDGE=anthropic 进行可选的 LLM 提炼）→ 门控 → 非有损地提炼到仓库中。cairn sweep 自动检测每个存在的工具（Claude Code、Codex、Antigravity CLI 和 Cursor 均受支持，位于 HarnessAdapter 接缝之后），因此你无需任何额外配置即可在所有四个工具中获得统一记忆。在 LLM 层级，它还会整合：与现有记忆重复的新记忆会被跳过，而一个不断演变的事实的较新版本会将旧笔记标记为 superseded_by（在回忆中保留但降级，永不删除）——具有故障保护，因此错误的调用永远不会丢弃一个独特的记忆（CAIRN_CONSOLIDATE=0 可禁用）。此外，还有一个代理驱动的 remember 工具，用于策划高价值记忆。
  • 检索 将 BM25 + 语义向量与倒数排名融合相结合，应用可选的图谱增强，并在没有嵌入模型可用时优雅降级为仅关键词模式——因此回忆永远不会悄然失效。一个可选的交叉编码器重排序器可增加精确度。
  • 混合智能： 开箱即用的离线本地嵌入（默认 FastEmbed / nomic-embed-text-v1.5）——自身表现强劲，并且在混合融合中（使用 nomic，即使在短轮次上，纯向量也略胜 BM25；参见基准测试）。设置 CAIRN_EMBED_MODEL 以选择另一个 FastEmbed 模型，或运行 CAIRN_EMBEDDER=ollama / 云层级以更进一步。
  • 时间记忆： 笔记可能带有 valid_from/valid_until/superseded_by frontmatter。回忆具有有效性感知——它会软降级被取代和已过期的事实（当前事实胜出），而从不隐藏它们（非有损），并注释每个结果的状态（current/superseded/expired/not_yet_valid）以及一个 as_of 锚点，以便代理可以随时间推理。对于没有有效性字段的笔记，此功能无效。
  • 来源感知回忆： 笔记带有 project/harness 来源，回忆会提升你当前项目的记忆（非有损——跨项目命中结果仍会显示，标记为 [from: <project>]）。传递 --project <repo> 以针对另一个仓库，或 --scope project 以硬过滤仅当前项目。

直接使用

插件是最简单的途径，但 agentcairn 只是一个包——通过按需 MCP 服务器（适用于任何 MCP 主机）或 cairn CLI 在没有 Claude Code 的情况下使用它：

uvx agentcairn                                       # on-demand MCP server for any MCP host
cairn ingest --vault ~/vault                         # distill recent agent sessions into the vault
cairn sweep  --vault ~/vault                          # ingest + reindex in one pass (cron-friendly)
cairn schedule install --vault ~/vault                # run sweep automatically every 30 min (launchd on macOS, crontab on Linux)
cairn recall "how did we fix the auth bug?"          # hybrid recall from the CLI
cairn savings                                        # how much context recall has saved you
cairn reindex ~/vault                                # rebuild the index from Markdown (always safe)
cairn doctor                                         # health-check the index

配置

所有设置都位于一个文件中——~/.agentcairn/config.toml——环境变量作为覆盖（优先级：CLI 标志 > 环境变量 > 配置文件 > 默认值）：

cairn config --init   # scaffold a fully-commented template (chmod 600)
cairn config          # show every setting's effective value and where it came from

例如，启用 LLM 记忆判断器只需取消两行注释——无需 shell 导出（插件的后台扫描直接读取文件）：

judge = "anthropic"
anthropic_api_key = "sk-ant-..."

支持的代理

agentcairn 在两个层面上工作。插件主机（Claude Code、Codex 和 Antigravity）获得一流的插件——一个捆绑的 MCP 服务器（回忆/搜索/remember）、一个记忆技能，以及（在 Claude Code 和 Codex 上）环境会话钩子；cairn install <host> 通过调用主机自身的 CLI 来安装插件。MCP 主机（其他所有）通过便携式 MCP 服务器获得相同的回忆/搜索/remember 工具；cairn install <host> 以非破坏性方式写入 MCP 服务器配置（你的其他服务器被保留，原始文件备份到 <config>.bak）。仓库保持一个单一的全局 ~/agentcairn，因此记忆在所有主机之间共享。

主机支持设置方式环境捕获
Claude Code🟢 插件cairn install claude-code✅ 开始时回忆 + 结束时捕获
Codex🟢 插件cairn install codex◐ 回忆/remember 实时；环境钩子已捆绑（验证中） 1
Cursor🔌 MCP 服务器 + 技能 + 摄取cairn install cursor◐ cairn sweep 自动检测记录 2
Claude Desktop🔌 MCP 服务器cairn install claude-desktop—
VS Code (Copilot)🔌 MCP 服务器cairn install vscode—
Gemini CLI 3🔌 MCP 服务器cairn install gemini—
Antigravity🟢 插件 + 摄取cairn install antigravity◐ cairn sweep 自动检测记录 4
任何其他 MCP 主机🔌 MCP 服务器uvx agentcairn（粘贴 cairn install … --print 代码片段）—

cairn install 按主机类型自动路由：

cairn install                 # detect installed hosts + preview (writes nothing)
cairn install codex           # install the Codex plugin (shells to `codex plugin …`; strips any stale MCP block from ~/.codex/config.toml)
cairn install antigravity --source ./plugin  # install the Antigravity plugin from a local checkout (see note)
cairn install cursor          # write MCP config + install the memory skill for Cursor
cairn install --all           # configure every detected host
cairn install codex --source /path/to/agentcairn  # use a local checkout instead of the marketplace

MCP 主机采用 JSON mcpServers 条目（VS Code 使用其 servers 键）。插件主机（Claude Code、Codex、Antigravity）通过主机 CLI 安装插件——MCP 服务器捆绑在插件中，不需要单独的配置条目。如果你之前使用 cairn install antigravity 将 MCP 条目写入 ~/.gemini/config/mcp_config.json，重新运行 cairn install antigravity 会自动移除该过时条目。

基准测试测量

我们以我们希望记忆系统被测量的方式对 agentcairn 进行基准测试——可复现、包含消融实验，且没有单一精心挑选的标题数字。 测试工具（benchmarks/）通过版本固定的下载器运行 LongMemEval-S 和 LoCoMo（数据集从不捆绑），确定性地对检索进行评分（recall/nDCG@k, MRR——无需 API 密钥，在 CI 中使用合成夹具运行），并提供一个可选的 LLM 判断 QA 层。

检索 — LoCoMo

完整 LoCoMo 集，轮次级，宏平均，FastEmbed nomic-embed-text-v1.5（默认嵌入器）：

方案recall@5recall@10MRR
仅 BM250.5270.6040.459
仅向量0.5360.6370.433
混合 (RRF)0.5620.6480.477
混合 + 图谱增强0.5620.6480.477
混合 + 重排序器0.6620.7350.608

我们从中解读到的——并公开说明：

  • 混合方案优于任一单独方案——RRF 融合是值得的。
  • 交叉编码器重排序器是最大的杠杆（相比混合方案，recall@5 提升 +0.10）；“ms-marco 领域偏移可能有害”的担忧在对话数据上并未出现。
  • 嵌入器默认值现在发挥了作用——使用 nomic，纯向量略胜 BM25（0.536 vs 0.527）；从旧的 bge-small 默认值（落后于 0.483）切换过来弥补了差距。一个 5 模型 FastEmbed 扫描确定了选择——nomic（768 维）在每维质量上胜出；更大的 1024 维模型并未超越它。完整表格：benchmarks/README.md。
  • 图谱增强在这些语料库上无效——LoCoMo/LongMemEval 没有原生的 [[wikilink]] 图谱，因此增强没有可作用的对象。它适用于真正相互链接的仓库，而非聊天日志，我们不会假装不是这样。

检索 — LongMemEval-S

完整 500 实例集 — 这是一个更简单的任务，证据会话之间区分明显。会话级别是先前工作报告的粒度；轮次级则是更细粒度、更能揭示语料库特征的切片：

方案会话 r@5会话 MRR轮次 r@5轮次 r@10轮次 MRR
仅 BM250.9200.9180.6800.7910.638
仅向量0.9360.9160.5070.6920.454
混合 (RRF)0.9540.9380.6400.7980.544
混合 + 重排序器0.9690.9630.7880.8910.716

如实解读：

  • 我们的 0.969 会话 recall@5 与先前工作在相同完整 500 问题集上的 ≈0.95 水平相当 — 并且在完整规模下，它表现出区分度（从 BM25 的 0.920 到重排序器的 0.969），而不是像小样本那样趋于饱和。
  • 重排序器再次成为最大的提升杠杆 — 轮次 r@5 从 0.640 提升至 0.788，会话 r@5 从 0.954 提升至 0.969。
  • 轮次级指标揭示了语料库特征： 在此数据集上，仅 BM25（0.680）优于 RRF 混合方案（0.640），因为纯向量方案在这些单轮证据片段上表现较弱（0.507）；是重排序器将默认方案拉到了前面。（对比 LoCoMo，纯向量方案略优于 BM25。）

上下文效率

agentcairn 召回的上下文比原本需要传入模型的完整历史记录小多少？默认配置（混合 + 重排序器，k=10）：

数据集查询数平均草堆大小平均召回大小 (k=10)上下文缩减比例
LoCoMo (3 段对话)49725,646 tok529 tok均值 51.1 倍 / 中位数 50.3 倍
LongMemEval-S (完整 500)470136,552 tok2,207 tok均值 64.7 倍 / 中位数 61.6 倍

估算值（约 4 字符/token），非计费成本；“草堆” = 完整索引历史记录，“召回” = 返回的 top-k 文本块。它衡量的是上下文大小，与检索质量无关。

QA 准确率

QA 准确率数据（由 LLM 评判）也已提供，但使用的是 Anthropic 评判器，而非论文中的 GPT-4o，因此无法与已发布的排行榜进行比较 — 仅对内部消融实验信号有效。关于如何运行及解读这些数据，请参阅 benchmarks/README.md。

路线图

  • v1 — 已完成。 核心循环：对话记录摄取 → 脱敏 → Markdown → 可重建的 DuckDB 索引 → 混合召回；MCP 服务器 + CLI；秘密信息脱敏；本地嵌入；可复现的基准测试工具。
  • v1.1 — 下一步，根据上述基准测试确定优先级：
    • ✅ 默认启用重排序器 — 实测最大的检索提升杠杆；可通过 CAIRN_RERANK=0 禁用。（已发布）
    • Ollama 嵌入层 — ✅ 通过 CAIRN_EMBEDDER=ollama 使用本地模型（CAIRN_EMBED_MODEL/OLLAMA_HOST）；云端方案（OpenAI/Voyage）仍待完成。
    • ✅ 双时态有效性 — 前置元数据 valid_from/valid_until/superseded_by；召回时软降级已取代/已过期的事实（非破坏性 — 从不隐藏），并标注每个结果的时效性及 as_of 锚点，使当前事实胜出，智能体可基于时间进行推理。（已发布）
    • 针对大型知识库检索延迟的内存 HNSW 方案。
  • v2 — ◐ Obsidian 插件（agentcairn-obsidian）— 一个知识库原生的记忆视图（列表 + 来源 + 时效性 + 图谱），用于在 Obsidian 中阅读/导航你的记忆；（MVP 已发布；语义召回仍保留在 CLI/MCP 中）。MotherDuck 云同步、可选的 LLM 实体提取仍待完成。

开发

agentcairn 专门使用 uv 进行依赖管理和工具链操作。

请勿使用 pip、poetry 或全局虚拟环境。

# First-time setup
uv sync                         # create .venv and install all deps (including dev)
uv run pre-commit install       # install git hooks (ruff + pytest run on every commit)

# Daily use
uv run pytest                   # run the test suite
uv run cairn --help             # run the CLI
uvx agentcairn                  # run the installed tool ephemerally (as the MCP server does)

# Formatting and linting
uv run ruff format .            # format all Python files
uv run ruff check --fix .       # lint with auto-fix
uv run pre-commit run --all-files

# Benchmarks (offline retrieval metrics need no API key)
uv run pytest benchmarks/tests/                                      # offline synthetic-fixture suite
PYTHONPATH=benchmarks uv run --group bench python -m cairn_bench.run --dataset locomo

MCP 服务器通过 uvx agentcairn 启动 — 无需全局安装。

许可证

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

Footnotes

  1. The Codex 插件安装及其捆绑的 MCP 服务器（回忆/搜索/remember）已在 Codex 中实时验证。环境会话钩子（开始时回忆，结束时捕获）随插件提供并使用 Codex 记录的钩子模式，但其在 Codex 上的端到端行为尚未确认；无论如何，捕获也会通过 cairn sweep 以带外方式进行。 ↩

  2. Cursor 没有插件钩子，因此环境捕获通过 cairn sweep 以带外方式进行（来源：Cursor 的全局 globalStorage/state.vscdb SQLite 数据库，cursorDiskKV 表，用户 "bubbles"）。Cursor 作为输出端的 MCP 主机（cairn install cursor → ~/.cursor/mcp.json）；没有 Cursor 插件。cairn install cursor 还将 using-agentcairn-memory 技能（回忆/记忆指导）安装到 ~/.cursor/skills/using-agentcairn-memory/SKILL.md。 ↩

  3. Gemini CLI（消费者）记录摄取不受支持——Google 正在淘汰 Gemini CLI（消费者截止日期 2026-06-18），转而支持 Antigravity CLI，agentcairn 改为摄取后者。cairn install gemini（MCP 服务器连接）对于任何支持 MCP 的基于 Gemini 的主机仍然有效。 ↩

  4. The Antigravity 插件捆绑了 MCP 服务器 + 记忆技能；cairn install antigravity --source <dir> 通过 agy plugin install 安装它，并从 ~/.gemini/config/mcp_config.json 中移除任何过时的 mcpServers.agentcairn 条目。注意：agy plugin install 接受本地目录或已注册的市场（而非 git 仓库），因此目前将 --source 指向克隆检出的 plugin/ 目录。Antigravity 没有公认的插件钩子，因此环境捕获通过 cairn sweep 以带外方式进行（路径：~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript.jsonl）。 ↩