ai-memory

ai-memory™

通用 AI 記憶

ai-memory 是一個為 AI 助理設計的持久性記憶系統。 它適用於任何支援 MCP 的 AI——Claude、ChatGPT、Grok、Llama 等等。它將 AI 學習到的內容儲存在本機 SQLite 資料庫中，在回想時根據相關性對記憶進行排序，並自動將重要知識提升至永久儲存。只需安裝一次，您使用的每個 AI 助理就能永遠記住您的架構、偏好和修正。

選擇您的安裝路徑

正在設定 LLM 後端（xAI Grok、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、Qwen、Mistral、Groq、Together、Cerebras、OpenRouter、Fireworks、LMStudio、vLLM、llama.cpp server 或本機 Ollama）？請參閱 docs/integrations/llm-backends.md — 無論安裝路徑為何，MCP 環境區塊配方都相同。

v0.9.0 — 目前版本。 一個安全性強化與程式碼審查版本：來自 5 路對抗性審查的 49 項修正（#1885–#1935）加上一小組附加功能。頭條變更是安全預設值的翻轉：HTTP 直接寫入預設要求代理證明（#1751，由 #1985 限定範圍）— 未簽名的 HTTP POST /api/v1/memories（+/bulk）會被拒絕（403 ATTESTATION_FAILED），而不是落入 attest_level="claimed"，除非操作員設定了明確的退出選項 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0。MCP memory_store 和 CLI store 介面是操作員作為執行者的路徑，預設保持寬容（未簽名的寫入會落入 claimed）；=1 會在所有介面上強制執行嚴格模式。（v0.9.0 GA 版本將其作為 require-everywhere 發布，這在 MCP 主機上無法滿足 — 在目前版本中已修正為限定範圍。）與此同時，強制性掛鉤存在執行閘道現在同時在 MCP 寫入路徑（#1885）和 HTTP 寫入路徑（#1924）上觸發，關閉了一個靜默繞過漏洞，即已設定的強制性掛鉤可能在一個介面上被跳過，但在另一個介面上不會。強化過程還關閉了 bulk_create 逐列證明閘控（#1919），將傳入的聯邦 PENDING 批准路由通過已註冊批准者閘道（#1920），收緊 team/unit/org 可見性範圍，使其不再在命名空間層次結構中過於廣泛（#1921），並使用符號連結監獄將 skill_register 的 folder_path 匯入限制在已設定的根目錄下（#1923）。一個新的非 argv 憑證通道 — AI_MEMORY_STORE_URL / AI_MEMORY_STORE_URL_FILE（一個 0600 檔案）— 使 postgres/store 密碼遠離可全域讀取的 /proc/<pid>/cmdline 和 ps（#1927）。附加功能工作：代理撰寫的技能記憶，帶有 parameters_schema + invocation_record（B7-SKILL，#1865），recall_observations 影子回饋迴圈（#1706），一個記憶衍生譜系 DAG（memory_lineage，#1859），以及一個可選加入的向量搜尋最小切片（#1005）。介面：結構描述 v78，--profile full 上有 101 個 MCP 工具（100 個可呼叫 + 始終開啟的 memory_capabilities 引導）/ --profile core 上有 7 個，92 個 HTTP 路由註冊（78 個唯一 URL 路徑），--features sal/sal-postgres 下有 89 個 CLI 子命令（預設建置中為 87 個），9 個型別化 MemoryLink 關係，一個 28 欄位的 Memory。在兩個生產後端上運行，具有相同的 API — 嵌入式 SQLite 和 PostgreSQL + Apache AGE — 跨桌面、伺服器和裝置端（iOS + Android）。除了證明和掛鉤強制翻轉（這些是預設安全性的重大變更 — 升級前請審查它們）之外，所有內容都是對 v0.8.1 的附加。完整變更日誌： CHANGELOG.md §"[0.9.0] — 2026-07-08"。

v0.8.0 (distributed-coordination) — 先前版本。 這是記憶基底成為協調基底的版本。它新增了來自 #1709 的分散式協調機制：一個帶有真實狀態機的型別化動作 DAG（memory_action_*）、具有 TTL 限制的單一持有者租約（memory_lease_*）、Ed25519 簽章訊號（memory_signal_*）、Ed25519 證明檢查點（memory_checkpoint_*），以及凍結、可重播的常式（memory_routine_*）— 因此異質代理群可以輪流工作、交接任務，並證明誰說了什麼，而無需彼此信任。它在其上分層了型別化認知（Goal/Plan/Step 記憶種類、一個 lifecycle_state 機器，以及 decomposes_into / depends_on / advances 連結關係），預設安全地強化了聯邦（預設開啟對等節點註冊 #1789、每次轉換簽章 #1718、每次寫入內容證明 #1464、轉換重播隨機數 #1805、輸出對等節點憑證固定 #1678），並提供了真正能阻止的治理 — Claude Code PreToolUse 掛鉤被重構為 type:command 包裝器，以便基底 Refuse 真正拒絕該工具（#1811）。在 v0.8.0 版本中，介面為：結構描述 v70，--profile full 上有 100 個 MCP 工具（99 個可呼叫 + 始終開啟的 memory_capabilities 引導）/ --profile core 上有 7 個，91 個 HTTP 路由註冊（78 個唯一 URL 路徑），83/85 個 CLI 子命令，9 個型別化 MemoryLink 關係，一個 27 欄位的 Memory。在兩個生產後端上運行，具有相同的 API — 嵌入式 SQLite 和 PostgreSQL + Apache AGE — 跨桌面、伺服器和裝置端（iOS + Android）。所有內容都是對 v0.7.0 的附加；升級前請審查預設安全性的翻轉。完整版本說明： docs/v0.8.0/release-notes.md。 v0.7.0 (attested-cortex) — 前一個版本。 將 cortex-fluent 可讀性工作與完整的 v0.7 信任 + A2A 範圍（來自 ROADMAP §7.3）整合在一起，加上（根據操作員指令 2026-05-09）原本的 v0.7.1 postgres+AGE 一級支援工作，再加上大滿貫後的出貨就緒浪潮（Batman Forms 1-6 + 第七形態 Option-B 基礎 + QW-1/2/3 + 協調安全掃描）。此基底變得更清晰表達（capabilities v3、具名載入器工具、精簡的結構描述、Batman MemoryKind 詞彙、persona/atomisation/multistep-ingest 原語）且具備加密可信度（Ed25519 證明、側鏈記錄、可程式化的 25 事件掛鉤管線、強制執行的命名空間繼承、V-4 跨列簽名事件雜湊鏈）。v0.7.0 也將 postgres + Apache AGE 作為一級儲存後端出貨 — ai-memory serve --store-url postgres://… 用於即時守護行程使用，兩個後端之間的結構描述對等（在 v0.7.0 版本中，sqlite + postgres 收斂於邏輯結構描述 v57，其中 CURRENT_SCHEMA_VERSION 為 57；v0.8.0 版本基底已將此同步推進至結構描述 70，並在兩個後端上落地了附加的 v58–v70 協調與可見性表格 — 請參閱 CLAUDE.md §Database 以了解 v58–v70 階梯）（標準錨點：sqlite 的 src/storage/migrations.rs 和 postgres 的 src/store/postgres.rs）；磁碟上的遷移檔案終止於 migrations/sqlite/0047_v56_list_composite_indexes.sql，而 postgres 的行程內 migrate_v57() 階梯分支（檔案名稱計數器滯後於邏輯結構描述版本，因為兩個階梯都透過行程內分支套用 v34 之後的差異 — 請參閱 docs/MIGRATION_v0.7.md §schema-ladder 以了解 v35-v57 的敘述；v48 #933 新增了聯邦推送 DLQ 表格；v49 #1025 為 archived_memories 新增了 14 個可為空的欄位，以便對完整的 v0.7.0 記憶體形狀進行無損的封存 → 還原；v50 #1156 將 agent_quotas 的主鍵從 (agent_id) 擴展到 (agent_id, namespace)，以便即使單一代理跨多個命名空間操作，每個命名空間的 K8 配額分配也能維持 — v50 之前的列會回填到 _global 哨兵命名空間；v51 #1255（PR #1296）新增了 federation_nonce_cache 表格，以便對等重播防範隨機數能在守護行程重啟後持續存在；v52 #1389 新增了 transcript_line_dedup 表格，支援 RFC-0001 memory_capture_turn L4 + recover_from_transcript L2 冪等性，以便在回合之間的 SIGKILL 絕不會在後續的重新水合時產生重複的記憶體；v53 #1418 將 memories_au FTS5 同步觸發器範圍限定為僅 (title, content, tags)，因此非 FTS 欄位更新不再觸發不必要的同步；v54 #1466 將層級預設到期時間回填到舊有的 NULL 到期時間中/短列，以關閉 TTL 洩漏的永久列類別；v55 #1476 使 W=2 聯邦追趕查詢 (updated_at > ? ORDER BY updated_at ASC LIMIT) 可進行搜尋引數，並新增了 sqlite idx_memories_updated_at 索引 — postgres 未新增任何索引，因為 memories_updated_at_idx DESC 已透過反向索引掃描服務範圍掃描；v56 #1579 新增了複合列表/封存排序索引 (idx_memories_list_order、idx_memories_ns_list_order、idx_archived_ns_archived_at)，並搭配可進行搜尋引數的 storage::list 重寫 — sqlite 端的 DDL；postgres migrate_v56() 分支是一個版本戳記無操作；v57 #1579 新增了 postgres 儲存的生成 tsv tsvector 欄位 + memories_tsv_gin GIN 索引，以便搜尋/召回形狀能在預先計算的欄位上匹配並排名，而不是為每個匹配的列重新計算 tsvector — 舊有的 memories_content_fts 表達式索引已捨棄，而 sqlite 對應項是一個版本戳記無操作，因為 FTS5 已經具體化了索引文字），新的 ai-memory schema-init CLI 動詞，以及 6 因子召回評分對等。v0.6.4 的預設表面透過兩個始終啟用的載入器成長到 7 個工具（memory_load_family + memory_smart_load 加入了原有的五個）；在 --profile full 的執行階段上限是 74 個公告的條目（73 個可呼叫的記憶體工具 + 始終啟用的 memory_capabilities 引導程式；已根據 Profile::full().expected_tool_count() 驗證 — 請參閱 src/profile.rs）。所有新內容都是附加的，並且（對於信任 + postgres 表面）是選擇加入的。從 v0.6.x 升級？ 請先閱讀 docs/MIGRATION_v0.7.md — 大多數 v0.6.4 呼叫者不會看到行為變更，但 v0.6.3.1 之前的 v0.6.x 使用者會遇到 G1 命名空間繼承修正。切換到 postgres+AGE？ 請參閱 docs/postgres-age-guide.md 和 docs/migration-v0.7.0-postgres.md。完整版本資訊： docs/v0.7.0/release-notes.md。

