claude-mem：讓 Claude Code 擁有持久記憶（89K 星持續增長中）

遺忘的問題

打開一個 Claude Code session，花四十分鐘教它你的專案認證系統怎麼運作、為什麼選了某個資料庫遷移策略、三個最棘手的 race condition 藏在哪裡。Claude 全都學會了，給你精準的、有 context 的建議。你關掉終端。

開新 session。Claude 完全不記得發生過什麼。

這不是 Claude 的智力缺陷，而是大型語言模型的運作方式。每個 session 都從全新的 context window 開始。模型無法存取前一個 session 的內容，除非你明確提供。你的 CLAUDE.md 有幫助，它記錄了專案慣例和架構決策，可以在 session 之間延續。但它是靜態的。你寫了一次，也許更新過幾次。它無法捕捉 Claude 在實際寫程式時學到的東西。

換個方式想。你雇了一個厲害的承包商，一天之內理解了你整個程式碼庫。工作結束時，他的記憶被清除。隔天早上，他走進來問「你的專案是做什麼的？」你遞給他一頁簡報（你的 CLAUDE.md）。有幫助，但無法取代他在八小時的閱讀、除錯和討論中累積的知識。

claude-mem 解決的就是這個問題。

claude-mem 做了什麼

claude-mem 是一個 Claude Code 外掛，讓你的 AI agent 在不同 session 之間保有記憶。它在 2026 年 2 月初爆紅，登上 GitHub trending 頁面後，三天內就增加了超過 5,000 顆星，目前已達 89K+ 星。

概念很直覺。想像一個開發者在每次工作時都做筆記。下班前翻過筆記，畫出重點，寫一份乾淨的單頁摘要。隔天早上上班前先讀那份摘要。他不記得所有事，但記得足夠多，不會重複同樣的對話、犯同樣的錯。

claude-mem 把這個過程自動化，只不過對象是你的 AI 程式代理。三個步驟自動發生：

1. 捕捉。 在 session 進行中，claude-mem 記錄 Claude 的操作：每次工具執行、每個觀察、每個決策點。
2. 壓縮。 session 結束時，原始觀察被 Claude 自身的推理能力壓縮成語義摘要。
3. 注入。 下一個 session 開始時，claude-mem 把壓縮後的 context 注入 Claude 的 context window。Claude 帶著記憶開始新的 session。

不需要手動操作。安裝外掛，記憶系統就在背景運行。

底層運作方式

實作比「把上個 session 的東西全倒進來」精巧得多。claude-mem 有六個主要元件協同工作。

Lifecycle Hooks

Claude Code 的外掛系統提供五個生命週期 hooks，claude-mem 全部都用上了：

• SessionStart 注入前幾個 session 的壓縮 context。Claude 在這裡「回想」。
• UserPromptSubmit 捕捉你的提問，用於模式辨識。久了以後，claude-mem 會理解你重複問哪類問題。
• PostToolUse 觀察每次工具執行。Claude 讀檔案、跑指令、改程式碼時，觀察都會被記錄。
• Stop 當 Claude 完成回應，外掛產生 session 摘要，包含完成項、學到的東西、下一步。
• SessionEnd 最終清理與摘要產生。

這些 hooks 不會阻塞。它們把工作排進背景 worker service 後立刻返回，不會拖慢你的 IDE。

Worker Service

一個背景 HTTP API 在 port 37777 上執行，由 Bun 管理。這個 worker 處理運算密集的部分：壓縮觀察、產生摘要、管理資料庫。它也在 http://localhost:37777 提供 web 檢視介面，你可以即時瀏覽記憶串流。

儲存

所有資料都進入本機的 SQLite 資料庫。Session、觀察、摘要，全部儲存在你的機器上。沒有雲端服務，沒有外部 API 呼叫。你的程式碼 context 留在你的硬碟裡。

搜尋方面，claude-mem 採用混合策略：SQLite FTS5 做全文關鍵字搜尋，加上 Chroma 向量資料庫做語義搜尋。你可以用精確詞彙或用意義來搜尋專案歷史。

