claude-mem：为 Claude 打造跨会话长期记忆的完整方案

谁还没被 Claude 的“金鱼记忆”坑过聊项目聊到一半它把半小时前定好的技术方案忘得干干净净或者你每天都要花几百字重新介绍一遍你的项目背景、代码习惯、部署环境。我最早用 Claude CLI 写代码时最崩溃的就是每次开新会话都要把上下文重新“喂”一遍而且喂得越详细后面真正谈正事的位置就越少。claude-mem 这个东西专治这个毛病。它做的事情说穿了就一句话让 Claude 的会话带上记忆而且是跨会话、可持续检索的那种长期记忆。它会在后台记录你的对话自动提炼出关键信息——你提过的偏好、拍板过的决策、确认过的约束——存到本地数据库里等你下一次开启新会话时把和当前任务相关的记忆自动注入给 Claude。你想想这就相当于给 Claude 配了一张“项目小抄”不用它自己记也不用你反复提醒。这个项目对三类人价值最大一是重度用 Claude CLI/API 做开发的程序员二是拿 Claude 当长期知识库整理器的研究者三是需要把 AI 协作流程沉淀下来的团队。接下来我会从设计思路、技术选型到实操配置和踩坑记录把这个项目的里里外外拆一遍尽量做到你能照着文章直接把记忆能力跑起来。1. 先从根上理解claude-mem 到底在解决什么1.1 无状态会话是 LLM 的“出厂设置”不管用哪个大模型核心机制都是“给定输入预测输出”。它没有真正意义上的“自我”也不存在“记着上一句话”这种状态。你每一次发起对话对模型来说都是一张白纸它能看到的所有信息就是你当前窗口里的这些 token。所谓“上下文”不是模型主动记住的东西而是你手动堆在窗口里的内容。这就带来了一个很实际的矛盾对话窗口虽然有几十万 token 的容量但每次会话结束这些内容就作废了。下次你再开一个会话又得从头开始。更麻烦的是日常对话里真正有长期价值的并不是每个字而是那些“被确认过的结论”——比如“这边数据库统一用 PostgreSQL不用 MySQL”“代码风格按 Prettier 默认配置来”“部署走 Docker Compose不要裸跑”。这些信息散落在多轮对话中你既不可能每次都重新说一遍也不可能靠截图存档去找。很多人会尝试用另一个办法把历史对话直接拼接进当前会话。这确实能让模型“看到”过去的记录但很快会撞上两个问题。一是窗口被历史占满几千行旧对话挤占了宝贵的空间模型在长文本里找重点的能力也没那么强。二是噪音太多历史里夹杂着“你好”“谢谢”“稍等我看下”这种无效内容反而干扰了模型对当前任务的判断。1.2 claude-mem 的切入角度外部记忆层claude-mem 的思路不是去“改模型”也不是把完整历史一股脑塞回去而是在会话之外单独建一层记忆系统。平时它旁路监听你的对话过程把有价值的信息抽出来、整理好、存进本地等下次会话开始时它再根据当前任务的上下文把相关的记忆作为系统提示词的一部分注入到对话窗口里。这样设计的好处非常明显。首先记忆是持久化的跨会话、跨项目都能用其次注入的内容是“精炼过的”不是原始日志占用 token 很少第三是记忆可以检索相关性高的优先展示不会把不相关的内容带到无关任务里。说白了它做的事情有点像给 Claude 配了一个外置大脑中的“长期记忆区”而每次会话窗口就是那个“工作记忆区”。1.3 与传统方案的核心差异你可能也听说过其他几种给 Claude 加记忆的野路子我简单对比一下你就知道 claude-mem 这种方案的差异在哪了。直接修改系统提示词在 Claude Code 的配置里写死一段背景说明。这种方式笨但有效问题是完全静态你项目一变就得手动改而且一个配置只能覆盖一类场景。维护 notes 文件夹有人会把自己的项目背景写进一个CLAUDE.md文件让 Claude 每次自动读取。这比写死强但依然要手动维护文件写长了同样占上下文。claude-mem 这种自动记忆层不是让你去写文档而是让它自动从对话里提炼记忆。你聊过的、确认过的、否掉的内容它替你整理。你不需要“主动维护”只需要正常用 Claude记忆就被沉淀下来了。我自己的体会是前两种方案适合“固定背景”比如告诉 Claude 你的名字、你用什么技术栈。但真正高频的痛点是“动态决策”今天定的方案、明天改的需求这些靠静态文件根本记不过来必须有一个自动化的抽取机制。2. 核心设计拆解一条记忆是怎么从对话里“长”出来的2.1 捕获层会话日志从哪来要让记忆系统懂你在和 Claude 聊什么第一步得拿到对话内容。claude-mem 利用了 Claude CLI 会话的一个特点每次会话本身会写日志。只要启动过claude命令开始一次对话系统就会在本地产生对应的会话记录这些记录是接近 JSONL 格式的对话流包含了用户输入、助手回复、工具调用等结构化信息。claude-mem 做的第一件事就是监听这些会话日志或者说在日志文件上做增量读取。前一次会话结束时你说了句“就用这个方案吧”这条信息就被默默记进了待处理队列。这个设计很巧妙它不需要改 Claude 本身的配置也不需要劫持 API 请求只是“读日志”所以通用性很强、侵入性极低。如果对日志抓取不熟悉可以把它类比成一个后台的“录音笔”你和 Claude 的对话过程它一直在后台做着高保真记录但不会打断你、也不影响对话本身只会等这一段聊完之后再去整理录音内容。2.2 提炼层从原始对话里抽取记忆点拿到了原始对话接下来不能直接全文存库否则就退化回“塞历史”的老路上了。claude-mem 的提炼过程本质上是一次摘要任务但它做的不是简单压缩而是定向抽取。具体来说它会针对每一轮对话按几个维度判断哪些信息值得沉淀用户明确表达的偏好比如“我不喜欢用单引号”“报错信息要贴完整上下文”。项目层面的约束比如“生产环境不要开 debug 模式”。已经确认的技术决策比如“用 Redis 做缓存层”。用户主动要求记住的内容比如“接下来我们约定接口一律走 /v2”。值得长期参考的事实比如“这个服务的超时上限是 3 秒不能改”。抽取动作本身就是一次调用 LLM 的过程一般走摘要模型或者小模型。成本可以接受因为不是每句话都处理而是按会话段落或事件节点触发。抽完之后的产出是一小段结构化的“记忆条目”通常包括记忆正文、来源会话 ID、产生时间、对应项目等元信息。2.3 存储层SQLite 加向量索引记忆抽取出来之后要有一个靠谱的落脚点。claude-mem 用的是本地 SQLite 为主存储外加向量化索引来做语义检索。SQLite 的好处不用多说单文件、零运维、跨平台读多写少的场景它非常稳。每条记忆一条记录字段设计上通常包括id唯一标识content记忆正文提炼后的文本片段project所属项目标识用来按项目隔离session_id来源会话created_at时间戳embedding文本向量值这里我额外提一下向量索引的作用。记忆存了一两百条之后不可能全部注入到每次会话里必须按“和当前任务的相关度”去筛选。比如你现在在聊前端组件拆分系统当然不能把上个星期和后端联调的记忆一股脑塞给你它得找出“和前端相关”的那几条。这个相关性匹配用传统的关键词命中不够灵活语义向量匹配就合适得多——把记忆正文和当前任务描述都转成向量算一个余弦相似度按阈值取 Top N。这个方案我试下来最顺手的一点是存储和检索解耦。存储层就是普通的 SQLite 查询你随时可以用数据库工具打开看里面到底存了什么透明度极高检索层是浮在存储上面的一个功能接口不需要的时候完全可以绕过直接做全量注入。2.4 注入层记忆如何参与下一次对话这是 claude-mem 的关键一步也是它和 Claude 集成深浅的分水岭。浅的做法是把记忆拼进你输入的文本里你每次提问前它先把记忆作为背景字块前置输出。这种做法对 CLI 环境不太好用因为用户不可能老手动触发也不符合“零感知”的理念。claude-mem 采用的是更深的集成如果用的是新版 Claude Code 或支持 MCP 的客户端它直接走 MCP 协议。MCP 全称 Model Context Protocol相当于给 AI 应用提供了一个标准的“外部工具接入协议”。claude-mem 以 MCP 服务的形式跑起来Claude 在会话开始时就能主动向它发起“查询记忆”的工具请求把返回内容作为上下文的动态补充。注入时机和策略上比较成熟的方案是分层注入。每次会话开始时注入一小部分“全局记忆”比如用户的通用偏好随后根据当前对话内容按需查询“相关记忆”只有当相关记忆量不足时才考虑注入会话摘要。这样能最大化控制 token 开销不让记忆占据主对话的位置。这套机制触发起来完全靠程序自动判断——由 Claude 自己在合适时机调用记忆工具用户在输入框里正常打字记忆就在后台完成了检索、注入、回应。相比手动粘贴历史记录效率提升非常明显。3. 实操过程把 claude-mem 跑起来的完整流程3.1 环境准备与安装动手之前先确认一下环境。claude-mem 面向的是已经装好 Claude CodeCLI 版本的用户你需要有一个能用命令行直接对话的 Claude 环境同时最好开通了 API key 用来支撑提炼摘要的模型调用。项目本身一般通过 npm 安装如果你本地已经有 Node.js 18 以上环境直接全局安装就行。我以常见安装路径为例帮你走一遍安装命令# 安装全局工具 npm install -g claude-mem # 查看版本确认安装成功 claude-mem --version装完之后需要初始化一个本地存储目录这个目录会用来放 SQLite 数据库文件和配置文件。一般在用户主目录下创建一个.claude-mem文件夹作为默认的数据根目录。不同版本的项目可能提供一键初始化命令执行完会自动生成默认配置模板方便后面二次修改。# 初始化存储目录与默认配置 claude-mem init初始化完成后建议先打开配置文件看一眼。里面可以看到数据库路径、项目名映射规则、记忆抽取触发阈值、注入条数上限这些关键参数。我个人的习惯是把记忆抽取的触发阈值调得略高一些避免连“今天天气不错”这种话都被当成记忆存下来。阈值高宁缺毋滥存下来的都是真正有价值的信息。3.2 配置 MCP 集成安装和初始化只是准备工作真正让 claude-mem 进入工作状态的是 MCP 配置。在用 MCP 之前你得先在 Claude 的配置文件里注册这个记忆服务让 Claude 知道“外部有一个工具可以调用”。如果你用的是 Claude Code 新版本配置文件通常是一个 JSON 或 TOML 格式的文本里面维护了一个mcpServers列表。claude-mem 注册进去大概长这样{ mcpServers: { mem: { command: claude-mem, args: [serve], env: { CLAUDE_MEM_PROJECT: my-project } } } }注册完成之后重启 Claude Code再用一次对话测试。你可以直接问它“你记得我上个项目里说过数据库必须用 PostgreSQL 吗”如果它能答上来说明记忆链路已经通了如果答不上来多半要检查两件事一是 MCP 服务有没有成功启动二是记忆库里到底存没存进去数据。项目区分这块我特别提醒一下。很多人一开始没在意所有对话都混在一个记忆库里结果在 A 项目里聊的配置被带到了 B 项目的会话里。正确做法是每个项目单独标注确保记忆按项目隔离。配置里可以把环境变量CLAUDE_MEM_PROJECT指到当前项目名或者通过配置文件里的项目映射规则来动态识别。3.3 日常使用与记忆管理命令集成配好之后日常使用倒不太需要额外操作你正常和 Claude 对话就行。但记忆系统总会有需要人工介入的时候比如发现存了一条错误记忆或者想清空某个项目的全部记忆。这时候 claude-mem 的命令行管理能力就有用了。我最常用的几个命令是# 手动列出最近 N 条记忆 claude-mem list --project my-project --limit 20 # 按关键词搜索记忆 claude-mem search --project my-project PostgreSQL # 删除某一条记忆用 id 定位 claude-mem delete --id 8f2a1c # 手动触发一次当前会话的记忆抽取 claude-mem extract --session session-id管理记忆就像管理自己的笔记软件一样定时清理是必要的。我发现记忆条目堆积到几百条之后即使有向量检索兜底也还是会出现注入内容不够精准的情况因为相似语义的记忆互相干扰。所以我会每隔一两周手动看一遍清单把过时、错误、重复的记录删一删。这个动作不复杂但能明显提升后续检索的精确度。3.4 把记忆扩展成团队共享知识库单机版的 claude-mem 跑顺了之后还可以尝试更进一步把记忆库放到一个共享位置让团队成员共用一套记忆。这个做法对团队协作特别有用——新人加入项目时不需要翻文档直接问 Claude 项目约束它就能从共享记忆里查到答案。技术实现上并不复杂SQLite 本身就是单文件你把它放到 NAS 或云盘同步目录里团队里每个人在配置里把数据库路径指到同一个文件即可。不过我得提醒你SQLite 的并发写锁限制比较明显多人同时写入时可能产生锁竞争。我的建议是正常读多写少的场景问题不大但如果团队规模超过三四个人且操作频繁尽量让每个人的本地写入走独立副本定期合并而不是直接让多人连同一个文件。把它当知识库用的时候我习惯在项目约定里加一条“所有重要的技术决策必须通过对话向 Claude 确认一次”确认过程自然会产生记忆。长期下来这个记忆库会变成一个活的、不断更新的项目资产比静态文档有价值得多。4. 常见问题与排查实录我踩过的坑4.1 记忆不生效Claude 依然“失忆”这种情况最让人抓狂。配好了、也对话了但下次开新会话问它它还是什么都不知道。我排查这类问题的顺序一直很固定先查记忆库里面有没有数据。用claude-mem list看看如果输出为空那问题出在“捕获或提炼”这一层要么是会话日志路径不对要么是提炼任务没跑。再查 MCP 服务注册是否正确。如果记忆库里明明有数据、但 Claude 就是调不到大概率是配置文件里mcpServers的路径写错了导致 Claude 启动时拉不到这个工具。最后查注入策略。有些版本默认不会在每个会话自动注入需要你在配置里打开“会话启动时自动查询记忆”的开关。有一次排查了很久最后发现是因为我用了代理环境变量导致 MCP 服务在启动时访问不了提炼模型接口直接启动失败。把环境变量理清之后就通了。4.2 记忆注入导致上下文窗口撑满记忆注入看着是省事但它不是零成本的。我刚用的时候把注入上限调得很高每条记忆的保留长度也没限制结果一个复杂任务下来记忆部分占了三四千 token真正留给对话的空间被严重挤压。解决方法是控制注入量。我通常把每条记忆的长度控制在两行以内并把单次注入条数限制在个位数。具体数值没有绝对标准取决于你任务的平均复杂度。如果你是做简单问答5 条足够如果是做大型代码重构反而建议减少记忆注入宁可自己手动贴一两条关键历史也要给代码上下文留足空间。4.3 隐私敏感信息被存进了记忆库这是我最想强调的一点。记忆系统是一个自动化的记录器它分不清“这个信息我可以记住”和“这个信息绝不能落盘”。有的用户会在对话里不小心输入密码、密钥、内网地址这些内容一旦被抽成记忆条目就会以明文存在本地 SQLite 里。文件本身没加密任何有机器访问权限的人都能读。我的建议是给 claude-mem 配一个敏感信息过滤规则写一个关键词黑名单凡是命中的内容都不进提炼流程。比如password、token、api_key、secret这些关键词直接拦截。另外生产环境的密钥一定要走系统环境变量不要出现在对话里这是底线问题。4.4 记忆污染存储了错误或过时的信息记忆系统最大的隐患不是没有记忆而是记住了一些错误的东西。举个例子你在某个项目早期定了“数据库用 MySQL”后来下一轮又改成“用 PostgreSQL”如果两次对话都被抽成了记忆那这两条记忆是冲突的。接下来 Claude 在检索时可能随机选中其中一条于是行为就不稳定。这个问题只能靠人工兜底。我会定期用管理命令清理过期记忆同时在新决策确认时有意识地说一句“之前说的方案作废改用新方案”。这样的话提炼层更容易识别这是对旧记忆的更新。现在不少记忆工具会加时间衰减或“冲突检测”但至少在 claude-mem 早期版本里手动维护仍然免不了。4.5 常见故障速查表症状可能原因排查操作修复建议记忆完全不生效会话日志路径配置错误运行claude-mem list确认数据是否入库修正日志路径配置Claude 不调用记忆工具MCP 注册失败或路径不对检查配置文件中的mcpServers段重新注册并重启 Claude上下文被记忆占满注入条数/长度上限过高查看配置中的上限参数调低注入条数和记忆长度记忆里出现敏感信息没有过滤规则直接查数据库原文配置敏感词黑名单并删除旧记录记忆互相冲突决策变更后旧记忆未清理使用claude-mem list和搜索定位手动删除过期条目提炼任务耗时过长模型调用的频率或阈值过低观察日志中的处理耗时提高触发阈值或降低频率写在最后我的使用体会和一点建议如果你准备在团队里推广 claude-mem我的建议是先别急着铺开。你先自己用一个星期跑一个真实项目把存储库里的记忆结构和抽取质量摸清楚。我刚开始用的时候抽取出的记忆里大概有三分之一是“噪音”比如把无关紧要的确认语气也当成了决策。后来我把触发阈值调高、加了一套项目前缀规则精准度才上来。任何记忆工具都需要调校不存在装上就完美的方案。还有一个小技巧把记忆系统当成你的第二个大脑而不是一个黑盒。定期打开数据库看看里面到底存了什么。我看到很多用户把 claude-mem 配好之后就再也不管了结果一两个月后记忆库里全是过时信息检索效果直线下降。每天花两分钟滚动浏览一遍晚上顺手删掉几条明显过时的这个习惯比任何参数调优都管用。我在实际项目里坚持这个习惯两个多月后最明显的感觉是每次和 Claude 开新会话它不需要我重复任何背景直接就进入正题了。这个“被记住了”的体验用过一次就回不去了。