一句話結論
claude-mem 是一套掛在 AI coding agent 上的「本機長期記憶壓縮系統」：它用 5 個 lifecycle hooks 自動把你與 Claude Code 的每一次工具使用記下來，交給一個小模型壓縮成語意化摘要（observation），存進本機的 SQLite ＋向量資料庫，下一個 session 開始時再自動把相關上下文注入回去。它不是叫你手寫 CLAUDE.md，而是讓記憶自動發生。
截至 2026 年 10 月 11 日，官方 repo 已累積 99,675 顆星、8,739 次 fork，授權 Apache-2.0，npm 最新版為 13.35.0（2026-10-09 發布），也是 Trendshift 上的熱門榜常客。
| 項目 | 內容 |
|---|---|
| 專案 | thedotmack/claude-mem |
| 主要語言 | TypeScript（同時內含 Python 的 Chroma 服務） |
| 授權 | Apache-2.0（作者 Alex Newman，@thedotmack） |
| Stars / Forks | 99,675 / 8,739（2026-10-11 查詢） |
| 最新版本 | npm 13.35.0（2026-10-09），累積 252 個版本 |
| 支援宿主 | Claude Code、Cursor、Windsurf、Codex CLI、OpenCode、Antigravity CLI、Grok Bot、T3 Code、Pi、OMP、DeepSeek Harness、OpenClaw |
| 系統需求 | Node.js ≥ 20、Bun ≥ 1.0（自動安裝）、uv（自動安裝）、SQLite（內建） |
為什麼 AI coding agent 需要記憶？
因為「同一個專案的上下文」是最貴、也最容易蒸發的資源。實際痛點有三個：
- 每次開新 session 都要重新交代一次。 你昨天花了兩小時讓 Claude 搞懂這個 repo 的目錄慣例、部署流程、踩過的坑，今天它全部忘光。
/compact只是把當前對話壓短，不是累積知識。 壓縮完的摘要只活在這個 session 裡，session 一關就沒了。CLAUDE.md要靠人維護。 你必須記得把「這次學到的事」寫回去，而且它會越寫越長、越長越貴。
claude-mem 的解法和這三條正面對撞：自動捕捉（不用你動手）、持久化（跨 session 存在本機資料庫）、選擇性注入（只把相關的撈出來，不是把整包塞回去）。官方文件把最後一點叫做 progressive disclosure（漸進式揭露），也是它省 token 的核心。
安裝：一行指令，或從 plugin marketplace
最短路徑是一行 npx：
# Claude Code（預設）
npx claude-mem install
# 其他宿主，加 --ide 參數
npx claude-mem install --ide opencode # OpenCode 1.3.4+ / 2.x
npx claude-mem install --ide t3code # T3 Code（Codex + Claude Code）
npx claude-mem install --ide antigravity # Antigravity CLI
npx claude-mem install --ide pi # Pi 原生擴充
npx claude-mem install --ide dsh --dsh-profile tui # DeepSeek Harness
或者直接在 Claude Code 裡面裝：
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
重新啟動 Claude Code，新 session 就會自動帶入上一個 session 的上下文。
安裝流程分三段：裝 runtime（自動補 Bun 與 uv，並偵測你機器上的 IDE 讓你多選）→ 登入（OAuth 裝置碼，免信用卡）→ 選記憶供應商。想完全跳過登入也可以：
# 完全不碰 cmem.ai，直接用你的 Claude 方案跑記憶壓縮
npx claude-mem install --provider claude
⚠️ 最容易踩的坑：
npm install -g claude-mem只會裝到 SDK／library，不會註冊 hook、也不會啟動 worker 服務。一定要用npx claude-mem install或/plugin指令。
它怎麼運作？5 個 hook ＋ 一個本機 worker
整個系統可以想成一條「捕捉 → 壓縮 → 儲存 → 注入」的資料流：
Claude Code session
│ UserPromptSubmit / PostToolUse / Stop / SessionEnd
▼
5 個 lifecycle hooks（hook-command.ts 編排）
│ 把工具使用事件 enqueue 進 worker
▼
本機 Worker Daemon（Express，port = 37700 + uid % 100）
├─ SDK Agent：呼叫小模型把事件壓成 observation / summary
├─ PendingMessageStore：佇列與重試，worker 掛掉也不擋你的 session
└─ ChromaSync：同步向量嵌入
▼
儲存層
├─ SQLite（claude-mem.db）：sessions / observations / summaries / user_prompts
└─ ChromaDB（chroma.sqlite3）：語意搜尋用的向量
▼
下個 session 的 SessionStart → 語意化上下文注入
Hook 的實際分工如下：
| Hook 事件 | 做什麼 | Timeout |
|---|---|---|
| Setup | 版本標記檢查，版本不符時提示你跑 npx claude-mem repair | 60s |
| SessionStart | 啟動 worker、注入上一次的上下文 | 60s |
| UserPromptSubmit | 註冊 session、啟動 SDK agent、做語意化注入 | 60s |
| PostToolUse | 捕捉工具使用，寫入 worker 佇列 | 120s |
| Stop（Summary） | 請 SDK agent 產生 session 摘要 | 120s |
| SessionEnd | 關閉 session、清空待處理訊息 | 30s |
有兩個設計值得稱讚：
- worker 掛掉不會擋住你：傳輸層錯誤（ECONNREFUSED、timeout、5xx）一律
exit 0，只有「客戶端自己的 bug」（4xx、TypeError）才exit 2。也就是說，記憶服務壞掉最糟的情況是「這次沒記到」，不會變成「Claude Code 打不開」。 - 重複寫入會去重：以
SHA256(memory_session_id + title + narrative)的前 16 碼當content_hash，30 秒內相同內容只留一筆，避免同一件事被記五次。
檢索：13.35 版的 mem_search 三層漸進式揭露
記憶存得多不是重點，撈得準又便宜才是。claude-mem 13.35.0 把檢索收斂成單一工具 mem_search，強制走三層：
| 層 | 回傳什麼 | 成本概念 |
|---|---|---|
| step 1/3 index | 精簡索引（標題＋ID） | 約 50–100 tokens/筆 |
| step 2/3 context | 你挑選的 anchor 前後時間脈絡 | 中等 |
| step 3/3 details | 只針對選定 ID 取完整內容 | 約 500–1,000 tokens/筆 |
Agent 可以在任何一層停下——如果索引標題就足以回答問題，它不會去抓細節。每一輪回覆結尾都會附上可讀的 Continue with: 游標（27 字元，ms_ 開頭），搜尋範圍、選項與已揭露 ID 都存在伺服器端，15 分鐘後過期，所以 agent 不需要在對話裡搬運整包搜尋結果。
幾個硬性上限值得記住（避免你以為壞掉）：
limit最多 20 筆索引；maxDetails預設 3、上限 5；depthBefore／depthAfter預設 2、上限 3- 查詢字串上限 500 字元／1 KiB UTF-8
mode: "auto"會用排名式詞彙檢索自動挑 anchor，完全不呼叫 LLM（所以不花模型費用）
另外有三個工具仍保留給舊客戶端與進階過濾：search、timeline、get_observations；需要主動寫入記憶時則用新的 save_memory：
// 請 agent 直接記下一條偏好或決策（worker runtime）
save_memory({
text: "本專案的 DB migration 一律用 alembic，不要手寫 SQL",
title: "Migration 慣例",
project: "my-app"
})
常用設定：~/.claude-mem/settings.json
所有設定集中在這個檔案（首次執行自動建立）。以下是實務上最常動的幾個：
| 設定 | 預設 | 說明 |
|---|---|---|
CLAUDE_MEM_PROVIDER | claude | 記憶壓縮用哪家：claude／gemini／openrouter／codex／cmem |
CLAUDE_MEM_MODEL | claude-haiku-4-5-20251001 | 壓縮用的模型；也可用 claude-sonnet-5、claude-opus-4-8 |
CLAUDE_MEM_MODE | code | 模式與輸出語言，如 code--zh（簡中）、code--ja、code--es |
CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | 每次注入幾筆 observation |
CLAUDE_MEM_WORKER_PORT | 37700 + (uid % 100) | worker 埠號，同機多使用者自動錯開 |
CLAUDE_MEM_DATA_DIR | ~/.claude-mem | 資料根目錄（DB、Chroma、log、settings 全在底下） |
CLAUDE_MEM_SKIP_TOOLS | 略 | 不記錄的工具清單（預設排除 TodoWrite、AskUserQuestion 等） |
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES | false | 是否在所有宿主注入彼此（Claude Code + Codex）的記憶 |
實務建議（來自官方 Production Guide，23 天、3,400+ 筆 observation 的實測）：
{
"CLAUDE_MEM_MAX_CONCURRENT_AGENTS": 3,
"CLAUDE_MEM_SEMANTIC_INJECT": true,
"CLAUDE_MEM_SEMANTIC_INJECT_LIMIT": 5,
"CLAUDE_MEM_TIER_ROUTING_ENABLED": true
}
其中 CLAUDE_MEM_TIER_ROUTING_ENABLED 官方實測可省約 52% 成本且不掉品質（把不同難度的壓縮工作分派給不同等級模型），SEMANTIC_INJECT 則是把「注入最近幾筆」升級成「注入最相關幾筆」的關鍵開關。
隱私控制
<private>標籤：把不想被存進記憶的內容包起來，例如`<private>` 這段 API key 與內部主機名不要記 `</private>`。- 資料落地位置：預設全在本機
~/.claude-mem/（claude-mem.db、chroma.sqlite3、logs）。要用雲端同步（cmem.ai）是選項，不是強制。 - Markdown 筆記匯入是 opt-in：設定
CLAUDE_MEM_MEMORY_WATCH_ROOTS才會監看指定資料夾（最多 8 個），而且會跳過隱藏檔、symlink 與超過 64 KiB 的檔案，也不會改寫你的原始檔。 - 原生記憶橋接：當你讀取 Claude Code／Codex 自己的記憶資料夾時，
PreToolUsehook 會自動補一份mem_search結果當上下文（上限 10,000 字元），可用CLAUDE_MEM_MEMORY_SEARCH_HOOK_ENABLED=false關閉。
成本、資料量與維運
「記憶」不是免費的：每筆 observation 都要呼叫模型壓縮一次。好消息是壓縮模型可以選便宜的小模型（預設就是 Haiku 等級），壞消息是用得越勤，壓縮費用越高。官方 installer 預設會引導你註冊 CMEM Pro（含 30 天試用，讓記憶「跑在你的方案之外」），試用到期後可以改用自己的 OpenRouter／Gemini key、或直接回歸 Anthropic 方案來負擔：
| 供應商 | 記憶壓縮跑在哪 | 費用歸屬 | 適用情境 |
|---|---|---|---|
| CMEM Pro（預設） | cmem.ai 的 cmem-observer 模型 | 訂閱制，前 30 天試用 | 不想管 API key、想先試效果 |
| OpenRouter | 你的 OpenRouter 額度 | 依用量 | 想自由換模型、有現成額度 |
| Gemini API | 你的 Gemini key | 依用量（有免費額度） | 已有免費 Gemini 額度 |
| Anthropic 方案 | 你的 Claude 方案額度 | 併入方案用量 | 不想多付一份錢 |
--provider host | 本機已登入的 agent（loopback） | 無需 API key | 離線／自架派 |
--provider codex | 你的 ChatGPT 訂閱（透過本機 Codex CLI） | 併入訂閱 | 已經有 ChatGPT 訂閱 |
資料量成長可以預期（官方實測、每天正常開發用）：
| 指標 | 每天 | 每月 |
|---|---|---|
| observation 筆數 | 約 120 | 約 3,600 |
| session summary | 約 40 | 約 1,200 |
| SQLite 檔案 | 約 0.8 MB | 約 24 MB |
| Chroma 向量庫 | 約 4 MB | 約 120 MB |
也就是說，一年下來大約是「幾百 MB」等級，本機硬碟完全吃得下，但備份與清理要有計畫。日常維運指令：
# worker 健康狀態
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT:-37777}/api/health"
# 資料庫統計
sqlite3 ~/.claude-mem/claude-mem.db "
SELECT 'observations' AS metric, COUNT(*) AS value FROM observations
UNION ALL SELECT 'summaries', COUNT(*) FROM session_summaries
UNION ALL SELECT 'pending', COUNT(*) FROM pending_messages WHERE status='pending'
UNION ALL SELECT 'active_sessions', COUNT(*) FROM sdk_sessions WHERE status='active';"
# 同機／多機同步（以 created_at + title 去重，可重複執行）
claude-mem-sync push <remote-host>
claude-mem-sync status <remote-host>
健康指標的警戒線（官方 Production Guide）：
| 指標 | 健康值 | 警戒值 | 處理 |
|---|---|---|---|
pending_messages（pending） | 0–5 | > 10 | 看 worker log，必要時重啟 |
pending_messages（failed） | 0 | 持續增加 | 可能是 circuit breaker 被觸發 |
sdk_sessions（active） | 0–3 | > 5 卡住 | 孤兒 session，重啟 worker |
| WAL 檔案大小 | < 10 MB | > 20 MB | 執行 PRAGMA wal_checkpoint(TRUNCATE) |
| 每日錯誤數 | 0–2 | > 10 | 檢查 log 模式 |
和替代方案比一比
| 方案 | 型態 | 授權 | 自動捕捉 | 檢索方式 | 最適合 |
|---|---|---|---|---|---|
| claude-mem | hook ＋本機 worker ＋MCP | Apache-2.0 | ✅ 自動（hooks） | mem_search 漸進式＋向量＋FTS | 想「開箱就有記憶」的 Claude Code／Codex 使用者 |
CLAUDE.md／專案指令 | 純文字檔 | — | ❌ 手寫維護 | 每次全量注入 | 只放少量、穩定的專案規則 |
| Claude Code 內建 compact／resume | 對話內 | 專有 | ⚠️ 半自動 | 只在同一 session | 單次長任務 |
| mem0 | 記憶層 API／服務（約 6.7 萬星，Apache-2.0） | Apache-2.0 | ❌ 需自行整合 | 向量檢索 API | 自己開發產品、要把記憶做進 App |
| basic-memory | Markdown ＋知識圖譜 ＋MCP（約 4,100 星，AGPL-3.0） | AGPL-3.0 | ⚠️ 筆記為主 | 知識圖譜／MCP | 想用 Obsidian 生態、堅持 markdown 可讀可帶走 |
| EverOS | 代理記憶作業系統 | 開源 | ⚠️ 需整合 | 超圖記憶 | 研究／多代理架構實驗 |
選型建議很簡單：你的痛點是「跟 AI coding agent 的對話記憶」就選 claude-mem；痛點是「產品裡要有記憶功能」就選 mem0；痛點是「知識要能自己帶著走」就選 basic-memory。
6 個實務陷阱
npm i -g claude-mem不等於安裝完成。 只裝 SDK，hook 與 worker 都不會註冊。請用npx claude-mem install。- 埠號衝突。 預設埠是
37700 + (uid % 100)，同機多個 profile 用同一組 UID 時仍可能撞到；設CLAUDE_MEM_WORKER_PORT固定值後重啟 worker。 - 版本升級後 hook 對不上。 用
claude plugin update之類外部方式升級後，Setup hook 會提示你跑npx claude-mem repair，照做即可（hook 永遠 exit 0，不會擋住 Claude Code）。 - 記憶壓縮會花錢。 用最便宜的小模型＋開啟 tier routing；不要把
CLAUDE_MEM_CONTEXT_OBSERVATIONS一路往上調。 - CMEM 代幣要小心。 repo README 明確寫著 CMEM 是第三方發行的代幣，只是被作者「公開擁抱」當社群催化劑。這與 claude-mem 本體的 Apache-2.0 開源授權是兩件事，遇到任何要求你買代幣才能解鎖功能的說法，請自己判斷真偽。
- 繁體中文沒有專屬 mode。 內建語言模式目前是
code--zh（簡體中文）與code--ja（日文）等；繁體使用者想要繁中 observation，得用/mode-creator自建模式，或接受簡中輸出。
站內延伸閱讀
- Zed 編輯器完整教學 2026：9.1 萬星 Rust 極速開源編輯器，Agent Panel、ACP 外部代理（Claude Code／Codex）、MCP 與自架 Ollama
- MCP 完整教學 2026：Model Context Protocol 是什麼、怎麼接上 Claude Code／Cursor
- Agent Skills 完整教學：Addy Osmani 開源 8.5 萬星專案，讓 Claude Code、Cursor 自動遵循工程紀律（2026）
- LibreChat 完整教學 2026：4.5 萬星自架 AI 聊天平台，整合 OpenAI／Claude／Gemini／Ollama
- EverOS：開源自演化 AI 代理長期記憶作業系統
資料來源
- GitHub：thedotmack/claude-mem（README、CHANGELOG 13.35.0、docs/architecture-overview.md、docs/production-guide.md、docs/codex-provider.md、docs/security.md）
- 官方文件：claude-mem 文件站（Installation、Configuration、Modes & Languages、Troubleshooting、Architecture）
- npm：claude-mem 套件頁（latest 13.35.0）
- GitHub API 查詢：stars／forks／授權／語言／建立與更新時間（2026-10-11）