用 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 tokenrefresh token 存 httpOnly cookie2025-06-10。 - API 错误统一抛 ApiError禁止在业务层直接 res.status(...)2025-06-11。 ## Discoveries - 定时任务本地开发用 npm run cron:dev 启动不要手工跑 node2025-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-memSQLite、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它会创建数据库目录和表。注册 hooksclaude-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...这种行话虽然不至于崩但会干扰注意力。正确做法是所有日志输出走 stderrstdout 只保留最终该给 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 是不是合法 JSONhooks 事件名有没有拼错。确认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_atload 时综合排序也可以让 capture 在写入前先做一次相似度检查如果库里已有类似记忆就更新而不是新增避免积累一堆互相矛盾的旧条目。7.3 项目级与团队级双层记忆现在 claude-mem 基本是单人单机但实际开发是团队的。扩展方向是项目级记忆跟着仓库走可以导出为文件让队友看到团队级记忆放进共享存储同时保留个人偏好记忆不外泄。这个方向做得好配上 Claude Code 的多人协作场景会很有价值。最后坦白一句claude-mem 不是银弹。它把跨会话记忆这个问题从“完全靠人肉”变成“半自动 人工卫生管理”但如果你不维护记忆照样会过期、会错乱、会反噬。我自己现在的习惯是先跑最小闭环体验“第二会话还记得我”的感觉再把 capture、load、recall 这些命令变成日常。至少从接上它开始我周一早上的咖啡终于可以专心喝完不用对着终端重新背诵项目背景了。