claude-mem：为 Claude 对话补上持久记忆的本地工具

开门见山地说：claude-mem 是给 Claude 对话补上"长期记忆"的本地工具。我把它接入日常的终端工作流之后，最大的感受是——终于不用每次新开会话都把项目背景、技术选型、踩坑记录从头讲一遍了。这个东西解决的是很多人忽略的一个痛点：大型语言模型的上下文窗口本质上是一次性的，今天聊出的结论，明天新开会话就归零。claude-mem 的思路清晰而朴素，把对话里有价值的信息提取出来、存进本地、在合适的时机重新注入给模型。它不改变模型本身的推理能力，但它改变了你和 AI 协作的持久度。

先说清楚它适合谁。如果你只是偶尔用网页版 Claude 聊聊天，这工具意义不大；但如果你和我一样，每天都在终端里用 Claude Code 或直接调用 API 写代码、改配置、维护脚本，那"持久记忆"这件事比任何提示词技巧都值钱。它省下的不是一次两次复制粘贴的时间，而是彻底消除了"每次都得重新对齐上下文"这种隐性成本。这篇东西我会从定位、原理、安装、集成、排障五个维度展开，尽量把我自己踩过坑之后的真实用法写明白。

1. 项目全貌与核心定位

1.1 claude-mem 到底是什么

一句话定义：claude-mem 是一个运行在本地、为 Claude 会话提供跨会话持久记忆的命令行工具。它不是模型、不是插件、也不依赖云端服务，所有数据都落在你自己的磁盘上。

从架构上看，它由三个部分组成。第一部分是会话监听器，在 Claude 输入输出流上挂接钩子，负责捕获对话中出现的、有长期价值的信息；第二部分是本地存储引擎，把捕获的内容结构化写入数据库，支持分类、加标签、设置作用域和过期时间；第三部分是上下文注入模块，在新会话开始时，根据当前工作目录和对话内容，从存储中检索出最相关的记忆，自动追加到系统提示词里。这三个部分正好对应记忆的三个基本操作：写入、存储、召回。

这个设计有一个容易被低估的点：监听、存储、召回三个环节是解耦的。也就是说，你可以只把它当成一个记忆记录器用，也可以只把它当成一个检索服务用，甚至可以在不同项目里混合使用不同的组件。我自己的用法是：监听全开、存储默认、召回精细调。每个环节的配置是独立的，这一点对实际使用非常友好。

1.2 它解决的核心痛点

我举一个实际场景。之前维护一个跨平台桌面应用项目，技术栈是 Electron 加 TypeScript，构建脚本里有一堆历史遗留的坑：某些版本的 Node 在 Windows 下会触发路径解析异常，CI 环境跑测试必须显式设置某个环境变量，打包阶段要先清理缓存目录。这些信息散落在几十次历史会话里，每次新开会话都要重新复述。你说烦不烦？烦。但更烦的是，复述过程中还有遗漏，导致 Claude 给出了已经验证过无效的建议。

装了 claude-mem 之后，我只需要在对话里明确说一句"记住：Windows 下构建前必须设置 X 环境变量"，这段信息就会被自动提取、清理、写入本地。下一次跟 Claude 讨论构建相关问题时，它会自动把这条记忆翻出来，放在上下文中供模型参考。我的角色就从"信息搬运工"变成了"信息审核员"——我不用再花时间复述，只需要在记忆预览时扫一眼，确认它抓取的信息没有歧义就行。

这里我想强调一个容易忽略的细节：工具真正改变的不是"模型记住了什么"，而是"你如何与模型协作"。上下文从一次会话的临时缓存，变成了可以累积、检索、复用的长期资产。资产会增值。用得越久，你和 AI 之间的默契越深，协作效率的提升也越明显。

1.3 适用人群与场景边界

不适合的人我也得说清楚。如果你只是偶尔用 Claude 写点文案、做点翻译，不需要记忆系统，反而会觉得它多此一举。如果你在一个信息高度敏感的环境里工作，对本地文件写入有严格管控，引入任何常驻工具之前都要先过一遍安全评估——这类场景我的建议是谨慎评估后再上。

