让Claude Code拥有长期记忆：claude-mem实战指南

我是从一次真实的崩溃开始接触 claude-mem 的。当时我用 Claude Code 改一个后端服务今天上午刚讨论完的数据库表结构下午让它继续优化查询时它居然又问了一遍字段含义还差点把已经废弃的状态枚举当成了新方案。那一刻我意识到Claude 再聪明本质上仍然是个金鱼脑——每次会话开启都是全新空白之前聊过的用户偏好、项目决策、代码事实全部归零。这太浪费了。claude-mem 就是冲着这个痛点来的它是一个给 Claude 用的长期记忆层通过把对话里产生的关键信息提取出来、存到本地再在后续会话里按需召回让 Claude 真正记得你。这篇文章我不打算复制 README而是详细拆解它的工作原理、部署过程、以及我用了一个多月后攒下的各种坑和心得希望对想给 Claude 加上记忆的你有点帮助。1. 从无状态到有记忆claude-mem 究竟解决什么问题1.1 AI 助手的失忆症每次会话从零开始用过 Claude 的人都知道它的单次对话能力很强但跨会话的记忆几乎为零。不是模型不想记而是它的工作方式决定了每个会话开始时上下文窗口里只有系统提示、工具说明和你当前输入的内容历史对话不会自动带进来。哪怕昨天刚从你这里学会了项目里用户ID统一用 Snowflake 而不是自增这个约定今天重新开个会话它还是会按自己的通用理解来甚至可能给出完全相悖的设计建议。这个问题在写代码、做架构决策、维护文档这类长周期任务里特别致命。因为开发工作是连续剧不是单元剧。上次决定了什么、否决过什么、为什么那么选这些信息分散在几十个会话里如果每次都要靠你重新复述一遍效率低不说还容易遗漏。你可能觉得那我把关键内容写进项目文档不就行了理论上可以但实践中有两个问题一是你不会每次讨论完都跑去更新文档二是 Claude 不会主动去读文档除非你在 prompt 里明确告诉它。而 claude-mem 的思路是把记忆从文档这种被动载体里解放出来变成一个主动的、可检索的、由 Claude 自己调用的系统。1.2 claude-mem 的定位一个轻量级记忆层claude-mem 不是模型也不是完整的应用框架它更像一个贴着 Claude 身边的秘书。你正常跟 Claude 聊天、写代码它在一旁把值得记的事情记下来下次对话时秘书把相关笔记悄悄递给 ClaudeClaude 就能想起来你是谁、你在做什么、你喜欢什么技术栈、你之前做过哪些决定。从实现上看claude-mem 是一个运行在本地的命令行工具同时也是一个 MCP 服务器。MCP 就是 Model Context Protocol模型上下文协议你可以把它理解成 AI 世界的 USB-C 接口——统一了 AI 应用和外部工具、数据源之间的连接方式。Claude Code 原生支持 MCP所以 claude-mem 可以非常自然地嵌入进去Claude 通过标准化的工具调用就能读写记忆不需要我们在 prompt 里做任何 hack。和那些重型的记忆框架相比claude-mem 的设计哲学很简单本地优先、文件落地、协议标准。它默认把记忆存在你机器上的某个目录里用普通文件组织不搞中心化数据库、不需要云端同步、也不强制你用特定格式。这一点对我来说很重要因为开发场景下的记忆很多是敏感代码逻辑和内部设计放在本地文件里可控性最强。1.3 为什么不用 Mem0 或自研脚本市面上有 Mem0 这种通用记忆层也有 Letta 这种把记忆做进 agent 框架的方案为什么我最后选了 claude-mem核心原因是它足够轻且和 Claude Code 绑定得深。Mem0 功能确实强大但引入向量库、需要配置 embedding 服务和 API key对只想让 Claude 记住点东西的场景来说有点重了。自研脚本我也写过但很快就意识到真正难的不是存储而是在合适的时机把合适的记忆拿回来给模型看这需要和模型调用流程深度配合自己做极易翻车。claude-mem 巧妙地站在了 MCP 这个生态位上存储简化成文件检索用轻量级方式关键词 结构化筛选和 Claude 的交互交给协议完成。它不追求做一个全能记忆系统只解决Claude Code 会话间什么都不记得这一个核心问题但解决得很干净。2. 核心设计与工作原理拆解2.1 记忆的三层结构事实、偏好与对话印记用了一段时间后我习惯把 claude-mem 里的记忆分成三类这样规划存储时更有条理。第一类是项目事实比如这个服务的数据库是 PostgreSQL 15连接走内网 5432用户表的主键是 user_id类型为 BIGINT这类信息是硬知识错了就会出大问题。第二类是用户偏好比如代码风格用 4 空格缩进、不用分号commit message 遵循 Conventional Commits这类信息反映了你的口味Claude 记住后输出会更贴心。第三类是决策记录比如二期重构时决定把订单模块拆成独立服务因为库存扣减太耦合这类信息能避免后续讨论重复拉扯。claude-mem 在底层其实不强制区分这三类它提供的是统一的记忆条目。但我们在使用中最好自己刻意去引导——让 Claude 在记忆时带上类型标签或关键词这样检索时才能更精准。别把这当麻烦这恰恰是记忆系统能用好的关键。2.2 MCP 如何让 Claude 学会使用记忆前面提到 claude-mem 是一个 MCP 服务器这里稍微展开说下为什么这个设计很聪明。如果没有 MCP你想给 Claude 加记忆能力只能把大量历史摘要塞进 system prompt要么溢出要么被模型当成噪声。而 MCP 做的事是把记忆封装成一组工具比如 remember、search、deleteClaude 根据当前对话需要主动决定是否调用、调用哪一个。整个交互流程是标准化的Claude Code 启动时通过 stdio 或 SSE 连上 claude-mem 这个子进程随后客户端列出服务器暴露了哪些 memory 工具当对话中出现值得记的内容或需要回忆时Claude 构造一条 JSON-RPC 请求发给服务器服务器执行本地文件读写把结果返回给 Claude。这整个过程对用户是透明的你看到的只是 Claude 突然准确地说出了你三周前提过的某个偏好。协议标准化最大的好处是生态收益任何支持 MCP 的客户端理论上都能接入 claude-mem。今天它被 Claude Code 用明天其他 AI 编程工具只要支持 MCP也能共享这套记忆数据。我甚至尝试过让 Claude Desktop 也挂上这同一个记忆目录跨应用共享记忆效果还挺有趣。2.3 记忆的写入从对话中提取并持久化记忆不是自动的段子claude-mem 提供了好几种写入方式我用得最多的是两种。一种是显式命令在对话里直接说请记住项目部署环境分为 dev/staging/prod其中 staging 与 prod 共用同一套数据库备份策略Claude 就会调用 remember 工具把这句话整理成结构化条目存下来。另一种是事后提取claude-mem 支持从一段聊天记录里批量抽取值得记忆的信息比如有一次我和 Claude 讨论了半小时 API 鉴权方案最后让它把这次对话中的重要决定和事实都记下来它就能从对话上下文里提炼出若干条记忆。持久化方面claude-mem 默认把所有记忆放在一个可配置的目录下通常是在用户主目录下的隐藏文件夹里。每条记忆是一个独立的小文件内容包含记忆正文、创建时间、更新时间以及你或 Claude 打的标签。用文件而不是数据库好处是你可以直接用 grep、cat、git 来管理和备份坏处是数据量大了之后检索效率肯定不如数据库但对于个人开发场景这点量完全不是问题。如果你不喜欢默认目录可以通过环境变量 MEMORY_DIR 改到任何你想放的位置我习惯把它放进和项目同级的.mem目录里方便一起提交到私有仓库做版本管理。2.4 记忆的读取检索与注入的时机比写入更重要的是读取。claude-mem 的做法是每次会话启动时Claude 可以根据当前任务和项目目录调用 search 工具去记忆库里寻找相关的条目。我这里说的相关在默认配置下主要是基于关键词和标签匹配比如你在讨论订单支付超时问题search 就能把之前记过的支付回调幂等键是 partner_trade_no这类记忆捞出来。关键在于Claude 不会一股脑把所有记忆全塞进上下文那样做既费 token 又容易干扰判断。它会先搜一把把命中结果按相关度排序再挑选最相关的一两条融入当前推理。这很像我们人类回忆事情的方式——不是把整本日记翻出来读而是顺着线索想起关键节点。实际使用中我发现 claude-mem 默认的检索策略偏保守命中可能不够多。解决办法是在 prompt 里约定涉及项目架构、用户偏好、历史决策时必须先搜索记忆再回答。这个小小的约定能让记忆工具的利用率提升一大截。3. 实操部署5 分钟接入 Claude Code3.1 安装 claude-mem 的几种姿势我是用 Go 工具链装的一条命令就完事。如果你机器上装了 Go可以这样装最新版go install github.com/nickcammarata/claude-mem/cmd/claude-memlatest如果你在 macOS 上也可以直接用 Homebrew 走官方 tap 安装好处是后续升级方便brew install nickcammarata/tap/claude-memLinux 或者不想装 Go 的同学去 GitHub Releases 页面下载对应平台的二进制文件放到 PATH 目录里也是一样的。装完之后先验证一下claude-mem --version能看到版本号就说明装好了。这里提醒一个问题因为 claude-mem 是社区项目迭代很快不同版本之间 MCP 配置格式可能略有差异如果发现工具不好使先确认是不是版本太老。3.2 把 claude-mem 注册为 MCP 服务器在 Claude Code 中使用 claude-mem核心就是把它的 MCP server 注册进去。现在 Claude Code 支持通过 CLI 命令直接添加 MCP 服务器一条命令搞定claude mcp add claude-mem -- claude-mem上面这条命令的意思是注册一个名叫 claude-mem 的 MCP 服务器启动方式为直接执行 claude-mem默认会进入 MCP server 模式。如果你手动修改配置文件通常是在~/.claude/settings.json里添加这样一段{ mcpServers: { claude-mem: { command: claude-mem, args: [] } } }配置好之后重新启动 Claude Code输入/mcp查看服务器列表如果能看到 claude-mem 处于 connected 状态说明接入成功。如果显示 failed 或 error多半是二进制不在 PATH 里或者需要显式指定路径把 command 改成 claude-mem 的绝对路径就好。3.3 记忆目录的初始化与路径选择claude-mem 首次运行时会自动在默认位置创建记忆目录大概在~/.claude-mem下面。我强烈建议你不要直接用默认目录而是通过环境变量指定到项目或工作区内部这样记忆和代码可以一起管理export MEMORY_DIR$HOME/code/myproject/.claude-mem把这个 export 写进项目的.env文件或者 Claude Code 的启动脚本里。我用的是项目内目录的好处是可以借助 Git 对记忆做版本管理哪天发现记忆被改错了直接git diff就能看到回滚也只敲一条命令。对于极强调隐私的场景你甚至可以在.gitignore里把记忆目录排除掉让它只留在本机。3.4 第一次对话让 Claude 学会用记忆启用 claude-mem 后第一件事不是急着灌记忆而是先做一轮热身。我在首次接入时会明确告诉 Claude接下来你可以使用记忆工具。开始前先搜索一下关于我的偏好和当前项目的事实如果没有再问我。这样能促使它主动感知记忆库的存在。然后我会通过显式命令写入几条基础档案比如请记住我叫 Neo偏好使用 TypeScript 和 pnpm代码注释风格尽量简洁提交信息使用中文但关键词使用英文。请记住本项目的技术栈是 React Vite Express数据库为 SQLite通过 Prisma 访问。写入后直接开一个新会话验证。果不其然再次进入项目时Claude 用了一段记忆它会说根据你的偏好我用 TypeScript 来写这个新模块可以吗这个瞬间你会真正感受到记忆的价值。4. 记忆管理的高级技巧与注意事项4.1 如何设计记忆内容避免记忆污染记忆系统最大的风险不是记不住而是记了不该记的东西。我曾经遇到过 Claude 把某一次的临时调试方案当成正式架构记下来后面所有相关建议都跑偏了。要避免这种污染第一原则是记忆必须有明确定义不要用模糊描述。项目数据库是 MySQL没问题数据库好像迁移过这种就别让 Claude 记。第二原则是定期清理过时信息。我的做法是每周用一个独立会话让 Claude 列出所有记忆并标记可能过时的条目我审核后批量删除。第三原则是对于重要项目最好区分用户偏好和临时决策。这个功能 claude-mem 可以通过标签实现比如给记忆打上user:preference、project:fact、decision:temporary这样的标签检索的时候就能按类型过滤。如果发现 Claude 要记的东西没有打标签你可以直接告诉它给这条记忆加上 project:fact 标签它会照做。4.2 记忆的查看、导出与备份因为我让 claude-mem 把记忆放在了项目目录下所以查看记忆非常简单直接看文件内容就行。用命令行的方式可以这样cat $MEMORY_DIR/*.md如果你的记忆力文件格式是 JSON 或 JSONL用 jq 解析也好用。claude-mem 本身也提供了 list 和 delete 这类工具通过对话就能让 Claude 调用。备份就更简单了对我而言这个目录已经纳入 Git 仓库日常推送时就完成备份了。如果你不想用 Git写个简单的 cron 脚本用 tar 打包也是够的。这里给一个我常用的检查命令把记忆目录按修改时间排序快速看出最近 Claude 都在记什么ls -lt $MEMORY_DIR | head -204.3 多项目隔离别让你的项目交叉感染如果你同时维护多个项目让它们共用一套记忆初始库是很危险的。比如 A 项目的数据库用 PostgreSQL如果被 B 项目检索到B 项目明明用的是 MongoDBClaude 就可能给出完全错误的建议。幸好 claude-mem 支持不同项目使用不同记忆目录我目前的做法是每个项目一个记忆目录同时让 Claude Code 启动时自动加载对应目录。实现方式可以在项目的启动脚本里 export MEMORY_DIR也可以借助 direnv 这类工具按目录自动设置环境变量。在 Claude Code 的 MCP 配置里也可以为不同项目分别注册不同名字的 MCP 服务器指向不同目录比如claude-mem-project-a和claude-mem-project-b。4.4 上下文长度与性能调优很多人担心加了一层记忆后 token 消耗会剧增实际用下来claude-mem 这方面的控制还算克制。它每次检索返回的记忆条目通常都有限额不会把整个库都塞进来。但如果你发现 Claude 在长对话中频繁搜索记忆仍然可能导致上下文快速膨胀。我的优化思路是第一给记忆内容瘦身尽量每条记忆只保留核心事实不要一大段叙事。第二引导 Claude 只在开话题和需要关键事实时搜索而不是每轮都搜。第三对于确定不会再变的项目事实可以显式告诉 Claude这条记忆不需要再次搜索直接相信即可减少重复读取。如果你用的模型上下文比较大比如 200K token那这点记忆开销基本可忽略。真正耗 token 的是让 Claude 把搜索到的内容反复推理而不是记忆本身。5. 实战踩坑记录与问题排查5.1 Claude 不主动调用记忆工具怎么办这几乎是每个人第一次接入 claude-mem 都会碰到的问题配置好了工具也显示了但 Claude 就是不用。别怪模型它默认偏向于直接回答而不是调用额外工具。解决方法很简单在 system prompt 或项目说明里显式写清楚规则——当涉及用户偏好、项目历史决策、技术栈选型时必须先搜索 claude-mem 记忆再做回答。如果没有命中明确告知用户我的记忆库中没有相关信息。加了这句之后我这边工具调用率立竿见影地提高了。你还可以在第一次对话中主动问 Claude你能看到 claude-mem 记忆工具吗尝试搜索我的名字。帮它建立工具使用的习惯。5.2 记忆内容过时或错误怎么修正要修正单条错误记忆直接让 Claude 调用删除工具把那条删掉然后重新记住正确内容。批量修正的话我习惯直接打开记忆文件用编辑器改。因为格式是纯文本改起来非常顺手改完让 Claude 重新加载即可。有一个小坑是如果记忆文件格式是 JSON手改时注意逗号和引号很容易改出语法错误。如果发现 claude-mem 读取失败先检查对应文件格式是否非法。我用过一段时间后养成了一个习惯每次手改前先把整个记忆目录备份一下避免手滑酿成大错。5.3 MCP 连接失败、重复加载怎么排查如果你在/mcp面板里看到 claude-mem 显示 failed大概率是二进制不在 PATH 或版本不匹配。先单独在终端执行claude-mem看能不能正常启动 MCP server。能启动但连接失败检查 MCP 配置里的 command 是否写成了绝对路径。还有一个容易踩的坑某些终端会把 MEMORY_DIR 设置成相对路径而 Claude Code 启动时的当前工作目录和预期不一致导致记忆定位失败。解决办法就是把 MEMORY_DIR 永远写成绝对路径。连接成功后还有个小概率问题是加载了旧版本的记忆改过环境变量但 Claude Code 还缓存着旧配置。重启 Claude Code 进程一般能解决。如果仍然不行可以在/mcp面板中移除后重新添加。5.4 隐私与本地存储的边界claude-mem 本质上会把你的对话内容提炼后写到磁盘这就意味着只要本地文件不加密任何能读取你电脑的人都能看到。如果你在记忆里记了一些敏感信息比如数据库口令、API Key那它实际已经相当于明文存储了。我的建议是绝对不要把密钥类信息放进记忆这类信息应该由环境变量或密钥管理工具负责。对于敏感度高的业务逻辑可以只记结论不记细节比如订单服务已改为事件驱动架构而不是订单支付接口的 private key 在 xxx 文件里。如果你确实需要在记忆里存敏感信息可以考虑把记忆目录放在加密磁盘镜像上。另外提醒一句如果你把记忆目录纳入 Git 仓库并推送到远端这条信息就基本等于公开了。传上去之前一定三思。5.5 问题排查速查表问题现象常见原因解决方法claude-mem 显示 failed二进制不在 PATH / 路径写错使用绝对路径配置 command终端手动启动验证Claude 不调用记忆工具系统提示没有明确规则在 prompt 中显式要求涉及历史决策前先搜索记忆记忆搜索不到任何结果记忆目录配错 / 索引未刷新检查 MEMORY_DIR 绝对路径重启 Claude Code记忆内容张冠李戴多项目共用同一记忆目录使用独立的 MEMORY_DIR 或注册不同的 MCP 实例手改记忆文件后无法读取JSON 语法错误用 JSON 校验工具检查或从备份恢复记忆库越来越乱缺少标签和定期清理约定 tagging 规则每周做一次记忆审计token 消耗异常增加模型每轮都搜索记忆限制搜索频率记忆条目精简瘦身6. 用了一个多月之后我是怎么继续深挖的最初我只看中 claude-mem 能解决跨会话失忆的问题但用得越久越发现它真正改变的是我和 AI 的协作模式。以前我要花不少时间帮 Claude 补背景信息现在它通过记忆库了解我大半的偏好和项目脉络我只需要关注新问题本身。这种感觉很接近带一个懂你的搭档干活你不需要反复解释他就能接上话。如果你也想尝试我建议不要一开始设计太复杂的记忆体系先用起来从记住你的名字和项目技术栈这种小粒度开始跑顺后再逐步加入决策记录、架构约定这些深水区内容。另外推荐把记忆库纳入版本管理哪怕只是本地 Git也能在你误删或 Claude 记错时留下后悔药。最后再分享一个小技巧claude-mem 的搜索能力在默认关键词匹配之外你也可以通过 prompt 让 Claude 在回答前自行调用 search 工具并综合多条记忆这有时候比单条记忆更准确。记忆不是越多越好关键是在需要的那一刻能想起来该想起的那件事。希望这个工具也能让你的 Claude 之旅顺畅很多。