和 Claude Code 协作，经常会撞上一个让人抓狂的场景：上周明明和它一起把某个模块重构好了，这周开新会话问"我们之前怎么处理的"，它一脸茫然——"我没有之前的对话记录"。
这种感觉像和一个得了短期健忘症的同事合作。每次开会他都精神抖擞，但上会说了什么、决定怎么做，全忘干净。
claude-mem 就是治这个"健忘症"用的。它给 Claude Code 加了一层持久化记忆——你每次会话做了什么、调了哪些文件、改了什么逻辑，全被自动捕获并压缩下来。下次开会，Claude 自动带着"上次的记忆"出现。
用了一周之后，写下这篇避坑+实战指南。
它到底解决什么问题？
先说痛点，再说工具。
Claude Code（以及 Cursor、Windsurf 这类 AI IDE）本质是无状态的。每次开新会话，模型都从零开始——它不知道你上周改了哪个文件、为什么引入这个依赖、踩过哪些坑。结果：
- 每次都得重新解释项目背景
- 它会重复犯你已经修过的错
- 长项目的架构决策随着时间被遗忘
- 你得自己手动写笔记同步给它
claude-mem 的做法是：背后跑一个 SQLite 数据库 + 一个本地 Worker 服务，通过 5 个生命周期 Hook（SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd）把会话里的每一次工具调用、每一次观察捕获下来，再让 Claude 自己提炼"今天学到了什么"。下次开会，这些摘要自动注入到上下文。
一句话总结：让 AI 从"一次性助手"变成"长期协作者"。
它实际适合谁？
我自己用下来，按"收益"排个序：
| 人群 | 收益 | 门槛 |
|---|---|---|
| 个人开发者，长期维护同一项目 | ⭐⭐⭐⭐⭐ | 低 |
| 团队协作，需要"知识沉淀" | ⭐⭐⭐⭐ | 中（需要约定 <private> 使用） |
| 一次性脚本/小工具 | ⭐ | 没必要，太重 |
| 处理敏感信息（密码/密钥/合规） | ⚠️ | 需主动用 <private> 标签（见下文隐私节） |
如果你的项目经常需要查"上次怎么弄的"，claude-mem 几乎必装。如果只是偶尔写个小脚本，没必要。
核心特性一览
我筛了一遍 README，挑出真正有用的几个：
| 特性 | 实际价值 |
|---|---|
| 🧠 跨会话持久记忆 | 不再每周重述项目背景 |
| 📊 渐进式披露 | 搜索时只返回索引，需要再展开详情，省 token |
| 🔍 mem-search 技能 | 用自然语言查"上周改了哪些文件" |
| 🖥️ Web Viewer 可视化 | 浏览器实时看记忆流，调试神器 |
🔒 <private> 标签 | 敏感信息不入库 |
| 🗣️ 28 种语言摘要 | 中文项目也能生成中文摘要 |
特别说一下渐进式披露这个设计。它把搜索拆成三层：
search— 只返回 ID 和一句话摘要（约 50–100 token/条）timeline— 给定 ID 拿上下文时间线get_observations— 只对真正需要的 ID 拉详情（500–1000 token/条）
作者号称比"一把梭全量返回"省 10 倍 token。在长项目里，这点很关键——否则光是把历史塞进上下文就能把你的窗口撑爆。
它支持哪些 Agent 环境？
光支持 Claude Code 的话，覆盖面有点窄。作者显然意识到了，所以做了多平台适配：
- ✅ Claude Code（主力）
- ✅ OpenCode
- ✅ Codex CLI
- ✅ Gemini CLI
- ✅ Hermes
- ✅ Copilot
- ✅ Antigravity CLI
- ✅ Cursor / Windsurf（通过 hook 配置）
我个人只在 Claude Code 里用，其他环境需要针对性安装（见后文「安装」一节）。
安装：两种姿势
姿势一：npx 一键安装（推荐）
npx claude-mem install这一条命令会帮你：
- 检查 Node.js 版本（要求 ≥ 20）
- 没装 Bun 自动装 Bun（Worker 服务依赖）
- 没装 uv 自动装 uv（向量搜索依赖）
- 注册 5 个生命周期 Hook
- 启动本地 Worker 服务（默认端口
37777）
如果你用的是 OpenCode 或 Antigravity CLI，加个参数：
npx claude-mem install --ide opencode
npx claude-mem install --ide antigravity姿势二：插件市场安装
在 Claude Code 里直接：
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem效果一样。
一个常见的坑
如果你执行的是 npm install -g claude-mem，只会装 SDK 库，不会注册 Hook，也不会启动 Worker。这种状态下你以为装好了，其实啥都没生效。务必用 npx claude-mem install。
Windows 用户的额外提醒
如果终端报 npm : The term 'npm' is not recognized，先去 [nodejs.org](https://nodejs.org) 装 Node.js，并确保加到了 PATH。装完重启终端再跑 npx。
配置：让它说中文
安装完会在 ~/.claude-mem/settings.json 生成默认配置。打开看一眼：
{
"CLAUDE_MEM_MODE": "code"
}如果你想让生成的摘要用中文，改成：
{
"CLAUDE_MEM_MODE": "code--zh"
}其他可选模式：code--ja（日语）、code--es（西班牙语）等，遵循 ISO 639-1 标准。
改完必须重启 Claude Code 才生效。这点我踩过坑——改完兴冲冲开了新会话，发现摘要还是英文，排查半天才想起来没重启。
实际使用：三种姿势
1. 被动使用：什么都不用做
装好之后，你正常用 Claude Code 就行。每次会话结束后，它会自动：
- 捕获你用过的所有工具（Read、Write、Edit、Bash…）
- 让 Claude 提炼"学到了什么"
- 存进 SQLite
- 生成摘要
下次开会，最近 10 个会话的摘要会自动注入到上下文。这就是默认行为。
2. 主动查询：mem-search 技能
你可以在会话里直接问：
"上周我们讨论过 auth 模块的 token 刷新逻辑，帮我找一下当时的决策"
Claude 会调用 mem-search 技能，自动从历史里捞出来。
如果它捞得不准，你可以要求"用 ID 123 的时间线展开看看"——这是它的高级用法。
3. Web Viewer 可视化
Worker 启动后，浏览器打开 http://localhost:37777 就能看到一个实时记忆流面板：
- 当前会话的所有观察
- 历史会话列表
- 每条记录的 token 占用
- 时间线视图
这个 UI 用了 SSE（Server-Sent Events）做实时推送，调试的时候特别爽——你能看到"这一刻它正在记录什么"。
隐私：怎么保护敏感内容？
claude-mem 默认会记录一切工具调用，包括你读取的 ~/.aws/credentials 这种敏感文件。
强烈建议：在写敏感内容时，用 <private> 标签包起来：
<private>
我的 API key 是 sk-xxx，不要记录
数据库密码是 admin123
</private>这些内容会在写入前被过滤掉，永远不会进 SQLite。
真实感受
好的方面
- 冷启动体验质变：以前开新会话，前 5 条消息都在解释项目背景；现在第一条消息就能直接进入正题。
- 架构决策不再丢：我之前改过一次数据库表结构，过了三周忘了为啥用
jsonb，它直接帮我找到当时的讨论。 - Web Viewer 调试神器：排查"为什么这个 bug 修了又出现"特别好用，能看到完整时间线。
- 中文模式：对国内开发者友好，摘要不是机翻味，是真的中文表达。
让我皱眉的地方
- 首次安装会装一堆东西：Bun、uv 都会自动装，对机器洁癖用户可能不爽。
- Worker 占内存：长时间不重启，Worker 进程会逐渐变大（毕竟要存历史）。
- 隐私靠自觉：
<private>标签要你主动用，没有自动识别密钥的机制。如果你忘了包，Bash 里的export TOKEN=xxx会被记录。 - 5 个 Hook 全部开启：对追求极简的用户来说，可能觉得侵入性强。但好在都可以在配置里关。
故障排查小抄
| 症状 | 排查方向 |
|---|---|
| 安装后没生效 | 检查 ~/.claude/plugins/ 下有没有 claude-mem 目录；确认重启过 Claude Code |
| Web Viewer 打不开 | Worker 默认端口 37777，被占用会改端口，看启动日志确认 |
| 摘要还是英文 | 改了 settings.json 没重启 Claude Code |
| Windows 装不上 | Node.js 没加 PATH，重新装 Node.js 后重启终端 |
| 想关掉 claude-mem | 卸载插件 + 删除 ~/.claude-mem/ 目录 |
需要更详细的诊断，可以在 Claude Code 里让 troubleshoot 技能介入。
写在最后
claude-mem 这个项目挺有意思——它不在 AI 模型本身上下功夫，而是把"记忆"做成了基础设施层。对个人开发者来说，相当于免费给自己的 AI 助手装了一个长期记忆外挂；对团队来说，它有潜力成为知识沉淀的载体（虽然这块还没完全成熟）。
我的建议是：先用一周，再决定留不留。装上它感受一下"跨会话记忆"是不是真的帮你省了时间。如果有，就是真香；如果没感觉，卸了也无妨，反正 npx claude-mem install 装起来，rm -rf 卸干净。
相关链接：
- 仓库：https://github.com/thedotmack/claude-mem
- 文档：https://docs.claude-mem.ai/
- 许可证：Apache 2.0