claude-mem 是什么：让 Claude Code 记住上一次做了什么，新版怎么装，用第三方 API 要多配一步

claude-mem 是一个开源的 Claude Code 记忆插件：它在后台把每次会话做过的事记成笔记，下次在同一个项目里开新会话时，自动把要点带进去。 项目在 GitHub 上是 thedotmack/claude-mem，Apache-2.0 协议，2026-11-13 查看时约 11.7 万星，最新版本是 11-12 发布的 15.18.3。除了 Claude Code，它也支持 Codex、Cursor、OpenCode 等十几种工具。

它更新很快，网上不少教程已经对不上了。先说两个最容易踩的坑：

1. 新版安装器会让你选「记忆由谁来记」，默认推荐的是 claude-mem 自己的托管服务，要登录、30 天试用还要绑支付方式。这一步可以跳过，下面会讲。
2. Claude Code 接的是第三方 API（不是用 Anthropic 账号登录）的话，claude-mem 默认不会跟着走你配的地址，装完看起来正常，其实一条笔记都没记下。要在它自己的配置文件里再写一遍。

它是怎么工作的

1. 你正常用 Claude Code。插件通过钩子（hooks）把每次工具调用（读了哪个文件、改了什么、跑了什么命令）交给本机的一个后台服务。
2. 后台服务再开一个「记笔记的 AI」（文档里叫 observer），把这些操作压缩成简短的笔记，会话结束时再写一段总结。
3. 下次在同一个项目里开新会话，Claude Code 一开场就拿到一份笔记索引，需要细节时再按编号去取。

所以第一个会话只记不用，从第二个会话开始才会带上记忆。想一次把整个仓库先过一遍，可以发送 /learn-codebase（普通仓库约 5 分钟，可选）。数据都在本机的 ~/.claude-mem 目录里，云同步默认关闭。

安装

运行要求：Node.js 20.19 以上（20.x 系列），或 22.12 以上；Bun 和 uv 安装器会自动装。

方法一：安装器（推荐）

npx claude-mem install

它会找出本机装了哪些编程工具，问你装到哪几个里，然后进入「记忆由谁来记」的选择（见下一节）。装完重启 Claude Code。

方法二：在 Claude Code 里装插件

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

这种方式第一次启动时要先编译启动器，第一个会话可能没有记忆，第二个就正常了。先跑一次 npx claude-mem install 可以避开这个空档。

别用 npm install -g claude-mem：这样只装了它的代码库，不会注册钩子，也不会启动后台服务，等于没装。

Windows 上提示找不到 npm，是 Node.js 没装好或者不在 PATH 里，装好后重开终端。钩子报 Executable not found in $PATH: "claude-mem" 时，运行 npx claude-mem doctor 看它提示怎么修。

安装时选「记忆由谁来记」

记笔记本身要调用大模型，所以要选由谁来出这部分的 Token：

不想注册 claude-mem 账号，在图形界面里选本地记忆，或者直接运行：

npx claude-mem install --provider claude

Claude Code 用的是第三方 Anthropic 兼容 API 的，也选这一项，再按下一节补配置。

用第三方 API 的要多配一步

选了 Anthropic 计划以后，记笔记的 AI 通过 Claude Agent SDK 发请求。它不会读你给 Claude Code 配的 ANTHROPIC_BASE_URL，也不会读终端里导出的变量（为了防止误用别的 Key 扣费，它故意屏蔽了从终端继承的 ANTHROPIC_API_KEY）。所以要在它自己的配置文件里再写一遍。下面以 CCSub 为例，用别的服务把地址和 Key 换掉就行。

第 1 步：在 ~/.claude-mem/.env 里写地址和 Key（文件不存在就新建）

ANTHROPIC_BASE_URL=https://www.ccsub.net
ANTHROPIC_AUTH_TOKEN=你的 API Key

地址和 Claude Code 里配的一样，不带 /v1。CCSub 也接受用 ANTHROPIC_API_KEY 传 Key，两种写一个就行。

第 2 步：在 ~/.claude-mem/settings.json 里固定型号

{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_MODEL": "填服务方支持的型号 ID"
}

CLAUDE_MEM_MODEL 默认是 haiku，claude-mem 不会帮你转换型号名，服务方不认识就会报错。到服务方的模型列表里挑一个写上完整 ID（CCSub 的见模型列表）。记笔记不需要最强的型号，选单价低的就够了。

第 3 步：重启后台服务

npx claude-mem restart

