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 + 語義向量與 Reciprocal Rank Fusion 融合，套用可選的圖譜增強，並在沒有嵌入模型可用時優雅降級到僅限關鍵字——因此回想功能永遠不會悄然失效。一個可選的跨編碼器重新排序器則能增加精確度。
  • 混合智慧： 開箱即用離線本地嵌入（預設為 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 判斷問答層。

檢索 — 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）：

資料集查詢數平均 haystack平均召回 (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），非計費成本；"haystack" = 完整索引歷史，"recalled" = 回傳的前 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）。 ↩