如果你每天用 Claude Code 写代码一定经历过这个场景昨天还在跟它讨论某段逻辑的重构方案今天开个新会话它一脸茫然地看着你好像你们从来没聊过。这不是模型变笨了而是 Claude Code 默认没有跨会话的长期记忆——每个新会话都是从零开始。为了解决这个问题我在项目里接入了 claude-mem一个给 Claude Code 加长期记忆的开源工具。这篇文章把我从安装、配置到实际使用积累的经验都写下来包括它的原理、完整的接入流程、记忆的提取和排序机制以及我踩过的几个坑。如果你正在用 Claude Code 做长期项目、想让它记住你的技术决策和项目偏好这篇应该能帮你省不少时间。1. Claude Code 的失忆问题与 claude-mem 的定位1.1 会话割裂带来的真实痛点Claude Code 是跑在终端里的 AI 编程 Agent能读写文件、执行命令、主动规划任务效率确实高。但它有一个非常明显的短板会话之间不共享记忆。每个新会话启动时它对之前的对话毫无概念除非你把上下文重新贴给它。这个问题在单次任务里影响不大但在一个持续几周甚至几个月的项目里会越来越扎眼。上次确定的架构决策、约好的接口命名规范、排查到一半的 Bug 线索到了新会话全被当成第一次听说。你只能重复一遍背景然后祈祷这次的理解跟上次一致。有人会反驳不是有 CLAUDE.md 吗 确实CLAUDE.md 可以放项目级说明但它本质是静态文档需要你手动维护。对话里临时定下的技术选型、你对某个模块的口头要求、一次调试过程中发现的隐性约束很难每次都有空整理进 CLAUDE.md。等你想起来要写细节早就丢了。静态文档和动态对话之间存在一个巨大的管理空档claude-mem 就是补这个空档的。1.2 claude-mem 不是聊天记录备份claude-mem 的定位不是存档聊天内容而是做一层可检索的结构化记忆。它通过 MCPModel Context Protocol跟 Claude Code 连接在对话过程中自动提取值得记住的信息整理成带重要性权重、标签和分类的记忆条目存到本地数据库。等下次开新会话Claude Code 会调用检索接口把跟当前任务相关的记忆拉出来作为上下文的一部分。这样一来昨天讨论的方案今天它确实记得。这个设计的核心价值在于把记忆从手工维护的文档变成了自动沉淀、按需调取的信息资产。它适合所有把 Claude Code 当作日常开发工具的人尤其是长期项目、多人协作、频繁切换任务的场景。2. 一条记忆从产生到被召回claude-mem 的工作链路2.1 从对话到记忆的四个阶段我习惯把 claude-mem 的工作流程拆成四步提取、嵌入、存储、检索。第一步是自动提取。claude-mem 会周期性拿当前对话内容通过内部提示词让语言模型提炼要点比如技术决策、项目约定、用户偏好、任务进展。每次提取完会生成候选记忆并打上重要性分数和分类。这一步是异步的不阻塞主对话所以你会感觉不到它在干活。第二步是嵌入。候选记忆要转成向量才能做语义检索claude-mem 用的是 FastEmbed 加 ONNX Runtime模型在本地跑。这一步决定了后续检索是按意思找而不是按关键词找。第三步是存储。向量和原始文本一起落到数据库默认是 SQLite也可以切换成 PostgreSQL。每条记忆还附带 created_at、last_accessed_at、access_count 这类元数据方便后续做权重衰减和清理。第四步才是用户能感知的部分——检索。新会话开始或在对话过程中Claude Code 会调用 run_memory_search 工具拿当前的问题去语义匹配记忆库返回最相关的一批结果注入上下文。整个过程对使用者是透明的你只看到它突然想起了之前的事。2.2 关键组件与数据流向这里面的几个关键组件值得单独说。MCP Server 是跟 Claude Code 通信的桥梁所有工具调用都走它FastEmbed 是嵌入引擎负责把文本变成向量SQLite/PostgreSQL 是记忆的物理载体提取队列负责异步处理对话文本。可以用一个生活化的类比提取阶段像你每天睡前在脑子里过一遍今天发生的事挑出值得记的嵌入阶段像把每件事浓缩成一句话并贴好标签存储阶段像把纸条放进抽屉并按主题归类检索阶段像第二天遇到相关话题时从抽屉里翻出对应的纸条。少了任何一个环节记忆都不成立。2.3 为什么语义检索比关键词检索更适合这里这是 claude-mem 设计和传统存档方式最大的区别。对话里的同一件事可能有无数种说法你问上次那个接口怎么改的存的时候可能是把 /users 接口的鉴权逻辑抽到中间件。关键词检索永远匹配不上这两个说法但语义检索可以。向量化的本质是把语言映射到高维空间里意思相近的句子距离相近所以能兜住这种口语化、碎片化的表达差异。实测下来跨会话召回准确率比我预想的高很多。3. 接入 Claude Code 的完整安装与配置流程3.1 安装前的准备与 uv 方式claude-mem 本质是一个运行在本地的服务进程所以要求你的机器上已经装好 Claude Code CLI。安装方式有三条路Python 生态的 uv/pipx、npm、Docker。我推荐第一条因为 claude-mem 是 Python 写的用 uv 管理依赖最干净不会把全局 Python 环境搞得一团糟。以 uv 方式为例先在终端执行安装uv tool install claude-mem装完之后把 claude-mem 的 MCP 服务注册进 Claude Code。MCP 协议就是让 Claude Code 发现工具并调用它的标准通道没有这一步两边根本不认识。注册命令长这样claude mcp add --transport stdio claude-mem -- uv tool run claude-mem mcp3.2 三种接入方式的选型npm 方式适合你没装 Python、或者团队统一用 Node 环境的情况npm install -g claude-mem claude mcp add --transport stdio claude-mem -- npx claude-mem mcpDocker 方式更适合服务器部署或者多人共享一个记忆库。它一般是起一个 HTTP 服务然后把 Claude Code 通过 http 传输接过去docker run -d -p 8000:8000 官方镜像名 claude mcp add --transport http claude-mem --url http://localhost:8000/mcpDocker 的具体镜像名和 HTTP 路径以仓库 README 标注为准版本之间可能有差异。三种方式的区别我整理了一下方式适合场景优点需要注意的点uv/pipx本地单机开发环境隔离干净、版本管理方便需要 Python 环境npm已有 Node 工具链一条命令装好依赖 Node 运行时Docker团队共享/服务器部署环境完全封装、可远程要维护容器和网络我个人是本地开发用 uv团队服务用 Docker。切换成本很低记忆库都在同一个 SQLite 或 PostgreSQL 文件里接哪个服务只是数据库指向的问题。3.3 验证接入是否成功配置完最重要的一步是验证。先跑claude mcp list如果看到 claude-mem 在列表里且状态正常说明 MCP 注册成功。然后新开一个 Claude Code 会话直接试一下斜杠命令/mem search 数据库迁移能返回结果哪怕是空结果就说明工具链路通了。第一次用的时候我建议先手动存一条记忆再搜一遍最直观/mem store 记住本项目接口统一走 /api/v1 前缀 /mem search /api/v1 接口规范如果返回了你刚存的内容恭喜记忆循环已经跑起来了。4. 记忆的自动提取、手动管理与排序机制4.1 自动提取到底提取了什么claude-mem 最省心的是自动提取。默认情况下它会在对话进行中或结束后把会话文本交给一个内置的提取提示词产出结构化记忆。我观察到的典型提取内容是技术选型及理由、项目结构和模块职责、你反复强调的编码偏好、尚未完成的待办、踩过的坑和解决方案。每条记忆会带 importance 分数0 到 1分数越高说明这条信息越值得长期保留。自动提取可以随时开关对话里输入/mem auto off关掉之后它只响应你手动触发的存储和搜索。我建议刚上手阶段保持开启跑一周之后再看库里存了什么、有没有噪声再决定要不要收紧。别一开始就关掉自动提取那样你根本感受不到这个工具的核心能力。4.2 手动存储、检索和查看全部记忆自动提取之外手动接口是我日常用得最多的。除了前面提到的 /mem store 和 /mem search 之外还有两个工具值得掌握store_memory 可以让 Claude 在对话过程中把临时决定直接写进记忆get_all_memories 可以拉取指定分类下的全部记忆适合做定期复盘和清理。工具层面的调用是 Claude Code 自动完成的你不需要手写但理解它们的存在能帮你判断当前会话为什么突然带上了某段记忆。如果你想让它忘掉某些内容目前没有一键删除的斜杠命令我后面会说我是怎么在 SQLite 里清理的。4.3 权重、分类与去重如何影响排序同一个记忆库里会积累几百上千条记忆不是每条都值得在这次会话拿出来。claude-mem 的排序规则是多因素叠加语义相似度是基础importance 分数加权access_count 和 last_accessed_at 会做时间衰减——很久没访问的低分记忆会被压到后面最近常在用的关键记忆排前面。这跟算法推荐有点像越相关、越重要、越常用的记忆越容易被召回。分类和去重也参与排序。每条记忆可以有 category你可以自定义分类名称比如 architecture、bugfix、style、user-preference。检索时如果当前任务能推断出分类会做一次过滤。去重则是靠嵌入空间里的相似度阈值如果新记忆跟已有记忆距离太近会被合并或丢弃。这套机制保证了记忆库不会无限膨胀成垃圾堆。5. 个性化配置与隐私边界5.1 调整分类和系统提示词让记忆更贴你的项目安装时默认的分类体系适合通用场景但我的建议是拿到项目第一天就改。claude-mem 的配置文件按 YAML 格式维护里面可以自定义记忆分类列表、自动提取开关、搜索返回数量、是否启用重排序等。我会把分类改成项目相关的名字比如 ledger-service、auth-refactor、data-migration。这样检索结果更精准复盘时也一眼能看懂。系统提示词也是可配的。CLAUDE.md 是给 Claude Code 的项目级指令claude-mem 类似地允许你定制记忆如何被呈现。比如你希望它每次带出记忆时附带来源会话信息或者只允许它引用高权重的记忆都可以在配置里调。这一步对结果质量影响很大值得花十分钟调一版。5.2 本地嵌入的隐私价值我对 claude-mem 最满意的一点是隐私设计。它做嵌入用的 FastEmbed ONNX Runtime 模型完全跑在本机对话内容、记忆内容都不会因为向量化这一步被发送到第三方。记忆默认存在本地 SQLite数据不出机器。如果你看到某些配置项可以接云端的 Embedding 服务不要被那个便利吸引——一旦走云嵌入你的对话摘要就离开本地了。除非你明确接受这一点否则本地嵌入是更稳妥的选择。另外claude-mem 有些可选功能需要调用外部搜索 API 来丰富记忆比如某些网络检索增强配置这类功能默认不开开启后查询词会发给第三方搜索服务。弄清楚哪些数据在本地、哪些会出网再用才安心。5.3 PostgreSQL 与 Docker 化部署单机开发用 SQLite 完全够但团队场景会有两个问题一是记忆库分散在各人机器上每个人记得的东西不一样二是 SQLite 并发写的能力有限。claude-mem 支持把记忆库切换到 PostgreSQL这样团队可以共用一个记忆库所有成员检索到的都是同一套上下文。配合 Docker 部署的 MCP 服务相当于给团队一个统一的项目大脑新人进来能快速获得历史上下文老人也不用反复解释背景。不过要提醒一句共享记忆库意味着所有成员的对话都会被提取写入团队规范上要约定清楚什么内容可以进库。这属于工程治理问题工具本身给不了答案但用久了你会发现明确边界比多一个功能更重要。6. 实测效果、常见坑与我的使用建议6.1 几个典型场景的真实效果跑了两周之后我感受最明显的场景有三个。第一个是跨天回归头天讨论完的模块重构方案第二天新会话直接能接着往下写不需要我把结论重新铺一遍。第二个是项目术语统一我们有个服务叫 ledger库里沉淀了它和 payment 的边界约定后面生成的代码很少再混淆这两个概念。第三个是调试上下文延续某次排查性能问题找到的根因记录在案两周后同类问题再出现它直接说出上次我们已经定位到是索引缺失。当然它也有局限。claude-mem 不是数据库复杂的关系型知识它表达得不够好它也不是实时系统提取队列有延迟刚聊完就去搜可能还是搜不到。理解这些边界才能正确使用它。6.2 我踩过的坑和对应的排查思路先说最常见的 MCP 没生效。表现是 /mem 命令无反应或者会话里根本看不到相关工具。排查链路是先 claude mcp list 确认注册再确认命令里的可执行文件路径在当前 shell 可用最后重启 Claude Code。我遇到过 uv 安装后 PATH 没更新的情况重启终端才正常。第二个坑是搜不到刚聊的内容。这不是故障是提取队列还没跑完。claude-mem 的提取是异步的长对话要等一等。排查时先看配置里 auto extract 是否开启再等十几秒重试还不行就开 DEBUG 日志确认提取任务有没有报错。第三个坑是记忆污染。当库里积累了几百条低分记忆检索结果里会出现不相关的内容既浪费上下文窗口又干扰判断。我的处理方案是把搜索返回条数往下调只保留最高的三五条定期按分类检查记忆库把明显过时或错误的记录清掉通过 importance 阈值过滤掉低分碎片信息。删记录我直接查 SQLite 表操作先备份再删别一次删过头。我把常见问题整理成了一张表方便你直接对照现象可能原因处理方式/mem 命令无响应MCP 未注册或进程未启动核查 claude mcp list重启会话搜不到刚聊的内容异步提取队列未完成等待重试确认 auto extract 开启检索结果混杂无关内容低权重记忆太多调低返回数量、清理记忆库、设 importance 阈值记忆重复出现去重阈值不敏感检查是否启用了重排序重新评估阈值团队记忆不同步各自使用本地 SQLite统一切到 PostgreSQL 共享库6.3 跟 CLAUDE.md 配合使用的分工最后说说我现在的使用分工。CLAUDE.md 放稳定不变的硬约束技术栈、目录规范、构建命令。claude-mem 放对话中产生的软知识临时决策、踩坑结论、偏好约定、历史上下文。两者互补不冲突。硬约束如果只放记忆里换个会话环境可能就丢了软知识如果全写进 CLAUDE.md文档会变得臃肿且没人维护。实际操作中我一般每周花十分钟看一眼记忆库删掉过时的、合并重复的、补两条值得长期保留的关键结论。这个习惯跟整理笔记很像——工具负责自动收集人负责最终把关。跑顺之后你会明显感受到 Claude Code 从每次都是新朋友变成了解项目来龙去脉的老同事。