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 文档中心
