Claude Code 装上跨会话记忆：claude-mem 实战指南

接触 claude-mem 纯属偶然。当时我连着两个礼拜用 Claude Code 写一个内部工具每天第一件事就是把项目背景、技术栈、代码规范重新讲一遍讲到第三遍我就开始怀疑人生这玩意儿不是号称能写代码吗怎么连我昨天说过接口统一走 /api/v2都不记得后来某天在技术群里看到有人讨论给 Claude Code 装记忆顺着线索摸到了 claude-mem 这个项目。实测下来它确实解决了我最头疼的跨会话记忆问题——Claude Code 每次对话是独立的上下文窗口一关什么偏好、决策、踩过的坑全清零。而 claude-mem 就像给 AI 配了一本随身笔记自动记录重要信息下次新会话里直接搜索就能想起来。这篇文章我不打算写成文档翻译就按我自己的实操顺序讲讲这工具到底解决什么问题、内部怎么运作、怎么配起来真正跑通以及我踩过的几个坑。适合正在被每次都要重复交代背景折磨的 Claude Code 重度用户也适合想给自己的 AI 工作流加一层持久记忆的人。1. 为什么 Claude Code 需要一个外部记忆1.1 会话隔离带来的重复劳动Claude Code 的工作方式是一条会话一条会话地推进。它每次启动会加载当前项目文件作为上下文但上一轮对话里你做的决策、定的命名规范、排除掉的方案它并没有地方保存。第二天继续干活它像个刚入职的实习生什么都要重新教。我遇到的最典型场景一个项目里选型定的是轻量级方案当时跟 AI 来回讨论了十几轮把理由和约束条件都讲清楚了。第二天新建会话让它继续改需求它直接推荐了另一个方案理由是这个更主流。不能说错但它把昨天拍板的决定完全忘记了我得再花二十分钟把前因后果讲一遍它才恍然大悟。这种重复劳动在小项目上还能忍项目多起来、周期拉长以后基本就是每天在给 AI 补课。真正的问题不是 AI 不聪明而是它没有跨会话的长期记忆每次都在失忆状态下工作。1.2 个人偏好与团队规范丢失比技术选型更烦的是个人偏好和团队规范。比如我习惯用单引号、缩进两个空格、错误处理统一走自定义的错误类型团队有接口命名规范、commit 前缀规范。这些东西散落在各种文档里每次想让 AI 遵守要么粘贴规范文件要么在对话里反复强调。有一次我实在受不了把规范写进 CLAUDE.md 里情况好了一些但 CLAUDE.md 只能覆盖当前项目而且更新不及时。真正养成的偏好应该沉淀在记忆里而不是靠手动维一个文档。claude-mem 的思路就是解决这个它有自动提取机制会在对话过程中识别这是一个值得记住的偏好/决策/教训存到本地数据库里。下次开会话一条搜索命令就能翻出来。2. claude-mem 的设计思路一个旁路记忆服务2.1 它不改Claude只是挂在旁边第一次看到 claude-mem 的架构图时我第一反应是这设计挺聪明的它没有去改 Claude Code 本身的代码而是在旁边开了一个独立服务通过事件监听的方式把对话过程中值得沉淀的信息捞出来存起来。整个链路大致是这样的Claude Code 运行时会把会话事件用户消息、助手回复、工具调用结果推送给 claude-memclaude-mem 跑在后台收到事件后做两层处理过滤和提取能存下来的信息按类型归档比如偏好、决策、教训、项目事实新会话里通过搜索接口MCP把相关记忆抬出来塞回上下文这架构的好处在于解耦。记忆服务挂了不影响 Claude Code 主流程更新记忆逻辑也不用重新装 Claude Code。本质上是一个旁路的记忆模块不侵入主程序。2.2 记什么、不记什么是设计核心真正花心思的是该记什么。如果所有对话全部都存下来数据库很快变成一锅粥搜什么都搜不准。claude-mem 的做法是事件驱动加规则提取只保留有长期价值的内容。我自己总结下来它重点捕获这几类用户明确表达的意见比如以后都用 X、不要用 Y重复出现的模式比如某个报错连续出现三次以上决策类内容例如方案 A 被否了原因是性能不达标代码库的关键事实比如这个模块已经废弃了不是所有信息都值得存存得多不如存得准。这也解释了 claude-mem 为什么做一个独立服务而不是简单地在 Claude Code 配置里加一个历史记录文件——它需要一套自己的过滤和提取逻辑这个逻辑应该独立演进。3. 安装与初始化从零到跑通3.1 环境准备claude-mem 是用 TypeScript 写的跑在 Node 环境上所以前置条件就两个装了 Node.js版本稍微新一点以及 Claude Code 本身处于可用状态。其它依赖基本都内置了不需要额外装数据库默认用 SQLite 文件存储这对我这种不喜欢折腾服务的人很友好。Node 版本建议 18 以上太低的话某些依赖装不上。我当时是在 macOS 上安装Linux 应该也没问题Windows 的话最好用 WSL 环境纯 PowerShell 环境下可能会出现路径问题。3.2 安装步骤实录安装本身很简单一条命令的事。实际过程我把它拆成四步安装核心包我用的 npm 全局安装装完检查一下版本号确认成功。初始化配置目录工具会在你的用户目录下创建一个隐藏文件夹用来放 SQLite 数据库和日志文件。启动记忆服务它默认会在本地某个端口起一个 HTTP 服务同时监听 Claude Code 的事件推送。接入 Claude Code在配置文件里声明 MCP 服务地址让 Claude Code 在会话启动时自动连上 claude-mem。这四步走完基本就处于静电状态了平时你正常用 Claude Code它在后台默默记录需要用记忆时调用命令或者让 AI 自己去查。注意安装后先跑一下诊断命令确认服务状态是 running 再开始干活。我头一回就是因为忘了启动服务配置了半天结果 Claude Code 一直报连不上。3.3 接入 Claude Code 的两种姿势接入方式有两种我推荐第二种方式做法适合场景手动配置在 Claude Code 的配置文件里手动添加 MCP 服务器地址和 token机器少、固定环境、想完全掌控配置自动配置运行工具自带的 setup 命令自动写入配置并拉起服务多项目、多终端、不想手动维护我一开始是用手动配置后来项目多了换到自动配置实测省心很多。它会把 MCP 的服务名、地址、鉴权信息都写进去还会做一次连通性测试。不过自动配置也有个前提它需要找到 Claude Code 的配置文件位置如果你的配置路径是自定义的可能得手动补一下。配置完成后可以新建一个会话输入/mcp之类的命令查看 MCP 服务是否在线。看到 claude-mem 出现在列表里且状态为 connected说明通道已经通了。4. 实操让记忆真正跑起来4.1 主动存记忆一条命令的事claude-mem 最基础也是最实用的功能就是手动存档。在对话过程中如果遇到你认为值得长期记住的内容直接输入存储命令再附上内容说明。比如/mem 项目代号 S 的接口地址前缀统一用 /api/v2旧版 /api/v1 不再更新它会把这句存进 SQLite并打上时间戳和来源会话标识。这个功能的价值在于主动沉淀当你发现 AI 开始反复问同一个问题时与其再回答一遍不如存一条记忆下次直接让它搜。我实际使用的频率是每次会话里存 3 到 5 条包括技术决策、命名约定、排除掉的坑、某个文件的具体位置。存的时候尽量写能被搜索到的句子关键词要具体。比如不要存注意性能这种废话要存订单列表接口超过 1 秒就告警瓶颈在数据库 N1 查询。4.2 搜索记忆唤醒过去的信息新会话里想用历史记忆最直接的方式是搜索命令/mem 搜索 订单超时问题它会把匹配到的历史记录按相关度列出来包括时间、来源会话摘要、内容片段。你可以选择把某一条加入当前上下文让 Claude Code 基于这个记忆继续工作。这个搜索过程实际是走 MCP 协议Claude Code 把用户意图传给 claude-memclaude-mem 在 SQLite 里做全文匹配和关键词打分返回结果。因为数据库是本地文件搜索速度基本是毫秒级体感跟本机搜索一样快。4.3 自动提取让记忆自动生长比手动存档更省心的是自动提取。这是 claude-mem 的隐藏技能它不仅仅是存储命令的仓库它还在后台监听对话事件自己判断哪些内容值得记录。我观察了一段时间它的自动提取准确率大概在七八成。比如某次我说这个项目不用考虑老的浏览器兼容了它之后就自动存了一条项目 X 不再支持旧浏览器的偏好记录。又比如我们发现一个诡异的并发 bug排查了半小时才定位到是缓存 key 冲突它把结论也提炼进了记忆库。自动提取的策略我猜是有几个信号用户用祈使句给指令、某句话里带不要/必须/以后/永远这类词、AI 在回复中总结的结论性句子。这些都是高价值信号。当然它也会误存比如我随口说的一句以后再说也会被当偏好存进去。所以它提供了一个管理界面可以查看所有存进去的记忆不合适就删。实操心得自动提取适合作为粗筛手动存档才是精炼。我一般每周花十分钟把记忆库刷一遍删掉误存的把模糊的改写成更精确的表达。这个习惯保持下来记忆库质量会越来越高。4.4 跨会话实战一个完整的例子说一个我实际跑通的场景。公司有个老项目要重构我第一周和 Claude Code 讨论了技术方案决定保持服务端渲染、前端逐步迁移到新组件库并约定不碰某个遗留模块。当时我在对话里说了很多理由这些信息被 claude-mem 自动记录了一部分我又手动补了几条关键决策。第二周换了个全新会话我直接说继续上周的重构计划然后跑了一下搜索命令把上周的几条核心决策拉了出来。AI 看到这些记忆后很快进入了状态它知道哪些模块不能动、新组件库用哪个版本、接口设计原则是什么没有再问一遍这个项目是什么结构。这个体验比没有记忆之前顺畅太多了。以前是每次都要把两周的项目进展浓缩成一段背景介绍现在只需要一个搜索动作。5. 存储、隐私与维护数据放在哪儿了5.1 本地数据库里有什么claude-mem 的数据默认存在用户目录下的一个隐藏文件夹里核心是 SQLite 文件。这个数据库里主要有几张表对话归档表存会话信息记忆条目标记关键内容还有一张标签表用来做分类。用 SQLite 而不是外部数据库这个选择很务实零配置、单文件、备份只需要复制一个文件。对于个人使用场景来说完全够用也没有额外的运维负担。有一点要注意记忆内容默认是不加密的存储的就是明文。如果你在对话里会涉及敏感信息建议在配置里打开加密选项或者至少不要把密钥类的东西直接喂给对话记录。5.2 备份、清理与迁移数据文件虽然小但它会随着使用不断增长。我用了两个月文件大约十来 MB增长主要是自动提取的条目。这里有两个维护习惯定期备份直接把整个配置目录打包走就行我写了一个 cron 任务每周自动 tar 一次丢到备份盘。定期清理删除过时的、错误的记忆条目。claude-mem 提供了列表和删除命令也可以直接打开 SQLite 手动处理但不建议新手这么干。迁移到新电脑也简单把配置目录整体拷过去重新装一遍工具启动时指定一下数据目录位置就无缝接上了。6. 常见问题排查与避坑指南6.1 我踩过的几个坑使用过程中我遇到了不少问题挑几个有代表性的列出来。现象原因解决方案搜不到任何历史记录服务没启动或者 MCP 连接失败检查服务状态重新连接 MCP自动提取完全没生效事件监听没有正确订阅检查配置里的监听开关确认会话启动时服务在线记忆内容乱糟糟搜出来一堆废话自动提取阈值太低误存太多调高提取阈值手动删掉低质量条目数据库文件被占用无法备份Windows 下 SQLite 文件句柄未释放先停掉 claude-mem 服务再备份跨项目记忆串味所有项目共用一个数据库开启项目隔离功能或用环境变量指定不同数据目录6.2 关键排查命令遇到问题先不要慌记住三个命令查看服务状态确认到底有没有在跑查看最近事件日志看 Claude Code 的事件到底推没推过来手动测试 MCP 通道确认 Claude Code 能连上这三个命令基本能定位九成问题。我遇到最多的还是服务没启动这种低级问题因为 claude-mem 作为一个后台服务不会自动开机自启重启电脑后容易忘记拉起来。注意Claude Code 升级后MCP 配置有可能会被重置。每次升级完顺手检查一下 MCP 列表别等到要用记忆了才发现连接断了。6.3 一些值得一试的高级用法除了基本功能claude-mem 还有几个进阶玩法记忆导出把整个记忆库导出成 Markdown 或 JSON方便做周报或者知识沉淀多项目隔离给不同项目指定不同的记忆库互不干扰自定义提取规则可以通过配置文件告诉它凡是提到 XXX 关键词的内容都要重点记录我现在就把几个长期维护的项目分成了不同的记忆库每个库只记自己项目的事情。虽然多了一道配置但搜索时不会被无关内容干扰准确率明显提升。最后再分享几个个人经验用 claude-mem 这段时间我最深的体会是记忆工具的价值不在于存得多而在于找得准。刚开始我巴不得把所有对话都录进去后面发现记忆库乱成一团反而不敢用了。后来养成定期整理的习惯只保留真正重要的决策和偏好搜索体验才真正好起来。另一个小技巧是配合 CLAUDE.md 一起用CLAUDE.md 负责当前项目的静态规范claude-mem 负责跨会话的动态记忆两者互补。静态规范不依赖记忆检索每次会话自动加载动态记忆则解决这次对话里才提过的事下次别再问的问题。两者配合下来Claude Code 才真正像一个有连续工作记忆的协作者。如果你也在被每天重新教一遍 AI 怎么干活折磨试试这个工具。不指望它教 AI 变聪明但它能让 AI 记住你说过的话这已经能省下大把时间了。