比较适合的人群是这三类：第一类是重度使用 Claude Code 的开发者，每天几十次会话，背景重复率极高；第二类是做多项目维护的工程师，需要在不同项目间快速切换上下文；第三类是喜欢沉淀知识的个人用户，把记忆库当成一个"半自动笔记系统"来经营。这三类场景的共同点，都是"上下文资产"的复利效应非常明显。

2. 核心机制与工作原理

2.1 记忆的完整生命周期

要理解一个记忆工具，最好的切入点就是跟着一条记忆走完它的一生。从产生到被清除，一条记忆在 claude-mem 里会经历四个阶段：捕获、清洗、存储、召回。

捕获阶段有两种路径。主动式是你在对话里显式表达"请记住……"，工具识别这个意图后把后续内容作为一条新记忆。被动式则是自动提取，工具根据启发式规则判断某段对话是不是"值得留存的信息"，比如一段报错信息加上对应的解决方案，或者一个明确的项目决策，这类内容会被自动归档。我一开始用的是纯主动式，后来慢慢开放了一些自动提取的开关，两种方式配合起来体验最好。

清洗阶段是最容易被忽略的。原始对话里通常有大量冗余：语气词、重复表达、上下文无关的闲聊。claude-mem 会把这层壳脱掉，把记忆内容压缩成紧凑的陈述句，同时抽取关键词、打上类型标签（事实、偏好、技能、决策四类标注）以及作用域标签。这一步做得好不好，直接影响后续检索的准确度。

存储阶段相对简单，内容写入本地数据库，同时建立关键词索引。召回阶段则是重头戏：当新会话中的对话内容与某条记忆在语义上或关键词上足够接近时，这条记忆就会被标记为"候选注入"，并在会话启动时按规则注入到上下文中。记忆不是永生的。工具支持 TTL 过期时间，长时间未被命中的记忆会自动降级，避免存储无限膨胀。

2.2 存储引擎的设计取舍

存储引擎的选择是 claude-mem 的一个很有意思的设计决策。我知道很多同类工具倾向于直接上向量数据库，因为语义搜索的效果确实更好。但 claude-mem 默认选择的是 SQLite，我认为这是经过权衡之后的成熟选择。

SQLite 的优势有三个。第一是零运维，单文件存储，不需要额外启动数据库服务，也就少了一个可能出故障的组件；第二是事务可靠，写入过程不会因为进程异常崩溃导致数据损坏，对频繁读写的小型工具来说这个特性非常关键；第三是数据可迁移性极强，一个 db 文件拷走，整个记忆库就跟着走了，备份和迁移都极其简单。

同时，它预留了外部向量索引的接口。如果你确实需要更强的语义召回能力，可以额外配置向量数据库，对 SQLite 中存储的文本切片做向量化检索，用"关键词快筛 + 语义精排"的两级结构来提升召回质量。这个设计思路在本地工具里是比较成熟的：核心场景追求稳定和简洁，进阶能力留给使用者按需开启。

我自己的体会是，选 SQLite 还有一个隐性的好处——排查问题特别方便。记忆库是标准 db 文件，可以直接用数据库工具打开查看表结构和数据，哪条记忆没写入、哪条记忆的标签不对，一眼就能看出来。黑盒是工具的天敌，这一点上 claude-mem 做得很坦诚。

2.3 上下文注入策略

记忆不是越多越好。把全部历史记忆一股脑塞进上下文，会有三个典型问题：一是超出上下文窗口，模型直接报错；二是无关信息干扰推理，模型抓不住重点；三是过时的决策污染新的判断，比如一个已经被推翻的技术方案还在充当指导意见。

claude-mem 的解法是分级注入。第一个层级是全局记忆，适用于跨项目通用的偏好和规则，比如"代码注释写中文""所有回答要给出可执行的命令示例"；第二层是项目级记忆，适用于当前工作目录对应项目的背景、选型、踩坑记录；第三层是会话级即时记忆，仅在当前会话内有效，用于临时约定。注入时，优先级从项目记忆到全局记忆递减，同时限制单次注入的数量和总字符数。比如默认配置下，单次注入不超过 10 条记忆，总长度不超过 2000 字符。

