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 和語義向量透過倒數排名融合進行合併，然後可選擇性地重新排序。模型/提供者的失敗會明顯地退回到 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/ 註冊表會保留該生命週期，而不會重複索引來源內容。對於自訂、受管理或會話覆蓋的 Claude 記憶體目錄，請使用 --source <dir>；在批次匯入時則使用 --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 下返回的上下文遠小於完整的已索引歷史記錄：

誠實地解讀這些數字：

• 檢索召回率並非問答準確度。這些表格比較的是受控的檢索方案，而非終端使用者的答案品質或其他產品的排行榜分數。
• Token 計數使用每個 token 約四個字元的啟發式方法。縮減比例比較的是已索引的資料堆與返回的區塊；這並非節省的計費成本。
• 圖譜提升在這些聊天語料庫上是惰性的，因為它們不包含原生的 [[wikilink]] 圖譜。它是為真實的相互連結的儲存庫設計的。
• 可選的問答判斷器使用 Anthropic 而非論文中的 GPT-4o 設定，因此這些問答結果對於相對消融研究有用，而非用於已發布的排行榜比較。

完整的指標、嵌入掃描、延遲測量、授權、指令和注意事項，請參閱 benchmarks/README.md。

隱私與限制- 儲存庫預設為明文設計，而非加密儲存。 AgentCairn 在自動寫入內文、標題、標籤之前，會先將已識別的憑證模式進行遮蔽處理；未知的模式及手動編輯的內容，則仍需由您自行負責。

• 雲端功能屬於明確的資料輸出。 預設為本機運作。若選擇使用雲端嵌入器或 LLM 評判器，則會將遮蔽後的剩餘文字傳送至該服務提供者。
• 本專案為測試版。 獨立使用需要 Python 3.11 以上版本，且首次載入本機模型可能需要一些時間。已發布的檢索證據最適用於對話記憶，而非通用的程式碼搜尋聲明。
• 環境行為會因主機而異。 上述的對照表是刻意設計的：Cursor 和 Antigravity 依賴掃描擷取；泛用的 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。