AI

claude-mem：突破 10 萬 stars 的 Agent 長期記憶系統，用 hooks 自動記錄、壓縮、再注入

Monday

本內容僅供參考，詳細使用規則與工具安全性與否，建議要進行相關安全性測試與評估

Coding Agent 最讓人無奈的一點，是它「每天都是第一天上班」：昨天花了一下午才搞懂的架構決策、踩過的坑、使用者的偏好，到了新 session 全部歸零。今年 6 月我們介紹過輕量的離線記憶工具 Recall；今天要看的 claude-mem（thedotmack/claude-mem）走的是更完整、也更重的路線——自動記錄 Agent 的每個動作、用 AI 壓縮、建立可搜尋的記憶庫，再在需要時注入。專案最近剛突破 10 萬 stars（約 101k），並在 10 月初的多份 AI 開源趨勢報告中名列前茅。

1. 專案背景與定位

claude-mem 由 Alex Newman（@thedotmack）開發，Apache-2.0 授權，以 TypeScript 撰寫，目前版本 13.39.0，main 分支已有 3,300+ commits。官方描述是「Persistent Context Across Sessions for Every Agent」——雖然名字有 Claude，但已支援 Claude Code、Codex、Gemini、Copilot、OpenCode、Hermes、OpenClaw、Antigravity CLI 等十多種 Agent。

它的定位是 Agent 的自動化長期記憶層：使用者不需要手動記錄任何東西，系統會在背景完成擷取、壓縮、索引與回填。

2. 技術架構與核心設計

  • 生命週期 hooks：掛在 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SessionEnd 六個事件上，自動擷取 Agent 在做什麼。
  • AI 壓縮：把原始活動壓縮成「觀察紀錄」與「session 摘要」，而不是保存完整對話。
  • 本機 Worker 服務：由 Bun 管理的本機 HTTP API，提供搜尋端點與網頁版記憶瀏覽器。
  • 雙重儲存：SQLite（含 FTS5 全文檢索）存放 session、觀察與摘要；Chroma 提供語意與關鍵字混合搜尋。
  • 三層漸進式揭露搜尋：先回傳精簡索引（每筆約 50–100 token）→ 再看時間軸脈絡 → 最後只對篩選後的 ID 取完整內容（每筆約 500–1,000 token）。官方宣稱「先篩選再取用」可節省約 10 倍 token。
  • MCP 搜尋工具：search、timeline、get_observations 等，另有 mem-search skill 支援自然語言查詢。
  • 隱私標籤：用 <private> 包起來的內容不會被儲存。
  • 多語言模式：可透過 CLAUDE_MEM_MODE 設定（例如 code--zh）。

3. 社群熱度與生態採用

約 101k stars、8.8k forks，open issue 只有 31 個——以這個規模來說維護狀況相當好。安裝方式包括 npx claude-mem install 互動式安裝，以及 Claude Code plugin marketplace。

壓縮記憶的模型有幾種選擇：官方託管的 claude-mem observer（有 30 天免費試用）、自帶 OpenRouter 或 Gemini 金鑰，或直接使用自己的 Anthropic 方案。另有可選的 cmem.ai 雲端同步。

4. 局限性與潛在風險

  • 你的工作內容會送去壓縮：hooks 擷取的內容（可能包括程式碼片段、指令輸出、檔案內容）必須送到某個模型做壓縮。若選擇託管的 observer，資料會離開本機，而 README 並未完整說明託管服務如何處理這些資料。處理機密專案時，建議改用自己的金鑰或 Anthropic 方案，並關閉線上選項（CLAUDE_MEM_ONLINE_OPTIN=false）。
  • 雲端同步的資料外流面：cmem.ai 同步是選用的，但開啟後記憶庫會在寫入時同步上雲，需確認是否符合公司政策。
  • <private> 依賴使用者自律：沒有標記的敏感資訊（例如 log 中出現的 token、客戶資料）仍會被記錄與壓縮。
  • 記憶污染：自動記錄代表錯誤的結論、過時的做法，甚至網頁中的惡意內容，都可能被寫進記憶並在未來被注入。需要定期透過網頁瀏覽器檢視與清理。
  • 本機服務的暴露面：Worker 是一個本機 HTTP 服務，README 沒有列出預設 port，應確認它只監聽 localhost。
  • 安裝方式容易誤用：npm install -g claude-mem 只會裝函式庫，不會註冊 hooks 與 worker，必須用 npx claude-mem install 或 plugin marketplace。
  • 與軟體無關的加密代幣：README 中有一段作者「正式支持」的第三方代幣 CMEM 的說明。這與軟體功能無關，讀者應自行判斷，本文不做任何投資相關評論。

5. 應用價值與適用場景

長期維護同一個 codebase、每天都會開好幾個 Agent session 的開發者最能受益：架構決策、除錯經驗、專案慣例都能被保留下來，不必每次重新解釋。三層搜尋設計也讓記憶的注入成本可控，不會一開 session 就塞滿 context。

如果你的工作以一次性任務為主，或對資料外流非常敏感，可以考慮更輕量、完全離線的方案（例如之前介紹的 Recall）。

Monday 的觀點與架構建議

  • 「先回傳索引、再按需取細節」的三層漸進式揭露，是所有 Agent 記憶與 RAG 系統都值得採用的設計：context 是稀缺資源，應該讓模型自己決定要深入哪一筆。
  • 記憶系統的關鍵決策其實是「誰來壓縮」：本機模型、自帶金鑰、或託管服務，決定了你的程式碼會流向哪裡。導入前請把這一點當作資安評估的第一題。
  • 建議為記憶庫建立定期審查機制，並把 <private> 的使用寫進團隊規範。
  • 從 claude-mem、Hermes Agent 到 Headroom 的跨 Agent 記憶，可以看到「記憶層」正在從單一 Agent 的附加功能，變成跨工具共享的基礎設施——未來的競爭點會是記憶的可攜性、可稽核性與隱私控制。

參考來源