用 Claude Code 用得越久，越容易在同一个地方被卡住：它什么都好，就是记不住昨天的事。你可以在一个会话里把某个模块的设计思路、命名约定、历史坑位讲得明明白白，但只要关掉终端，下一个会话里的它就是一个全新的 AI——所有“我们之前不是说好了吗”都得重新解释一遍。claude-mem 就是冲着这个痛点来的开源工具：它把会话结束时的关键信息沉淀到本地 SQLite，再在下一会话开始时自动把它们注入上下文，相当于给 Claude Code 装了一个“本地外脑”。这篇文章不是 README 的翻译，而是我从实际使用和机制拆解里得到的完整记录，包括它解决的问题、核心实现、接入配置、实测效果，以及我踩过的一串坑。如果你正在长周期项目里用 Claude Code，被“会话失忆”折磨得每天都要重复交代背景，这篇文章应该能帮上忙。
1. 先看痛点：Claude Code 的“会话失忆”到底卡在哪
1.1 单会话内的惊艳，掩盖了跨会话的归零
我最早被 Claude Code 圈粉，就是因为它能在一个会话里把整条链路理顺。让它看一遍项目目录结构、读几个核心模块、跑一下测试，它就能把当前状态理解得八九不离十。这种能力确实好用，但本质上依赖的是“当前会话上下文”：Claude 能记住的，只是窗口里现在摆着的东西。
等这个会话结束，一切归零。下一次打开终端，它不会记得你上次让它看过什么，不会记得你纠正过它什么，也不会记得你最后选了 A 方案而不是 B 方案。在长周期项目里，这就变成一个每周都要重复的循环：我一边喝咖啡，一边把项目背景、技术栈、当前进度、历史坑位重新讲一遍。讲完之后，还得忍受它按照自己的理解重新开始，然后逐条纠正。最折磨人的不是打字，而是“我们已经讨论过”这件事本身。
1.2 靠 CLAUDE.md 和复制粘贴硬扛的不可持续
Claude Code 原生支持 CLAUDE.md，你在项目根目录写一个文件，每次会话它会自动读进去。这个机制很好，但它本质上是“静态配置”：你得自己去维护、更新、删改。会话里自然涌现的知识——比如昨天调试三小时发现的边界条件、刚才和同事敲定的技术取舍——不会自己跑进 CLAUDE.md。如果你忘记更新，它对下一个会话就是“没有发生过”。
还有人用最原始的方案：把昨天的对话记录整理成一段文字，粘进今天的新会话。短期可行，长期撑不住。首先上下文会被历史纪要大量占用，剩下的窗口给不了 Claude 足够的空间处理新问题；其次手工摘录必然丢信息，每次粘贴的累积成本也在不停涨。我在项目里试过两周，最后放弃了，因为每天光整理粘贴纪要就要花掉十几分钟，而且效果完全看状态。
1.3 记忆缺口到底缺在哪：上下文 vs 记忆
很多人以为 Claude 的上下文窗口已经这么大了，还要记忆做什么？这是两个维度的事。上下文解决的是“这次能看到多少信息”，记忆解决的是“下次还记不记得之前的信息”。哪怕上下文窗口再大，会话一关，窗口里的一切就归零了。claude-mem 做的事情，简单来说就是在窗口关闭之前，把里面最有价值的那部分信息“捞”出来存好，等下次开会话再放回去。
这个定位决定了它不是花哨的东西：不需要 GPU、不需要向量数据库、不需要额外服务。它就是一套“会话落盘 + 启动回填”的机制，很朴素，但能解决最疼的问题。
2. claude-mem 的核心工作逻辑：在会话与会话之间“接住”信息
2.1 一次完整的记忆闭环：capture → 存储 → load
整个记忆流程可以拆成三个环节，理解了这套闭环，你就知道这个工具为什么是这么设计出来的：
- 会话结束时，Claude Code 触发 SessionEnd 事件，执行
claude-mem capture。 - capture 读取当前会话的对话记录和项目状态，把冗长的讨论“提炼”成若干条记忆：项目事实、决策、偏好、待办事项。
- 提炼结果写入本地 SQLite 数据库，每条都带着项目路径、会话 ID、时间戳等元信息。
- 新会话开始时，Claude Code 触发 SessionStart 事件，执行
claude-mem load。 - load 从 SQLite 中筛选出当前项目最近、最相关的记忆，格式化成一段干净的文本。
- Claude Code 把这段文本自动作为上下文的一部分注入，Claude 一上来就“想起来”了。
整套流程里，唯一需要消耗模型算力的是 capture 阶段的“提炼”。load 阶段是纯本地查询，几乎零成本。这个设计很聪明：把贵的操作放在会话结束后的后台，把便宜的操作放在用户最在乎的启动速度上。
2.2 自动记忆 vs 主动记忆：什么时候用命令
工作流里最有用的其实是自动 capture，因为人在干活的时候不会想着去存一条东西。你只管跟 Claude 对话，会话结束后它自己把值得记的留下。但主动记忆命令也很重要。比如你刚拍板“这个接口先冻结，等数据库迁移完再解”，这种关键决定如果不立即固化，等会话结束时它可能已经夹在一堆中间讨论里，capture 提炼时未必能准确捞出来。
用类似claude-mem remember的主动命令，可以把正在发生的上下文立刻钉死，优先级比事后总结更高。recall用来在会话中快速自查：之前有没有记过相关的东西？特别是当 Claude 的表现和你的预期不符时，用 recall 看它脑子里被注入了什么，能迅速定位问题。forget用来删除过期或错误的条目。记忆一旦错了，比没有记忆更危险。
2.3 记忆注入后的样子：一个 load 输出的最小样例
load 输出给 Claude 的内容一般是干净、短句、带日期的 markdown。这里给一个我常用的注入样例结构：
# Project Memory: my-project ## Decisions - 认证模块使用 JWT + refresh token，refresh token 存 httpOnly cookie（2025-06-10）。 - API 错误统一抛 ApiError，禁止在业务层直接 res.status(...)（2025-06-11）。 ## Discoveries - 定时任务本地开发用 npm run cron:dev 启动，不要手工跑 node（2025-06-12）。 ## Pending - 数据库迁移 #42 尚未执行，迁移后需要清理旧 query 写法。为什么不用 JSON？因为 stdout 会被当作 prompt 的一部分，JSON 对模型来说可读但浪费 token，还有转义问题。干练的文本反而效果最好。Claude 本质上不是数据库，它需要的是“人话”。
2.4 和 CLAUDE.md、MCP 各自的边界
这几个方案经常被放在一起比较，但它们解决的问题其实不同。
| 方案 | 本质 | 谁来维护 | 典型问题 |
|---|---|---|---|
| CLAUDE.md | 静态项目说明 | 人 | 容易过期，需要人主动更新 |
| MCP 服务 | 实时工具调用 / 外部数据获取 | 自动 + 配置 | 解决数据来源，不解决跨会话记忆 |
| claude-mem | 动态会话记忆 | 自动提炼 + 人工纠错 | 记忆可能过时或污染，需要卫生管理 |
所以它们不是谁取代谁。CLAUDE.md 适合放“稳定的项目事实”，claude-mem 适合放“会话中刚发生的重要决策”，MCP 负责让 Claude 能实时取到外部数据。三位一体的体验是最好的，我这里没有做替换，而是让 claude-mem 补齐了 CLAUDE.md 管不住的那部分。
3. 从代码层面看 claude-mem：SQLite、hooks 与提示词注入是怎么串起来的
3.1 为什么存储层选 SQLite，而不是 JSON 文件
如果你只是给自己写个小脚本，用 JSON 文件当存储也行。但 claude-mem 面对的是长期大量会话：每次 capture 都可能写几十条记录，每次 load 都要做过滤、排序、去重。JSON 文件每次全量读、全量写，很快就不行了，而且写坏一个括号，整个记忆库就废了。
SQLite 是单文件、零服务、有事务的数据库，用起来和 JSON 一样简单，查询能力和健壮性完全不是一个级别。几千条记忆、多个项目的混合数据，在 SQLite 里就是几条 SQL 的事。按项目路径过滤、按时间排序、限制返回条数，都极其顺手。我一个项目用下来，数据库文件也就几 MB，完全不用担心体积问题。
3.2 hooks 配置：claude-mem 最省心也最容易被忽略的设计
Claude Code 原生支持 hooks 机制，可以在会话生命周期的事件点上执行外部命令。claude-mem 正是靠这个机制把自己“缝”进 Claude Code 的。核心配置长这样：
{ "hooks": { "SessionStart": [ { "matcher": "", "hooks": [ { "type": "command", "command": "timeout 30 claude-mem load" } ] } ], "SessionEnd": [ { "matcher": "", "hooks": [ { "type": "command", "command": "claude-mem capture" } ] } ] } }我自己的习惯是 SessionStart 必须加 timeout，因为如果 claude-mem 卡住，连 Claude Code 都启动不了；SessionEnd 慢一点无所谓，反正是会话结束后跑。matcher 留空表示所有会话都触发，你也可以按文件路径或目录写 matcher，做更细粒度的控制。这个配置是整个工具的命脉，后面我会专门讲它出问题时怎么排查。
3.3 记忆表的设计与检索排序逻辑
从机制上推断，记忆库的核心表大致是这样一个设计（不同版本可能有差异，但整体思路通用）：
CREATE TABLE memories ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, project_path TEXT NOT NULL, content TEXT NOT NULL, kind TEXT DEFAULT 'fact', -- decision | discovery | pending | preference created_at TEXT NOT NULL DEFAULT (datetime('now')), updated_at TEXT NOT NULL DEFAULT (datetime('now')), access_count INTEGER DEFAULT 0 ); CREATE INDEX idx_memories_project_time ON memories(project_path, created_at DESC);加载时典型的查询逻辑是：先按 project_path 过滤出当前项目，再用关键词和时间做排序，最后 LIMIT 一个条数上限。关键词匹配不上时，降级为“最近 N 条”，保证每个新会话至少有基础记忆可用。
不少版本也支持自定义记忆阈值，比如只返回 30 条以内。为什么默认不做向量检索？因为本地向量库要么依赖 Python 生态的 embedding 模型，要么得引入外部 API，启动慢、有额外成本，和这个工具“轻”的定位不符。关键词 + 时间 + 项目过滤，已经能解决 80% 的场景。
3.4 初始化时它改了哪些东西
初始化命令通常会做两件事：一是建好数据库目录和表，二是往 Claude Code 的 settings.json 里写 hooks。这里就有一个选择：写用户级配置（~/.claude/settings.json）还是项目级配置（.claude/settings.json）。
用户级对所有项目生效，方便，但容易串味；项目级更干净，记忆隔离性好，还能跟着仓库走，对团队协作友好。我更推荐项目级，或者至少初始化之后手动检查一下它写到了哪一层。我见过不少朋友装完什么都不看，结果在多个项目间出现了记忆互相干扰的问题，根源就在这里。
4. 本地接入 claude-mem 的完整过程与验证方法
4.1 安装与初始化
不同渠道分发的版本，安装命令不太一样。有的是 pip 包，有的是直接下载二进制，有的是脚本安装。我建议按官方 README 来，装完首先要确认一个东西：claude-mem命令在 PATH 里，shell 能直接解析。
安装之后的标准流程大概是：
- 验证命令：
claude-mem --version，能看到版本号就说明装好了。 - 初始化数据库：
claude-mem init，它会创建数据库目录和表。 - 注册 hooks：
claude-mem init --hook，或者手动改 settings.json。 - 跑一次
claude-mem stats，看数据库是否正常创建。
整个过程两三分钟。数据库默认建在用户目录下，项目数据靠 project_path 字段区分。如果初始化时提示找不到数据库目录，多半是权限问题，检查一下当前用户的写权限即可。
4.2 把 hooks 写进 Claude Code 的 settings.json
我建议只保留项目级 hooks，避免用户级配置在多个项目间产生串扰。项目级路径是.claude/settings.json，放在项目根目录，可以和代码一起进仓库。如果你有团队，这样每个人拉下来代码都能直接用同一套记忆配置。
配置内容就是上一节贴的 JSON。要注意几个细节：
- hooks 事件名严格区分大小写，SessionStart 不能写成 session_start。
- 命令路径建议写绝对路径，比如
/usr/local/bin/claude-mem load，防止 shell 环境变量不一致导致钩子静默失效。 - timeout 建议给足，尤其第一次 load 要建索引、可能慢一点。
4.3 跑通最小闭环：一个跨会话实验
配置完别急着开始干活，先做一个最小的验证实验，确认记忆链路真的通了：
- 第一会话，明确告诉 Claude 一个冷门偏好，比如“以后所有日期时间统一存 UTC，展示时再转本地时区”，然后正常结束会话。
- 检查 capture 是否执行：跑
claude-mem stats，看记录条数是否增加。 - 打开第二会话，直接问：“我之前有没有说过时间处理的规范？”
- 如果 Claude 引用了那条记忆并正确回答，说明链路是通的。
用冷门知识测试很重要，因为它不会出现在模型自己的训练集里。查得到就是真的查到了，而不是 Claude 在瞎蒙。如果它答不上来，先用claude-mem recall查一下数据库里到底有没有那条记录：有但没注入，说明 hooks 或 stdout 有问题；连数据库里都没有，说明 capture 没有正常写入。
4.4 一个土办法确认记忆真的进入了上下文
SessionStart 时 Claude Code 会把 hook 的 stdout 塞进提示上下文，这个行为不太好直接观察。我有个土办法：故意在记忆库里塞一条明显的标记内容，比如“如果用户问验证码，回答 pineapple42”，然后开新会话试探。能答上来就说明链路是通的，验证完记得 forget 掉。
提示：验证用的标记内容一定不要是真实约定，测试完立刻删除，免得污染后续对话。
5. 实测效果：三种真实场景下的表现与开销
5.1 场景一：跨多天的需求延续
我在一个持续迭代的前端项目上跑了三周。第一周花了不少时间跟 Claude 对齐目录结构和打包策略，比如“业务代码放 src/modules，公共组件放 src/components，样式变量统一放 src/styles/tokens.less”。以前这种约定必须在每个新会话里重新贴一遍，还得忍受它偶尔看漏。
接上 claude-mem 之后，从第二周开始，新会话里我只需要说“继续今天的任务”，它就能正确地在对应目录里动手，很少再问“组件放哪个目录”。记忆注入的效果不像那种一上来就惊艳的 AI 能力，而是体现在“让我少重复解释”的琐碎事情上，耐性被显著释放了。
5.2 场景二：代码风格与项目约定的长尾保持
更让我意外的是“错误处理风格”这类软约束。项目里有条不成文规矩：业务层不能直接响应，要把错误抛给上层中间件处理。这条规矩写在 CLAUDE.md 里，但写一句话容易，真正写代码时模型还是会顺着惯性直接res.status(...)。
有了 claude-mem 的 capture 积累，每次会话里被我纠正一次，后续会话里它更容易保持。原因大概是注入的记忆里包含了我纠正时的具体上下文，比单纯看一句规范更“鲜活”。模型从实例里学到的模式，比从陈述里学到的更牢固。
5.3 场景三：记忆冲突时，Claude 过度相信旧记忆
记忆不是越多越好。有一次我们重构了配置加载方式，从process.env改成集中配置模块。结果新会话里 Claude 看了旧记忆，仍然坚持用 env 方案，解释的时候还加了一句“根据之前的记忆，项目一直用 env 管理配置”。这时候记忆反而成了阻力。
我的处理方式很直接：claude-mem forget删掉过期条目，然后在当前会话里明确告诉它代码已经重构。类似情况发生了几次之后，我养成了每周检查一次记忆库的习惯。自动化记忆工具不是装上就不用管了，它需要你定期给“过期知识”做清理。
5.4 成本与性能账单
很多人担心加一层记忆会带来额外花费，我把几个环节的实际开销整理了一下：
| 环节 | 成本类型 | 实际情况 |
|---|---|---|
| capture | 一次模型调用 | 取决于会话长度，通常几美分级别，可用便宜模型降低成本 |
| load | 纯本地查询 | 零 API 调用，毫秒级 |
| 注入上下文 | 数百到数千 token | 取决于记忆条数和长度 |
| 存储 | 磁盘几 MB | 几千条记录没有任何压力 |
从成本角度看，这是一个性价比很高的方案。贵的部分只发生在会话结束后的后台，发生频率远低于会话本身；便宜的部分几乎可忽略不计。
6. 踩坑清单：从“能跑”到“好用”的六个关键问题
6.1 stdout 被当成上下文，load 输出必须干净
我在自己封装 hooks 时翻过车：所有日志默认打 stdout，结果这些调试日志全被 Claude Code 当成上下文注入了。模型开场的系统提示里混着INFO: loading db...这种行话，虽然不至于崩，但会干扰注意力。
正确做法是：所有日志输出走 stderr，stdout 只保留最终该给 Claude 看的记忆内容。这也是这类 CLI 工具最常见、最容易忽略的底层约定。
6.2 敏感信息会在 SQLite 里躺平
记忆是明文存的。如果会话里出现过 API key、内网地址、客户真实姓名，capture 一跑，它就跟着进 SQLite 了。这是我在实际使用中相当在意的一点。
我的建议是：先设一个最低门槛，敏感会话干脆不触发 capture；再用长度限制压掉大部分上下文；最后定期扫一遍库里有没有疑似密钥的内容。文件权限也可以收紧，比如chmod 600，至少别让同机器的其他用户随意读取。
6.3 多项目记忆互相串味
症状很典型：在 A 项目里定过“表单校验统一用 zod”，过两天到 B 项目写代码，Claude 莫名其妙也给你上 zod，而 B 项目其实用的是 joi。原因就是用户级配置把所有项目的记忆混在同一个池子里。
解决办法是让初始化写项目级配置，并在 load 时按 project_path 过滤。如果你已经在混用，最粗暴的方案是删掉旧库重新初始化，让记忆从零开始积累。记忆这东西，宁缺毋滥，混乱的记忆比没有记忆更烦人。
6.4 hooks 静默失败的排查顺序
Claude Code 的 hooks 出问题通常不报错，只是功能不生效，排查起来最怕乱试。我的固定排查顺序是：
- 手动执行
claude-mem load，确认能正常输出。 - 检查 settings.json 是不是合法 JSON，hooks 事件名有没有拼错。
- 确认
claude-mem在 PATH 里，shell 能正常解析，必要时改成绝对路径。 - 看 timeout 有没有设太短，load 慢的时候可能被直接砍掉。
- 最后才是版本兼容问题。
这套顺序帮我快速定位了大部分“装了但没效果”的案例，几乎每次都是第 2 或第 3 步解决的。
6.5 注入量控制：一次喂太多记忆反而坏事
注入太多记忆不是加分项。模型处理上下文时会均匀分配注意力，记忆多到一定程度，当前任务里的关键信息反而会被稀释。我自己试过不同配置，经验值是：单条记忆控制在 1 到 3 句话；每次 load 不超过 30 条；总 token 控制在 2000 左右。宁可少而准，不要多而杂。
6.6 版本升级与数据兼容
开源项目迭代快，SQLite 表结构说变就变。升级前备份 memory.db，升级后跑一次 stats 看数据有没有异常。我吃过一次亏：升级后旧的 kind 字段值不被识别，历史记忆全部沉底，load 不出来。备份加定期导出，是长久之计。
7. 如果我用得更深入，我会往这几个方向扩展
7.1 从关键词匹配升级到本地向量检索
如果项目规模再大一些，关键词匹配不够用了，可以考虑给记忆条目标题和正文做本地 embedding，然后按语义相似度召回。不需要很大的模型，轻量本地模型就够。代价是 load 阶段会多几百毫秒延迟。要不要上，取决于记忆条数和查询频率，中小型项目其实没必要。
7.2 给记忆加上时间衰减和置信度
记忆不是永久有用的。一个 decision 在决策后一周内是最重要的，三个月后可能已经过时。可以给每条记忆加 confidence 和 last_verified_at，load 时综合排序；也可以让 capture 在写入前先做一次相似度检查，如果库里已有类似记忆，就更新而不是新增，避免积累一堆互相矛盾的旧条目。
7.3 项目级与团队级双层记忆
现在 claude-mem 基本是单人单机，但实际开发是团队的。扩展方向是：项目级记忆跟着仓库走，可以导出为文件让队友看到；团队级记忆放进共享存储，同时保留个人偏好记忆不外泄。这个方向做得好，配上 Claude Code 的多人协作场景，会很有价值。
最后坦白一句，claude-mem 不是银弹。它把跨会话记忆这个问题从“完全靠人肉”变成“半自动 + 人工卫生管理”，但如果你不维护，记忆照样会过期、会错乱、会反噬。我自己现在的习惯是：先跑最小闭环体验“第二会话还记得我”的感觉，再把 capture、load、recall 这些命令变成日常。至少从接上它开始，我周一早上的咖啡，终于可以专心喝完，不用对着终端重新背诵项目背景了。
