最近在折腾 Claude Code 做项目的时候，我最大的痛点就是它“记性不好”。每次新开一个会话，它对之前的需求背景、技术选型、踩过的坑完全是一片空白，经常同一件事要重复交代三四遍，非常消耗耐心。后来我在 GitHub 上挖到一个叫claude-mem的开源工具，专门给 Claude Code 做长期记忆，用了一段时间确实解决了不少问题。这篇就聊聊它是怎么设计的、怎么装、怎么用，以及我实测过程中踩过的那些坑。
1. 这工具解决的是谁的痛点
先明确一下场景。如果你只是拿 Claude Code 来临时问几个代码问题，那claude-mem对你的价值不大。但如果你像我一样，把它当成一个长期参与项目的“结对程序员”，每天都要在这个项目里做增量开发、修 Bug、重构模块，那你一定遇到过下面这些情况。
上下文窗口不够用。Claude Code 的会话上下文虽然不小，但塞满了代码片段、报错日志之后，真正留给“业务背景”的空间就很少了。更麻烦的是每次新开会话就从头开始，你得重新描述项目结构、依赖关系、目前的进度，甚至上次已经确认过的技术方案。
claude-mem的思路很直接：把当前项目的历史决策、命令执行记录、代码变更摘要、常用的技术偏好全部存到本地数据库里。下次开新会话时，它可以自动把这些记忆注入给 Claude Code，让新会话一开始就有“老员工”的上岗状态。
它不是一个记忆插件那么简单。它会监听你的命令执行记录和 Claude 的回复内容，自动提取关键信息。比如你上次选择了 PostgreSQL 而不用 MySQL，理由是“需要 JSON 字段的复杂查询”，这个决策会被整理成一条记忆存下来。下次再聊数据库选型时，Claude 不需要你重复说明，就能直接基于上次的结论继续。
适合谁用，我总结下来有这么几类：一类是长期维护同一个代码库的开发者，另一类是喜欢用 Claude Code 管理终端命令和自动化脚本的人，还有一类是团队里想让 AI 辅助工具沉淀项目知识的工程师。如果你只是偶尔用一次，可能感受不到它的价值，但一旦进入连续开发状态，这个记忆层就是刚需。
2. 核心设计拆解：记忆是怎么被记录下来的
claude-mem这套机制我拆开看，本质上是“监听 + 提取 + 存储 + 检索”四个环节的闭环。理解这个闭环，后面用起来才有底。
2.1 监听：情报从哪来
它依赖 Claude Code 的两个输入源。第一个是完整的会话记录，包括你输入的命令、Claude 的回答和中间生成的编辑内容；第二个是命令执行结果，也就是你在终端里跑的构建、测试、Git 操作等命令的输出。通过监听这些信息，它能拿到“当前项目发生了什么”的事实，而不需要额外手动记录。
实现上，它利用了 Claude Code 提供的 hook 机制。你可以把它理解成给 Claude Code 装了一个“旁听员”，每当有会话事件发生时，hook 会被触发，claude-mem拿到对应的数据去做处理。这些 hook 不需要你手动编写复杂的集成代码，只需要在配置文件里声明路径即可。
这里有个容易被忽略的细节：它监听的是本地数据，所有信息都留在你自己的机器上，不会上传到任何云端服务。这一点对很多对代码安全敏感的开发团队很重要。
2.2 提取：怎么从流水账里挖出有用的记忆
如果只是原封不动地保存所有日志，那其实是“假记忆”，检索时根本没法用。claude-mem在提取阶段做了几层处理。
第一层是清洗，把带有随机路径、时间戳、临时变量的内容标准化，避免同一件事因为路径不同被存储成两条记忆。第二层是摘要，对于过长的对话会生成精简摘要，而不是保存完整对话，这样既节省空间，也提高后续匹配效率。第三层是结构化，它会根据内容类型给记忆打标签，比如“技术决策”“环境配置”“代码修复”“用户偏好”等，方便后续按标签过滤。
它还会从命令历史里提取“有意义的事件”。比如你运行了一条npm run migrate命令并成功了，它可能记一条“数据库迁移命令已通过 npm run migrate 完成”；如果运行失败了，则可能记录失败原因。这种执行事件在后面的调试场景中特别有用。
2.3 存储：本地优先的数据库结构
存储层使用的是 SQLite，每个项目对应一个独立的数据库文件。这个设计很务实，避免了多项目之间的记忆互相污染。每个记忆条目会保存创建时间、来源类型（对话还是命令）、关联的 Git 分支或标签、内容文本、以及一个用于快速检索的向量向量索引。
向量索引的加入是为了做语义检索。普通的数据库查询需要你提供精确的关键词，但是记忆这种东西往往不是用精确词能想起来。比如你只记得“之前好像讨论过数据去重的问题”，但具体记不清当时的语句，有了向量索引后，语义检索可以找到那句话的核心含义相近的记忆条目，大幅提高命中率。
如果不想用向量检索也可以，它提供了一个开关，切换后只做全文关键词匹配。对性能紧张的机器来说，关掉向量功能能省不少资源。
2.4 检索：自动注入与主动查询
记忆存下来最终是为使用服务的。claude-mem提供了两种检索方式。
一种叫“自动上下文注入”，在每次 Claude Code 会话启动时，它会读取当前项目最近的几条关键记忆，作为背景信息拼到系统提示词里，让 Claude 一开始就“知道”项目发生过什么。注入数量可以配置，我通常会设成 5 条，太少没意义，太多会占用上下文。
另一种叫“主动查询”，你可以在对话里直接问“我们之前关于分页方案的结论是什么”，claude-mem会把这个问题转换成检索条件，找出相关记忆后以系统消息的形式返回给 Claude，再让 Claude 根据这些记忆生成回答。
这两种检索方式配合起来，基本覆盖了日常使用的高频场景：被动唤起背景知识，主动追问历史决策。
3. 安装与配置实操：一步步搭起来
说再多原理不如跑通一次。安装claude-mem的整体流程不长，但有几个配置点比较容易出错，我把完整步骤写在这里。
3.1 环境准备与安装
前提是你已经装好了 Node.js（建议 v18 以上）和 Claude Code。然后全局安装claude-mem：
npm install -g claude-mem安装完成后，检查版本号：
claude-mem --version如果能看到版本信息，说明安装成功。接下来需要在你的项目目录里做初始化，但它本身不是通过交互式命令初始化的，而是通过配置文件来激活。运行下面的命令可以生成一个示例配置：
claude-mem init这个命令会在当前目录生成一个.claude-mem.json配置文件，同时告诉你默认的数据存储位置。以我的习惯，我会把这个配置文件提交到 Git 仓库里，这样团队其他人拉下来也能自动使用同一个记忆体系。不过要注意，SQLite 数据库文件不要提交，它保存在全局目录下，通过配置文件里的路径指定。
3.2 配置 hook 与上下文注入
在 Claude Code 的配置文件claude.json中，会看到一段关于 hooks 的配置。claude-mem需要你在配置中注册 Stop 和 PreToolUse 等 hook，这样它才能捕捉会话和命令事件。
一个典型的最小配置长这样：
{ "hooks": { "Stop": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "claude-mem capture --hook Stop" } ] } ], "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "claude-mem capture --hook PreToolUse" } ] } ] } }这里的matcher: "*"表示捕获所有类型的工具调用，你可以根据项目需要改成只匹配 Bash、Read 等特定工具，减少不必要的监听开销。
配置完 hooks 后，建议重新启动一次 Claude Code 会话，并在终端运行下面这个命令来验证记忆捕获是否正常：
claude-mem status如果输出显示数据库路径、记忆条数等信息，说明链路已经通了。如果显示没有监听事件，多半是 hook 没有生效，优先检查claude.json的路径是否正确。
3.3 调整关键参数
在.claude-mem.json中有几个参数跟日常使用的体感关系密切，我逐一说明。
第一个是maxContextItems，表示每次自动注入几条记忆。默认值我记得是 3，我在中大型项目里调到 5，在大型 monorepo 里反而降到 2。因为记忆注入会占用上下文空间，记忆多了未必都是有用的，反而可能干扰 Claude 对当前任务的理解。
第二个是sessionExpiryDays，用来控制记忆保留周期。默认 30 天，但如果你的项目跨度很长，有些技术决策可能要在几个月后重新被翻出来，可以调到 90 天。这里要注意，时间越长数据库增长越快，检索性能也会小幅下降，所以定期清理还是有必要的。
第三个是useEmbeddings，这是向量检索的开关。默认开启，如果机器性能一般，或者项目比较小，可以关掉。关闭后检索退化为关键词匹配，准确率会低一些，但速度更快，占用资源更少。
4. 实操过程与核心环节实现
光配置完还不算真正用起来。我以一个真实项目为例，演示我在开发一个 Node.js 后端服务时，如何用claude-mem做到“跨对话连续工作”。
4.1 第一天建立项目记忆
我通常会从最基本的业务需求开始，让 Claude Code 帮我把项目骨架搭起来，包括目录结构、依赖管理、数据库连接等。在这个过程中，我不需要做任何额外操作，claude-mem会通过 hook 自动把关键决策记下来。比如我说“使用 Fastify 而不是 Express，因为我们需要原生支持异步错误处理”，这句话就会被提取为一条技术决策记忆。
第一天结束时，我运行一个指令查看当前项目已经积累了哪些记忆：
claude-mem list --limit 10输出大致长这样：
1. [decision] 选择 Fastify 作为 Web 框架，原因是原生支持异步错误处理 2. [config] 数据库连接使用 PostgreSQL 15，连接字符串在 .env 中 3. [cmd] 执行 npm run migrate 完成初始表创建 4. [bug] 解决 nodemon 热重载失效，原因是 Node v20 的 watch 模式与其冲突 5. [pref] 用户偏好使用 TypeScript 严格模式，所有新代码需带上类型注解看到这些，我心里基本有数了：下次会话哪怕我什么都不说，Claude 也能知道用什么框架、什么数据库、什么代码风格。
4.2 第二天无缝继续开发
第二天早上新开一个 Claude Code 会话，我还没输入任何项目背景，就直接说“帮我把用户表的索引优化一下”。正常情况下，Claude 应该会问“你的用户表在哪里”，但因为系统提示词里自动注入了数据库相关的记忆，它默认知道了表结构在这个项目的迁移文件里，并且知道我们用的是 PostgreSQL，于是直接开始分析当前索引，给我提出了联合索引优化建议。
这就是自动注入的价值：新会话拥有“上一会话的上下文沉淀”，但不是简单的把大段对话塞回去，而是提炼出最关键的几条事实。在体验上真的像一个老搭档回来了，而不是每次都要重新介绍自己。
如果你觉得某次 Claude 的回答没有依据当前项目的记忆，你也可以显式向记忆库提问：
claude-mem query "我们之前对数据库迁移的策略是什么"这个命令会返回相关的记忆片段，你还可以把查询结果手动粘贴到对话里，让 Claude 基于这些记忆继续处理。
4.3 记忆修正与手动补充
机器自动提取的记忆并不总是完全准确。比如有一次我明明说的是“暂时不接入 Redis”，但提取出来的记忆变成了“考虑使用 Redis 做缓存”，意思完全反了。这时候需要手动调整。
调整分两种方式：删除错误记忆、手动新增补充记忆。删除用一条命令：
claude-mem delete --id 42这里的 id 可以通过claude-mem list查看。手动新增则是这样：
claude-mem add "我们决定暂不引入 Redis，后续缓存需求优先用 PostgreSQL 的物化视图方案" --tag decision手动新增的记忆和自动提取的会一同进入后续检索流程，Claude 在后续对话中也能使用。建议每周花个几分钟检查一遍自动提取的内容，把明显错误的删掉，把重要的补充进去。这个习惯能让记忆库的质量越来越高。
4.4 与团队协作的注意事项
claude-mem虽然默认是本地单人使用，但它也支持多人共享同一套记忆库。做法是让数据库文件放在团队的共享目录下，或者通过同步工具把数据库定期上传到共享盘。
不过我不推荐团队直接在同一个数据库上读写，因为并发写入会造成 SQLite 锁冲突。更稳妥的方案是每个成员各维护一份本地记忆，但把.claude-mem.json配置和人工维护的“项目知识库”文件提交到代码仓库，通过约定让所有人共享重要的历史决策文本，而不是共享数据库二进制文件。
团队使用时还有一条铁律：不要把敏感信息写入记忆。比如 API 密钥、内部系统地址、客户隐私数据，一旦被存入记忆库，后续每个会话都会被自动注入给 Claude Code，泄露风险成倍增加。虽然claude-mem的数据完全在本地，但一旦数据库泄露或被某些工具索引，后果很严重。我自己的做法是在.claude-mem.json里配置一个敏感词过滤列表：
{ "ignorePatterns": ["api[_-]?key", "password", "secret", "token"] }命中正则的内容在写入前就会被过滤掉，从源头杜绝敏感信息进入记忆库。
5. 常见问题与排查技巧实录
用了一个多月，遇到的坑不少。挑几个最典型的写出来，希望能帮你少走弯路。
5.1 记忆没被自动写入
这是最容易遇到的问题。配置完 hooks 后，跑了几轮对话，claude-mem list还是空的。排查步骤我建议按这个顺序来：
第一，确认 Claude Code 的配置路径是否正确。有些版本更新后配置文件位置变了，导致 hooks 没有生效。第二，查看claude-mem的日志输出。它默认会把运行日志写到指定的日志文件，路径在配置文件里，打开日志看有没有捕获事件。第三，手动测试采集功能：
claude-mem capture --hook Stop --debug如果手动能捕获，说明程序本身没问题，问题就出在 hook 的调用时机或权限上。常见原因是claude-mem的可执行文件路径没有被 Claude Code 找到，把命令改成绝对路径即可。
5.2 记忆重复率过高
提取出来的记忆很多是同一个意思，比如“使用 Fastify”出现了七八次。这是因为每次对话提到 Fastify，都会生成一条类似的记忆。重复记忆不仅浪费空间，还会干扰检索排名。
解决办法主要有两个。一个是降低捕获频率，在 hook 配置里把matcher改成只监听某些关键工具，比如平时不用监听Read工具，它没有多少值得记忆的内容。另一个是利用claude-mem的去重阈值参数，配置文件里有个similarityThreshold, 默认 0.95，意思是相似度超过 95% 的记忆会被自动合并。你可以把它调低一点，比如 0.9，合并更多重复项。
5.3 上下文注入导致 Token 消耗上升
自动注入记忆本质上就是在系统提示词里多塞一段内容，所以 Token 消耗确实会上升。如果你的每次会话都会自动注入 5 条记忆，每条平均 200 Token，那单次会话就要多消耗 1000 Token。对于经常跑超长会话的人来说，这个成本不小。
我的优化思路是分层管理：短期记忆优先，长期记忆按需查。把maxContextItems调低到 2，只保留最近最重要的决策，更久远的记忆不自动注入，但在对话中如果涉及历史问题，再用claude-mem query主动查询。这样既不丢失历史信息，又能把上下文占用控制在合理范围。
5.4 向量索引占用内存过高
如果项目记忆条数特别多，开启向量功能后内存占用会明显增加，有个几千条记忆的库可能多占几百 MB。如果你的开发机配置不高，建议关闭useEmbeddings，改用纯关键词检索。关闭后你会发现查询质量确实有下降，但日常使用还能接受。折中方案是定时清理旧记忆，只保留最近 90 天的内容，能显著减少向量索引体积。
5.5 升级claude-mem后数据库兼容问题
这个工具的更新频率不算低，偶尔会有数据库结构变更。升级后第一次运行如果报错，先别急着删数据库。通常它会自动做迁移，如果迁移失败，手动备份原来的 db 文件，然后运行claude-mem migrate命令尝试修复。我经历过一次从旧版本升上来后查询接口变了，花了一点时间熟悉新命令，但数据都还在。建议升级前养成备份数据库的习惯，路径在配置文件的databasePath字段里，直接复制一份就行。
6. 一些实际的体会
claude-mem这个工具乍看只是“给 Claude Code 加了个记忆”，但真正用起来后会改变你和 AI 协作的方式。以前我在会话里要花五分钟描述上下文，现在直接开始提需求，因为上下文已经在系统提示词里等着了。以前我担心 AI 的“短期记忆”会导致重复劳动，现在至少在同一项目内，这种重复被极大降低了。
它也不是没有问题。自动提取的质量参差不齐，偶尔会有错误结论被当作记忆存下来，所以定期人工审视记忆库是有必要的。但整体来说，对于长期在同一个代码库上使用 Claude Code 的开发者，这个工具值得一试。
最后分享一个小技巧：如果你在多个项目之间切换，建议每个项目都单独初始化一份配置，并保持数据库独立。这样项目 A 的记忆不会干扰项目 B 的对话。如果你发现自己经常在项目 B 中谈到项目 A 的代码，那其实说明当前任务可以拆成两个独立会话，或者该考虑把公共知识提到团队文档里了。
