Claude Code长期记忆增强：claude-mem MCP工具原理与配置实践

我一直觉得，编程类 AI 助手目前最大的短板不是能力，而是“记性”。你可能也有过这种体验：在一个维护了好几个月的项目里，你已经反复跟 Claude Code 交代过“跑测试统一用 pytest，别用 unittest”“提交信息按 conventional commits 写”“这个仓库别动 dist 目录”，结果每次新开会话，它都像第一天上班一样，把你之前的约定忘得干干净净。你只能一遍遍重复解释，偶尔还会撞上它一个劲地按默认方式办事，气得人直拍桌子。claude-mem 这个开源工具，就是专门冲着这个尴尬点来的：它给 Claude Code 装上一套长期记忆，让 AI 记住你的项目约定、个人偏好，甚至上一轮对话推进到了哪一步。简单说，它以一个 CLI 工具的形式存在，同时通过 MCP（Model Context Protocol）挂在 Claude Code 上，自动把对话内容沉淀成可检索的记忆文件，并在新会话开始前把相关记忆重新喂回去。这篇文章我会从它的核心机制讲起，再带着你把配置、使用、踩坑整个流程过一遍，希望能帮你少走我当初走过的弯路。

1. 从“每次会话都是新生儿”到“越用越懂你”：claude-mem 在解决什么

1.1 为什么会话一关，AI 就失忆

先说本质。大语言模型的上下文窗口，本质上是一次性传入的“任务纸条”：你每发一条消息，Claude Code 都会把当前会话里此前的所有对话内容重新整理成上下文，提交给模型推理。一旦进程退出，这段上下文就没了。虽然官方有--resume之类的恢复机制，但它恢复的是聊天记录本身，并不能主动帮你把“这个项目有什么约定”“我偏好什么样的代码风格”这类需要长期沉淀的信息提取出来、分类存好、再在合适的时机主动说出来。

我之前也试过用.claude/rules.md或者在项目里塞 CLAUDE.md，把约定写死在文件里。这个办法能解决一部分问题，但有两个明显的缺陷：一是所有项目约定都得你手动维护，时间一长文件和实际代码脱节；二是它只解决“静态规则”，解决不了“上次我们讨论到哪儿了”“这个模块后来确认了哪种方案”这类带时间线的动态信息。claude-mem 不一样，它把记忆从模型的大脑里搬到外部存储里，形成一套独立于会话生命周期的持久层。这样，模型每一次新会话都可以从外部存储里加载“有用的过去”，而不是真的变成新生儿。

1.2 一个工具，两层身份：CLI 与 MCP Server

claude-mem 这个名字很容易让人以为它只是个简单的命令行小工具，但实际上它在日常使用中更重要的身份是 MCP Server。我尽量用大白话解释这几个概念：

• CLI 身份：你可以在终端里直接敲claude-mem的一些子命令，比如查看当前积累了哪些记忆、搜索某条具体约定、删除一条过时信息。这是给人用的管理界面。
• MCP Server 身份：MCP 协议相当于给 Claude Code 这类模型客户端开放了一组“可调用的外部工具接口”。claude-mem 以 MCP Server 的形式运行后，Claude Code 在对话中就能自主决定“是否要读取记忆”“是否要写入记忆”，不需要开发者在代码里做任何硬编码适配。

也就是说，你既可以在服务器上把它当作一个记忆管理后台来操作，又可以在 Claude Code 里通过对话无缝地调用它。我见过很多其他记忆插件是单进程硬耦合的，而 MCP 这种客户端-服务器结构的好处是解耦：Claude Code、其他支持 MCP 的客户端、或者你自己写的脚本，都可以共用同一套记忆服务。

1.3 到底适合什么人用

我自己用了快两个月，感觉它的价值曲线是分场景的。最典型的受益者是下面几类人：

• 一个人同时维护多个仓库的独立开发者和外包开发者。项目多、切换频繁，靠脑子记住每个仓库的约定根本不现实。
• 长期项目参与者。一个项目做三个月以上，核心代码演进、技术决策、重构理由如果不在代码注释里，AI 重构时很容易“好心办坏事”。
• 喜欢用 AI 结对编程但不希望每次重新“调教”的小团队。把团队规范沉淀到记忆库里，新会话直接继承，减少重复沟通。