Progressive Disclosure

這是讓 claude-mem 從「聰明」變成「實用」的關鍵設計決策。把每個過去 session 的完整歷史注入 context window，會淹沒 Claude 的推理能力。研究一再顯示，更多 context 不等於更好的結果。注意力隨著輸入長度增加而衰退。（深入了解原因，可參考Context Engineering with Skills。）

claude-mem 用三層檢索系統解決這個問題：

• 第一層：索引。 精簡的搜尋結果，包含觀察 ID、標題、類型、時間戳記。每筆結果約 50-100 tokens。
• 第二層：時間線。 特定觀察的前後脈絡。提供敘事流而不需完整細節。
• 第三層：完整細節。 只對相關的特定 ID 取得完整觀察資料。每筆約 500-1,000 tokens。

Claude 先從索引開始。如果需要某個主題的更多細節，再往下挖。這種漸進式揭露方式，與一次取得所有資料相比，省下約 10 倍的 token 用量。

安裝與設定

在 Claude Code session 中輸入兩行指令就能安裝：

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

重新啟動 Claude Code，外掛自動啟用。你下一個 session 的內容，會在再下一個 session 中自動出現。

需求：

• 支援外掛的 Claude Code（最新版本）
• Node.js 18.0.0 以上
• Bun（缺少時自動安裝）
• Claude Pro 訂閱或 Anthropic API key

外掛以 AGPL-3.0 授權，原始碼完全公開可檢視。

關於 npm 套件： claude-mem 有發布到 npm，但 npm install -g claude-mem 只安裝 SDK/程式庫，不會註冊外掛 hooks 或設定 worker service。請一律使用上面的 /plugin 指令安裝。

設定

設定檔在 ~/.claude-mem/settings.json，首次執行時自動建立。你可以調整壓縮用的 AI 模型、worker 連接埠、資料目錄、log 層級和 context 注入設定。大多數開發者不需要改預設值。

隱私控制

你可以用 <private> 標籤包住任何內容，排除它被儲存。敏感憑證、個人筆記、任何你不想被持久化的東西，標記就好，claude-mem 會跳過。

實際影響

差異在前幾個 session 後就很明顯。以下是會改變的模式：

架構決策會留住。 你解釋一次 API 使用特定的錯誤處理模式。下一個 session，Claude 已經知道這件事。不需要重新說明，也不需要更新 CLAUDE.md。

Bug context 會延續。 你花一個 session 除錯 WebSocket handler 的 race condition。Claude 理解了根因、修復方式和邊界情況。下一個 session 遇到相關問題，Claude 有那段歷史可以參考。

寫程式慣例是被觀察到的，不是被宣告的。 你的 CLAUDE.md 可以寫「使用 named export」。但有幾十種微慣例很難文件化：測試檔案怎麼命名、工具函式放哪裡、偏好什麼錯誤訊息。claude-mem 從實際行為中捕捉這些，不需要你明確記錄。

重複提問會消失。 如果你在三個 session 中問了三次「auth middleware 做什麼」，claude-mem 辨識出這個模式。答案會在未來的 context 注入中被優先排序。

搜尋專案歷史

claude-mem 提供 MCP 搜尋工具，讓 Claude 用自然語言查詢你的記憶。三層工作流程：

// 第一步：搜尋索引
search(query="authentication bug", type="bugfix", limit=10)

// 第二步：檢閱結果，找出相關 ID

// 第三步：只取需要的完整細節
get_observations(ids=[123, 456])

這表示 Claude 可以主動查閱過去的 context，而不只依賴 session 開始時注入的內容。

與 Agent Skills 及 Context Engineering 的關係

如果你一直在關注 Agent Skills 生態系，你會注意到 claude-mem 從不同角度解決了同一個根本問題。

Skills（透過 SKILL.md 檔案）編碼靜態知識：流程、限制條件、領域專業。你寫一次，跨專案分享，agent 按需載入。它們很適合把團隊標準和可重複流程制度化。