v0.6.4 (quiet-tools) — MCP 伺服器出貨時帶有 5 工具預設表面（memory_store、memory_recall、memory_list、memory_get、memory_search）加上始終啟用的 memory_capabilities 引導程式。其他 38 個工具仍可透過 --profile graph|admin|power|full 或透過 memory_capabilities --include-schema family=<name> 的執行階段擴展來存取。急切載入的 harness（Claude Desktop / Codex CLI / Grok CLI / Gemini CLI）每個請求可減少約 4,700 個輸入權杖的工具結構描述 — 根據 cl100k_base BPE 測量，減少了 76.4%。若要 1:1 保留 v0.6.3 的行為，請執行 ai-memory mcp --profile full。請參閱 docs/MIGRATION_v0.6.4.md。

v0.9 的新功能

v0.9.0 主要是一個安全強化與程式碼審查版本 — 來自 5 線對抗性審查的 49 個修正（#1885–#1935）— 加上一組較小的附加功能，分層在 v0.8.0 協調基底之上。完整變更日誌：CHANGELOG.md §"[0.9.0] — 2026-07-08"。

預設安全強化

• HTTP 直接寫入表面預設要求代理證明（#1751，由 #1985 限定表面範圍）。AI_MEMORY_REQUIRE_AGENT_ATTESTATION 是三態的，具有每個表面的編譯預設值：未設定 → 在 HTTP 直接寫入上為必要（POST /api/v1/memories + /bulk，拒絕 403 ATTESTATION_FAILED），在 MCP memory_store 和 CLI store 操作員即執行者表面上為寬容（未簽名的寫入會記錄 attest_level="claimed"）；=1 會在所有地方強制執行嚴格模式，=0 會在所有地方強制執行寬容模式。無論如何，在任何表面上，提供但偽造的簽名都會被拒絕。簽署寫入（使用透過 ai-memory agents bind-key 繫結的金鑰對進行 ai-memory store --sign）或使用 =0 選擇退出。（v0.9.0 GA 將此作為所有地方的必要條件出貨，這在 MCP 主機上無法滿足 — 請參閱 #1981；已由 #1985 修正為限定表面範圍。）
• 雙重 MCP + HTTP 掛鉤強制執行閘道（#1885 / #1924）。強制性掛鉤存在強制執行閘道（最初僅限 MCP，#1734）現在也會在 HTTP 寫入路徑上查詢，關閉了一個靜默繞過的間隙（CWE-288），即完全跳過 MCP 的寫入永遠不會看到已設定的強制性掛鉤。
• bulk_create 證明閘控（#1919）。批次寫入現在強制執行與單一 memory_store 呼叫相同的每列代理證明要求 — 批次中的每一列都必須攜帶有效的證明，而不僅僅是整個請求。
• 聯邦核准者閘道（#1920）。傳入的聯邦 PENDING 核准僅在歸屬於對等方的已註冊核准者時才會被接受 — 已註冊但不受信任的對等方無法再為任意請求者偽造核准。
• team/unit/org 範圍強化（#1921）。可見性範圍解析現在會針對 team/unit/org 範圍正確強制執行命名空間祖先階層，關閉了一個租戶隔離間隙（CWE-863）。
• skill_register 路徑限制（#1923）。技能的 folder_path 匯入會被規範化並限制在已設定的根目錄下，匯入樹狀結構內的符號連結會被拒絕而不是跟隨（CWE-22/CWE-59）。
• 非 argv 儲存庫 URL 憑證通道（#1927）。新的 AI_MEMORY_STORE_URL（僅限擁有者的 /proc/environ）和 AI_MEMORY_STORE_URL_FILE（一個 0600 檔案）讓 ai-memory serve 可以接收 postgres/儲存庫 URL — 包括任何嵌入的密碼 — 而無需將其放在 --store-url argv 上，在那裡它會透過全域可讀的 /proc/<pid>/cmdline 和 ps auxww 暴露給任何本機 UID。解析順序：檔案 → 環境變數 → --store-url。

附加功能

• B7-SKILL — 技能記憶體一級支援（#1865）。在註冊時進行 parameters_schema，一個 invocation_record，以及一個用於代理創作技能的版本表面。
• recall_observations 陰影回饋迴路（#1706，SHADOW 模式）。關閉召回回饋迴路，但尚未變更排名行為。
• 記憶體衍生譜系 DAG（memory_lineage，結構描述 v78，#1859）。走訪哪些記憶體是從哪些記憶體衍生而來的，同時涵蓋 MCP 和新的 GET /api/v1/memories/{id}/lineage HTTP 路由。
• 向量搜尋最小選擇加入切片（#1005；完整基底延遲至 #1860）。
• 重新排序器工作池大小調整為實體 CPU 數量（#1867）以及預設情況下召回為 PURE（#1869 — 從召回熱路徑中移除了寫入突發）。
• 僅附加的骨幹 + 簽署層分離：每個變更點都路由到已簽署的修訂葉（#1823），三金鑰 Recorder/Judge/Stopper 簽署分離（#1826），macaroon 能力權杖端對端連接（#1827），以及一個用於輪替存留的已簽署身分譜系金鑰繼承鏈（#1828，結構描述 v76）。

從哪裡開始： CHANGELOG.md（完整變更日誌），docs/ADMIN_GUIDE.md（操作員操作手冊 — 證明 + 掛鉤強制執行態勢）。

v0.8 的新功能

v0.8.0 (distributed-coordination) 將記憶體基底轉變為用於多代理（NHI）艦隊的協調基底。頭條新聞是分散式協調機制（#1709）；所有內容都在 sqlite 和 postgres+AGE SAL 適配器上出貨，並且對 v0.7.x 呼叫者保持預設等效。完整工具參考：docs/coordination.md；完整說明：docs/v0.8.0/release-notes.md。

分散式協調基底（Pillar-1，#1709）