反过来，纯写一次性脚本、临时做算法验证、或者项目高度敏感不允许任何历史信息跨会话留存的人，就不太适合用。它需要一种“投资心态”：前期花一点点成本整理和校正记忆，之后每开一个会话都能省下大量重复说明的时间。

2. 记忆的完整闭环：从会话流水到结构化记忆再到自动注入

很多工具号称“有记忆”，但实际上只是把聊天记录打了个包塞回上下文，这跟 claude-mem 的设计思路差别很大。我拆解一下它背后的完整闭环，你会明白为什么它不是简单的历史存档。

2.1 第一层：会话捕获——记录不是存聊天记录那么简单

claude-mem 要沉淀记忆，第一步必然是把会话内容捕获下来。这里最大的坑在于：不能把每条对话都原封不动存起来。一次正常的结对编程会话可能有几百轮消息，如果全部存成原始文本，存储会膨胀，后续检索时的相关性也会被大量噪声干扰。所以它的做法通常是在会话进行到一定阶段（比如达到一定轮次、或是在会话结束时）触发一次“滚动摘要”：用模型把这段时间的对话压成一个简洁的摘要，保留技术决策、问题结论、用户明确表达的偏好这些高价值信息。

我打一个比方：写日记的人不会把每一分钟的所见所闻都录像，而是晚上花十分钟写下今天最值得记的事情。claude-mem 做的事情就是“每晚写日记”，它的摘要模型负责替你做信息压缩。在这个环节里，摘要的“粒度”很关键。如果粒度太细，一条记忆写几百字，后续注入时上下文就爆了；如果粒度太粗，记忆就变得像“今天讨论了某个问题”这种废话。我的经验是，摘要应该往“可执行”方向写，比如“用户确认了数据库迁移统一用 Flyway，不再用 Liquibase”，这比“讨论了数据库迁移工具选择”有用一百倍。

2.2 第二层：结构化抽取——把“金子”从聊天里筛出来

有了摘要，下一步是结构化抽取。claude-mem 会把摘要文本交给一个模型，让它按预设的字段模板抽取信息，生成类似下面的结构化条目：

{ "id": "mem_8f3a2c9d", "type": "project_decision", "project": "gateway-service", "content": "API 网关的限流策略统一使用 Redis 令牌桶，QPS 阈值 5000，不临时改配置", "tags": ["gateway", "redis", "rate-limit"], "importance": 0.8, "created_at": "2025-06-18T10:24:00+08:00", "source_session": "session_abc123" }

这里的type通常分成几类：项目事实、工程规范、用户偏好、决策记录、待办事项。为什么一定要结构化？因为非结构化的聊天摘要只能靠关键词硬匹配，而结构化的记忆可以按类型过滤、按重要度排序、按项目隔离、甚至按时间衰减。我自己在排查一条记忆污染问题时深有体会：如果没有 type 字段，你根本没法只删“过期偏好”而保留“项目事实”。

这个抽取环节可以通过模板 prompt 来约束。常见的做法是给模型几个 few-shot 示例，让它学会区分“临时说的一句话”和“一个值得长期记住的约定”。例如“这个函数今晚要改好”是无效记忆，而“本项目的错误码统一走 errors 包定义的枚举”才是真正值得长期沉淀的规范。

2.3 第三层：记忆注入——新会话如何“带上装备”

记忆存好之后，最难的就是“在恰当的时候把恰当的记忆喂回去”。如果每次新会话都把全部记忆一次性塞进上下文，那跟没过滤的日记本没有区别，只会白白挤占宝贵的上下文窗口。claude-mem 的检索模块通常会做这样几件事：

1. 根据当前工作目录或 git 仓库根路径确定 project_id，优先筛出该项目的记忆；
2. 对当前会话开头输入的第一条用户消息做关键词提取或向量化；
3. 把话题相关的记忆条目按重要度、时间戳排序，截取一个上限（例如最多注入 3000 token 的记忆）；
4. 将所有选中的记忆拼成一个“Memory Context”块，注入到系统提示的最前面。

