Claude Code 每次關掉重開都忘了上次改過什麼，於是很多人去裝 10 萬星的 claude-mem。它能裝，但安裝器別一路回車。 2026 年 10 月的 v15 安裝器默認選中 CMEM Pro 託管觀察器，30 天試用結束後按 $30/月計費。想零月費，可以安裝時加 --provider claude，或者裝完把 observer 換成自己的 key。
這不是一篇「裝上就永久記住」的宣傳稿。 下面按「官方自報 / 第三方單例 / 我實測 / 未知」分開寫，所有數據覈對時間爲 2026-10-30。
claude-mem 核心要點
先看一張表，決定要不要往下讀。
| 要點 | 說明 | 對你的影響 |
|---|---|---|
| 熱度 | GitHub thedotmack/claude-mem，105,017 stars，Apache-2.0（2026-10-30 GitHub API 讀數） |
星數只代表熱度，好不好用還得自己判斷 |
| 版本 | npm 與 GitHub release 最新都是 15.6.0（2026-10-29）；README 徽章寫 15.7.0，兩者對不上 | 以 npm 版本爲準，別被徽章誤導 |
| 默認收費 | 安裝器默認選 CMEM Pro，試用 30 天后 $30/月 | 不想訂閱就換路線 |
| 零月費路線 | --provider claude 用自己的 Claude 套餐，或裝完改成自帶 key |
錢從套餐額度或 API 餘額裏出 |
| 不是純本地 | observer 模型會讀取你的工具調用內容 | 涉及敏感倉庫時要先想清楚 |
📷 截圖位，編輯時補：GitHub 倉庫首頁（
thedotmack/claude-mem，顯示星數與最新 release）
claude-mem 到底記什麼
一句話：claude-mem 是一個跑在本機的記憶層，不是新的聊天模型，也不是雲筆記。它抓取會話中「發生過的事」，壓縮後存起來，下次開會話時再喂回給 Claude。
整個流水線分 5 段：
- hooks（生命週期鉤子）：Claude Code 在會話開始、提交 prompt、工具調用前後、停止和結束時會觸發事件，claude-mem 在這些位置掛了鉤子。
- worker：本機用 Bun 運行的一個 HTTP 服務，負責接收 hook 事件。默認端口是
37700 + (uid % 100)，所以不一定是 37700。 - observer（觀察器模型）：worker 把原始工具調用交給一個模型，壓縮成結構化的 observation。
- observation（觀察記錄）：每條包含類型、標題、敘述和涉及文件，寫入
~/.claude-mem/claude-mem.db（SQLite），向量索引放在~/.claude-mem/chroma/（Chroma 是一個向量數據庫，用來做語義檢索）。 - 下次 SessionStart 注入：新會話開始時，自動注入當前項目最近的相關 observation，默認最多 50 條。Claude 還可以通過 MCP 工具（
search→timeline→get_observations三層）按需檢索更早的記憶。
需要注意，它只記錄被 hooks 抓到的內容。你在會話外想到的事、沒有經過工具調用的討論，不會自動進庫。另外，Claude Code 自帶的原生 memory（MEMORY.md）和 claude-mem 是兩套系統，默認會並行運行，不是同一個東西。
claude-mem 裝前 3 個硬條件
下面三條任何一條不滿足，都別急着裝：
- Claude Code ≥ 2.1.139：低於這個版本時，hook 的
args會被忽略，表現爲靜默不記錄，最難排查。先運行claude --version，版本不夠就運行claude update。 - Node 20+：npm 包聲明的是
^20.19.0 || >=22.12.0，用node -v確認。Bun（≥1.1.31）和 uv 由安裝器自動安裝。第三方單例在 Ubuntu 26.04 上測得 Bun、uv、Chroma 合計約佔 1.2 GB 磁盤。 - 能接受 observer 看到工具調用內容：無論選哪條路線，你的工具調用、prompt 和摘要素材都會發給所選的 observer provider。倉庫裏有密鑰、客戶數據或未公開代碼的，先別開。
Windows 用戶的 hooks 不需要 Git Bash，但裝完要重啓終端或 IDE，讓新的 PATH 生效。
claude-mem 3 條安裝路線怎麼選
| 路線 | 要不要 cmem 賬號 | 錢從哪出 | 內容發給誰 | 適合誰 |
|---|---|---|---|---|
| A：默認 CMEM Pro | 要，且試用需綁卡 | $30/月起，試用 30 天 | cmem.ai 託管觀察器 | 不想配 key、需要雲同步或多機 |
B：--provider claude |
不要 | 消耗 Claude 套餐額度 | Anthropic | 已有 Claude 訂閱 |
| C：B 裝完再換自帶 key | 不要 | 按 provider 用量計費 | 你配置的端點，例如 API易 apiyi.com | 想控制成本、已有 API 餘額 |
插件市場是另一種入口，下面單獨作爲路線 C’ 說明。第三條路線必須先走 B：openai-compatible 不是安裝器的 --provider 可選值，只能裝完後手動改 settings。
路線 A：默認 CMEM Pro（claude-mem 安裝器默認項）
- 運行
npx claude-mem install。 - 會看到什麼：第一步預選檢測到的 Agent 並安裝 runtime。第二步打印一個
XXXX-XXXX設備碼，打開瀏覽器做 OAuth 授權（登錄這一步不要卡）。第三步記憶 provider 默認選中 CMEM Pro，選中後會打開 checkout 或試用頁。 - 要注意的條款（官方定價頁，2026-10-30 覈對）：
- 試用需要信用卡或借記卡，預付卡不行。
- 計費從「試用結束」或「包含額度用完」開始，以先到者爲準。
- 自動升級設置可能把訂閱從 Pro 往上挪到 Heavy（$70/月）或 Max（$100/月）。很多教程只寫了「no card required」，漏掉了這一步。
- 怎麼算成功：安裝結束後會打印 Version、Plugin dir、IDEs、Account、Cloud sync、Worker URL，再跑後面的 5 項驗收。
路線 B：--provider claude，零月費安裝 claude-mem
- 運行
npx claude-mem install --provider claude。 - 只想保留一套記憶的話，改用
npx claude-mem install --provider claude --disable-auto-memory。這個參數會寫入CLAUDE_CODE_DISABLE_AUTO_MEMORY=1，關閉 Claude Code 原生的 auto-memory。 - 會看到什麼：
Skipping claude-mem login: --provider claude runs memory on your own Anthropic plan.、Cloud sync: OFF (local)、Auto-memory: left enabled（沒加 disable 參數時）。安裝器還會讓你選 observer 模型，選 Haiku，不要選 Opus。 - 怎麼算成功：全程沒有出現 cmem 登錄或付款頁面，
npx claude-mem doctor全部打勾。
源碼裏只有 claude 和 host 兩個 provider 免登錄。第三方實測 --provider openrouter 會停在 Waiting for OAuth login in the browser…。所以想用第三方 key，正確順序是先用 B 裝完，再改配置。
路線 C’：Claude Code 插件市場
- 在 Claude Code 裏輸入
/plugin marketplace add thedotmack/claude-mem。 - 再輸入
/plugin install claude-mem，然後重啓 Claude Code。 - 會看到什麼：第一場會話時 launcher 還在編譯，可能沒有任何記憶。想消除這個空窗，補跑一次
npx claude-mem install --provider claude即可。 - 千萬別用
npm install -g claude-mem：它只安裝 SDK 庫，不註冊 hooks，也不啓動 worker，還會遮住真正的 launcher。
claude-mem 裝完怎麼驗收：5 項檢查
先記住一點：第一場會話是「採集場」，本身沒有歷史可以注入，第二場纔會看到記憶。第一場就期待「它記得我」，很容易誤判爲失敗。
| # | 檢查項 | 命令 / 操作 | 怎麼算通過 |
|---|---|---|---|
| 1 | doctor | npx claude-mem doctor |
Bun、uv、Plugin、Hook launcher、Worker、Claude Code version（2.1.139+）、Chroma 全部 ✓ |
| 2 | status | npx claude-mem status |
worker 健康，並顯示端口號 |
| 3 | viewer | 瀏覽器打開 http://127.0.0.1:<PORT>/，記憶在 /viewer |
頁面能打開；跑過一場會話後能看到條目 |
| 4 | sqlite count | sqlite3 ~/.claude-mem/claude-mem.db "select count(*) from observations;" |
第一場會話結束後返回值大於 0 |
| 5 | context inject | curl "http://127.0.0.1:<PORT>/api/context/inject?project=<項目名>" |
返回內容就是下一場會話會注入的記憶 |
端口從 ~/.claude-mem/settings.json 的 CLAUDE_MEM_WORKER_PORT 讀取，也可以 curl http://127.0.0.1:<PORT>/api/health 確認。doctor 輸出中最容易出問題的是 Hook launcher 那一行。只要出現 not on PATH 或 is not the claude-mem hook launcher，都要先處理，再看其他項。
📷 截圖位，編輯時補：worker viewer 頁面（
/viewer，展示 observation 列表）
claude-mem 成本：官方「省 96%」與第三方「+4,226 tokens」
兩個數字都對，只是口徑不同，不能混用。
- 官方自報：4 條 observation 約 1,093 tokens，原始工作量 26,447 tokens，因此「省約 96%」。MCP 三層搜索「比全量注入省約 10 倍」。這些是項目方自己的估算，不是第三方審計。
- 第三方單例（ComputingForGeeks，2026-10-24，claude-mem 15.0.2，Sonnet via OpenRouter）：同一句「Reply with the single word ready」，不開 claude-mem 時輸入 28,489 tokens。開啓後即使記憶爲空，輸入也有 32,715 tokens，多出 +4,226 tokens（約 +14.8%），成本多 $0.010。這只是單機、單次、單項目的測試，不代表你的賬單。
結論放在前面：「省」指的是記憶本身比原始記錄緊湊，「多」指的是每場會話都要額外背一筆固定開銷。 項目越忙、注入條數越多，固定開銷越大。2026 年上半年的 Issue #618、#2469 都有用戶反映 tokens 很快被喫完。那是舊版本的體驗，不等同於 15.6.0 的現狀，但說明記憶從來不是免費的。
5 個 claude-mem 成本控制開關
CLAUDE_MEM_CONTEXT_OBSERVATIONS：默認 50，調到 10–20 能直接降低注入量。CLAUDE_MEM_SEMANTIC_INJECT：保持默認false。開啓後每條 prompt 都會追加相關記憶。CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES：保持默認false，否則會把所有宿主的記憶都注入進來。CLAUDE_MEM_DISABLE_TOOL_HOOKS=1：關閉工具調用級的 observation，只保留會話級摘要，省 tokens，也省進程開銷。CLAUDE_MEM_OPENAI_COMPAT_OBSERVATION_BATCH_SIZE：默認 1，事件堆積時再逐步調大，不要一上來就設成 32。
三條路線的費用對比
| 方案 | 計費方式 | 價格（美元） | 適合 |
|---|---|---|---|
| CMEM Pro | 訂閱 | $30/月，30 天試用（Heavy $70、Max $100） | 重度用戶、需要雲同步 |
| Claude 套餐 | 消耗訂閱額度 | 不單獨計費，但會和寫代碼搶額度 | 已有 Claude 訂閱 |
API易 claude-haiku-5-5 |
按量 | 輸入 $0.1 / 輸出 $0.5 / 緩存讀 $0.01 每百萬 tokens（單次 ≤100,000 tokens；超過 100,000 tokens 時輸入 $0.5/1M，階梯計價） | 低頻、中頻用戶 |
價格數據取自 API易 apiyi.com 價格總表（頁面更新於 2026-10-27 14:50 UTC+8），型號與價格以平臺型號列表爲準，實際扣費以控制檯爲準。作爲參考，同平臺的 claude-haiku-4-5-20251001 爲輸入 $1 / 輸出 $5 / 緩存讀 $0.1，claude-sonnet-5-5 爲 $2 / $10 / $0.1，claude-opus-5-5 爲 $4 / $20 / $0.2。observer 是高頻、結構化的小任務，Haiku 級別模型就夠用。按量計費適合低頻和中頻使用；重度用戶請自己用一週的實際用量算賬，再和 $30/月對比。
把 claude-mem 的 observer 換成 API易
這是路線 C 的完整做法，適合已經有 API 餘額、不想爲記憶單獨開訂閱的國內開發者。API易支持人民幣充值，按 1:7 固定匯率結算（官方價格頁口徑）。
- 先按路線 B 裝好：
npx claude-mem install --provider claude。 - 打開
~/.claude-mem/settings.json，寫入四個鍵： "CLAUDE_MEM_PROVIDER": "openai-compatible""CLAUDE_MEM_OPENAI_COMPAT_BASE_URL": "https://api.apiyi.com/v1""CLAUDE_MEM_OPENAI_COMPAT_MODEL": "claude-haiku-5-5""CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "sk-你的API易key"- 不想把 key 明文寫進 settings 的話，可以改寫到
~/.claude-mem/.env：OPENAI_COMPAT_API_KEY=sk-你的API易key（目錄權限 0700、文件權限 0600）。 - 運行
npx claude-mem restart。憑證只在 worker 啓動時讀取，不重啓就不會生效。 - 怎麼算成功：
npx claude-mem doctor顯示 provider 爲 openai-compatible。新會話產生的下一條 observation 出現在 viewer 中。
有兩個坑要提前避開。第一，base URL 必須帶 /v1，末尾不要加斜槓，否則會拼出雙斜槓導致 404。三種 base URL 的區別可以參考：help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html。第二，四個鍵只要缺一個，claude-mem 就會靜默退回 Claude 路線，表面看起來一切正常，錢卻從套餐里扣。
接口實測（我用 API易 key 在 2026-10-30 測試）：
GET /v1/models返回 200，共 259 個模型，其中包含claude-haiku-5-5。POST /v1/chat/completions使用claude-haiku-5-5，帶response_format: {type: "json_object"}，返回 200，耗時約 2.0 秒，返回合法 JSON，用量 59 tokens。- 帶上 claude-mem 會發送的
reasoning: {enabled: false}字段，同樣返回 200，沒有報 400。 - Anthropic 原生
/v1/messages也返回 200。
結論邊界：以上只驗證了「API易端點能接受 claude-mem 需要的請求形狀」。我沒有在本機完整跑通 claude-mem 的 observation 鏈路，接口通過也不等於整條插件鏈路已驗證。
🚀 快速上手建議：先在 API易 apiyi.com 控制檯創建一個單獨的 key，專門給 claude-mem 用。這樣一週後可以單獨查看這個 key 的消耗，判斷按量計費是否比訂閱划算。如果你的 Claude Code 本體也打算接入，可以參考：help.apiyi.com/claude-code-apiyi-integration-tutorial.html。
claude-mem 隱私：哪些留在本地，哪些會外發
本地存儲（都在 ~/.claude-mem/，可用 CLAUDE_MEM_DATA_DIR 修改位置）：claude-mem.db（sessions、observations、summaries、prompts）、chroma/ 向量索引、logs/、settings.json，以及默認關閉的截圖目錄 media-v1/。
會離開本機的內容：
- observer 調用：工具調用內容、prompt 和摘要素材會發給你選的 provider。選 Anthropic 就發給 Anthropic，選 CMEM 就發給 cmem.ai，選 API易 就發給 API易。
- 遙測默認開啓：數據發往 PostHog，使用隨機 install UUID，錯誤信息會脫敏。關閉方法是運行
npx claude-mem telemetry disable或設置DO_NOT_TRACK=1，安裝器最後也會問一次。 - 雲同步需主動開啓：默認關閉。開啓後會把 observations、會話摘要、完整 prompt 文本上傳到 cmem.ai。
你能用的控制手段：
- 用
<private>...</private>包住的內容在 hook 層就會被剝掉，不會進庫。 - 自動脫敏默認關閉。需要設置
CLAUDE_MEM_REDACT_ENABLED=true纔會啓用 16 個內置密鑰模式（AWS、GitHub PAT、OpenAI/Anthropic key、JWT、PEM 等），再加CLAUDE_MEM_REDACT_GENERIC_ENABLED=true可增加 3 個通用模式。不要默認以爲它會替你脫敏。
claude-mem 常見故障排錯表
| 現象 | 原因 | 處理 |
|---|---|---|
每個 hook 報 Executable not found in $PATH: "claude-mem" |
launcher 不在 PATH | 運行 npx claude-mem install 重裝，重啓終端、IDE 和 Claude Code |
會話顯示 memory hooks are not active |
launcher 沒有生效 | 同上，再用 npx claude-mem doctor 查看 Hook launcher 行 |
| 完全不記錄，也不報錯 | Claude Code 低於 2.1.139 | 運行 claude update |
claude-mem 命令被別的程序遮住 |
曾經 npm install -g claude-mem |
用 which -a claude-mem 查找，再 npm uninstall -g claude-mem |
| viewer 打不開 | 端口不是 37700，或 worker 沒啓動 | 從 settings 讀取端口，運行 curl http://127.0.0.1:<PORT>/health |
| 端口被佔 | 其他進程衝突 | 設置 export CLAUDE_MEM_WORKER_PORT=38000 後重啓 worker |
| 自定義端點 404 | base URL 寫錯 | OpenAI 兼容用 /v1，Anthropic 原生用根域名；確認模型 id 出現在 /v1/models 中 |
| 配了第三方 key，仍然走 Claude | 四個鍵沒寫全，靜默 fall through | 補全 settings，運行 npx claude-mem restart |
| observation 爲空或被截斷 | 小模型不遵守 JSON 結構，或撞到輸出上限 | 調大 CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS（默認 4096），換更穩定的模型 |
| 反覆超時 | 流式請求 90 秒無 token 就放棄 | 調大 CLAUDE_MEM_LLM_STREAM_IDLE_TIMEOUT_MS，或換小模型 |
| hook 一直殺掉 worker | 插件與 worker 版本不一致（#3857、#3940，已修復） | 運行 npx claude-mem update，必要時運行 npx claude-mem@latest install |
| 兩套記憶互相打架 | 原生 auto-memory 與 claude-mem 並行 | 重裝時加 --disable-auto-memory |
claude-mem 風險與封號自負
這一節請裝之前讀完。
- 社區項目，無背書：claude-mem 是社區開源項目，不是 API易 官方產品，API易 不爲它提供背書或 SLA。
- 內容外發：工具調用內容會發給你選的 observer。含密鑰、客戶數據、未公開代碼的倉庫，先別開。
- 額度消耗：它可能消耗大量 tokens 或套餐額度。建議先用一個小項目試一週，觀察賬單再決定。
- 風控與限流：頻繁觸發的 hooks、共享賬號、中轉 key，都可能觸發平臺風控或限流。建議用單獨的 key、小號、單個項目來試，後果由讀者自負。本文對 API易 只能確認接口實測通過，不承諾不會限流。
- 卸載有殘留：
npx claude-mem uninstall之後，~/.claude-mem仍然保留，裏面有數據庫和可能保存的 key，需要手動執行rm -rf ~/.claude-mem。另外~/.bun、~/.cache/uv第三方實測約佔 1.1 GB，如果沒有其他項目在用，也可以一併刪除。
claude-mem 常見問題 FAQ
Q1：10 萬星說明 claude-mem 一定好用嗎？
不說明。星數只代表熱度。token 開銷、隱私邊界、版本節奏都要自己評估，星數增長是否有水分也沒有獨立審計。
Q2：claude-mem 和 Claude Code 自帶的 memory 是一回事嗎？
不是。原生 memory 是 MEMORY.md，claude-mem 是獨立的 hooks + 數據庫，默認兩套並行。只想保留一套，安裝時加 `–disable-auto-memory`。
Q3：裝完第一場會話就有記憶嗎？
沒有。第一場負責採集和壓縮，第二場纔會注入。要用驗收第 4 項（sqlite count）和第 5 項（context inject）來確認。
Q4：不綁卡、不訂閱，能用 claude-mem 嗎？
能。用 `–provider claude` 安裝，消耗 Claude 套餐額度。或者裝完把 observer 換成 API易 apiyi.com 的按量 key，按實際 tokens 計費，新用戶還有免費測試額度可以先試。
Q5：observer 用什麼模型合適？
用 Haiku 級別的模型，比如 `claude-haiku-5-5`。observation 是高頻、結構化的小任務，用 Opus 這類旗艦模型既貴，又容易把輸出預算花在思考上。
Q6：能只用本地模型嗎？
可以。把 `openai-compatible` 指向 Ollama、LM Studio 或 vLLM 即可。但小模型必須能穩定輸出 observation 的 JSON 結構，否則會產出空記錄。
Q7：中文 observation 怎麼開？
在 settings 中設置 `”CLAUDE_MEM_MODE”: “code–zh”`（內置模式，不用另裝），然後重啓 Claude Code。
claude-mem 核心要點 Key Takeaways
- 本質：hooks 抓取工具調用，交給 observer 壓縮後存入 SQLite，下次會話注入。
- 默認坑：v15 安裝器預選 CMEM Pro，試用要綁卡，之後 $30/月。
- 零月費：
--provider claude安裝，再按需改 settings 換成自帶 key。 - 成本：官方自報「省 96%」，第三方單例「+4,226 tokens」，兩者口徑不同。
- 隱私：observer 會外發內容；遙測默認開啓；脫敏和雲同步都需要手動開。
- 上手方式：在 API易 apiyi.com 單獨建 key，配合
claude-haiku-5-5按量跑一週再算賬。
總結：claude-mem 跨會話記憶，誰該裝、誰別裝
該裝的 3 類人：
- 長期維護同一個項目、經常關掉重開 Claude Code 會話的人。
- 經常需要回答「上次爲什麼這麼改」「那個 bug 最後怎麼修的」的人。
- 願意花 10 分鐘配置一次，並且能接受 observer 讀取工具調用內容的人。
不該裝的 3 類人：
- 只跑一次性腳本、項目沒有連續性的人。用 CLAUDE.md 加自己的筆記更便宜。
- 代碼或數據不能離開本機、不能離開指定合規區域的人。
- 磁盤或 CPU 很緊張的機器用戶，以及期待「裝完立刻變聰明」的人。
裝的話，按「路線 B → 5 項驗收 → 調小注入條數 → 視情況換 observer」這個順序走，最不容易踩坑。想用按量計費驗證 observer 成本，可以在 API易 apiyi.com 用免費額度先跑一個小項目。
📚 參考資料
- claude-mem GitHub 倉庫：源碼、release 與 issues
- 鏈接：
github.com/thedotmack/claude-mem -
說明： 星數、版本、#618、#2469、#3857、#3940 等問題記錄
-
claude-mem 官方文檔：安裝、配置、故障排查
- 鏈接：
docs.claude-mem.ai/installation -
說明： 系統要求、settings 默認值、openai-compatible provider 配置
-
CMEM 定價頁：CMEM Pro / Heavy / Max 條款
- 鏈接：
cmem.ai/pricing -
說明： 30 天試用、綁卡要求、計費起點（2026-10-30 覈對）
-
ComputingForGeeks 第三方實測：15.0.2 安裝與 token 開銷
- 鏈接：
computingforgeeks.com/claude-mem-claude-code -
說明： +4,226 tokens 單例數據來源（2026-10-24）
-
API易 模型文檔：型號與價格列表
- 鏈接：
docs.apiyi.com/models - 說明： 型號與價格以平臺型號列表爲準
作者：APIYI 技術團隊
技術交流：配置中遇到端點或模型問題，歡迎在 API易 官網首頁聯繫我們，更多接入說明可訪問 docs.apiyi.com 文檔中心