这个限制非常重要。把注入总量压缩在可控范围内，既保证了相关性，又避免了对主对话的干扰。用一句直白的话说：给模型的记忆是"精选摘要"，不是"数据库导出"。我在调参阶段试过把 max_items 调到 30，结果模型输出质量肉眼可见地下降。克制，才是记忆注入的第一原则。

2.4 从"上下文"到"长期记忆"的认知升级

很多人的困惑是：我已经在每次 API 请求里带上了历史对话，这不就是记忆吗？不是，那是"临时的上下文拼接"，不是"结构化的长期记忆"。两者有本质区别。前者是把一个会话内的多轮消息全部塞回去，长度不可控，信息无分层；后者是经过清洗、筛选、分级的精准摘要，长度可控，且能跨越不同会话累积。

把这两个概念分清之后，你就知道 claude-mem 的价值定位了。它不负责帮你管理历史对话的完整性，它负责帮你沉淀"值得被记住的东西"。这是一种从"聊天记录"到"知识资产"的转变，也是我使用这个工具后认知上最大的变化。

3. 实操环境搭建与快速上手

3.1 环境准备与安装

我最初在一台 macOS 上安装第一版，后来又在公司的 Linux 工作机上装了一次，两个环境都没有遇到障碍。claude-mem 是基于 Node.js 实现的，所以前置条件只有一个：Node 版本不低于 18。确认版本号之后，通过 npm 全局安装即可。

node -v npm install -g claude-mem

装完以后不要急着用，先执行初始化命令：

claude-mem init

init 会做三件事：检查系统依赖、创建默认配置目录、生成一个初始配置文件。默认的配置目录在用户主目录下的~/.claude-mem/，里面会有config.json、memories.db和一个memories/目录。到这里基础设施就搭好了。但我要特别提一句，init 只是搭好了架子，它并不会自动挂载到 Claude 会话里。要让记忆真正生效，你需要在 Claude Code 的 hook 配置中注册一个启动钩子，或者在你自己的 API 封装层里引入 claude-mem 的注入函数。这一步是很多人装完之后发现"没生效"的原因。

3.2 基础命令逐一演练

安装配置好之后，实际操作非常简单。我日常最常用的命令是四个。

第一条是记忆写入。显式添加一条记忆，可以带标签、带作用域：

claude-mem add "构建前必须先执行 npm run prepublish" claude-mem add "部署流程参考 docs/release.md" --labels deploy,workflow --scope project

写入的同时打上标签，这是我从一开始就坚持的习惯。不要图省事省略标签，因为标签是后续快速过滤的利器。第二条是记忆查询。支持关键词模糊匹配和标签过滤：

claude-mem query "构建顺序" claude-mem query "构建" --labels deploy

第三条是记忆管理。查看全部、编辑、删除某条记忆：

claude-mem list claude-mem edit <id> claude-mem remove <id>

用起来跟操作一个轻量级笔记工具差不多，没有学习成本。第四条是上下文预览，这是我个人最推荐反复使用的命令：

claude-mem preview

preview 会把"当前会话即将注入给模型的所有记忆"完整打印出来。每次开新会话前跑一遍，确认注入的内容符合预期。做 AI 工具最忌讳的就是黑盒感，preview 恰恰是破除黑盒的关键窗口。我会在下一节详细解释这个命令的实操价值。

3.3 关键配置项说明

配置文件采用 JSON 格式，核心配置项主要有下面这些：

我的建议是：刚开始使用时，先把auto_extract关闭，全部改为手动添加。等用上两周，熟悉了工具的写入风格和召回能力之后，再逐步打开自动提取。这样做可以避免记忆库在初期就堆入大量无用的杂质信息。我自己就是这么干的，第一阶段养成了主动沉淀信息的习惯，打开自动提取之后，配合阈值过滤，记忆库的质量始终保持在比较高的水平。

还有一个细节值得注意。preview 命令在你手动调整完注入参数后尤其重要。它的输出就是要发给模型的真实记忆列表，你检查预览就等于在做"输入审查"。每次调完max_items或max_chars之后都跑一次 preview，能直观看到改动带来的影响。

4. 在真实工作流中的集成方式

4.1 与 Claude Code / API 的对接

