claude-mem：为Claude Code装上长期记忆，终结AI编程失忆症

用了快一个月，我还是没把claude-mem从开发环境里卸掉。

如果你在用 Claude Code，大概率经历过这种让人抓狂的时刻：昨天刚和它把模块边界聊清楚、定好了接口命名风格，今天新开一个会话，它一脸无辜地问你“这个项目是做什么的”；等你花二十分钟把背景重新捋一遍，它又开始朝着上一次已经被否掉的方向写代码。问题不在模型，在于 Claude Code 的每次会话都是“无记忆”的，一旦/compact压缩了上下文或者新开会话，之前沉淀的决策就全部归零。claude-mem就是冲着这个痛点来的——它给 Claude Code 装上一套长期记忆系统，把每次会话里值得留存的决策、洞察、上下文沉淀下来，下次会话自动带着这些记忆上线。

这篇文章把我这段时间的安装、配置、使用和踩坑记录全部捋了一遍。我不会只贴官方 README 翻译，而是把“为什么它要这么设计”“哪些参数值得调”“真正跑起来会碰见什么问题”这些文档里不会明说的事情都展开。无论你是被 AI 无记忆折磨的普通开发者，还是想给自己团队引入 AI 编码助手的工程负责人，这篇文章应该都能让你少走几个弯路。

1. 先把问题说透：Claude Code 的“失忆”到底有多伤

1.1 上下文窗口陷阱：不是模型不行，是每次都在裸奔

Claude Code 的上下文窗口虽然不小，但它对一次会话里能记住的信息量依然有硬上限。更麻烦的是，你每输入一段代码、它每回复一段内容，都会挤占上下文空间。项目稍微复杂一点，对话框里滚到后面，它连你自己最开始写的需求描述都快忘光了。官方给的出路是/compact，把历史对话压缩成摘要释放空间——但压缩这件事本身就是一种“暴力丢信息”。

我实测的感受是：/compact之后，Claude Code 通常还能记住“最近几轮聊的大方向”，但很多关键细节会变得模糊，比如选定了哪个第三方库、为什么拒绝某一版方案、某个函数命名大家统一成了什么风格。这些信息恰恰是一个长期项目的命脉。你不可能每次开新会话都重新交代一遍，更不可能指望它自己从记忆碎片里把上下文拼出来。

这个问题的本质不是模型能力，而是产品形态：Claude Code 把每一次运行当成一次性的、无状态的交互来设计。对于一个动辄需要连续开发好几周的项目来说，这种无状态性就是效率黑洞。

1.2 传统自救方案为什么救不了你

在没有claude-mem之前，我试过几种常见思路，每种都有明显短板。

第一种是维护一个项目笔记文件，比如CONTEXT.md或者AGENTS.md，每次会话开头让 Claude Code 先读一遍。这个方法能解决一部分问题，但副作用很大：笔记永远滞后，需要手动维护，而且一旦项目进展快，笔记就成了一堆没人想读的过期信息。我有好几次在AGENTS.md里写下的“当前最佳实践”，一周之后已经和代码仓库的真实状态脱节了。

第二种是把每个会话都“存档”，需要时翻出来让 Claude Code 参考。这个思路方向是对的，但实现成本高，而且存下来的日志一大堆，真正有价值的关键决策被淹没在大量过程性对话里。让 Claude Code 去啃几个小时的聊天记录，既费 token 又费时间，效果还不可控。

第三种是写 Hook 脚本，在会话开始或结束时把某些信息写入文件。这个方案自由度最高，但也意味着我要自己设计记忆格式、自己处理读写时机、自己解决汇总逻辑——说白了，从零搭一套记忆系统。折腾几次之后我放弃了：我需要的不是脚手架，而是开箱即用的解决方案。

1.3 日志不等于记忆：核心区别在哪里

等到我真去研究claude-mem的设计思路时，才意识到关键分野：日志和记忆是两回事。日志是一切发生过的流水账，而记忆是在流水账里提炼出的、对“未来决策”依然有意义的信息。