这样新会话开起来之后，模型在读到你的第一条需求之前，其实已经“看过”了项目历史摘要。你会发现它一开始就知道之前聊到哪个模块、你反复强调过什么约束，语境感完全不一样。

3. 环境准备与最小可运行配置：一轮下来的完整步骤

下面进入实操环节。我按自己当时第一次配通的过程写，尽量不漏关键步骤。

3.1 安装前想清楚一个问题：谁来当“记忆加工厂”

claude-mem 本身只负责调度和存储，真正的摘要、抽取这些“动脑”的活还是要交给模型。它默认会调用 Claude 的接口，通常读取环境变量ANTHROPIC_API_KEY。如果你用的是 Anthropic 官方的模型，开箱即用；如果出于成本、隐私或合规考虑，想把记忆加工换成其他兼容 OpenAI 协议的服务，也可以通过环境变量指定 base_url、模型名和密钥。我的建议是：

• 摘要任务用便宜、快速的模型即可，记忆质量对“聪明程度”要求没那么高；
• 结构化抽取建议用能力稍强一点的模型，因为字段判断错了，后面的检索全乱；
• 检索阶段如果走嵌入向量，则需要一个 embedding endpoint；如果只做关键词匹配，那模型都不用参与。

这个决定会影响后面的配置，我建议你在安装之前先想清楚。省得装完才发现默认模型用不了，还要回来改配置。

3.2 具体安装与注册到 Claude Code

安装过程不复杂，常见的是用 uv 或 pip 装：

# 推荐用 uv，速度快且环境隔离干净 uv tool install claude-mem # 或者用 pip python -m pip install -U claude-mem

装完之后，理论上它会提供一个claude-mem命令。你可以先跑一下：

claude-mem --version

确认装成功。这时候还没有真正“长”到 Claude Code 身上，因为 Claude Code 需要知道去哪找这个 MCP Server。我用的注册方式是：

claude mcp add claude-mem -- uvx claude-mem serve

如果你没有用 uv，也可以写成-- python -m claude_mem serve。这条命令的本质是告诉 Claude Code：每次启动时，帮我起一个名叫 claude-mem 的子进程，它的 MCP Server 入口是claude-mem serve。

注册完之后，建议重启一下 Claude Code，然后在对话里简单验证：

你身上挂载了哪些 MCP 工具？

如果能看到类似mem_read、mem_write、mem_search这样的工具列表，说明注册成功。不同版本暴露的工具名可能略有差别，以 README 为准。

3.3 验证记忆闭环

注册只是让工具连通，真正要验证的是“记忆是否会沉淀、是否会回注”。我当时的验证步骤是这样的：

1. 在一个 git 项目目录下启动 Claude Code，输入一句很明确的约定，比如“记住：本项目所有外部访问必须走 service 层，禁止在 controller 直接操作 repository”；
2. 退出会话，重新打开一个全新的 Claude Code 会话；
3. 输入“你对这个项目的代码分层有什么了解？”

如果 claude-mem 工作正常，新会话应该能复述出上面那句约定。如果回答一片空白，通常查两个地方：一是 MCP Server 是否真的在运行，二是记忆文件有没有生成。

3.4 记忆文件落在哪儿

默认情况下，claude-mem 会把数据存放在用户目录下的隐藏文件夹，常见结构类似：

~/.claude-mem/ ├── config.yml # 全局配置 ├── sessions/ # 原始会话摘要 └── memory/ └── gateway-service/ └── memories.jsonl

你可以打开config.yml调整存储目录、模型参数、注入上限。我习惯把存储目录改到我自己创建的某个备份路径下，方便做定时备份和清理。

4. 让记忆真正长在项目里：按项目隔离、记忆类型与注入策略

工具跑通只是第一步，真正让记忆产生价值的是后续的维护策略。这里讲几个我摸索出来的关键点。

4.1 按项目隔离：避免“甲项目的经验污染乙项目”

