Claude-Mem 是以單行指令安裝的 Claude Code 外掛，將每次 session 的決策、bug 修復、檔案脈絡存入本機 SQLite + ChromaDB，並在下次啟動時自動注入相關上下文。本手冊涵蓋安裝、架構、查詢方式、隱私控制與常見問題。
Claude Code 預設沒有跨 session 的記憶。每次重新開啟，它對 codebase 一無所知，架構決策、認證 bug、Docker volume 設定需要重新說明。這個狀況在開發者社群稱為「Goldfish Brain（金魚腦）」。
傳統的解法有兩個,但都不夠用:把 CLAUDE.md 塞滿、或讓 Claude 自動寫 memory。前者每次 session start 就把整份文件灌進 context,不管你今天做的是哪個功能;後者 Anthropic 自己也承認是 unstructured(無結構)、不可搜尋的。當專案規模超過幾千行,這兩種方法都會崩潰。
Claude-Mem 走另一條路:它在 Claude Code 的生命週期 hook(SessionStart、PostToolUse、UserPromptSubmit、Stop)注入觀察者,自動抓取每一次工具呼叫的輸入與輸出,用 Claude 的 agent-sdk 壓縮成結構化的 observation,存進本機 SQLite,並用 ChromaDB 建立向量索引。下次你問「我們上次怎麼修那個 Docker mount 的 bug?」它能秒答。
Claude-Mem 為 Claude Code 新增跨 session 的可搜尋記憶，記錄專案歷史與過往決策。所有資料儲存於本機，不上傳至雲端。
Claude-Mem 採用漸進式揭露（Progressive Disclosure）三層檢索，避免一次將所有記憶載入 context 消耗大量 token，只在需要完整細節時才往下展開。
列出符合查詢的觀察 ID、標題、類型、時間。Claude 先看這個,判斷哪些可能相關。
~50–100 tokens / 結果提供特定觀察前後的時間軸,讓 Claude 理解事件流但不展開完整內容。
中等 token 消耗只在 Claude 認為「這條 ID 真的需要」時才抓完整資料。含 facts、narrative、concepts 等欄位。
~500–1000 tokens / 結果依官方文件，這套漸進檢索比一次全部載入節省約 10 倍 token。mem-search 執行於 fork 出去的 subagent，搜尋的中間步驟不會影響主對話的 context window。
~/.claude-mem/claude-mem.db):結構化 observation 儲存。37700 + (uid % 100),預設舊版是固定 37777。
安裝後沒有出現記憶功能，通常是因為執行了 npm install -g claude-mem。該指令只安裝函式庫，不會向 Claude Code 註冊 hook，也不會啟動背景 worker。
npm install -g claude-mem 只裝了函式庫，不會啟動 hook，也不會啟動 worker。重啟 Claude Code 後不會出現任何記憶功能。
打開 Claude Code,進到任何一個 session,輸入這兩行:
/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem
然後完全離開 Claude Code、再開一次。注意是「完全退出」,不是 /clear。重啟之後 hook 會註冊、worker 會啟動。
npx claude-mem install
這條指令會:檢查 Node 是否 ≥ 18、自動裝 Bun 與 uv、註冊 hooks 到 ~/.claude/plugins/、建立 ~/.claude-mem/ 目錄與預設 settings.json、啟動 worker。
只需要 Node.js 18 以上。其他東西(Bun、uv、SQLite)全部會自動裝。Windows 使用者請走 WSL2,原生 PowerShell 路徑有報過 npm 不是內部命令 的問題。
重啟 Claude Code 後,新開一個 session,看頂部是不是多了一塊「previous observations relevant to what you're working on」的區段。如果有,就成功了。沒有的話,瀏覽器打開 http://localhost:37777(或你的自訂 port)看 Web Viewer。
安裝完不代表立刻有記憶。Claude-Mem 是在 session 結束時才會壓縮儲存。所以你需要先做一個「示範 session」讓它記東西,下一個 session 才看得到效果。
用你平常的方式進入 codebase 根目錄,啟動 Claude Code:claude。Claude-Mem 是「以資料夾為單位」記憶的,所以路徑很重要。
讓 Claude 幫你做一件事,例如「幫我看一下 auth 模組的結構,然後修這個登入 bug」。期間它會 read 檔案、跑 bash、改檔案,每一步都會被 PostToolUse hook 抓下來成為 observation。
用 /exit 正常離開,或直接關掉 terminal。Stop hook 會觸發壓縮,把這次 session 的觀察整理成結構化記憶。壓縮大約需要幾十秒,在背景跑,不會擋你。
同一個資料夾再開 Claude Code,SessionStart hook 會比對你正在做的事跟過去的記憶,把相關的 observation 注入 context。你會在最上方看到一個摘要區塊。
「我們上一次怎麼處理 auth 那個 bug?」這類問題會自動觸發 mem-search skill,Claude 會在 subagent 裡搜尋本機記憶,只回傳相關片段。
查詢記憶以自然語言輸入即可。Claude 會判斷是否需要搜尋本機記憶，決定查詢時 UI 會顯示 mem-search skill 被觸發。
下面這些句子任何一句都會觸發 mem-search:
# 回顧 "我們上次做了什麼?" "What did we do last session?" # 找特定 bug 或決策 "這個 bug 我們以前修過嗎?" "我們是怎麼實作 authentication 的?" "What changes were made to worker-service.ts?" # 近期活動 "Show me recent work on this project" "What was happening when we added the viewer UI?"
| 操作 | 說明 |
|---|---|
| Search Observations | 全文搜尋所有 observation |
| Search Sessions | 全文搜尋 session 摘要 |
| Semantic Search | 透過 ChromaDB 向量做語意搜尋 |
| Timeline Query | 抓某時段或某 ID 周邊的時間軸 |
| Get Observation by ID | 用 ID 取單筆完整資料 |
| File History | 查特定檔案的修改歷史 |
| Concept Search | 用概念標籤(如 "auth"、"caching")搜 |
| Filter by Type | 只看 decision / bug-fix / refactor 等類型 |
| Recent Activity | 列出最近的觀察(預設最後 N 筆) |
| Cross-Session Search | 跨多個 session 找一致模式 |
mem-search 執行於 fork 出去的 subagent，搜尋的中間結果不會留在主對話的 context。Claude 只將最後的相關摘要拉回。相比之下，MCP 工具定義會永久佔用 context，token 消耗較高。
Claude-Mem 內建一個 React 寫的 Web Viewer,跑在本機 http://localhost:37777(或你 user 對應的 port)。打開瀏覽器就能即時看到記憶串流、搜尋整個歷史、管理設定。
/api/observation/{id} 取完整內容,方便給其他工具引用。新版的預設 port 是 37700 + (uid % 100),所以同一台機器不同 OS 使用者自動分開不衝突。如果你之前用的是固定 37777 又被別的程式占用,可以在 ~/.claude-mem/settings.json 設定 CLAUDE_MEM_WORKER_PORT 換掉。
Claude-Mem 記錄 session 中所有工具呼叫的輸入與輸出，包含檔案內容、bash 輸出、使用者 prompt。資料主要儲存於本機，但壓縮階段會將摘要送至 Anthropic API。在 terminal 處理 secret 時須留意此行為。
解決方法是用 <private> 標籤把不想被記下來的內容包起來:
這是我的 API key 設定流程,請幫我看一下格式對不對: <private> AWS_ACCESS_KEY=AKIA... DATABASE_URL=postgres://user:pass@host/db </private> 格式應該是 .env 還是 JSON 比較適合?
標籤剝除是發生在 hook 邊緣 處理,代表 private 內容根本進不到 worker 與 database。但這要你「記得用」,Claude-Mem 不會幫你自動偵測 secret。
~/.claude-mem/ 是可搜尋的工作紀錄，敏感性與 shell history 相近。若有將 ~/.bash_history 排除於備份之外的習慣，建議一併排除此目錄。
同一台機器想跑工作專用、私人專用兩套記憶?Claude-Mem 支援多 profile,用環境變數切換即可。Port 也會自動分開不衝突。
下列內容整理自 Reddit、GitHub Issues 及社群評測，涵蓋實際使用回饋與已知限制。
不要安裝完就期待立刻有效。先跑一個完整工作流(read 檔案、改 code、跑測試)讓它有東西記,下一個 session 才會看到效果。
每週開一次 localhost:37777 看記憶有沒有亂掉。如果發現很多無意義的 observation(例如重複的 ls 結果),代表你的工作流可能讓它抓了太多噪音。
claude-mem 以資料夾路徑為單位區分記憶。如果你在 home 目錄做了五個不同專案,記憶會混在一起。每個專案用獨立 git repo 資料夾。
標籤是手動的,人會忘。比較安全的做法是把 .env 載入跟 secret 操作放到 Claude Code 沒接觸過的 shell session。
因為 issue #618,在重度使用前先用一個小專案測一週,看 token 消耗的差異。如果暴增就先暫停。
原生 Windows 安裝會踩 npm 路徑問題。WSL2 + Ubuntu 是官方文件唯一明確支援的 Windows 路徑。
把 mcp-search server 設到 Claude Desktop 的 claude_desktop_config.json,可以在桌面版聊天裡直接搜尋你 terminal 的工作記憶。
幾週後這資料夾就是你的工作智慧財產。設個 rsync 或 Time Machine 排除路徑,但要備份。換機器時直接拷過去就接得回來。
「Uses too much tokens」這個 issue 是 claude-mem 目前最大的開放問題。在投入生產用之前先去 GitHub 看當前狀態。
claude-mem 內建 troubleshoot skill,描述你遇到的問題就會自動診斷。不必先去 GitHub 翻 issue。
Claude Code 記憶方案不只 claude-mem 一種。可選項包括官方的 CLAUDE.md、Anthropic 內建的 Memory feature、Cole Medin 的 claude-memory-compiler、memsearch、Omega 等。以下比較各方案的差異與適用情境。
| 方案 | 搜尋能力 | 自動捕捉 | 儲存 | 適合 |
|---|---|---|---|---|
| CLAUDE.md | 無 | 手動 | 靜態檔 | 小專案、團隊共享規則 |
| Auto Memory(官方) | 弱 | 自動 | 無結構 | 個人偏好、輕量記憶 |
| claude-mem | 三層 + 語意 | 每個工具呼叫 | SQLite + Chroma | 長期專案、需要回顧決策 |
| memsearch | 語意 + 結構 | 自動 | Markdown + Milvus | 需要可讀、可 git 追蹤的記憶 |
| claude-memory-compiler | 中 | 自動 | 知識文章 | 愛 Karpathy 風格的學習筆記 |
常見問題與解法整理如下，涵蓋安裝失敗、port 衝突、token 消耗異常及隱私控制等議題。
npm install -g claude-mem。改用 npx claude-mem install 或在 Claude Code 裡用 /plugin install claude-mem。然後完全退出 Claude Code 再開。37700 + (uid % 100),不一定是 37777。看 ~/.claude-mem/settings.json 裡的 workerPort。或直接設環境變數 CLAUDE_MEM_WORKER_PORT。npm: The term 'npm' is not recognized 之類的問題。<private> 標籤或避免讓 Claude 讀那個檔。~/.claude-mem/ 整個資料夾到新機器,SQLite + Chroma 索引都在裡面。沒有官方 export 指令,但因為是 SQLite,你可以用任何 sqlite3 工具讀。