打个比方，你每天上下班走同一条路，不需要记住每一秒看到的街景，但你会记住“这段路最近在修路，要绕行”——这就是日志与记忆的区别。claude-mem做的不是把对话完整存储下来，而是每次会话结束后，让模型把这些对话压缩成若干条“洞察片段”（insights），把“决定、原因、偏好、结论”这类值得长期保留的颗粒度信息挑出来，剩下的过程性内容直接丢弃。这个思路，说实话，比市面上很多“对话历史备份工具”高了一个层次。

2. 深入核心原理：生成式记忆图谱与时间分层设计

2.1 什么是生成式记忆图谱

claude-mem最核心的概念是“生成式记忆图谱”（generative memory graph）。听起来唬人，拆开看并不复杂。

传统做法是给 AI 配一个向量数据库，把所有历史对话切成块做 embedding，然后靠相似度检索。这也是一种“记忆”，但它本质上是把一堆原始日志扔给 AI 自己翻。claude-mem的做法不一样：每个会话结束后，它会调用模型把这段会话生成成一簇相互关联的“洞察”节点，这些节点之间带有语义关系——A 决策依赖 B 调研结论、C 方案被否定的原因是 D。这些节点不是简单的文档碎片，而是经过提炼的知识单元，天然适合作为后续决策的参考。

这等于给 AI 建了一座结构化的“私人笔记”，而不是一个堆满杂物的仓库。它从设计上就更接近人类记忆的工作方式：我们不会记住每一句话的每一个字，而是记住“这件事得出了什么结论”。

2.2 时间分层结构：记忆如何保鲜与沉降

记忆图谱里有一个非常聪明的机制，叫时间分层。简单说，越是最近的记忆越精细、越容易被检索到；距离现在越久远的记忆，越会被压缩合并，变成更高层的抽象结论。

举个例子，这周几次会话都围绕“拆分用户认证模块”展开，记忆图谱里会留有这几次会话的详细洞察节点，包括当时分析的依赖关系、决定弃用某个库的原因。再过几周，这些细颗粒度的节点会被折叠成一条“用户认证模块已完成重构，统一走 token 认证方案”的总条目。这样设计有两点好处：一是控制记忆体积，不会无限膨胀；二是让新会话的 AI 不会被淹没在陈旧细节里，它看到的是当前最需要关注的最近记忆，历史记忆则以摘要或索引形式存在。

这套时间分层机制，实际效果等同于让 AI 具备“短期记忆”和“长期记忆”的区分。它不把一切信息等量齐观，而是模拟了人类遗忘与沉淀的节奏。

2.3 为什么用 SQLite 而不是向量数据库

我最初比较困惑的一点是：claude-mem为什么不用向量数据库？毕竟市面上讲 AI 记忆的教程几乎默认上 embedding。研究完之后发现，这是刻意的取舍。

向量检索解决的是“模糊语义召回”的问题，而claude-mem的洞察节点本身已经是模型提炼过的结构化信息，节点数量远小于原始对话的 token 数，通过 SQLite 直接做过滤和排序就可以了。什么时候需要模糊召回呢？当记忆量巨大且无法抽象时。但claude-mem用生成式方法提前做好了抽象，就不需要再叠一层向量库。这带来了实实在在的好处：零额外服务依赖、数据库就是一个单文件、备份迁移异常简单、没有 embedding 成本。对个人开发者来说，这种“少即是多”的选择非常明智。

从我实测看，claude-mem默认把数据库放在~/.claude-mem.db，一个文件搞定全部记忆，完全不需要 Docker、不需要 Redis、不需要向量库，这对于降低使用门槛几乎是决定性的。

3. 安装与集成：一条命令跑起来，但细节里全是坑

3.1 一键安装与手动安装，我建议怎么选

claude-mem提供了一键安装脚本，官方说法是 turnkey install，一行命令搞定：

curl -Ls https://claude-mem-install.teticio.workers.dev | sh

这个脚本会完成三件事：安装claude-memPython 包、注册 Claude Code 的 MCP 服务器、把相关 Hook 挂到 Claude Code 配置里。我自己第一次就是用这个脚本装的，整个过程很快，装完就可以直接用。

