上午接着改一个老项目，Claude Code 一开新会话，又问“这个仓库用什么测试命令”“上次那个鉴权坑修到哪了”。这不是模型笨，而是上下文窗口本来就会从新会话重新开始。Claude Code 自带的记忆能保存规则和偏好，claude-mem 解决的是另一件事：把过去会话里的观察压缩、存起来，再在以后需要时检索回来。

先分清：CLAUDE.md 不是完整历史记录

Claude Code 官方文档把记忆分成两类：一类是你写的 CLAUDE.md，用来放项目规则、命令、架构约定；另一类是 auto memory，由 Claude 根据纠正和偏好自己记笔记。它们都会在新会话开始时进入上下文，但官方也提醒，这些内容是上下文，不是强制配置。

这意味着 CLAUDE.md 适合写“每次都要遵守什么”，比如测试命令、代码风格、目录说明。失败场景也很明确：你把每次排查过程、临时结论、几十条聊天记录都塞进去，文件很快变长，Claude 反而更难抓住重点。

claude-mem 解决的是“过去发生过什么”

claude-mem 的思路不是让你手动维护一份越来越长的说明书，而是通过 Claude Code 插件和 hooks 捕获会话里的工具使用、问题、修复过程，再生成语义摘要，放进本地存储和检索系统。下一次会话开始或你搜索记忆时，它再把相关片段拿出来。

所以它能做的是延续项目上下文：记得上次调试了哪个模块、踩过什么错误、偏好哪种写法、某个决定为什么这么定。不能指望它替你保证每条规则都绝对执行；需要强约束的内容，仍然应该写进 CLAUDE.md、项目规则或 hook。

安装时不要走错入口

官方现在推荐直接运行 npx claude-mem install。安装器会检查运行环境，按提示选择要接入的 IDE 或 CLI，并配置压缩观察所用的模型提供方。也可以在 Claude Code 里用插件市场命令安装：/plugin marketplace add thedotmack/claude-mem，再执行 /plugin install claude-mem。

这里最容易错的是把 npm install -g claude-mem 当成完整安装。官方说明里已经写清，这只会安装 SDK 或库，不会注册插件 hooks，也不会启动 worker service。失败场景就是命令看起来装好了，新会话却没有任何历史上下文进来。

配置文件主要看这几个位置

安装后，先看 ~/.claude-mem/settings.json。官方配置页说明，这个文件会在首次运行时自动创建。常看的项包括 CLAUDE_MEM_PROVIDER、CLAUDE_MEM_MODEL、CLAUDE_MEM_CONTEXT_OBSERVATIONS、CLAUDE_MEM_DATA_DIR 和 worker 端口。

一般用户先不要急着调很多参数。先用默认配置跑两三次真实项目会话，再打开本地 memory viewer 或用搜索工具查一遍记忆质量。若摘要太多、上下文太吵，再减少注入观察数量；若经常想不起旧问题，再提高检索数量或补充更清晰的项目规则。

怎么在日常使用里调出记忆

装好并重启 Claude Code 后，claude-mem 会自动在后台工作。你可以直接问：“上次这个项目的登录问题查到哪一步？”“找一下我之前关于测试框架的记忆。”官方 README 还提到它提供 memory search 相关工具，适合先搜索紧凑结果，再按 ID 拉取详细观察，避免一次把大量旧内容塞进上下文。

一个实用习惯是：每次完成关键修复后，给 Claude 一句明确收束，比如“记住：这个项目的登录失败不是 token 过期，而是回调 URL 环境变量写错”。这种句子更容易被压缩成有用观察。失败场景是整段聊天都在绕，最后没有一句明确结论，后面检索到的只是一堆模糊过程。

隐私内容要主动挡住

claude-mem 官方提供 <private> 标签，用来标出不希望持久保存的内容。API Key、密码、客户数据、临时调试 token，都应该放进这个标签里再发给 Claude。它能降低误存风险，但前提是你记得主动使用。

更稳的做法是：密钥不要直接贴进对话；必须贴时用 private 标签包住；定期检查本地记忆；团队机器不要混用同一套数据目录。claude-mem 带来的收益是少重复解释项目，代价是你要认真管理什么东西可以被记住。

适合谁，不适合谁

它适合长期维护项目、频繁开新会话、经常让 Claude Code 接着昨天工作的人。特别是多模块项目、连续排错、重构计划、个人偏好很多的场景，收益很明显。

它不适合把所有内容都交给记忆系统的人。安全规则、发布流程、代码规范，仍然要放在 CLAUDE.md 或项目规则里；一次性实验、敏感数据、客户资料，不应该无脑进入长期记忆。把 claude-mem 当成“可搜索的项目回忆录”，而不是“永远不会错的规则引擎”，使用起来会更稳。