本書目錄
10 章節 · 約 15 分鐘讀完
Claude-Mem 解決的問題
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?」它能秒答。
它解決的三個具體痛點
架構決策不必重講:「為什麼這個服務用 PostgreSQL 而不是 Redis?」之類的回答只需講一次,以後 session 自動帶入。
**同樣的 bug 不必修兩次:**修過的 Docker volume mount 錯誤,下次出現會直接被認出來。
**token 消耗下降:**原作者宣稱長期任務可降低 95% 的 token 用量(但這個數字有爭議,見第 8 章)。
三層檢索架構說明
Claude-Mem 採用漸進式揭露（Progressive Disclosure）三層檢索，避免一次將所有記憶載入 context 消耗大量 token，只在需要完整細節時才往下展開。
Tier 1
Index 層 — 標題與時間戳
- 列出符合查詢的觀察 ID、標題、類型、時間。Claude 先看這個,判斷哪些可能相關。
- ~50–100 tokens / 結果
Tier 2
Timeline 層 — 上下文敘事
- 提供特定觀察前後的時間軸,讓 Claude 理解事件流但不展開完整內容。
- 中等 token 消耗
Tier 3
Full Details 層 — 完整觀察
- 只在 Claude 認為「這條 ID 真的需要」時才抓完整資料。含 facts、narrative、concepts 等欄位。
- ~500–1000 tokens / 結果
依官方文件，這套漸進檢索比一次全部載入節省約 10 倍 token。mem-search 執行於 fork 出去的 subagent，搜尋的中間步驟不會影響主對話的 context window。
底層技術元件
SQLite(
~/.claude-mem/claude-mem.db):結構化 observation 儲存。ChromaDB:向量嵌入,做語意搜尋。
Bun + uv:第一次安裝時自動裝上,Bun 跑 worker,uv 是 Chroma 的 Python 套件管理器。
Worker Service:Express API,跑在 port
37700 + (uid % 100),預設舊版是固定37777。6 個 Hooks:Setup、SessionStart、UserPromptSubmit、PreToolUse(Read)、PostToolUse、Stop。
正確的安裝方式與常見錯誤
安裝後沒有出現記憶功能，通常是因為執行了 npm install -g claude-mem。該指令只安裝函式庫，不會向 Claude Code 註冊 hook，也不會啟動背景 worker。
方法 A:從 Claude Code 內部安裝(官方推薦)
打開 Claude Code,進到任何一個 session,輸入這兩行:
claude code
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem然後完全離開 Claude Code、再開一次。注意是「完全退出」,不是 /clear。重啟之後 hook 會註冊、worker 會啟動。
方法 B:用 npx(不要用 npm install -g)
terminal
npx claude-mem install這條指令會:檢查 Node 是否 ≥ 18、自動裝 Bun 與 uv、註冊 hooks 到 ~/.claude/plugins/、建立 ~/.claude-mem/ 目錄與預設 settings.json、啟動 worker。
驗證安裝成功
重啟 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。
結束 session
用
/exit正常離開,或直接關掉 terminal。Stop hook 會觸發壓縮,把這次 session 的觀察整理成結構化記憶。壓縮大約需要幾十秒,在背景跑,不會擋你。下一次開啟 Claude Code
同一個資料夾再開 Claude Code,SessionStart hook 會比對你正在做的事跟過去的記憶,把相關的 observation 注入 context。你會在最上方看到一個摘要區塊。
直接用自然語言問它
「我們上一次怎麼處理 auth 那個 bug?」這類問題會自動觸發 mem-search skill,Claude 會在 subagent 裡搜尋本機記憶,只回傳相關片段。
日常查詢:記憶搜尋操作
查詢記憶以自然語言輸入即可。Claude 會判斷是否需要搜尋本機記憶，決定查詢時 UI 會顯示 mem-search skill 被觸發。
5.1萬用查詢句型
下面這些句子任何一句都會觸發 mem-search:
natural language queries
# 回顧
"我們上次做了什麼?"
"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?"5.2mem-search skill 的 10 種搜尋模式
| 操作 | 說明 |
|---|---|
| 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 找一致模式 |
Web Viewer:看見你的記憶
Claude-Mem 內建一個 React 寫的 Web Viewer,跑在本機 http://localhost:37777(或你 user 對應的 port)。打開瀏覽器就能即時看到記憶串流、搜尋整個歷史、管理設定。
Viewer UI 能做什麼
**即時觀察串流:**每次 Claude 跑工具,你能在 viewer 看到新的 observation 跑進來。
**全文 + 語意搜尋:**不必開 Claude Code,直接在瀏覽器搜過去的工作。
**切換版本通道:**在 Settings 可以打開 beta features。
**Smart Trash:**誤刪的記憶可以從垃圾桶救回來。
**引用觀察 ID:**直接連到
/api/observation/{id}取完整內容,方便給其他工具引用。
隱私控制:<private> 標籤
Claude-Mem 記錄 session 中所有工具呼叫的輸入與輸出，包含檔案內容、bash 輸出、使用者 prompt。資料主要儲存於本機，但壓縮階段會將摘要送至 Anthropic API。在 terminal 處理 secret 時須留意此行為。
解決方法是用 <private> 標籤把不想被記下來的內容包起來:
prompt
這是我的 API key 設定流程,請幫我看一下格式對不對:
<private>
AWS_ACCESS_KEY=AKIA...
DATABASE_URL=postgres://user:pass@host/db
</private>
格式應該是 .env 還是 JSON 比較適合?標籤剝除是發生在 hook 邊緣 處理,代表 private 內容根本進不到 worker 與 database。但這要你「記得用」,Claude-Mem 不會幫你自動偵測 secret。
把記憶分隔開:多 Profile 模式
同一台機器想跑工作專用、私人專用兩套記憶?Claude-Mem 支援多 profile,用環境變數切換即可。Port 也會自動分開不衝突。
社群整理的實用技巧 10 則
下列內容整理自 Reddit、GitHub Issues 及社群評測，涵蓋實際使用回饋與已知限制。
Found an open-source tool that gives Claude Persistent Memory via SQLite and reduces token usage by 95% on long-running tasks
**實戰價值:**這是引爆 claude-mem 的原帖。95% 是長期任務的數字,日常使用不會那麼誇張。
Hit 5-hour usage limit in a SINGLE session with ~140k tokens
**反面教訓:**有報告指出 PostToolUse hook 每次都呼叫 agent-sdk 做摘要,Pro 方案的 5 小時 rolling limit 會被吃光。GitHub issue #618 還在追蹤。
Anytime it uses observation instead of relearning something… that's basically 8× more efficient to run off of Claude-mem observations
**關鍵指標:**不要看 95%,看 8×。每命中一次記憶,就是 8 倍效率。代表「記憶命中率」比「壓縮率」更重要。
CLAUDE.md is a blunt instrument: it loads the entire file into context at session start, regardless of relevance.
**選型建議:**專案小用 CLAUDE.md 足夠;專案大、檔案多就用 claude-mem。兩個可以並存。
On a managed machine (corporate laptop, shared dev box) this is a real amount of "stuff" — port 37777, Bun, uv, SQLite all auto-install
**企業限制:**如果你在公司限制嚴格的 laptop 上,先確認 port 37777(或新版 37700+)沒被擋,uv 跟 Bun 能裝。
Once you've built up a few weeks of memory, switching away from Claude Code feels worse. Memory is a soft form of stickiness.
**長期考量:**累積幾週後,離開 Claude Code 的成本會升高。記憶資料是 SQLite,理論上可以匯出但目前沒有官方匯出工具。
10 個社群整理的實用招數
01
裝完先做「示範 session」
不要安裝完就期待立刻有效。先跑一個完整工作流(read 檔案、改 code、跑測試)讓它有東西記,下一個 session 才會看到效果。
02
定期看 Web Viewer 確認記憶品質
每週開一次 localhost:37777 看記憶有沒有亂掉。如果發現很多無意義的 observation(例如重複的 ls 結果),代表你的工作流可能讓它抓了太多噪音。
03
不要在同一個資料夾混做太多專案
claude-mem 以資料夾路徑為單位區分記憶。如果你在 home 目錄做了五個不同專案,記憶會混在一起。每個專案用獨立 git repo 資料夾。
04
用 <private> 包 secrets,但別依賴它
標籤是手動的,人會忘。比較安全的做法是把 .env 載入跟 secret 操作放到 Claude Code 沒接觸過的 shell session。
05
注意 token 消耗,先在便宜的任務上試
因為 issue #618,在重度使用前先用一個小專案測一週,看 token 消耗的差異。如果暴增就先暫停。
06
Windows 一律走 WSL2
原生 Windows 安裝會踩 npm 路徑問題。WSL2 + Ubuntu 是官方文件唯一明確支援的 Windows 路徑。
07
結合 Claude Desktop MCP 一起用
把 mcp-search server 設到 Claude Desktop 的 claude_desktop_config.json,可以在桌面版聊天裡直接搜尋你 terminal 的工作記憶。
08
備份 ~/.claude-mem/ 資料夾
幾週後這資料夾就是你的工作智慧財產。設個 rsync 或 Time Machine 排除路徑,但要備份。換機器時直接拷過去就接得回來。
09
觀察 GitHub issue #618 的進度
「Uses too much tokens」這個 issue 是 claude-mem 目前最大的開放問題。在投入生產用之前先去 GitHub 看當前狀態。
10
把 troubleshoot skill 當第一線客服
claude-mem 內建 troubleshoot skill,描述你遇到的問題就會自動診斷。不必先去 GitHub 翻 issue。
vs CLAUDE.md / Auto Memory / 競品
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 風格的學習筆記 |
判斷流程
專案 < 1000 行 + 規則簡單 → CLAUDE.md 就夠。
個人偏好(語氣、coding style) → Anthropic 內建 Memory 就好。
長期專案(數週以上)+ 你常常忘記昨天做了什麼 → claude-mem。
記憶要能 git diff 追蹤、團隊共享 → memsearch。
token 預算很緊 → 先做小規模測試,評估 issue #618 是否影響你。
疑難排解 & FAQ
常見問題與解法整理如下，涵蓋安裝失敗、port 衝突、token 消耗異常及隱私控制等議題。
Q.裝完沒有任何記憶,新 session 上方也沒有任何摘要,怎麼辦?
99% 是因為你跑了 npm install -g claude-mem。改用 npx claude-mem install 或在 Claude Code 裡用 /plugin install claude-mem。然後完全退出 Claude Code 再開。
Q.localhost:37777 打不開?
新版預設 port 是 37700 + (uid % 100),不一定是 37777。看 ~/.claude-mem/settings.json 裡的 workerPort。或直接設環境變數 CLAUDE_MEM_WORKER_PORT。
Q.Token 用量爆增,5 小時 limit 一下就到?
這是已知 issue #618。臨時解法:(1) 在 settings 把 PostToolUse 的摘要頻率降低;(2) 改成只在 session 結束才摘要;(3) 大型 session 時暫時 disable plugin。長期看官方 patch。
Q.Windows 原生不能用嗎?
README 寫有 Windows Setup Notes 但官方推薦 WSL2。原生 PowerShell 路徑會碰到 npm: The term 'npm' is not recognized 之類的問題。
Q.怎麼確認某個敏感檔案沒被記下來?
用 Web Viewer 搜該檔名,看 observation 列表。如果有,從 viewer 的 Smart Trash 把它移到垃圾桶。長期應該用 <private> 標籤或避免讓 Claude 讀那個檔。
Q.記憶可以匯出 / 跨機器搬嗎?
可以,直接拷貝 ~/.claude-mem/ 整個資料夾到新機器,SQLite + Chroma 索引都在裡面。沒有官方 export 指令,但因為是 SQLite,你可以用任何 sqlite3 工具讀。
Q.跟 Cursor、Gemini CLI 等其他 AI tool 相容嗎?
官方 README 提到也支援 Gemini CLI(restart 即生效)。Cursor 目前不在官方支援列表,但 SQLite 資料庫是開放結構,理論上可寫 adapter。
Q.OpenClaw gateway 是什麼?需要嗎?
OpenClaw 是個 self-hosted gateway。可以一行指令把 claude-mem 裝成持久外掛、加上 Telegram/Discord/Slack 的觀察通知。一般本機用戶不需要,團隊或自架伺服器才會用到。
Useful Links
About This Guide
內容彙整自 Claude-Mem 官方文件、GitHub README、andrew.ooo 深度評測、DataCamp 教學、Medium 開發者實測、以及 r/ClaudeAI 社群討論。
授權注意:Claude-Mem 是 AGPL-3.0,部分元件(Ragtime)為 PolyForm Noncommercial。商用前請確認。
Editorial & design — Tenten
Updated · May 2026