不过如果你像我一样有多版本 Python 环境，或者对“curl 到 sh”有心理洁癖，也可以手动安装：

pip install claude-mem # 或者 pipx install claude-mem（推荐，避免污染全局 Python 环境）

手动安装之后，还需要单独注册 MCP 服务器并配置 Hook，脚本帮你做掉的那部分要自己补。从我的经验看，新手优先用一键脚本，等用顺了再手动拆解细节也不迟。等到要部署到多台机器或者做成团队标准化环境时，手动安装反而更好控制。

3.2 MCP 服务器配置：Claude Code 怎么“摸到”记忆

安装完成后，claude-mem以 MCP 服务器（Model Context Protocol Server）的形式和 Claude Code 通信。MCP 可以理解为给模型提供的一组可调用工具的协议接口，Claude Code 原生支持 MCP，所以不需要额外插件。

如果你检查 Claude Code 的 MCP 配置文件，会发现里面多了一个claude-mem条目，典型结构类似：

{ "mcpServers": { "claude-mem": { "command": "npx", "args": ["-y", "claude-mem@latest"], "env": { "CLAUDE_MEM_DB_PATH": "~/.claude-mem.db", "CLAUDE_MEM_MAX_RECENT_THOUGHTS": "30", "CLAUDE_MEM_TARGET_CONTEXT_WINDOW_SIZE": "60000" } } } }

这里有几个环境变量值得认真对待。CLAUDE_MEM_MAX_RECENT_THOUGHTS控制每次自动注入多少条最近记忆，默认 30，如果你项目上下文本身很满，可以调低，比如 10 到 15。CLAUDE_MEM_TARGET_CONTEXT_WINDOW_SIZE是目标上下文预算，默认 60000，单位是 token——它告诉claude-mem最多为记忆预留多少上下文空间。这个参数很关键，我后面会专门讲怎么调。

实际配置内容以你机器上安装脚本生成的结果为准，版本差异可能导致字段不同，但核心环境变量差不多就是这三个。

3.3 校验安装结果，别上来就闷头干活

装完先别急着开新会话，跑一遍健康检查：

claude-mem doctor

这个命令会检查数据库状态、MCP 注册、Hook 挂载情况，把潜在的配置问题一次暴露出来。我第一次跑doctor就发现 npm 环境没装对，MCP 服务器起不来，花了三分钟解决。如果你跳过这一步，开个新会话发现 Claude 始终“记不住东西”，再回头排查反而费时间。

另外可以确认一下记忆目录是否生成。claude-mem会自动在项目目录下创建.claude-mem/memories/，里面是排好序的 markdown 文件，每条记忆都能直接打开看。这个目录的存在让我很安心：记忆不是黑盒，而是可以直接读、直接改的文本。我建议把这个目录纳入版本管理（除非有敏感信息），这样团队其他人也能共享项目记忆。

4. 实操体验：在 Claude Code 里真正“带记忆”地开发

4.1 一个典型的带记忆会话，流程是什么样的

装好claude-mem之后，一个典型的编码会话会变成这样。

你新开一个 Claude Code 会话，它启动时会通过 MCP 自动读取这个项目的近期记忆。如果之前聊过“这个项目使用 FastAPI + SQLAlchemy 2.0”，它会在回应你的第一句话之前就带上这个背景，而不是傻乎乎地问你“这个项目用什么框架”。你让它实现一个新接口，它会结合记忆里的命名偏好、模块边界、历史决策来写代码，写出来的东西更像连续工作了几周的队友，而不是一个刚入职就上岗的实习生。

会话过程中，它会根据你的要求调用list-recent-thoughts、search-thoughts这类工具拉取记忆。这些工具本质上就是 MCP 暴露给 Claude 的检索接口：前者列出最近的洞察，后者按关键词搜索历史记忆。这里有个使用窍门：当新会话涉及老功能时，主动让 Claude 先搜一下相关记忆，它会自动触发search-thoughts把自己“唤醒”，效果比手动粘贴旧记录好得多。