怎么确认生效：在 Claude Code 里正常干几步活，然后去服务方后台看请求记录。用 CCSub 的话，控制台「使用记录」里会多出一批来自记笔记的请求。没有的话看 ~/.claude-mem/logs/ 里的日志：服务方拒绝请求时，报错会原样记在那里，它不会悄悄改发到 Anthropic 官方。

两个常见报错：

• 型号不存在：CLAUDE_MEM_MODEL 写的不是服务方支持的 ID，按第 2 步改。
• thinking 参数被拒（400）：claude-mem 默认给记笔记的请求关掉思考，有的服务不接受这个参数。它遇到这种 400 会自动去掉参数重试，不用管；一直报的话，在 settings.json 里加 "CLAUDE_MEM_OBSERVER_THINKING": "omit"。

不想走 Anthropic 协议的，也可以把 CLAUDE_MEM_PROVIDER 设成 openai-compatible，再配 CLAUDE_MEM_OPENAI_COMPAT_BASE_URL、CLAUDE_MEM_OPENAI_COMPAT_API_KEY 和 CLAUDE_MEM_OPENAI_COMPAT_MODEL，用服务方的 OpenAI 兼容接口。

费用：会多用多少 Token

会多用，而且比很多人想的多。这部分费用记在你选的那个记忆来源上：

• 每次工具调用都会触发记笔记的请求。默认一次请求只带一次工具调用的内容。
• 记笔记的 AI 是一段持续的对话，每次请求都会带上这段对话之前的内容，攒满后才换一段新的。官方文档的实测：按现在的默认上限，对话攒满时一次请求约 2.6 万 Token。
• 会话结束时还有一次总结。

Claude Code 一个会话调用几十上百次工具很常见，按 API 计费时加起来不少。CCSub 的缓存读写按输入单价计，这类反复带上之前内容的请求，不会因为命中缓存而变便宜。几个省钱的办法：

• 选单价低的型号（上一节第 2 步）。
• 换成精简模式："CLAUDE_MEM_MODE": "code--chill"，只记以后很难再查出来的东西，笔记更少。
• 合并请求：CLAUDE_MEM_CLAUDE_OBSERVATION_BATCH_SIZE 设成 4 之类，几次工具调用合成一次请求（范围 1–32）。
• 缩小对话上限：调低 CLAUDE_MEM_OBSERVER_MAX_CONVERSATION_CHARS（默认 100000 字符），每次请求带的历史就更短。
• 暂停记录："CLAUDE_MEM_OBSERVER_ENABLED": "false" 停止新的记录，已有的记忆和搜索照常能用。

最准的是看自己的账单：用 CCSub 的话，在「使用记录」里按时间段把这些请求加起来，就知道一天大概多花多少。

让笔记用中文写

默认笔记是英文的。在 ~/.claude-mem/settings.json 里加：

{
  "CLAUDE_MEM_MODE": "code--zh"
}

重启 Claude Code 生效。内置的精简模式 code--chill 只有英文版，所以省钱和中文笔记只能选一个，除非自己写自定义模式。

隐私和默认开着的东西

• 不想被记下的内容，用 <private> 和 </private> 包起来，它不会存。
• 匿名使用统计默认开着，关掉：npx claude-mem telemetry disable。
• 工具结果里的截图默认会保存在 ~/.claude-mem/media-v1/，在设置页的 Images 里关掉 Keep images 就不存了。
• 默认每天自动更新，不想自动升级在 settings.json 里设 "CLAUDE_MEM_AUTO_UPDATE": "false"。
• 记忆数据只在本机，云同步要自己打开。

常见问题

装完开新会话，没看到任何记忆？ 第一个会话只记不用，开第二个会话再看。还是没有的话运行 npx claude-mem doctor，它会检查 Bun、uv、钩子启动器和后台服务。用第三方 API 的，先按上面「多配一步」检查。

提示 memory hooks are not active？ 按提示运行 npx claude-mem install，再重启 Claude Code。这类钩子写法需要 Claude Code 2.1.139 或以上，用 claude --version 看版本。

每天额度用得比以前快？ 多出来的是记笔记的请求，按上面「费用」一节的办法调，或者先暂停记录对比一下。

和 API 服务的关系

claude-mem 不改 Claude Code 本身的接口配置，Claude Code 照常走你配的服务；它只是额外开了一个记笔记的 AI，这部分要单独配地址和 Key。用 Anthropic 账号登录的人按默认装就行，用第三方 API 的人记得补上「多配一步」。

还没配置好 Claude Code 的话，先看 Claude Code 接入教程；用 Codex 的看 Codex CLI 接入教程。