我在刚上手的时候犯过一个特别蠢的错误：在一个项目里要求 Claude“记住用 pnpm”，结果另一个 npm 项目里它也默认用 pnpm，搞得依赖怎么装都出错。后来翻配置才知道，claude-mem 默认会以 git 仓库根路径作为项目标识，不同仓库的记忆应当天然隔离。

所以你在配置或者使用时要注意：

• 如果两个子目录属于同一个 monorepo，但业务场景差异很大，可以考虑配置额外的 project_id 规则；
• 如果两个仓库虽然代码不同但约定通用（比如都属于同一家公司、都用同样的代码规范），你可以把它们归到一个共享项目下，这样记忆能互相复用；
• 最怕的情况是“默认隔离失效”。比如你没有把根目录放进 git，claude-mem 可能会把两个文件夹当成同一个项目，记忆互相串。我的建议是所有使用 claude-mem 的项目都确保有干净的 git 根。

4.2 记忆类型与“该记什么”

下面这张表是我自己整理的常用记忆类型，也对应了 claude-mem 对记忆条目的分类习惯：

值得提醒的是，type只是标签，真正决定记忆有没有用的是“可执行性”。一段记忆如果在后续对话里不能影响模型的行为决策，那就该删。我在清理的时候会反复问一句：“如果下个月一个新会话看到这条记忆，它能少做一件蠢事吗？”答案是否定的，直接删。

4.3 记忆检索：关键词匹配还是向量相似度

不同版本对检索的实现策略不完全一样。简单部署时，关键词匹配完全够用，比如记忆里搜“限流策略”，命中 Redis 令牌桶那条。但对跨语言表达比较敏感的场景，比如你这次问“接口防刷怎么做”，关键词“限流”可能就搜不到“rate-limit”标签下的内容，所以不少部署会选择引入向量检索，把记忆内容预先 embedding 成向量，然后对当前问题向量做相似度检索。

我个人的建议是：先跑最小版本，把记忆积累到几百条之后再评估要不要上向量。记忆少于五百条时，关键词匹配加项目隔离已经能覆盖绝大部分场景，向量检索带来的收益有限，却平添了 embedding 接口维护成本。

4.4 启动注入还是按需搜索

注入策略有两种流派。第一种是“启动注入”：每开新会话就把相关记忆一股脑塞进上下文。优点是模型从一开始就知道上下文，不用“想起来去查”；缺点是占上下文窗口，而且塞进来的记忆不一定跟本次任务相关。第二种是“按需搜索”：启动时不注入或只注入极少的关键记忆，等模型在对话中判断需要历史信息时，自己调用 MCP 工具去搜索。

claude-mem 实际支持的方式往往介于两者之间。我的折中方案是：

• 每次启动只注入项目级规范、用户级偏好这类“长期稳定”的记忆，这部分体积小、命中率高；
• 任务相关的动态信息（上一次做到哪一步、某个模块的讨论结论）留给模型在对话中按需搜索。

这样既保证模型“开局不裸奔”，又不会把一次性的上下文窗口全占满。

5. 跑起来之后必须面对的四个现实问题：成本、干扰、隐私与维护

功能看起来很美，但实际用起来有几个问题会反复折磨你，我一个个说，顺便给处理方案。

5.1 上下文预算：记忆也会“偷走”窗口

很多人以为给模型加记忆是免费的，实际上每一条注入的记忆都在消耗宝贵的上下文 token。假设一个项目的记忆包有 4000 token，你可能觉得不多，但加上代码片段、工具返回结果、多轮对话，很容易逼近 Claude Code 的上下文上限。上下文一满，模型要么丢弃早期内容，要么回答质量明显下降。

我建议给记忆设一个预算上限，比如不超过上下文总长度的 10% 到 15%。同时定期清理低重要度记忆，尤其是在项目进入稳定期后，历史决策的记忆可以精简，只留还在生效的规范和约束。

5.2 陈旧与矛盾的记忆：AI 也开始“记错事”