4.2 /memory 命令：失去的上下文，一键找回来

claude-mem最抓我眼球的一个功能是/memory命令，它专门用来解决被/compact打残的上下文。

用过 Claude Code 的人都知道/compact是省上下文的神器，但它很像“把昨天写的备忘撕掉只留一句话摘要”，细节全丢。claude-mem的解法是：压缩之前，先把当前会话里值得记住的内容写入记忆库，然后/compact执行后再通过/memory把相关记忆重新注入上下文。等于在压缩这个危险操作前后各加了一道安全网。

我的习惯是：每次/compact前先手动跑一遍/memory，让 Claude 把当前对话里的关键决策显式提交到记忆库，然后再压缩。实测下来，压缩后的“失忆感”大幅降低，很多细节原子都能保留。这个操作别省，特别是聊了很久的复杂会话，一次/memory的成本几乎可以忽略，但省下来的重讲时间非常可观。

4.3 记忆不是只会自动成长，你也能亲手种下“长期记忆”

claude-mem最实用的一个设计是：它不只是被动记录会话，还允许你主动添加长期记忆。

通过记忆编辑器，你可以手动向数据库写入项目级的备忘。比如“本项目的数据库迁移统一使用 Alembic，禁止手写 SQL”这种约定，可能并不是某次会话里自然得出的结论，而是团队规范，但你又希望 Claude 开发时始终遵守——这就该用记忆编辑器手动固化。

我强烈建议项目启动的第一天就手动建几条核心记忆：技术栈、架构约定、编码风格。这相当于给 Claude Code 做了一次“入职培训”。我还喜欢在每次重大设计完成后，主动把结论手动更新进记忆里，而不依赖自动提取。自动提取负责“广”，手动记录负责“准”，两者配合，记忆质量能好一个档次。

体验下来，claude-mem让我最惊喜的是“记忆颗粒度”的把握。它不会把你塞给它的一大段代码原样存下来，而是提炼成一句话级别的洞察，例如“用户模块的鉴权逻辑已统一到auth.py的create_token()，不要再在各路由里重复实现”。这种颗粒度在后续开发中直接可用，不会造成信息过载。

4.4 上下文预算：Token 控制才是最该花心思的地方

这节是全文最值得划重点的部分——记忆系统如果不能控制 token 开销，会反过来成为上下文负担。claude-mem提供了一些参数来约束记忆对上下文的占用。

一个是前面提到的CLAUDE_MEM_MAX_RECENT_THOUGHTS。这个值决定每次会话自动带入的最近记忆条数。不要贪多，30 条我实测在一般项目里已经够用；如果你经常处理大型代码库，上下文本身紧张，压到 10 条左右反而更重要。记忆再多，挤占了代码和工具输出的空间，AI 反而变笨。

另一个是CLAUDE_MEM_TARGET_CONTEXT_WINDOW_SIZE。它相当于给你设定了一个“记忆不逾矩”的天花板。假如你目标上下文是 60000 token，记忆系统会自动估算载入记忆的开销，超出预算的部分就不会硬塞进来。我第一次使用没调这个参数，一段时间后明显感觉 Claude 变“迟钝”了——大量的记忆条目挤占了主任务空间，输出质量反而下降。把预算从默认值往下调整之后，记忆确实变精简了，AI 回复质量回到正常水平。

经验法则：记忆是辅助，不是主导。我给读者的建议是搜证式使用好过全量注入——与其一股脑把几十条记忆全塞给 Claude，不如在需要时让它按关键词检索。你可以观察一下 Claude Code 的 MCP 工具调用输出，看看它有没有主动触发search-thoughts，如果没有，可以提醒它“查一下记忆库”，这比拉高上限要高效得多。

5. 常见问题与排查实录：我踩过的那些坑

5.1 安装后数据库没建起来、记忆不生效，先跑 docotor

claude-mem有一个专门的诊断命令，我前面提到过claude-mem doctor。它是我排查问题的第一站，基本上 90% 的“装了没反应”问题都能从这里找到线索。

