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 和語意向量透過 Reciprocal Rank Fusion 融合，然後可選地重新排序。模型/提供者失敗時，會明顯地回退到帶有診斷資訊的 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/ 註冊表保留了該生命週期，而不會對來源內容進行兩次索引。使用 --source <dir> 指定自訂、受管理或會話覆寫的 Claude 記憶目錄，或在批次匯入時使用 --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 下返回的上下文遠小於完整的索引歷史：

誠實地解讀這些數字：

• 檢索召回並非 QA 準確度。這些表格比較的是受控的檢索分支，而非最終使用者的答案品質或其他產品的排行榜分數。
• Token 計數使用約每四個字元一個 token 的啟發式。縮減比較的是索引的草堆與返回的區塊；這並非計費成本節省。
• 圖譜提升在這些聊天語料庫上是無效的，因為它們沒有原生的 [[wikilink]] 圖譜。它是為真實的互聯保險庫設計的。
• 可選的 QA 評判使用 Anthropic 而非論文中的 GPT-4o 設定，因此這些 QA 結果適用於相對消融——而非已發表的排行榜比較。

完整指標、嵌入掃描、延遲測量、授權、指令和注意事項位於 benchmarks/README.md。

隱私與限制

• 保險庫本質上是純文字設計，並非加密儲存。 AgentCairn 會在其自動化的 body/title/tag 寫入前，遮蓋已辨識的憑證模式；未知模式與手動編輯仍由您自行負責。
• 保險庫檔案僅限擁有者存取（0600/0700）。 由於保險庫為純文字且遮蓋僅為盡力而為，檔案權限實際上是其唯一的存取控制。共享 GID 的設定（例如兩個 Docker 容器位於同一群組但不同 UID）需要群組存取權限，因此 vault_group_writable = true 會將新的保險庫筆記與目錄權限放寬至 0660/0770。此設定刻意為選擇性啟用：在 macOS 上，每個本機使用者的主要群組皆為 staff，因此預設群組可讀會將您的記憶暴露給機器上的其他帳號。此開關絕不會放寬保險庫以外的任何內容——索引、分類帳、鎖定檔案與 ~/.agentcairn/config.toml 皆保持私有。
• 雲端功能為明確的對外傳輸。 預設仍維持本機運作。選擇啟用雲端嵌入器或 LLM 評判器，會將剩餘的遮蓋後文字傳送至該供應商。
• 此專案仍處於測試階段。 獨立使用需 Python 3.11 以上版本，且首次載入本機模型可能需要一些時間。已發表的檢索證據最適用於對話記憶，而非通用的程式碼搜尋宣稱。
• 環境行為因主機而異。 上述矩陣為刻意設計：Cursor 與 Antigravity 依賴 sweep 捕捉；一般 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 License 2.0 — 寬鬆授權，並附明確的專利授與。版權所有 © 2026 Charles C. Figueiredo。