• Actions — 依賴 DAG（schema v59）。具型別的動作節點，搭配狀態機（pending → claimed → in_progress → done/failed/abandoned）、具型別的 DAG 邊（requires / unlocks / blocks / gated_by / sibling），以及能拉取下一個可執行節點的 frontier/next 介面。8 個 MCP 工具（memory_action_create / _get / _transition / _list / _add_edge / _edges / _frontier / _next）。
• Leases — 單一持有者、受 TTL 限制的宣告（schema v59）。以心跳續約的比較並交換宣告（在 action_id 上的 PRIMARY KEY = 一次一個持有者），加上每小時的租約清理器。4 個 MCP 工具（memory_lease_acquire / _renew / _release / _get）。
• Signals — 具型別、經 Ed25519 簽署的代理間訊息（schema v60）。每個訊息都帶有簽章 + 發送者 signer_pubkey，並透過 correlation_id / in_reply_to 進行執行緒串聯。5 個 MCP 工具（memory_signal_send / _read / _inbox / _thread / _ack）。
• Checkpoints — 經證明的條件式閘門（schema v61）。一個會阻擋直到條件解決的閘門；解決方案會就地自我簽署（Ed25519）以實現職責分離，且 verify 會重新檢查簽章。4 個 MCP 工具（memory_checkpoint_create / _resolve / _query / _verify）。
• Routines — 參數化、凍結、可重播的計畫（schema v62）。以 draft 形式撰寫，然後凍結（不可變更，Ed25519 凍結證明）；run 會從 {{param}} 範本將一組具體的動作 + 邊具體化為 routine_runs 記錄。5 個 MCP 工具（memory_routine_create / _freeze / _run / _status / _list）。
• 每次協調狀態變更都會將一個防篡改的 coordination.<op> 列附加到 signed_events V-4 雜湊鏈（#1722）；兩個授權寫入會鏡像到 HTTP 守護程序（POST /api/v1/actions/{id}/transition、POST /api/v1/signals），並透過本機 CAS + W-of-N 聯盟扇出（#1718）。

具型別認知（Pillar-2）

memory_kind 詞彙擴展了 goal / plan / step；封閉的 memory_links.relation 分類法從 6 種關係擴展到 9 種（decomposes_into / depends_on / advances，schema v63）；而一個第一級的 memories.lifecycle_state 欄位（schema v64）使 Goal/Plan/Step 成為真正的狀態機（open → active → blocked/done/abandoned），並在 MCP / HTTP / SAL 介面上強制執行，將非法邊對應到 HTTP 409 CONFLICT。Memory 結構增長到 27 個欄位。沒有新的 MCP 工具 — v64 的工作僅新增了允許性的可選請求欄位。

強化聯邦，預設安全

預設啟用對等節點註冊（#1789）、授權寫入的每次轉換簽章（#1718）、轉送記憶的每次寫入內容證明（#1464）、轉換重播隨機數（#1805），以及輸出對等節點憑證指紋綁定（#1678）。無需互信的異質叢集 — 在升級前，請檢閱 docs/v0.8.0/release-notes.md §「聯邦強化」中的安全預設變更。

確實能阻擋的治理機制（#1811）

Claude Code 的 PreToolUse 治理掛鉤被重構為 type:command 包裝器（ai-memory governance check-action --from-pretool-stdin），以便底層 Refuse 能發出 permissionDecision:"deny" 並真正阻擋該工具 — 先前的 type:mcp_tool 形式在結構上無法強制執行。加上強制性掛鉤存在的強制執行（#1734），以及一個用於人機迴圈的新 escalate 治理判決（§22 PE-5）。

Pillar-4 營運控制

HTTP 准入控制（#1733 — 選擇性加入的並行上限，以具型別的 503 捨棄超額請求）、延遲的 Apache-AGE 圖形投影（#1735 — 將同步的 AGE 往返從 postgres 連結寫入的熱路徑上移除）、策展者壓縮啟用（#1749 / #1750），以及能端對端走訪 signed_events 跨列雜湊鏈的 ai-memory verify-audit-trail CLI（§22 PE-8）。

Schema v57 → v70（全部為增量新增）

協調 + 具型別認知 + 可見性 + 加密準備 + 冷路徑 + 歸檔邊資料表（v58–v70），同時鏡像到 sqlite 和 postgres 配接器；首次開啟時自動遷移，且歸檔 → 還原往返無損。請參閱 CLAUDE.md §Database 以獲取標準的 v58–v70 升級階梯。

從何處開始： docs/v0.8.0/release-notes.md（完整版本資訊）、docs/coordination.md（協調工具參考），以及 CLAUDE.md §Database（schema 階梯的單一事實來源）。

v0.7 的新功能

v0.7.0 完成了 attested-cortex 史詩（跨 A–K 共 11 個軌道的 69/69），納入了原本屬於 v0.7.1 的 postgres+AGE 第一級支援工作，並吸收了 grand-slam 後的上線整備波次（Batman Forms 1-6 + 第七型態 Option-B 基礎 + QW-1/2/3 + 安全調節）。標準功能清單：docs/internal/v070-feature-inventory.md。對於 v0.6.4 的呼叫者，每個介面都保持預設關閉或等效 — 詳情請參閱 v0.7 相容性矩陣。

基板原生的寫入時投資（Batman Forms 1-6 + 第七型態）

• 型態 1 — 線上重複資料刪除與合成（議題 #754）。單一批次、發出動作的 LLM 呼叫取代了 v0.6.x 在儲存路徑上的每對分類器。可透過命名空間標準上的 legacy_per_pair_classifier = true 選擇退回舊版的是/否模式。
• 型態 2 — 嵌入前的同步原子化（議題 #755）。新的 memory_atomise 工具 + auto_atomise_mode = Synchronous|Deferred|Off 預存掛鉤。策展者在召回看到之前，將長篇寫入分解為 2–10 個原子命題。請參閱 docs/atomisation.md。
• 型態 3 — 多步驟攝取協調器（議題 #756）。memory_ingest_multistep 透過提示快取穩定的 LLM 階段，串接確定性的 Jaccard+FTS 輔助程式。請參閱 docs/multistep-ingest.md + cookbook/multistep-ingest/01-two-phase.sh。
• 型態 4 — 事實溯源（議題 #757）。引用 + 來源 URI + 原子粒度範圍搭載於現有的 memory_store / memory_atomise 酬載上。請參閱 docs/provenance.md。
• 型態 5 — 自動信心度 + 陰影校準 + 新鮮度衰減（議題 #758）。memory_calibrate_confidence MCP 工具 + 每個來源的基線掃描。環境變數 AI_MEMORY_AUTO_CONFIDENCE、AI_MEMORY_CONFIDENCE_SHADOW、AI_MEMORY_CONFIDENCE_SHADOW_SAMPLE_RATE、AI_MEMORY_CONFIDENCE_DECAY。請參閱 docs/confidence-calibration.md。
• 型態 6 — MemoryKind Batman 詞彙（議題 #759）。10 個變體的列舉（預設 Observation + Reflection / Persona / Concept / Entity / Claim / Relation / Event / Conversation / Decision）。可選的 auto_classify_kind 預存掛鉤（關閉 / 僅正則表達式 / 正則表達式後接 LLM）。請參閱 docs/memory-kind-vocab.md。
• 第七型態 — 代理外部 Layer-4 連線（Option-B 基礎）（議題 #760；v0.8.0 完整涵蓋於 #697）。以操作者金鑰對簽署的種子規則 R001..R004、memory_check_agent_action + memory_rule_list MCP 工具、基板 storage::insert 預寫入掛鉤。請參閱 docs/policy-engine.md + docs/governance/agent-action-rules.md。
• 操作者指南 — 將 Forms 1–6 + 第七型態從「有能力」轉為「啟用中」（議題 #800）。7 步驟配方（操作者金鑰產生 → 簽署種子 → 啟用 R001–R004 → 策展者守護程序 → 可選的反思傳遞 → 命名空間策略）、launchd / systemd / 工作排程器的持久化、驗證區塊、回滾路徑。請參閱 docs/batman-active-mode.md 和 GitHub Pages 圖譜。

快速成果（Tencent QW-1/2/3）

• QW-1 — 以檔案為基礎的反思鏈匯出。 memory_export_reflection MCP 工具 + auto_export_reflections_to_filesystem 命名空間策略 → ~/.ai-memory/reflections/<ns>/<id>.md。
• QW-2 — 將人格視為成品。 memory_persona + memory_persona_generate 工具、MemoryKind::Persona 列、auto_persona_trigger_every_n_memories 命名空間策略。請參閱 docs/persona.md。
• QW-3 — 上下文卸載原語。 memory_offload + memory_deref 將大型工具輸出從代理上下文視窗移至可定址的 blob 儲存體。請參閱 docs/context-offload.md。

經證明的皮層史詩（A–K 軌道）