我遇到过一次很典型的场景：doctor显示一切正常，但 Claude Code 新会话里始终看不到记忆。后来发现是 MCP 服务器启动的 npx 环境变量不对，导致服务器根本没连上数据库。MCP 配置里command: npx在某些 Node 环境里需要指定完整路径，比如/usr/local/bin/npx。如果你doctor输出里提示 MCP 连接失败，优先检查你的 Node 安装路径，再用绝对路径替换这段配置。

5.2 记忆太多把上下文撑爆了，怎么降级？

这个问题我在 4.4 里提过思路，这里给一个具体的排查顺序。

先看doctor输出里记忆条数和近似的 token 占用。如果数字明显偏高，先把CLAUDE_MEM_MAX_RECENT_THOUGHTS调低，比如从 30 降到 15 甚至 8。观察一两轮，如果依然觉得上下文紧张，再把CLAUDE_MEM_TARGET_CONTEXT_WINDOW_SIZE调低。这个顺序是从“软限制”到“硬限制”，逐步收紧。

还有一个隐藏技巧：用/memory命令先把当前会话的关键点写入记忆，如无必要不新增记忆条目。自动提取尽量在会话结束时靠命令行清理操作触发一次。日志该删就删，不用每条都留。

5.3 数据库文件想换个位置/迁移到新机器，怎么操作

claude-mem的数据库本质就是一个 SQLite 单文件，默认在~/.claude-mem.db。想换位置很简单，设置环境变量CLAUDE_MEM_DB_PATH指向新路径即可，注意要让 MCP 服务器和命令行工具使用同一个路径，否则会出现“命令行有记忆，会话里读不到”的奇怪现象。

跨机器迁移更简单：把.claude-mem.db文件拷到新机器，设置同样的CLAUDE_MEM_DB_PATH，然后运行claude-mem doctor验证。我在换电脑时试过这个过程，整个迁移不超过五分钟，比迁移一套开发容器省心得多。

5.4 记忆文件该不该进版本库？团队协作怎么办

这个问题的答案取决于项目敏感度。

如果是个人项目，.claude-mem/memories/放进 Git 仓库问题不大，反而可以作为跨设备同步的简易手段。如果是商业项目，要小心，记忆文件里很可能包含你曾让 AI 处理过的内部架构细节、客户信息、未发布的方案，这些都是敏感内容。我的建议是：默认加入.gitignore，只在你自己确认可分享的前提下手工提交。团队协作场景下，与其共享同一个数据库，不如让每个成员各自维护本地记忆，同时把项目级核心规范通过手动记忆条目每个人各写一份。这样避免多端写同一个 SQLite 文件引发锁冲突。

5.5 版本升级带来行为变化，怎么应对

claude-mem更新节奏不慢，版本升级后偶尔会感觉到行为变化，比如记忆注入的条数变多、工具列表变了、字段名不同了。我的建议是每次升级前先看一眼claude-mem的 CHANGELOG，升级后立刻跑claude-mem doctor。如果发现记忆格式变更导致旧数据读取异常，不用慌，数据库里的原始洞察节点通常没丢，等新版本重新扫描索引即可。

如果你用的是 npx 方式启动 MCP，注意npx默认可能缓存旧包，升级失效时试试清一下 npx 缓存或者去掉-y参数手动拉取新版，这是我在一次升级后卡了很久才发现的玄学坑。

5.6 常见问题速查表

6. 一些经验之谈：怎么把 claude-mem 用到真正顺手

6.1 记忆质量靠“喂”，不靠“攒”

用了这么长时间，我最大的体会是：记忆系统不是你用得越久就越准，而是你喂得越对就越香。claude-mem的价值密度取决于沉淀的记忆是否高质量。如果会话本身是一堆烂芝麻烂谷子，自动提取出来的洞察也不会有什么价值——垃圾进，垃圾出。