CLAUDE.md 編碼專案層級的 context：架構、慣例、「永遠做 X，永遠不做 Y」。它在每個 session 開始時被注入。

claude-mem 加上第三個維度：動態的、session 衍生的知識。 它捕捉 agent 在實際工作中學到的東西，而不是人類預先想到並寫下的內容。

三種方式是互補的，不是競爭的。一個結構良好的設定看起來像這樣：

想深入了解這些層級如何互動和爭奪 context window 空間，可參考 Context Engineering with Skills。那篇文章的核心洞見直接適用於此：context window 中的每個 token 都在與推理能力競爭。claude-mem 的漸進式揭露架構正是為了尊重這個限制而存在。

讓設計良好的 skills 有效的因素，也讓 claude-mem 有效：在正確的時機提供高訊號 context，而不是把所有東西都灌進模型。

Termdock 與延續性堆疊

Session 延續性有兩個面向。一個是你的終端環境狀態：哪些分割窗格開著、在哪些目錄中、哪些程序正在跑。另一個是你的 AI 的知識狀態：它學了什麼關於你的程式碼、你的偏好、你的專案歷史。

Termdock 的 session 恢復處理第一個面向。你闔上筆電再打開，你的終端佈局完全復原。左邊 Claude Code、右上測試執行器、右下伺服器 log 的三窗格配置，全部回來。

claude-mem 處理第二個面向。Claude Code 帶著上一個 session 學到的知識回來。

兩者合在一起，形成完整的延續性堆疊：你的實體工作空間和你的 AI 認知工作空間，都能跨越 session 邊界存活。不用重新設定，不用重新解釋。

限制與考量

89K 星代表真實的社群驗證，但不表示你該盲目安裝。以下是需要評估的項目：

Token 成本。 每個注入的記憶 token 都在與 Claude 處理當前任務的推理能力競爭。claude-mem 的漸進式揭露顯著緩解了這個問題，但不是零成本。建議在前幾週監控你的 token 用量，了解實際影響。

儲存在本機。 記憶資料庫在你的機器上。如果你在多台電腦之間工作，記憶不會自動同步（除非你手動同步資料庫）。這是隱私優勢，也是可攜性限制。

壓縮有損。 AI 產生的摘要品質不差，但終究是摘要。細微的 context 可能在壓縮中被省略。對於關鍵的專案知識，你仍然需要在 CLAUDE.md 中明確記錄，而不是依賴 claude-mem 來記住。

隱私涵蓋範圍。 claude-mem 儲存關於你的程式碼、你的提問和工具使用的觀察。<private> 標籤給你控制權，但你需要主動使用它。透過 http://localhost:37777 的 web 檢視器確認哪些東西被儲存，並據此調整你的習慣。

相依鏈。 外掛需要 Bun、uv（Python 套件管理器，用於向量搜尋）和背景 worker service。更多元件意味著更多潛在故障點。自動安裝處理了大部分情況，但你應該知道你的系統上跑了什麼。

專案正在積極維護中（目前 v6.5.0），以 AGPL-3.0 授權。開源授權代表你可以檢視確切的資料捕捉與儲存方式。對於一個處理你程式碼 context 的外掛，這份透明度很重要。

帶走什麼

持久化 AI 記憶不是要讓模型「更聰明」。模型已經很聰明了。關鍵在於讓模型有所了解：在它需要的時候，給它需要的 context，而不是強迫你在每個 session 手動管理那些 context。

claude-mem 自動化了捕捉、壓縮、注入的循環。它用漸進式揭露維持 token 效率。所有資料儲存在本機。它整合了 Claude Code 外掛系統的 lifecycle hooks。

如果你已經在日常開發中使用 Claude Code，claude-mem 補上了靜態設定檔無法提供的那一塊：在實際工作中累積出來的知識。

安裝它。跑幾個 session。看看 web 檢視器。自己決定那些記憶是不是有用的。