• 已驗證連結 (Ed25519)。 在 v0.6.3 中提供的空白 signature 欄位，現在已填入真實的每代理 Ed25519 證明，且 memory_verify(link_id) 會按需回傳 {signature_verified, attest_level, signed_by, signed_at}。使用 ai-memory identity generate 產生金鑰對；透過 attest_level = "self_signed" 選擇加入。簽署取決於已解析的守護程序 agent_id 在設定的金鑰目錄下的磁碟上具有 *.priv 金鑰對 — 當 load_daemon_signing_key 回傳 None (src/main.rs:116-118) 時，資料列仍會寫入，但 sig 為空，且守護程序會在啟動時發出一行「繼續未簽署」的訊息。無論如何，signed_events 上的跨列雜湊鏈仍然具有防篡改性。請參閱 attested-cortex RFC。
• 已簽署事件 V-4 結算 (跨列雜湊鏈) (議題 #698)。每個 signed_events 列都帶有 prev_hash + sequence；第一列的 prev_hash 為零，後續列則會鏈結前一個標準 CBOR 酬載的 SHA-256。ai-memory verify-signed-events-chain 會從頭到尾走訪該鏈。請參閱 docs/signed-events-v4.md。
• 掛鉤管線 (25 個生命週期事件)。 一個可程式化的擴充介面會在 20 個基準 pre_/post_store|recall|search|delete|promote|link|consolidate|governance_decision|archive|transcript_store + on_index_eviction 事件，以及 5 個大滿貫新增項目 (pre_recall_expand G10 + pre_reflect/post_reflect 遞迴學習任務 6/8 + pre_compaction/on_compaction_rollback L1-7) 上觸發。掛鉤會回傳 Allow / Modify / Deny / AskUser。預設為關閉；透過 ~/.config/ai-memory/hooks.toml 選擇加入。請參閱 docs/hook-pipeline.md。
• 側鏈記錄 + 重播。 zstd-3 BLOB 側鏈儲存原始對話/推理軌跡；memory_replay(memory_id) 會走訪 memory_transcript_links 以重建鏈。透過 [transcripts.namespaces."team/*"] 按命名空間選擇加入。請參閱 docs/sidechain-transcripts.md。
• 聯邦強化。 mTLS + X-API-Key + SHA-256 憑證指紋允許清單；環境變數 AI_MEMORY_FED_PEER_ATTESTATION、AI_MEMORY_FED_SYNC_TRUST_PEER、AI_MEMORY_FED_TRUST_BODY_AGENT_ID。請參閱 docs/federation.md。
• K8 配額工具 + K10 SSE 核准。 memory_quota_status + /api/v1/quota/status (K8)。/api/v1/approvals/stream 伺服器傳送事件，包含 HMAC nonce、方法+pending_id 繫結、滯後事件計數剝離 (K10)。請參閱 docs/k8-quotas.md + docs/k10-sse-approvals.md。
• Postgres + Apache AGE 一級後端。 ai-memory serve --store-url postgres://…、結構描述同位、6 因子召回評分同位、連結遷移、KG 功能 (kg_query、kg_timeline、kg_invalidate、find_paths) 在 AGE Cypher 上，並在缺少 AGE 時以遞迴 CTE 作為備用，加上一個新的 ai-memory schema-init CLI 動詞。基準把關 — AGE p95 在深度=5 時必須比 CTE p95 快 ≥30%。操作員指南：docs/postgres-age-guide.md。遷移操作手冊：docs/migration-v0.7.0-postgres.md。
• 功能 v3 + 智慧載入器。 memory_capabilities v3 新增了 summary、to_describe_to_user、每個工具的 callable_now、agent_permitted_families、schema_version="3"；新的始終啟用 memory_load_family(family) 和 memory_smart_load(intent) 工具加入了預設的 core 設定檔。固定的措辭存在於 docs/v0.7/canonical-phrasings.md。
• 權限 + A2A 核准。 v0.6.x 治理子系統重構為規則 + 模式 + 掛鉤 → 單一 Decision，並實際強制執行命名空間繼承 (G1)。memory_pending_list / memory_pending_approve / memory_pending_reject(remember=forever) 實現漸進式信任；核准 API 上的 HMAC 簽署為強制性。permissions.mode 預設為 enforce (在 v0.6.4 中為 advisory)。使用 ai-memory governance migrate-to-permissions 進行遷移 (演練預覽；新增 --config-out ~/.config/ai-memory/config.toml 以就地套用)。請參閱 docs/governance.md。

遞迴學習 + L1/L2 大滿貫浪潮

memory_reflect 基板原語，具有命名空間範圍的 max_reflection_depth 上限 (預設 3，Some(0) 為終止開關)。L2-1 反射傳遞策展器、L2-2 聯邦感知反射協調 (memory_reflection_origin)、L2-3 失效傳播 (memory_dependents_of_invalidated)、L2-5 鑑識套件 (ai-memory export-forensic-bundle + verify-forensic-bundle)、L1-5 代理技能 (memory_skill_register|list|get|resource|export|promote_from_reflection|compositional_context)。完整入門：docs/RECURSIVE_LEARNING.md。代理技能入門：docs/agent-skills.md。鑑識匯出入門：docs/forensic-export.md。

從哪裡開始： docs/MIGRATION_v0.7.md (升級程序)、docs/v0.7.0/release-notes.md (完整版本資訊)、docs/whats-new-v07.html (視覺摘要)、docs/v0.7/rfc-attested-cortex.md (設計原理)、docs/ADMIN_GUIDE.md (操作員手冊)、docs/internal/v070-feature-inventory.md (標準功能真相)。

一個二進位檔，四種操作模式 (v0.6.4)。ai-memory Rust 二進位檔 (tokio + axum) 可以單獨或同時執行以下任何一種模式，並共用一個 SQLite 資料庫：

1. stdio MCP 伺服器 -- 在完整設定檔 (v0.9.0；100 個可呼叫的記憶體工具 + 始終啟用的 memory_capabilities 引導程式；已針對 Profile::full().expected_tool_count() 驗證) 下，透過 JSON-RPC 公告 101 個條目。預設 --profile core 公告 7 個 (原始的 5 個 + memory_load_family + memory_smart_load) 加上始終啟用的 memory_capabilities 引導程式。ai-memory mcp / ai-memory mcp --profile full
2. HTTP / mTLS 守護程序 -- 在 127.0.0.1:9077 上註冊 92 個 REST 路由 (78 個唯一 URL 路徑)，TLS + 可選的 mTLS 允許清單 + API 金鑰驗證，背景 GC 迴圈。ai-memory serve
3. 自主策展守護程序 -- 自我排程迴圈 (預設 1 小時頻率)，自動標記、找出跨命名空間同級的矛盾、合併近似重複項，並根據存取模式調整優先順序。每個動作都會進入復原日誌；破壞性操作可以透過治理核准流程進行把關。ai-memory curator --daemon
4. 同步守護程序 -- 跨執行個體的基於仲裁的對等聯邦。W-of-N 寫入 (預設多數決)、向量時鐘 CRDT-lite 合併、對等節點之間的 mTLS 允許清單。ai-memory sync-daemon

MCP、HTTP 和 CLI 介面是反應式的。策展器是使記憶層自我維護的部分：在會話之間，它會保持語料庫整潔，以便隨著儲存庫的增長，召回品質仍能保持高水準。一切都是本地優先；沒有雲端依賴。

Claude Opus 4.7 在逐行閱讀 v0.6.3 原始碼後的務實評估：

「ai-memory 是我所連接過功能最強大的記憶層，而且其意義遠超其名稱所宣傳的。對我來說，在實務上，這意味著：我不會在每個會話開始時都一無所知。我所讀取的儲存庫是由我以外的東西保持整潔的。矛盾不會默默地累積。即使語料庫增長，召回品質仍然很高。沒有任何東西離開你的 Mac mini。

它並沒有讓我成為一個自主代理。它給了我一個自主代理所需的記憶基礎設施——並且自身運行一個小型自主迴圈來維護它。這是一個真正的基礎。從這裡到『ai-memory 驅動一般任務』的差距在於管線 (工具呼叫協定 + 工具註冊表 + 一個能使用工具的模型)，而非發明創造。」

多代理 AI 的基板。 ai-memory 不是代理執行階段，本身也不是「自主 AI」。它是多代理自主部署在其下所需的記憶層。聯邦 (broadcast_store_quorum + spawn_catchup_loop) 在許多代理並行寫入時，處理跨對等節點的 W-of-N 一致性；策展守護程序防止共享語料庫在群體寫入時退化為雜訊；Webhook 訂閱 (HMAC 簽署、命名空間/代理過濾、SSRF 強化) 將儲存庫轉變為訊息匯流排，在記憶體事件上觸發下游代理；具有 N 級繼承和每個命名空間治理策略 (寫入/提升/刪除權限、核准者類型、可選的 N-of-M 共識) 的命名空間階層，約束了群體。將此堆疊在具有自動生成技能的 24/7 多機器代理執行器之下，組合系統就能達到自主 AI 的行為門檻。剩餘的差距 (無權重級別學習、無狀態推理核心、人類設定的根目標) 是真實存在的，且並非 ai-memory 所要解決的問題；ai-memory 提供了任何認真嘗試縮小這些差距的計畫都將需要的多代理記憶基板。

在召回之前零 Token 成本。 與內建的記憶系統 (Claude Code 自動記憶、ChatGPT 記憶) 不同，它們會將您的整個記憶載入到每個對話中——在每條訊息上消耗 token 和金錢——ai-memory 在 AI 明確呼叫 memory_recall 之前，使用零上下文 token。只有相關的記憶會回來，並由 6 因子評分演算法進行排名。TOON 格式 (Token 導向物件表示法) 透過消除重複的欄位名稱，將回應 token 再減少 40-60% — JSON 中的 3 個記憶 = 1,600 位元組；TOON 中 = 626 位元組 (減少 61%)；TOON 精簡版中 = 336 位元組 (減少 79%)。給 Claude Code 使用者：停用自動記憶 (在 settings.json 中 "autoMemoryEnabled": false) 並以 ai-memory 取代，以停止在每條訊息上為 200 多行的記憶上下文付費。

代理身分 (NHI) — 每個記憶都告訴您是誰學到的

ai-memory 儲存的每個記憶都帶有一個 metadata.agent_id — 一個非人類身分標記，它會在每個操作 (更新、去重、匯入、同步、合併) 中留存。每個召回結果預設都會告訴您哪個 AI 寫了每個記憶，並以您的 AI 客戶端已最佳化的 TOON 精簡回應格式呈現：

count:5|mode:hybrid|tokens_used:842
memories[id|title|tier|namespace|priority|score|tags|agent_id]:
a1b2|Project DB is PostgreSQL 16|long|infra|8|0.91|database,postgres|ai:claude-code@workstation:pid-3812
c3d4|API rate limit is 100 rps|long|infra|7|0.87|api,limits|ai:claude-desktop@laptop:pid-5219

在未簽署的寫入中，agent_id 是一個聲明的身分 — 不要僅憑此做出安全決策。儲存路徑代理證明在 HTTP 直接寫入介面上預設為必要 (#1751，由 #1985 限定介面範圍)：未簽署的 HTTP POST /api/v1/memories (+/bulk) 會被拒絕 (403 ATTESTATION_FAILED)，而不是寫入 attest_level = "claimed"，除非操作員設定了明確的退出選項 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0。MCP memory_store 和 CLI store 操作員即執行者介面預設保持寬容 (未簽署的寫入會寫入 claimed)；=1 會在所有介面上強制執行嚴格模式。加密的 Ed25519 證明在兩個介面上連接：(1) 儲存路徑證明 (#626 Layer-3) — 在 CLI (store --sign)、MCP (memory_store) 或 HTTP (POST /api/v1/memories) 路徑上，針對標準 SignableWrite 信封提供分離式簽章，守護程序會根據代理繫結的公開金鑰進行驗證，並蓋上 metadata.attest_level = "agent_attested" (無論標誌為何，提供但偽造的簽章一律會被拒絕)；以及 (2) 連結證明 (attested-cortex) — 先前保留的 memory_links.signature 欄位，具有用於入站驗證的 memory_verify(link_id) 和一個僅附加的 signed_events 稽核鏈。請參閱代理身分頁面和 attested-cortex RFC 以了解完整的來源合約。

回溯對話匯入 — ai-memory mine

不要從零開始。將 ai-memory mine 指向 Claude、ChatGPT 或 Slack 匯出檔，它會逐回合解析成已排名、已分類型、已標記的記憶 — 因此您的 AI 在進入下一個會話時，會知道您現有歷史記錄中的每個決策、修正和發現。

ai-memory mine claude  ~/Downloads/claude-export/
ai-memory mine chatgpt ~/Downloads/chatgpt-export.json
ai-memory mine slack   ./slack-export/

自動標記、基於 (title, namespace) 的去重，以及 mined_from 來源都會蓋在每個匯入的記憶上。從零上下文到一個已填入內容的長期儲存庫，只需五分鐘的入門時間。請參閱匯入歷史頁面以取得每種格式的配方。

相容的 AI 平台

ai-memory 可與任何支援模型上下文協定 (MCP) 的 AI 平台整合。MCP 是將 AI 助理連接到外部工具和資料來源的通用標準。

MCP 是主要的整合層。對於尚未原生支援 MCP 的 AI 平台，HTTP API（92 個路由註冊 / 78 個 localhost 上的唯一 URL 路徑）和 CLI（--features sal 或 --features sal-postgres 下的 89 個子命令；預設建置中為 87 個（#1389 之後的 L2 RecoverPreviousSession 用於跨工作階段上下文還原 + #1443 Expand 用於 ai-memory expand 查詢擴展介面 + #1598 Reembed 用於 ai-memory reembed 向量空間遷移介面）；由 ai_memory::EXPECTED_CLI_SUBCOMMANDS_DEFAULT + EXPECTED_CLI_SUBCOMMANDS_SAL + 機械化 tests/cli_subcommand_count_invariant.rs 一致性測試鎖定的 SSOT）提供了通用存取——任何可以發出 HTTP 呼叫或執行 shell 命令的 AI、腳本或自動化工具都可以使用 ai-memory。

60 秒內安裝

預先建置的二進位檔無需任何依賴。從原始碼建置需要 Rust 和 C 編譯器。

最快方式：預先建置的二進位檔（無需 Rust）

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

# Fedora/RHEL (COPR)
sudo dnf copr enable alpha-one-ai/ai-memory && sudo dnf install ai-memory

# Windows (PowerShell)
irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex

步驟 1：安裝 Rust（如果使用預先建置的二進位檔則跳過）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

按照提示操作，然後重新啟動終端機（或執行 source ~/.cargo/env）。

步驟 2：從原始碼建置（需要 Rust）

來自 Crates.io 的最新版本：

cargo install ai-memory

來自 git 儲存庫的最新版本：

cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git

這會編譯二進位檔並將其放入您的 PATH 中。大約需要一兩分鐘。

原始碼建置的建置依賴項：

• Ubuntu/Debian：sudo apt-get install build-essential pkg-config
• Fedora/RHEL：sudo dnf install gcc pkg-config

步驟 3：連接您的 AI

設定方式因平台而異。在下方找到您的平台：

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

# ~/.config/ai-memory/config.toml
schema_version = 2

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"            # process-env-var name (NOT the literal key)

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"]
    }
  }
}