所以我现在的习惯是：每段重要设计讨论结束前，会明确让 Claude 总结一下结论和理由。不是为了写文档，而是让这次会话的核心内容容易进入记忆。这种显式“收束”的动作，能让claude-mem的自动提取命中率显著提升。平时我会观察.claude-mem/memories/目录下的内容，如果发现某段时间记忆条目偏空或者明显跑偏，多半是那段时间的会话太碎片化，下次注意让会话聚焦一点。

6.2 不要把它当知识库，它是决策参考，不是代码仓库

还有一个容易误用的点：很多人会把claude-mem当成“代码知识库备份”，想着把自己的最佳实践全部塞进去，让 AI 随时取用。我的经验是不要这么做。claude-mem定位是“项目记忆”，它擅长记录的是“为什么做这个决定”“我们定了什么约定”“之前踩过什么坑”。它不适合存大段代码片段，也不适合存文档正文。塞得越杂，AI 检索时噪音越大。

真正好用的方式，是把它当成 AI 助手的“工作背景板”：技术栈简介、架构约定、历史决策、用户偏好、踩坑记录。这些内容加起来也不会占据太多 token，但对 AI 输出的定向作用极大。代码本身，让 AI 在项目文件里自己看就行了。

6.3 结合/compact使用，形成工作流闭环

“/memory→/compact→ 继续开发”是我最推荐的一整套工作流。

当对话长了，先触发/memory把上下文沉淀到记忆库，然后执行/compact压缩，压缩后让 Claude 自动读取记忆恢复关键上下文。这比裸奔式/compact的效果好太多。几个朋友问我说为什么我的 Claude Code 看起来这么“记得住事”，秘密就在这个常规操作里。

还有个小技巧：每次开工前，花十秒钟看看.claude-mem/memories/里的最新几条记忆。这不仅是校验，还能提醒你自己项目最近的焦点在哪。有次我就是翻记忆时发现“上瘾症”一样的反复改某个设计，意识到问题出在需求没定清楚，赶紧去对齐需求而不是继续堆代码，节省了整整一天。

6.4 结合其他 MCP 工具的取舍

claude-mem不是唯一值得装的 MCP 工具，但我觉得算是最没有负担的之一。它不像某些重量级 MCP 工具那样需要跑一堆服务，也不需要联网到第三方平台，数据完全本地化，这让我很放心。

不过我也建议你别贪多。MCP 工具装多了，Claude Code 启动时会逐个加载，既拖慢启动速度，也增加工具调用冲突的概率。我的原则是：记忆系统只装一个，检索能力只装一个，文件操作只装一个，够用即可。claude-mem在我的配置里就是那个“记忆系统”角色，其他的要么本地没价值，要么和它功能重叠。

6.5 安全与隐私，给你一句实在提醒

claude-mem把记忆存成本地文件，对隐私友好。但便利的另一面是，你让 AI 处理过的所有敏感信息，都可能沉淀进这个数据库里。如果数据库文件丢失或被盗，里面就是一份“思维画像”。我的建议是：不要让它记录明文密钥、token、密码之类的信息；数据库目录权限尽量收紧；如果你在公共电脑或共享开发机上工作，记得用完退出。安全上的多一分谨慎，换来的是长期放心。

另外给你一个规划和扩展思路：claude-mem的数据库是标准 SQLite，记忆文件是 markdown，这意味着你完全可以写脚本对它做二次开发，比如做一个记忆可视化面板、统计项目决策热词、在 CI 里生成项目进展周报。它的底层设计足够开放，不只是“装完即用”那么简单。我最近就在尝试每周自动导出记忆库里的关键决策，生成项目周报，效果还不错。这个方向如果你有兴趣，可以顺着数据格式往下挖。

我在用claude-mem之前，一直觉得“AI 编代码没记忆”是一个只能靠人工补笔记来缓解的问题。现在回头看，问题不是没有解，而是需要一个设计上就想清楚“什么是值得记住的”的工具。claude-mem的生成式记忆图谱、时间分层、本地存储这一套组合拳，恰好把“AI 记忆”这件事做得既有结构、又够轻量。如果你也正在被 Claude Code 的失忆问题折磨，我建议你花一个下午把它装起来，认认真真跑一个真实项目，你会回来感谢那个愿意动手的自己。