claude-mem 不是独立使用的工具，它是为 Claude 客户端服务的外挂记忆层。我主要用两种方式对接。第一种是 Claude Code 的 hook 机制。在配置里注册会话启动钩子，让每次新会话创建前自动执行 claude-mem 的注入命令，把预检索到的记忆拼接到系统提示词的后部。这个方案配置一次之后完全无感，适合重度终端用户。

第二种方式是自己封装 API 调用。如果你的项目是直接调用 Anthropic API，那就在构造请求参数的地方增加一个检索步骤：

import { retrieveMemories } from 'claude-mem'; const memories = await retrieveMemories({ query: '构建流程', project: currentProject, }); const messages = [ { role: 'system', content: defaultSystemPrompt + '\n\n' + memories.map((m) => `- ${m.content}`).join('\n'), }, // ...用户消息 ];

这段代码的核心在于检索的时机要恰当。不要在用户输入之前静态检索，而是在拿到本轮用户消息之后、发送给模型之前，用用户消息作为检索关键词去召回记忆。我一开始偷懒在启动时静态检索，结果效果很差；改成动态检索之后，召回命中率明显提升。原因很简单：记忆召回依赖查询词的质量，用户输入往往是当前信息需求的最准确表达。

4.2 项目级记忆隔离

做记忆工具容易，但把记忆隔离做好很难。claude-mem 在这一点上的设计逻辑是：默认把当前工作目录作为项目标识。你在/project-a目录下打开的会话，只会注入/project-a作用域内的记忆；切到/project-b，换的是一整套上下文。

这个设计有两个直接好处。第一是避免串味，A 项目的技术选型不会莫名其妙地出现在 B 项目的对话里；第二是安全，不同项目的敏感信息天然隔离。如果两个项目确实需要共享部分内容，那就把它们放进全局作用域。我维护的一组工具库和内部服务之间，就是通过全局作用域来共享"代码风格规范"这类公共规则的。

作用域自动检测通过scope.auto_detect开启。如果你在一个目录里同时维护多个子项目，这个功能会显得特别顺手——不需要手动切换，工作目录一变，记忆域随之变化。对于每天要在多个项目之间横跳的人来说，这种无感的隔离体验确实值得拥有。

4.3 多端同步与迁移

我平时在家里的笔记本和办公室的台式机之间切换，两边的记忆库需要保持同步。claude-mem 的 SQLite 存储结构让这件事变得比较简单。我直接把记忆库文件放进私有云盘同步目录，或者用版本库管理，换一台机器时拉取覆盖一遍即可。

但这里有个必须提醒的坑：如果两边同时写入，会发生冲突。SQLite 本身对多进程并发写入有锁机制，但跨机器的文件级同步并不保证数据一致性。同一时刻两台机器各写各的，之后文件互相覆盖，就会丢掉其中一边的更新。我现在采用的做法是把写操作集中在主力机上，另一台机器的 claude-mem 只开启读取模式。如果你经常在多个设备间切换，务必规划好"主写从读"的模式，这是我从丢过一次记忆库后学到的教训。

4.4 团队协作场景的一点想法

多人共享一个记忆库是我试验过但没有长期采用的方案。技术上可行，团队内把记忆库放在共享盘上，每个人都能写入和召回。问题在于，每个人的工作习惯不同，会自动写入很多对别人毫无价值的信息，记忆库很快就会变成一团浆糊。

我的建议是：团队场景不要共享同一个记忆库，而是共享"规范文档"。把确认过的项目决策、技术选型、踩坑记录整理成一份规范文档放入项目仓库，每个人本地用 claude-mem 建立一个"项目级规范索引"，指向该项目文档即可。这样既保留了个人记忆的独立性，又保证了团队知识的统一来源。本地记忆库是高度个性化的东西，强行共享往往得不偿失。

5. 常见问题与排查技巧实录

5.1 记忆注入后模型表现反而变差

这是我使用过程中遇到的最值得警惕的问题。有一段时间我向记忆库里写入了大量技术细节，之后明显感觉 Claude 的输出质量下降，思考路径经常被带偏。排查到最后发现，原因是注入的记忆条数太多，而且新旧记忆之间存在矛盾。比如早些时候记录了一个临时方案的实现步骤，后来又采用了新的方案，但旧的记忆还留在库里，模型在决策时受到了"历史噪音"的干扰。

解决办法有两个原则。第一是精简，优先保证注入记忆的条数少而精。第二是一致性，写入新记忆时如果发现与旧记忆冲突，先删除旧的再写入新的。这里有个实操技巧：用claude-mem preview检查注入效果时，不要只看内容是否相关，换位思考一下——如果我的思考上下文里只有这些信息，我会不会困惑？凡是可能造成干扰的，一律删除。记忆注入的目标是让模型拿到清晰的规则，而不是让它做信息筛选。

5.2 记忆库膨胀与清理策略

记忆库是会长大的。如果开启了自动提取，一天下来可能写入几十条记录，一个月下来就有几百条低价值信息混在里面。我建立了一个固定的清理节奏：每周跑一次claude-mem list，快速扫一遍所有记忆概要，把过时的、低价值的直接remove。不要舍不得删，记忆库的核心价值在于被检索到的那部分，而不是存储的总量。

同时利用 TTL 机制做兜底。把default_ttl调成 30 天而不是默认的 90 天，让大量临时信息自动过期。重要的长期记忆单独标记优先级并设为永不失效。这个机制有点像邮箱里的垃圾邮件过滤：短期信息自动清退，值得长期保留的单独保护。有了这套分级管理策略，记忆库的膨胀速度会得到明显控制。

5.3 自动提取质量不稳定

自动提取是一把双刃剑。它在识别"问题—解决方案"对时表现相当出色，但也会经常把过程性的、不稳定的中间信息当成长期记忆存下来。比如调试过程中随口说了一句"这个方法暂时不可用"，两天后你已经换上另一个方案，这条旧记忆还躺在库里，新旧信息互相打架。

我的经验是：自动提取要配合"阈值过滤"来使用。claude-mem 支持配置一个提取置信度阈值，越过阈值的信息自动入库，低于阈值的进入待确认队列，由你手动决定是正式归档还是丢弃。这个阈值值得花一点时间反复调。设置得太低，杂质会源源不断涌进来；设置得太高，有价值的记忆又会被拦下。我目前的阈值设置在既能拦截明显噪声、又不漏掉关键决策的水平，大约每十条提示信息里会有一条进入待确认状态。

5.4 检索命中率低的问题

如果你发现新会话里该出现的记忆没有出现，先别急着怀疑工具坏了。第一个要检查的是作用域。确认当前工作目录是否在预期项目下，scope.auto_detect是否因为符号链接或目录嵌套而指向了错误的作用域。第二个要检查的是检索关键词。claude-mem 的默认检索依赖关键词匹配，如果你的记忆内容和会话输入在措辞上差异很大，命中率就会偏低。比如你记的是"部署之前需要执行构建"，而会话输入只提了"怎么发布"，关键词匹配不到很正常。

我解决这个问题的办法是：写入记忆时多补充同义词和场景词。比如"部署、发布、上线流程"这三个词可以同时出现在一条记忆里。这样召回的时候，无论用户从哪个角度进入话题，都能命中同一条记忆。如果你确实需要更强的语义匹配能力，再考虑启用外部向量索引。这个开关适合在记忆量较大、关键词覆盖不全的场景下开启，降本增效的意义在于用全局检索能力快速捞回那些措辞不同但语义相近的内容。

写在最后的实操心得

用 claude-mem 这几个月，我最深的体会是：记忆工具的价值不在存储，而在筛选。工具本身不会自动帮你把最有价值的信息选出来，它只是忠实地记录和召回，你越清楚自己想留下什么样的信息，它发挥的作用就越大。我给自己定了一条规矩：每一周结束前，花十分钟浏览一下本周新增的记忆，删除无用的、合并重复的、修正过时的。这十分钟是维持记忆库健康度成本最低的投资。

最后分享一个小技巧。如果你和我一样在多个项目间切换，建议在每个项目的根目录建一个名为memory-rules.md的文件，里面只写项目的核心规则和常用命令，然后在 claude-mem 里对每条规则建立索引时，明确标注"该项目文档以 memory-rules.md 为准"。这样你在任何一个目录下打开会话，模型都能在记忆里找到"去看这个文档"的指引，而不是每开一个新会话都要把整份文档塞进上下文。这个方法是我在实际使用中逐步摸索出来的，对控制上下文体积和提升召回准确性都有实实在在的帮助。