★ FEATURED ARTICLE Claude Code 用久了很多人都会遇到一个特别拧巴的场景上午刚让 AI 梳理完整个项目的模块划分下午新开一个会话它又一脸茫然地问你这个项目的技术栈是什么。你甚至懒得解释只能把需求重新贴一遍再附上一句之前不是说过了吗。claude-mem 这个工具就是专门来解决这种AI 失忆症的。它本身不改变模型能力而是在模型之外加了一层长期记忆。核心思路非常朴素把你在 Claude Code 里每一轮有价值的对话、决策、项目约定自动抽取出来存到本地 SQLite 数据库里下一次新会话启动时再根据当前上下文把相关的记忆重新注入给模型。这样 AI 虽然本质上还是那个每次都是新面孔的模型但它的记忆却被你留在了本地。这篇文章我会从机制到实操把 claude-mem 的完整用法拆一遍重点讲清楚它背后的记忆提取逻辑、安装配置的细节、日常使用中容易踩的坑以及我自己的几个进阶玩法。适合正在使用 Claude Code、被重复上下文折磨得不耐烦的开发者。1. 项目概述claude-mem 是什么解决的到底是什么问题1.1 用过 Claude Code 的人都懂上下文断裂有多痛Claude Code 的会话机制本质上是一次性的。你每开一个新会话模型拿到的上下文就是当前对话窗口里的内容外加你手动写在配置文件里的那点东西。上一条会话里讨论过的架构方案、踩过的坑、最后拍板的接口设计通通不会自动带过来。以前大家是怎么解决这个问题的最常见的是维护一个 CLAUDE.md 或者项目说明文档把本项目的重要约定一股脑写进去。但这里有个天然缺点这玩意儿是静态的、手写的。你得自己记得去更新它而且更新时机往往滞后。AI 在会话中自己做出的决策、你对方案的反驳和修正、以及那些试了 A 方案不行改走 B 方案的隐性经验都不会自动沉淀下来。我统计过自己的使用情况在没引入 claude-mem 之前每次新开会话光复述背景信息就要花掉三四轮对话。多人协作时更痛苦同事问你这个模块当时为什么用 PostgreSQL 不用 MySQL你只能回去翻聊天记录。上下文断裂不只是一个便利性问题它直接拉低了 AI 编程工具的实际产出效率。1.2 claude-mem 的定位与核心价值claude-mem 瞄准的就是这个空白。它做的事情简单说就是会话记忆的自动抽取、结构化存储、按需回填。你可以把它理解成给 Claude Code 装了一个外挂的海马体模型本身没有变记忆能力但每次会话开始时它能把之前沉淀下来的相关经验重新喂给模型让 AI 看起来好像一直记得你。跟传统 RAG检索增强生成方案比claude-mem 轻量得多。它不需要向量数据库不需要搭服务甚至不需要配置嵌入模型一条 sqlite3 命令就能管理全部数据。对于个人开发者和三五人的小团队来说这比搭建一套知识库系统划算太多了。它解决的也不是单次会话的效果而是跨会话的连续性问题这两者对 AI 编程体验的影响是量级上的差别。方案维护成本自动程度上下文连续性适用场景CLAUDE.md低但全靠手动低弱稳定的项目约定人工笔记高容易遗忘低弱临时性备忘claude-mem安装后几乎零干预高强频繁使用 Claude Code 的日常开发2. 核心机制拆解记忆是怎么被提取、存储和回填的2.1 三层记忆模型我第一次用 claude-mem 的时候以为它就是一个简单的记录对话日志工具用了几天才发现它的记忆结构分了三层不同层级的记忆有不同的生命周期和召回方式。第一层是核心记忆Core Memory对应的是跨项目通用的个人偏好。比如你习惯用 Python 3.11、提交信息必须按 Angular 规范写、前端组件库统一用 Ant Design。这些属于这个人做事的方式适用于所有项目提取后会长期保留。第二层是项目记忆Project Memory绑定某个具体项目目录的知识比如这个仓库的支付模块用的是状态机模式生产环境数据库连的是主从架构只在该项目的新会话中召回。第三层是会话记忆Session Memory这是最细粒度的记忆记录一次会话里产生的具体事实比如刚才把接口超时时间从 2 秒改成了 5 秒。这个分层设计相当聪明。如果所有记忆混在一起跨项目召回时就会污染上下文反而降低模型判断的准确性。分开存储之后召回范围可以通过项目路径自动圈定相关度会好很多。用生活中的例子类比核心记忆是你的职业习惯项目记忆是某个客户项目的规矩会话事实是前两天刚讨论过的具体安排三者的保鲜期和适用范围完全不一样。2.2 存储引擎为什么选 SQLiteclaude-mem 把记忆数据放在本地 SQLite 数据库文件里而不是用 MySQL 或者 MongoDB更不是向量数据库。我一开始也觉得奇怪按说记忆检索应该用向量比较才算智能后来实际用起来才明白这个选择的合理性。对于个人工具场景记忆条目的量级也就是几千到几万条SQLite 的 FTS5 全文搜索在这个量级下响应速度快得根本感知不到延迟。SQLite 是单文件数据库备份就是把.db文件拷贝走同步到新机器也是拷过去就行完全不需要运维。最实用的一点是你可以用系统自带的 sqlite3 命令直接在终端里查记忆数据排查问题的时候特别方便。向量检索当然也可以插进来做语义匹配但大多数场景下用关键词精确匹配已经足够。毕竟记忆通常是你自己写的或者 AI 从对话里提取的术语本身就比较准确这时候全文搜索命中率并不差。工具设计者没有为了显得高级而引入重依赖这个克制我觉得是对的。2.3 自动提取与回填的工作流程claude-mem 的完整工作流程可以拆成四步每一步我都在实际使用中验证过。第一步是监听会话。它通过 MCP 协议跟 Claude Code 通信MCPModel Context Protocol模型上下文协议本质上是一个标准接口让模型可以调用外部工具。claude-mem 作为 MCP 服务端能拿到当前会话的元数据包括项目路径、会话 ID 等。第二步是候选记忆采集在会话进行过程中它会根据启发式规则识别可能值得记住的片段。第三步是会话结束后的提取这个阶段会调用模型对候选片段做一次过滤和精简把口语化的对话整理成结构化的记忆条目再写入 SQLite。第四步是召回与注入下次新会话启动时claude-mem 根据当前项目路径做相关性匹配把最相关的记忆插入到系统提示词里让模型在回答问题之前就已经知道了历史背景。阶段触发时机核心动作产出监听会话持续中收集对话上下文原始片段采集会话进行时启发式规则筛选候选候选记忆提取会话结束后模型整理与精炼结构化记忆条目回填新会话启动时相关性匹配与注入注入后的系统提示词这里面最关键的环节其实是第四步的回填。记忆存了不用就是死数据回填做得好不好取决于相关度匹配的算法和一整套过滤逻辑。实操中你会发现回填的记忆需要控制数量如果一股脑把所有历史记忆全塞给模型上下文窗口会爆而且杂音会干扰模型判断。默认配置下只会注入最相关的几条这个度需要根据自己的项目复杂度来调。2.4 过滤和去重逻辑记忆系统做不好很容易变成垃圾场填满垃圾。claude-mem 在这块做了两层处理。第一层是价值过滤谢谢好的可以这类寒暄和确认性话语会在采集阶段就被抛掉。第二层是语义去重同一个决策如果在多个会话里被反复提到系统会保留信息量最完整的那条并合并其它条目里的补充信息。从我自己的使用经验看这两层过滤在 80% 的场景下是够用的。但因为它本质上还是依赖模型判断偶尔也会出现误杀或者漏网。我遇到过把一次重要架构讨论的片段当成噪音丢掉的情况也遇到过把两个相似但不同的 Bug 修复记录合并成一条的情况。这类问题后面在第 5 节会专门讲排查和处理办法。3. 安装配置全流程从零到一跑起来3.1 环境准备安装 claude-mem 之前我建议你先确认自己的环境满足四个条件。第一电脑上得有 Node.js 运行时版本建议 18 以上。因为 Claude Code 本身就是 Node.js 生态的工具claude-mem 作为它的扩展同样跑在 Node 环境里你机器上既然能跑 Claude CodeNode 环境基本就有了。第二需要 npm 或 pnpm 包管理器用于安装 claude-mem 本体。第三要装好 git这不是安装 claude-mem 的硬性要求但后面如果你想从源码构建或者参与二次开发没有 git 会很不方便。第四提前装好并至少跑通过一次 Claude Codeclaude-mem 是在它的基础上做增强不会替你解决 Claude Code 本身的安装问题。操作系统方面macOS 和 Linux 用起来最顺手Windows 在 WSL 2 环境下也没问题。我的建议是如果你的主力环境是原生 Windows优先开一个 WSL 2之后所有环节都会顺畅很多。3.2 安装与初始化安装过程并不复杂核心命令就两条。如果你通过 npm 安装执行npm install -g claude-mem如果你想用最新源码或者对项目做二次开发可以走 git 路线git clone https://github.com/yourfork/claude-mem.git cd claude-mem npm install npm run build npm link安装完成之后进入一个你已经用 Claude Code 跑过的项目目录执行初始化claude-mem init这一步它会做三件事在用户主目录下创建~/.claude-mem/文件夹生成配置文件config.json和 SQLite 数据库文件memories.db然后尝试在当前项目里注册 MCP 服务。初始化完成后需要重启 Claude Code 才能让 MCP 生效。验证是否装好可以跑一下状态命令claude-mem status看到类似Database OK的提示就说明数据层没问题。我再提醒一句init是在项目目录级别执行的如果你在另一个项目目录下也要用 claude-mem需要重新在那个目录里执行一次claude-mem init来注册 MCP 服务否则 Claude Code 不会在那个项目里加载记忆工具。3.3 核心配置参数说明配置文件默认路径是~/.claude-mem/config.json。我用文本编辑器打开后的默认内容大概是这样的{ memoryDir: ~/.claude-mem, autoMemorize: true, maxMemoryContext: 5, minSimilarity: 0.4, projectScope: auto }这四个配置项是日常起作用的我一个个说。memoryDir是记忆数据的存放目录默认在用户主目录下。如果你有多个工作目录且想让它们共享同一套记忆可以把多个项目的配置都指向同一个目录。autoMemorize控制是否自动提取记忆默认是 true。开着省心但如果你发现提取出来的东西质量太低可以先关掉自动提取只用手动方式记重点。maxMemoryContext控制每次新会话最多注入几条历史记忆默认是 5。项目复杂度高、上下文需求多的时候可以调到 8 或 10但别贪多超过这个数值模型处理起来会明显变慢还容易分心。minSimilarity是召回相关度的最低阈值默认 0.4数值越高召回越严格越不容易混入不相关的记忆。注意不要在主目录下直接改完配置就开始用。改完配置以后在各个项目目录里重新跑一次claude-mem init让新的配置值真正同步到各项目的 MCP 服务配置里去这一步漏掉的话改了半天也可能不生效。4. 日常使用操作手册让记忆在项目里流动起来4.1 常用命令速查claude-mem 的命令设计得很直观第一次用基本不用翻文档。我整理了一份高频速查表按我的使用频率排的命令作用claude-mem status查看数据库状态、记忆条数、最近提取时间claude-mem recall以时间倒序浏览最近的记忆claude-mem search 关键词全文搜索记忆内容claude-mem remember 内容手动写入一条记忆claude-mem delete id按 ID 删除一条记忆claude-mem stats统计各类型记忆的数量分布recall和search是我用得最多的两个。每天下班前我会用recall扫一遍今天沉淀了什么发现明显过时的就删掉。search更像一个针对性拉取比如遇到一个 Bug 想确认之前是不是修过类似的直接搜关键词比翻聊天记录快得多。4.2 接入 Claude Code 的 MCP 配置claude-mem 能跟 Clude Code 深度协作靠的是 MCP 协议。正常执行claude-mem init之后它会自动在当前项目的.mcp.json文件里写入服务配置。这个文件在项目根目录下内容大体会是这样{ mcpServers: { claude-mem: { command: claude-mem, args: [serve] } } }配置写进去以后重启 Claude Code模型就具备了调用 claude-mem 工具的能力。这时候你可以在对话里直接问检索一下我们之前关于支付超时的结论Claude 会自动调用记忆工具并把结果作为上下文来回答。如果发现.mcp.json里没有自动写入也有一个通用的手动添加办法在 Claude Code 的设置界面里添加一个 MCP 服务命令填claude-mem参数填serve。不同版本的入口位置会有点差别但 MCP 服务的字段结构是通用的。每次改完.mcp.json记得重启 Claude Code我吃了好几次没重启导致工具不生效的亏。4.3 记忆管理的日常工作流工具装上只是开始真正让记忆系统产生价值靠的是日常使用中形成流程。我自己跑了几个月之后固定下来一套三步操作节奏。第一步是会话结束时的自动沉淀。这是 claude-mem 自动帮我完成的我的做法是确保autoMemorize开着并定期抽查提取质量。第二步是每周的记忆巡检。周末我会花十分钟跑一遍claude-mem recall把已经失效的条目删掉比如已经上线的临时方案、已经废弃的接口约定。这一步很重要记忆系统最大的敌人不是记不住而是记住太多过期的东西。第三步是关键的主动写入。有些重要约定如果对话中没有被自动捕捉到我会在会话里直接说一句请把以下内容记入记忆XX 接口的连接超时调整为 5 秒这样触发 claude-mem 的手动写入路径。4.4 与 claude-mem 协同时的提示词技巧还有一个细节值得专门写一段。即便 claude-mem 在会话启动时会自动注入相关记忆我仍然会在任务开始前主动跟 Claude 确认一遍背景。比如说先不要动手改代码。请用记忆工具搜索一下我们在支付模块历史上做过哪些决策重点看超时时间和幂等方案然后总结给我。这样做有两个好处。第一它把记忆内容显式地放进当前上下文中模型在后续处理中引用这些信息的准确度会更高。第二如果你发现它搜出来的东西跟实际情况对不上说明记忆提取或召回的环节出了问题可以及时排查。记忆系统的质量是需要校准的校准方式就是定期在对话里主动测试召回结果。5. 常见问题与排查技巧实录5.1 安装和初始化阶段的坑这个工具整体装起来不复杂但我在早期踩过几个很典型的坑在这里一并列出来。第一个坑是claude-mem命令找不到。表现是执行命令时提示command not found。原因基本是 npm 的全局 bin 目录没有加进 PATH。解决方法是先找到 npm 全局目录执行npm config get prefix然后把$(npm config get prefix)/bin加进系统 PATH。第二个坑是 MCP 服务没有生效。我一度以为是 claude-mem 没装好折腾半天才发现是完全忘了重启 Claude Code。MCP 配置是启动时加载的不重启就不会加载新注册的工具。第三个坑是初始化之后memories.db文件没有生成。先检查配置文件目录的写权限再确认 Node 版本是不是太老这两个问题会在信息提示里被掩盖排查时优先排除。如果实在排查不出来我建议用最笨也最有效的办法把~/.claude-mem/目录备份后整个删掉重新执行claude-mem init。反正数据库里存的只是记忆不会有代码文件初始化失败不会造成业务损失。5.2 记忆不生效和噪声过多记忆不生效就是明明存了但新会话就是记不起来。这种问题我遇到过三次每次原因都不一样。第一次是autoMemorize被我不小心改成了 false导致新会话不再注入记忆。第二次是minSimilarity设得过高新会话的内容跟历史记忆之间的相似度评分达不到阈值记忆就召不回来。第三次是项目路径不匹配我在 A 目录初始化的 claude-mem跑到 B 目录去开会话B 目录没有注册 MCP 服务自然就完全没有记忆能力。检查路径时记住一个原则记忆是按项目路径隔离的哪个目录 init 了哪个目录才有记忆。相反的极端问题是噪声过多。如果你发现新会话里注入的记忆经常跟当前任务八竿子打不着那就是过滤逻辑没有生效。优先确认maxMemoryContext是不是设得太高了默认 5 条虽然看起来少但每条都是精挑的。其次是调高minSimilarity把它从 0.4 往上拉比如 0.6召回的召回精度会明显提升代价是会丢掉一些边界相关度不够高的记忆。我的习惯是宁可少召回不要假召回。5.3 隐私与数据安全要注意的事claude-mem 的所有记忆数据都存储在本地 SQLite 文件里这个设计带来了很大的隐私优势你的对话内容和项目决策不会被上传到任何第三方服务器。但本地存储不等于绝对安全有几个使用习惯需要特别注意。第一~/.claude-mem/memories.db里存的都是明文如果这个文件落在别人手里对方能直接看到你所有项目的技术决策和代码片段。不要把~/.claude-mem整个目录提交到 git 仓库里哪怕是私有仓库也要养成习惯忽略它。第二如果你有多个项目同时使用注意记忆查询时的路径隔离。claude-mem 是按项目路径区分记忆范围的但如果两个项目不小心配了同一个memoryDir记忆就会串味这不仅是管理混乱的问题还可能导致 A 项目的敏感信息在 B 项目的会话中出现。第三如果你的电脑设置了自动备份到云盘~/.claude-mem目录会跟着备份里面的记忆内容也就跟着上了云。对保密要求高的项目这种自动同步之前先想想能不能接受。提示针对最敏感的项目可以给 claude-mem 单独设置一个独立的memoryDir比如/path/to/secret-project/.claude-mem。用完之后整目录清掉数据完全不落盘。这是最干净的做法。6. 进阶玩法与个人心得6.1 多项目记忆隔离与共享如果你跟一样同时维护好几个项目你会发现 claude-mem 默认的按项目路径隔离既是优点也是限制。优点是每个项目独立A 项目的记忆绝不会跑到 B 项目去互不干扰。但缺点是我在 A 项目里踩过的这个 SDK 的 v3 版本有大坑别用这种经验B 项目完全不知道。为此我摸索出的折中方案是在 A 和 B 项目各配一个独立 memoryDir同时把这类跨项目通用的经验通过手动claude-mem remember写入一个共享的核心记忆库里然后在涉及到的项目里把memoryDir指向这个共享库。这种做法在技术上是可行的它的本质是把 core-level 的记忆和 project-level 的记忆分开管理符合我之前说的三层记忆模型。但要注意共享库一旦建立它的内容增长速度会很快建议每两周做一次清点去除不然过了两三个月这套库就变成了没人敢动的大泥球。6.2 记忆结构的分类与标签我强烈建议在 workflow 里加一道分类标签的工序。claude-mem 允许给记忆条目附加类型标签我的习惯是分成四类标签含义示例decision技术决策及理由支付模块改用状态机而非直接 if-elseinterface接口约定与变更user API 的 email 字段改为可选bug根因复盘的 Bug 记录空指针根因是上游返回了 null 而非空数组preference个人或团队偏好提交信息用 Angular 规范加了标签之后最大的收益是召回和筛选可以联动。比如每次新会话我只想注入decision和interface就可以在手动的记忆检索指令中带上标签过滤。日常巡检也更有目标性刷一遍bug标签就能快速回看最近修过的坑。给记忆做标签看起来多了一步操作但长期积累下来检索效率的提升非常明显。6.3 我踩过几次坑之后的体会文章最后说点我自己的真实体会。第一点是别指望纯自动。现在很多工具宣传语都强调零配置、全自动但 claude-mem 这种记忆工具提取质量完全依赖于模型的判断而模型判断必然有误差。我前两周过度相信自动提取后来发现大量关键决策根本没有被记录反而是很多临时性的讨论被当成重点存了下来。把它调成自动提取 每周手动巡检的模式之后效果才真正稳定起来。第二点是记忆要断舍离。记忆系统最重要的品质不是大而全而是精而准。宁可每次新会话注入三条高质量记忆也不要塞入二十条正确但无用的废话。定期清理过时条目这一点怎么强调都不过分。第三点是记忆里最有价值的不是做了什么而是为什么这样做。AI 帮你改代码的过程本身已经有了代码注释和 git 记录但当时为什么放弃方案 A 选方案 B这种隐性的决策理由只会存在于对话里。claude-mem 存下来的最大价值正在于它把这种决策理由结构化地保留了下来。你问它这个模块为什么用状态机它真的能给你一个带着来龙去脉的答案。用 claude-mem 这几个月我最直观的感受是AI 从每次都得重新自我介绍一遍的临时工变成了好像一直记得你做事风格的长期搭档。光凭这一点就足够让我把它列为 Claude Code 用户的第一件官方外挂了。
阅读完成 · 觉得有帮助？