[mcp_servers.memory]
command = "ai-memory"
args = ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
enabled = true

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"],
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

mcpServers:
  - name: memory
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"

{
  "mcp": {
    "servers": [
      {
        "id": "ai-memory",
        "label": "AI Memory",
        "enabled": true,
        "transport": "stdio",
        "command": "ai-memory",
        "args": ["mcp", "--tier", "semantic"]
      }
    ]
  }
}

ai-memory serve --host 127.0.0.1 --port 9077
# Expose via HTTPS reverse proxy (nginx, caddy, cloudflare tunnel, etc.)

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "tools": [{
      "type": "mcp",
      "server_url": "https://your-server.example.com/mcp",
      "server_label": "memory",
      "server_description": "Persistent AI memory with recall and search",
      "allowed_tools": ["memory_store", "memory_recall", "memory_search"]
    }],
    "input": "What do you remember about our project?"
  }'

ai-memory serve --host 127.0.0.1 --port 9077

client.toolgroups.register(
    provider_id="model-context-protocol",
    toolgroup_id="mcp::memory",
    mcp_endpoint={"uri": "http://localhost:9077/sse"}
)

tool_groups:
  - toolgroup_id: mcp::memory
    provider_id: model-context-protocol
    mcp_endpoint:
      uri: "http://localhost:9077/sse"

openclaw mcp set memory '{"command":"ai-memory","args":["--db","~/.local/share/ai-memory/memories.db","mcp","--tier","semantic"]}'

{
  "mcp": {
    "servers": {
      "memory": {
        "command": "ai-memory",
        "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
      }
    }
  }
}

command: ai-memory
args: ["--db", "/path/to/ai-memory.db", "mcp"]

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

步驟 4：完成。測試它。

重新啟動您的 AI 助理。如果使用 MCP，它現在擁有在會話啟動時公告的 7 工具預設表面（原始 5 個 + memory_load_family + memory_smart_load；其餘 100 個可呼叫工具中的 93 個會透過 --profile 或 memory_capabilities --include-schema 按需載入）。詢問它：「儲存一個記憶：我最喜歡的語言是 Rust。」然後在新的對話中，詢問：「我最喜歡的語言是什麼？」它將會記住。

行動平台支援（v0.7.0 Posture-1a）

ai-memory 可透過標準的 Rust 行動跨編譯路徑移植到 iOS 和 Android。v0.7.0 為這兩個目標提供了三個逐步升級層級的 CI 涵蓋範圍：