记忆这个东西像房间里的杂物，不收拾就会堆积成灾。举一个我踩过的真实案例：项目早期我们用的是 REST API，我在会话里明确要求“所有接口按 REST 风格实现，不要引入 GraphQL”。后来团队决定全面迁移到 GraphQL，聊天记录里也讨论了这个变更，但更早那条“禁止 GraphQL”的记忆权重仍然很高，导致新会话里 Claude 经常在前几轮就提出“你是不是搞错了”，或者拒绝按新的 GraphQL 方案写代码。这就是典型的矛盾记忆。

处理办法没有银弹，只能在记忆管理上做“记性卫生”：

• 每周抽十分钟用claude-mem的列表命令过一遍最近新增的高重要度记忆；
• 当一个技术决策反转时，主动写一条新记忆并显式说明“此前的某条记忆已废弃”；
• 如果工具支持，及时给废弃记忆打上status=archived，避免它继续参与检索排序。

5.3 调用成本与隐私边界

claude-mem 的记忆加工必然要调用模型接口，这意味着摘要和抽取环节会产生 token 费用。以我的实际项目为例，一个两小时的深度调试会话，如果配置了滚动摘要加结构化抽取，大概会产生 5 到 10 次模型加工调用，费用并不高，但如果你同时在十来个项目里高频使用，一个月累计下来也是需要关注的数字。优化手段包括：只在会话结束时做一次完整抽取、调低摘要频次、用更便宜的模型处理非关键项目。

隐私问题更值得注意。默认情况下的记忆数据存放在本地，但如果摘要和抽取请求发送到云端 API，那“本地存储”并不等于“数据不出门”。涉及密钥、内部 IP、客户敏感数据的项目，我建议要么不用这个工具，要么把记忆加工模型切到自托管的本地服务上。不要拿生产环境的真实令牌去测试记忆功能，这是最基本的底线。

5.4 与官方 resume、子代理特性的关系

Claude Code 官方本身提供了--resume恢复会话的能力。claude-mem 和它并不是重复功能：resume恢复的是对话轮次本身，重点在“接着聊”；claude-mem 沉淀的是高价值约定和决策，重点在“跨会话长记性”。两者配合时，我一般是靠 claude-mem 保存长期规范，靠官方 resume 维持当天的连续调试状态，各司其职。

另一个容易混淆的是子代理（subagent）相关的记忆配置。Claude Code 的某些子代理或插件也有自己的短暂记忆机制，如果同时开启，可能会发现同一条信息既存在子代理上下文里，又注入进主对话，造成重复。我的经验是：子代理内的记忆留给临时任务，长期约定统一交给 claude-mem 管理，别搞出好几套并行的记忆源。

6. 写在最后：我的使用心得与适合它的场景

最后聊几句实在话。工具本身不难配，难的是“记忆卫生”意识。我刚开始的半个月，记忆库里堆了大量低价值信息，检索时排在前面的永远不是最该出现的那条，模型表现甚至不如没用 claude-mem 的时候。后来我给自己立了三条规矩，效果好很多：

第一条，明确告诉 Claude Code 哪些话需要记住，哪些话不用记。比如在对话里直接说“请记住：这个项目的部署走容器化，不要手工 SSH 上去改”，一条明确且可执行的记忆，抵得上十条泛泛的总结。

第二条，定期复盘记忆库。每个周五花十分钟删除低价值、过期、矛盾的条目。这听起来像额外工作，但省掉的是后续无数个会话里的重复解释和错误执行。

第三条，记忆注入上限要克制。每次只让最重要的 5 到 8 条记忆进入初始上下文，其余靠对话中按需搜索。我用下来觉得这个组合最平衡。

claude-mem 目前在我看来还不是那种装完就不用管的自动工具，但它的核心思路——把 AI 的长期记忆从模型内部搬到外部持久层——我觉得是正确方向。如果你跟我一样，长期跟 Claude Code 在多个项目里结伴干活，花一个下午配置好它，再用一两周把记忆库养起来，之后每次新会话的“带入感”确实是质的提升。我后续还打算再研究一下它的记忆合并与冲突处理能力，毕竟多项目、多用户共享一套记忆库才是团队协作下更有挑战的场景。