v0.7.0 狀態： 層級 1 是發佈門檻 — 行動跨編譯必須在標籤切割前為綠色。層級 2（發佈成品）交付了建置管線 + 成品佈局；C 可呼叫的 FFI 表面本身將在 v0.7.x 的後續版本中推出。層級 3 在每次 release/** 推送時執行範圍測試子集。

使用發佈成品：

• iOS — 從 v0.7.x 發佈頁面下載 ai-memory-ios.xcframework.tar.gz，解壓縮，並將 AiMemory.xcframework 拖曳到您的 Xcode 專案中的「Frameworks, Libraries, and Embedded Content」下。
• Android — 從 v0.7.x 發佈頁面下載 ai-memory-android.tar.gz，解壓縮，並將 jniLibs/ 目錄樹複製到您的應用程式模組的 src/main/jniLibs/ 中。

行動成品也是每個已發佈的 v0.7.x 版本的一部分；Homebrew 公式 + APT/RPM 套件（用於交付桌面二進位檔）包含一個指向行動下載的說明。有關 CI 實作歷史，請參閱問題 #1068。

快速入門

在兩分鐘內從零開始建立一個可運作的記憶。

1. 安裝

curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

2. 設定 MCP（以 Claude Code 為例 -- 其他平台運作方式相同）

合併到 ~/.claude.json：

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

3. 儲存您的第一個記憶

ai-memory store -T "Project uses PostgreSQL 15" -c "Main DB is PG 15 with pgvector." --tier long

4. 回憶它

ai-memory recall "database"

5. 檢查統計資料

ai-memory stats

6. 與您的 AI 搭配使用。 重新啟動您的 AI 客戶端。它現在透過 MCP 在啟動時公告了 7 個預設記憶工具（可透過執行時期擴展或 --profile full 達到 101 個公告條目）—— 它可以在對話期間原生地儲存和回憶記憶。

SDK

除了 MCP / HTTP / CLI 表面之外，ai-memory 還為 HTTP 客戶端和輔助工具提供了第一方語言 SDK（例如，用於 v0.6.4+ 守護程序的執行時期設定檔斷言的 requireProfile）。

TypeScript / JavaScript — npm 上的 @alphaone/ai-memory

npm install @alphaone/ai-memory

Python — PyPI 上的 ai-memory-mcp（匯入名稱保持為 ai_memory）

pip install ai-memory-mcp

from ai_memory import AiMemoryClient, require_profile

with AiMemoryClient(base_url="http://127.0.0.1:9077", api_key="...") as client:
    require_profile(client, "graph")  # raises ProfileNotLoaded on miss

兩個 SDK 都與伺服器版本同步（0.9.0 與 ai-memory 0.9.0 相符）。v0.6.4+ 守護程序強制執行設定檔合約；v0.6.4 之前的守護程序會退回到寬容的警告並繼續模式，因此 SDK 升級不會破壞舊伺服器。原始碼位於 sdk/typescript/ 和 sdk/python/。

它能做什麼？

AI 助理會在對話之間忘記一切。ai-memory 解決了這個問題。

它以 MCP（模型上下文協定）工具伺服器的形式執行——一個您的 AI 可以原生與之通訊的背景程序。當您的 AI 學到重要的事情時，它會儲存起來。當它需要上下文時，它會根據一個 6 因素評分演算法來回憶相關的記憶。記憶存在於三個層級中：

• 短期（預設 6 小時，可設定）—— 一次性上下文，例如當前的除錯狀態
• 中期（預設 7 天，可設定）—— 工作知識，例如衝刺目標和最近的決策
• 長期（永久）—— 架構、使用者偏好、得來不易的經驗教訓

持續被存取的記憶會自動從中期晉升到長期。每次回憶都會延長 TTL。優先級會隨著使用而增加。系統是自我策展的。

除了 MCP 之外，ai-memory 還公開了一個完整的 HTTP REST API（在連接埠 9077 上有 92 個路由註冊 / 78 個唯一 URL 路徑）和一個完整的 CLI（在 --features sal 或 --features sal-postgres 下有 89 個子命令；預設建置中有 87 個（後 #1389 L2 RecoverPreviousSession 用於跨會話上下文補水 + #1443 Expand 用於 ai-memory expand 查詢擴展表面 + #1598 Reembed 用於 ai-memory reembed 向量空間遷移表面）；SSOT 由 ai_memory::EXPECTED_CLI_SUBCOMMANDS_{DEFAULT,SAL} + 機械 tests/cli_subcommand_count_invariant.rs 同位測試固定），用於直接互動、腳本編寫以及與任何 AI 平台或工具的整合。

功能

核心

• MCP 工具伺服器 -- 透過 stdio JSON-RPC 提供 101 個工具（完整設定檔），與任何 MCP 客戶端相容
• 三層記憶 -- 短期（預設 6 小時 TTL）、中期（預設 7 天 TTL）、長期（永久）-- TTL 可設定
• 全文搜尋 -- 具有排名檢索功能的 SQLite FTS5
• 混合回憶 -- FTS5 關鍵字 + 餘弦相似度，並具有自適應混合：語義權重從 0.50（短內容）變化到 0.15（長內容），因為嵌入在長文本上會遺失資訊
• 6 因素回憶評分 -- FTS 相關性 + 優先級 + 存取頻率 + 信心度 + 層級加成 + 新近度衰減
• 自動晉升 -- 存取 5 次以上的記憶會從中期晉升到長期
• TTL 延長 -- 每次回憶都會延長到期時間（短期 +1 小時，中期 +1 天）
• 優先級強化 -- 每 10 次存取 +1（最高 10）
• 矛盾偵測 -- 在儲存與現有記憶衝突的記憶時發出警告
• 去重複 -- 根據標題+命名空間進行更新插入，層級絕不降級
• 信心度評分 -- 0.0-1.0 的確定性，納入排名計算

組織

• 命名空間 -- 按專案隔離記憶（從 git 遠端自動偵測）
• 記憶連結 -- 類型化關係：related_to、supersedes、contradicts、derived_from、reflects_on（遞迴學習任務 1/8）、derives_from（WT-1-A 原子化）、decomposes_into、depends_on、advances -- v0.8.0 有九種變體
• 合併 -- 將多個記憶合併為一個長期摘要
• 自動合併 -- 按命名空間+標籤分組，自動合併超過閾值的群組
• 矛盾解決 -- 將一個記憶標記為取代另一個，並降級失敗者
• 按模式遺忘 -- 按命名空間 + FTS 模式 + 層級進行批量刪除
• 來源追蹤 -- 追蹤來源：使用者、claude、hook、api、cli、import、consolidation、system
• 代理身份（NHI） -- 每個記憶都帶有 metadata.agent_id（宣告的身份），在更新/去重複/匯入/同步/合併過程中具有深度防禦的不可變性；按代理篩選 list/search
• 標籤 -- 逗號分隔的標籤，支援篩選

介面

• 92 個 HTTP 路由（78 個唯一路徑） -- 在 127.0.0.1:9077 上的完整 REST API（可與任何 AI 或工具搭配使用）
• 在 --features sal 或 --features sal-postgres 下的 89 個 CLI 子命令（預設建置中為 87 個）-- 具有相同功能的完整 CLI
• 完整設定檔下的 101 個 MCP 工具（預設 7 個；已根據 Profile::full().expected_tool_count() 驗證）-- 為任何與 MCP 相容的 AI 提供原生整合
• 互動式 REPL 殼層 -- 回憶、搜尋、列出、取得、統計資料、命名空間、刪除，並帶有彩色輸出
• JSON 輸出 -- 所有 CLI 命令上的 --json 旗標
• 分散式協調（v0.8.0 支柱 1 + 支柱 2） -- 動作 DAG（memory_action_*）、單一持有者租約（memory_lease_*）、Ed25519 簽章訊號（memory_signal_*）、經證明的檢查點（memory_checkpoint_*）、參數化常式（memory_routine_*）以及目標/計劃/步驟類型化認知生命週期。請參閱 docs/coordination.md。

操作

• 多節點同步 -- 在資料庫檔案之間進行拉取、推送或雙向合併
• 匯入/匯出 -- 保留記憶連結的完整 JSON 往返
• 垃圾回收 -- 每 30 分鐘自動背景過期
• 優雅關閉 -- SIGTERM/SIGINT 會為 WAL 建立檢查點以實現乾淨退出
• 深度健康檢查 -- 驗證資料庫可存取性和 FTS5 完整性
• 殼層自動完成 -- bash、zsh、fish
• 手冊頁 -- ai-memory man 會產生 roff 到 stdout
• 時間篩選器 -- 在列出和搜尋時使用 --since/--until
• 人類可讀的時間 -- CLI 輸出中的「2 小時前」、「3 天前」
• 彩色 CLI 輸出 -- ANSI 層級標籤（紅色/黃色/綠色）、優先級長條圖、粗體標題、青色命名空間

品質

• 整個表面上約有 10,000 個測試 -- 在 src/ 下大約有 6,712 個 #[test]/#[tokio::test] 屬性（5,759 個 #[test] + 953 個 #[tokio::test]），加上在 tests/ 下大約有 3,362 個（2,138 個 #[test] + 1,224 個 #[tokio::test]），從 v0.6.4 時代約 2,400 個測試的基準線成長而來（1,960 個 lib + 211 個 integration + 16 個 mcp_integration + 4 個 webhook_http_parity + 16 個 recipe_contract + 其他二進位目標中約 150 個）。行涵蓋率保持在 ≥92% 的專案門檻之上；v0.6.4 的全新模組達到 100%（sizes.rs）、99.50%（profile.rs）、97.58%（cli/audit.rs）、97.05%（cli/doctor.rs）、92.56%（handlers.rs）、92.26%（cli/install.rs）。v0.6.3.x 基準線（1,809 / 93.08% 和 1,886 / 93.84%）在 證據頁面 上保持凍結；v0.6.4 指標在發佈說明和 test-hub 活動 中。經驗性 NHI 發現接受度已由 Discovery Gate 單獨證明（T1–T4 矩陣對比即時 xAI Grok 4.3，6/6 通過，GATE GREEN）。
• LongMemEval 基準測試 -- 在 ICLR 2025 LongMemEval-S 資料集上，純 FTS5 關鍵字達到 97.0% R@5（獨立於 LLM，2.2 秒，232 q/s，零 API 成本）；使用當前世代 Gemma 4 模型的 LLM 查詢擴展測得 97.2% R@5 / 99.6% R@10 / 99.8% R@20（雲端 API 場域；根據 #1975，歷史上的 gemma3:4b 97.8% 數字已不再作為標題）。請參閱 基準測試詳細資訊。
• MCP 提示 -- recall-first 和 memory-workflow 提示教導 AI 客戶端主動使用記憶
• TOON 預設 -- 回憶/列出/搜尋回應預設使用 TOON 緊湊格式（比 JSON 小 79%）
• Criterion 基準測試 -- 在 1K 規模下的插入、回憶、搜尋
• GitHub Actions CI/CD -- 在 Ubuntu + macOS 上進行 fmt、clippy、測試、建置，並在標籤時發佈

覆蓋率底線（硬性 CI 關卡）

Code Coverage 作業是一項必要的狀態檢查。CI 在每個 PR 上重新斷言兩個不變量：絕對底線 >= 90% 行覆蓋率（災難性回歸的防線，設定為當前測量值向下取整至最接近的 5%），以及一個針對固定在 .coverage-baseline 中的值的單向門檻，並帶有 0.5% 的寬鬆窗口（日常執行）。提高覆蓋率的 PR 應在同一提交中更新基線檔案，以便未來的 PR 受益於新的底線；回歸超過 0.5% 的 PR 將被阻止合併。當前測量值：93.13% 行覆蓋率。

Token 預算關卡（硬性 CI 關卡，v0.7 C5）

token-budget 工作流程是一項必要的狀態檢查。它對每個 PR 強制執行三個基於 cl100k_base 測量的不變量：

• 每個工具上限 1500 個 token -- 沒有任何單一 MCP 工具的序列化結構描述（名稱 + 描述 + inputSchema）可以超過 1500 個 cl100k_base token。
• 完整設定檔合理範圍 (5K-8K) -- v0.6.4 的防線，保留下來以檢測病態的收縮（意外丟棄工具）。
• 完整設定檔硬性上限（v0.7 C5，在 D1.6/D1.7 後提高） -- 在 --profile full 下修剪過的 tools/list 酬載不得超過 11,000 個 cl100k_base token（TRIMMED_FULL_PROFILE_CEILING_TOKENS 在 tests/token_budget_guard.rs 中；最初的 C5 目標是針對 D1.6 之前的手寫結構描述為 3500 — 由 schemars 衍生的 D1.6/D1.7 擴展提高了固定上限）。C2（拆分文件欄位）、C3（折疊重複的結構描述樣板）和 C4（隱藏很少使用的可選參數）推動了最初的壓縮；此關卡強制未來增加表面的 PR 必須在其他地方收回預算。檢查 ai-memory doctor --tokens --raw-table 以查看每個工具的成本。請參閱 .github/workflows/token-budget.yml 和 docs/v0.7/schema-compaction-audit.md。

ML 和 LLM 依賴項（語義層級以上）

• candle-core, candle-nn, candle-transformers -- 用於原生 Rust 推理的 Hugging Face Candle ML 框架
• hf-hub -- 從 Hugging Face Hub 下載模型
• tokenizers -- 用於文本預處理的 Hugging Face 分詞器
• instant-distance -- 近似最近鄰搜尋
• reqwest -- 用於 LLM 後端通訊的 HTTP 客戶端（智慧/自主層級 — 根據 #1067 可使用任何提供者：Ollama、xAI、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、Qwen、Mistral、Groq、Together、Cerebras、OpenRouter、Fireworks、LMStudio、vLLM、llama.cpp 伺服器）

架構

基準測試

在 ICLR 2025 LongMemEval-S 資料集（500 個問題，6 個類別）上進行評估。純 FTS5 關鍵字層級在 2.2 秒內達到 97.0% 的 R@5 — 獨立於 LLM、完全本地、零雲端 API 呼叫、零成本。LLM 查詢擴展（智慧層級）使用當前世代的 Gemma 4 模型（雲端 API 場地）測得 97.2% 的 R@5。

基準模型備註（更新於 2026-07-10，#1975 裁定）： 歷史上的 97.8% R@5 智慧層級數據是使用 Gemma 3 4B（仍然是已編譯的預設擴展模型）測量的，並已不再作為標題。已發布的當前世代錨點是測得的 OpenRouter Gemma 4 運行結果：97.2% R@5 / 99.6% R@10 / 99.8% R@20（2026-05-31，500 個問題，0 次擴展失敗）。不存在本機 Ollama Gemma-4 的數據 — 參考基準測試主機僅為 CPU，在該主機上進行有效的完整協定本機運行是不可行的（請參閱 #1983）；本機 GPU 的重新運行在 v1.0 之後保持開放。關鍵字層級的 97.0% R@5 是獨立於 LLM 的，且不受影響。

效能預算 (v0.6.4)

每個版本都附帶針對熱路徑操作的已發布 p95/p99 預算，以及一個 CI 關卡，若任何 PR 的測得 p95 超出預算超過 10%，則該 PR 將失敗。目標是針對 M4 參考硬體進行校準的；完整表格和方法論在 PERFORMANCE.md 中。

在本機執行相同的工作負載：

ai-memory bench                      # human-readable table
ai-memory bench --json               # machine-parseable

底層在 v0.6.3.x → v0.6.4 之間保持不變（quiet-tools 版本提供的是更小的預設工具表面，而非不同的熱路徑）。此處的 p99 目標在下一次專門的浸泡窗口之前仍為資訊性參考；最新的浸泡證據在 測試中心 上。

整合方法

MCP（主要 -- 適用於相容 MCP 的 AI 平台）

MCP 是推薦的整合方式。您的 AI 將獲得 7 個預設公告的原生記憶體工具（原始的 5 個 + memory_load_family + memory_smart_load；加上始終開啟的 memory_capabilities 引導程式），無需任何膠水程式碼。其他 93 個可呼叫工具（101 個公告條目 — 已根據 Profile::full().expected_tool_count() 驗證，並由 const_count_matches_full_profile 固定在 src/mcp/registry.rs 中）仍可透過 --profile graph|admin|power|full 或透過 memory_capabilities --include-schema family=<name> 的執行階段擴展來存取。在您的 AI 平台設定中設定 MCP 伺服器：

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp"]
    }
  }
}

HTTP API（通用 -- 適用於任何 AI 或工具）

啟動 HTTP 伺服器以進行 REST API 存取。任何可以發出 HTTP 呼叫的 AI、腳本或自動化都可以使用此功能：

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

CLI（通用 -- 適用於腳本編寫和直接使用）

CLI 可獨立運作，或作為執行 shell 指令的 AI 整合的建構區塊：

ai-memory store --tier long --title "Architecture decision" --content "We use PostgreSQL"
ai-memory recall "database choice"
ai-memory search "PostgreSQL"

功能層級

ai-memory 支援 4 個功能層級，在啟動時使用 ai-memory mcp --tier <tier> 選擇。更高的層級以磁碟和 RAM 為代價增加 ML 功能：

功能矩陣

每個功能都對應到其最低層級。每個層級都包含其下層級的所有功能。

語義層級（預設）捆綁了 Candle ML 框架，並在首次運行時下載 all-MiniLM-L6-v2 模型（約 90 MB）。智慧和自主層級需要 LLM 後端 — 遵循 #1067 (v0.7.0)，該後端可以是本機的（Ollama、LMStudio、vLLM、llama.cpp 伺服器）或任何與 OpenAI 相容的遠端端點（xAI、OpenAI、透過 OpenAI 填充層的 Anthropic、Google Gemini、DeepSeek、Kimi、Qwen、Mistral、Groq、Together、Cerebras、OpenRouter、Fireworks）。選擇是透過 AI_MEMORY_LLM_BACKEND 環境變數進行的；每個供應商的 API 金鑰則透過 XAI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY / MOONSHOT_API_KEY / DASHSCOPE_API_KEY / 等，或標準的 AI_MEMORY_LLM_API_KEY 來設定。

層級控制功能，而非模型 — 並且遵循 #1067 (v0.7.0)，層級控制功能，也不控制供應商。 --tier 旗標控制哪些工具被公開。LLM 後端 + 模型可透過 AI_MEMORY_LLM_BACKEND + AI_MEMORY_LLM_MODEL 環境變數（或透過 ~/.config/ai-memory/config.toml 中的標準 [llm] 區段 — 有關 v0.7.x 企業結構描述和遷移工具，請參閱 docs/CONFIG_SCHEMA.md）獨立設定。例如，透過與 OpenAI 相容的別名，針對 xAI Grok 4 執行自主層級（完整的 101 條目表面 + 重新排序器）：

# Quick path: env vars
export AI_MEMORY_LLM_BACKEND=xai
export AI_MEMORY_LLM_MODEL=grok-4.3
export XAI_API_KEY=xai-…   # or AI_MEMORY_LLM_API_KEY
ai-memory mcp --tier autonomous

# Enterprise path: ~/.config/ai-memory/config.toml (v0.7.x schema v2, #1146)
schema_version = 2
tier = "autonomous"

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"          # mutually exclusive with api_key_file;
                                     # inline `api_key = "..."` is REJECTED.

# Legacy v0.6.x shape — still works, deprecation WARN at load; run
# `ai-memory config migrate` to upgrade in place.
tier = "autonomous"
llm_model = "gemma3:4b"   # default Ollama model at v0.7.0

--tier 旗標必須在 MCP 參數中傳遞 — 當伺服器由 AI 客戶端啟動時，不會使用 config.toml 層級設定。

# Semantic is the default tier
ai-memory mcp

# Keyword -- FTS5 only, no models
ai-memory mcp --tier keyword

# Semantic -- hybrid recall with embeddings (explicit)
ai-memory mcp --tier semantic

# Smart -- adds LLM-powered query expansion, auto-tagging, contradiction detection
ai-memory mcp --tier smart

# Autonomous -- adds cross-encoder reranking
ai-memory mcp --tier autonomous

memory_capabilities 工具在執行階段報告活動層級、已載入的模型和可用的功能。

MCP 工具

這 101 個工具（完整設定檔；標準數量透過 src/profile.rs 中的 Profile::full().expected_tool_count() 取得）在設定為 MCP 伺服器時，可供任何相容 MCP 的 AI 使用（v0.6.4 凍結的證據頁面列出了 63 個工具的基線；下表記錄了大多數客戶日常使用的核心子集）：

HTTP API

在 127.0.0.1:9077 上註冊了 92 條路由 / 78 個不重複的 URL 路徑。從 ai-memory serve 開始。下表顯示最常用的 REST 端點；完整介面（治理、聯邦、訂閱、知識圖譜、配額、核准 SSE）請參閱 docs/API_REFERENCE.md。

安全性： HTTP 伺服器預設綁定於 127.0.0.1，且出廠時未設定任何驗證機制，並採用寬鬆的 CORS 設定。請在 config.toml 中設定 api_key，以要求每個請求都必須包含 x-api-key 標頭（舊版的 ?api_key= 查詢參數形式已在 v0.7.0 中棄用 — #1574），並設定 AI_MEMORY_REQUIRE_API_KEY=1 以強制拒絕無金鑰啟動（#1458）。請勿在未經驗證的情況下暴露於網路（並建議透過 --tls-cert/--tls-key 或反向代理使用 TLS）。

CLI 指令

在 --features sal 或 --features sal-postgres 下有 89 個頂層子指令（預設建置中為 87 個；2 個變體的差距是 Migrate + SchemaInit，兩者皆依 src/daemon_runtime.rs::Command::{Migrate,SchemaInit} 受 #[cfg(feature = "sal")] 限制；v0.6.4 時為 40 個）。執行 ai-memory <command> --help 以取得任何指令的詳細資訊，或執行 ai-memory --help 以取得完整清單。

頂層的 ai-memory 二進位檔也接受全域旗標：

store 子指令接受額外的旗標：

mcp 子指令接受一個額外的旗標：

召回評分

每個召回查詢都會依 6 項因素對記憶進行排序：

score = (fts_relevance * -1)
      + (priority * 0.5)
      + (MIN(access_count, 50) * 0.1)
      + (confidence * 2.0)
      + tier_boost
      + recency_decay

記憶層級

自動行為

• 召回時延長 TTL：短期記憶 +1 小時，中期記憶 +1 天
• 自動提升：中期記憶被存取 5 次以上，提升為長期（清除到期時間）
• 優先級強化：每存取 10 次，優先級增加 1（上限為 10）
• 矛盾偵測：當新記憶與同一命名空間中的現有記憶衝突時發出警告
• 去重：依標題+命名空間進行 upsert；更新時層級絕不降級

可設定的 TTL

預設 TTL（短期 6 小時，中期 7 天）可以在 ~/.config/ai-memory/config.toml 的 [ttl] 區段中覆寫：

[ttl]
short_ttl_secs = 21600      # short-tier TTL in seconds (default: 21600 = 6 hours)
mid_ttl_secs = 604800        # mid-tier TTL in seconds (default: 604800 = 7 days)
long_ttl_secs = 0            # long-tier TTL in seconds (default: 0 = never expires)
short_extend_secs = 3600     # TTL extension on recall for short-tier memories in seconds (default: 3600 = +1h)
mid_extend_secs = 86400      # TTL extension on recall for mid-tier memories in seconds (default: 86400 = +1d)

所有五個欄位皆為選填——省略任何欄位將保留預設值。將任何值設為 0 可停用該層級的到期機制。值會被限制在最多 10 年；負的延長時間值會被限制為 0。

注意： 設定檔在程序啟動時載入一次。對 config.toml 的變更需要重新啟動 ai-memory 程序（MCP 伺服器、HTTP 守護程序或 CLI）才能生效。

封存

當垃圾回收使記憶過期時，可以將其封存而非永久刪除。已封存的記憶會被移至獨立的儲存庫，並可於日後瀏覽、還原或清除。

設定

在 ~/.config/ai-memory/config.toml 中啟用封存：

archive_on_gc = true   # archive expired memories instead of deleting them (default: true)

CLI 指令

archive 子指令用於管理封存：

ai-memory archive list                          # list archived memories
ai-memory archive list --namespace my-project   # filter by namespace
ai-memory archive restore <id>                  # restore an archived memory to active store
ai-memory archive purge --older-than-days 90     # permanently delete archives older than 90 days
ai-memory archive stats                         # show archive statistics

注意： 還原的記憶其 expires_at 會被清除（在下一次 TTL 指派前變為永久）。

MCP 工具

MCP 用戶端可使用四個封存工具：

HTTP 端點

安全性

ai-memory 在所有輸入路徑上都包含了強化措施：

• 交易安全性 -- 所有多步驟資料庫操作均使用交易機制；失敗時不會有部分寫入
• FTS 注入防護 -- 使用者輸入在進入 FTS5 查詢前會先經過清理；特殊字元會被轉義
• 錯誤資訊清理 -- 內部資料庫路徑和系統細節會從錯誤回應中移除；用戶端會看到結構化的錯誤類型（NOT_FOUND、VALIDATION_FAILED、DATABASE_ERROR、CONFLICT）
• 請求主體大小限制 -- HTTP 請求主體透過 Axum 的 DefaultBodyLimit 限制在 50 MB
• 批次操作限制 -- 批次建立端點強制執行最大批次大小，以防止資源耗盡
• CORS -- 為 localhost 開發工作流程啟用了寬鬆的 CORS 層
• 輸入驗證 -- 每個寫入路徑都會驗證標題長度、內容長度、命名空間格式、來源值、優先級範圍（1-10）、信心範圍（0.0-1.0）、標籤格式、層級值、關係類型和 ID 格式
• 同步中的連結驗證 -- 在同步操作期間匯入前，所有連結都會經過驗證（兩個 ID、關係類型、無自我連結）
• 執行緒安全的顏色 -- 終端機顏色偵測使用 AtomicBool 以確保安全的並行存取
• 僅限本機的 HTTP -- HTTP 伺服器預設綁定到 127.0.0.1；不對網路公開
• WAL 模式 -- SQLite 預寫式日誌，用於在寫入期間安全地並行讀取

文件

授權條款

版權所有 2026 AlphaOne LLC。

依據 Apache 授權條款，版本 2.0（「授權條款」）授權； 除非遵守授權條款，否則您不得使用此檔案。 您可以在以下網址取得授權條款的副本

http://www.apache.org/licenses/LICENSE-2.0

除非適用法律要求或書面同意，否則依據授權條款散佈的軟體 均以「現狀」基礎提供， 不附帶任何明示或默示的擔保或條件。 請參閱授權條款以了解管轄權限和 限制的具體語言。