给AI编程助手装上长期记忆：CLAUDE.md与MCP Memory Server实战

AI 编程助手什么都好就是记性太差。Claude Code、Codex、VS Code 里的 AI 插件、Qoder 这类工具换个会话就对项目里的技术栈、命令规范、代码风格彻底失忆逼着你每次都得把同样的背景知识重新贴一遍。今天这篇就讲怎么用两分钟给这四个入口装上长期记忆让它们不再重启即失忆。这套方案不需要改模型、不需要重新训练用到的都是工具本身提供的记忆机制零成本、可落地适合被重复描述上下文折磨的开发者也适合想让团队知识沉淀下来的负责人。我大概用了小半年才把这套组合摸顺。踩过的坑不少所以文章里除了配置步骤还会把原理、优先级、常见报错和排查思路都讲透。你照着做基本能在两分钟内把最核心的记忆能力跑起来。1. 所谓长久记忆到底在治什么病1.1 会话一关就失忆是工具设计如此先说个扎心的事实Claude Code、Codex 这类命令行 AI 助手本质上每次会话都是重新认识你。模型本身没有持续记忆能力它只在你给的上下文窗口里工作。你关掉终端或者新开一个会话它对你昨天敲定的命名规范、目录约定、测试命令一无所知。这不是产品的 bug而是早期设计时就没把跨会话记忆放进默认能力。于是大家被迫养成了一个习惯每次开工都先甩一段背景说明给 AI什么技术栈、依赖管理工具、禁止用某函数、上次写到哪一步……这段话既是给 AI 看的也是给自己看的——因为你换个项目、换个工具又要重写一遍。长期记忆要解决的就是把这段重复劳动的背景说明变成工具自己能读取、能维护、能沉淀的东西。1.2 长期记忆的三个层次先建立认知我在实际使用中把记忆方案分成三个层次这个认知非常重要。你先理解了后面配置就不容易乱。第一层是静态记忆文件。就是 CLAUDE.md、AGENTS.md 这类文本文件工具每次启动时自动加载像员工手册一样。适合放不会频繁变化的信息技术栈、构建命令、目录结构、代码风格、禁止事项。第二层是动态记忆服务。通过 MCPModel Context Protocol接入一个 Memory ServerAI 在对话过程中可以主动翻笔记写笔记相当于给模型配了一个随身记事本。这一层适合放动态信息任务进度、模块关系、当前决策、用户偏好。第三层是配置切换器。比如 CC Switch 这类工具让你在多套 API 后端配置之间一键切换。和记忆结合起来理解就是不同的项目、不同的后端各自配一套记忆组合。这三个层次不是互斥的而是叠加使用。我的日常状态是静态记忆文件管世界观Memory Server 管临时状态CC Switch 管切换。1.3 四个工具各自能挂到哪一层先把这个表放这里后面所有操作都围绕它展开。工具静态记忆文件动态记忆方案顺手可用的切换方式Claude CodeCLAUDE.md全局/项目MCP Memory Serverclaude mcp 命令、CC SwitchCodexAGENTS.md全局/项目MCP新版本支持Codex 配置文件VS Code通过 Claude Code 插件读取同一套 CLAUDE.md同一个 MCP 服务.vscode/settings.json 环境变量Qoder项目规则文件 / AGENTS.mdMCP 设置面板里录入IDE 内置设置注意Qoder 这类产品的版本迭代很快不同版本的配置入口名称可能有差异但你只要认准项目规则和MCP 设置这两个入口思路是通用的。2. 两分钟上手第一层CLAUDE.md 和 AGENTS.md 的实操2.1 Claude Code 的 CLAUDE.md从全局到项目Claude Code 的记忆文件很好认就叫 CLAUDE.md。它分两个主要作用域。全局记忆放在~/.claude/CLAUDE.md无论你在哪个目录启动 Claude Code它都会自动加载。项目记忆放在项目根目录的CLAUDE.md或.claude/CLAUDE.md只有在这个项目里启动时才加载。优先级上项目级文件高于全局文件。也就是说全局文件写通用偏好项目文件写本项目专属约定两边内容冲突时以项目为准。我第一次配置的时候全局文件写的比较啰嗦把什么代码风格、注释习惯、回复语气全堆进去了。用了几天发现不对劲token 消耗变大而且 Claude 经常在无关紧要的细节上过度遵守。后来我精简到十行以内效果反而更好。一个可以直接抄作业的全局 CLAUDE.md 示例# 全局约定 - 代码注释使用中文commit message 使用英文 - 默认优先考虑可维护性再考虑性能 - 回答尽量给出可直接运行的完整代码不要省略导入语句 - 不确定需求时先向我确认不要自作主张项目级 CLAUDE.md 更适合放工程相关约定# 项目约定 - 包管理器使用 pnpm禁止使用 npm 或 yarn - 测试框架为 Vitest测试文件放在 tests/ 目录 - 组件统一使用 TypeScript React函数组件优先 - 新增接口前先看 src/types/api.ts不要重复定义类型写完保存重新打开 Claude Code 会话让它加载新配置然后随便问一句我们这个项目用什么包管理器它能答对说明记忆已经生效了。这里有个细节Claude Code 在某些版本里也支持.claude/CLAUDE.md如果根目录的CLAUDE.md不生效就试试.claude/子目录这种写法。不同版本加载规则略有差异以官方文档为准。2.2 Codex 的 AGENTS.md一份文件管住 Codex 行为Codex 对应的记忆文件是 AGENTS.md。这个文件如今已经有行业标准的趋势很多 AI 编程工具都在向它兼容所以越早维护收益越大。项目级别就是项目根目录建一个AGENTS.md内容风格和 CLAUDE.md 类似。全局级别一般在用户目录下常见位置是~/.codex/AGENTS.md具体路径也要看版本。AGENTS.md 里我建议重点写三块内容构建命令、测试命令、提交规范。因为 Codex 在做具体任务时会频繁执行命令如果这些信息不给它它经常瞎猜。比如# 项目指令 ## 构建 - 开发模式pnpm dev - 生产构建pnpm build ## 测试 - 运行全部测试pnpm test - 只跑单个文件pnpm vitest tests/xxx.test.ts ## 代码提交 - 提交信息遵循 Conventional Commits - 提交前必须通过 pnpm lint 和 pnpm test写完 AGENTS.md 后重启 Codex 会话让它自己读一遍文件内容确认解析正常。2.3 在 VS Code 和 Qoder 里让这些文件生效很多人有个误区觉得在 VS Code 里用 AI 插件就等于放弃了 CLI 工具里攒下的记忆配置。实际上不是。以 VS Code Claude Code 插件为例插件本质上是把 Claude Code 的能力搬进了 IDE。它启动时会读取同一个~/.claude/CLAUDE.md和项目级CLAUDE.md所以你在命令行里写好的记忆文件到 VS Code 插件里自动生效不需要额外配置。Qoder 这类 AI IDE 的思路也类似。它通常支持项目级规则文件你可以把项目约定放进去也可以在它的设置界面里找到 MCP 服务配置入口把和 Claude Code 里一致的服务地址填进去。我同事在 Qoder 里就是这么干的核心思路和我们这里完全一致。所以结论是静态记忆文件值得尽早纳入 Git 仓库跟着项目走。换人、换机器、换工具只要项目还在记忆就在。3. 更深一层MCP Memory Server 的接入3.1 先解释一下 Memory Server 到底是什么CLAUDE.md 和 AGENTS.md 是每次启动时加载的手册但手册有个天然的短板内容不会自动更新。今天你让 AI 记住当前正在重构 auth 模块它记下了。明天你再问它它可能忘了因为这句记忆没有写进文件。MCP Memory Server 解决的就是这个问题。MCP全称 Model Context Protocol是一套让 AI 工具和外部数据源交互的开放协议。Memory Server 是其中一个经典实现它用知识图谱的方式存储三类信息实体Entity、关系Relation、观测Observation。打个比方CLAUDE.md 是贴在工位上的员工手册Memory Server 是 AI 随身的笔记本。手册是别人写好的笔记本是 AI 自己边干边记的。遇到新信息它可以主动掏出笔记写一笔遇到问题它可以翻笔记找答案。这个能力的价值在项目周期长、上下文跨度大的场景里特别明显。不用你每次手动把上次聊到哪了贴给它对话里自然就带着。3.2 在 Claude Code 中接入并验证接入很简单。前提是你本机有 Node.js 环境因为 Memory Server 是通过 npx 启动的。先确认一下node -v有输出就说明环境没问题。然后执行claude mcp add memory --scope user -- npx -y modelcontextprotocol/server-memory这条命令的意思是把一个名为 memory 的 MCP 服务注册到用户级别对所有 Claude Code 项目生效。--scope user是用户级如果想只让当前项目生效可以去掉或者改成--scope project。我建议把记忆数据文件放到一个固定目录方便备份。可以通过环境变量指定路径claude mcp add memory -e MEMORY_FILE_PATH$HOME/.config/ai-memory/memory.json --scope user -- npx -y modelcontextprotocol/server-memory这样 memory.json 就被固定下来了。验证是否添加成功claude mcp list能看到 memory 这一项就说明注册成功。然后重启 Claude Code 会话随便聊几句让它记住你是后端开发者偏好 TypeScript。下一轮会话里问它我之前说过我的技术偏好是什么如果它能答上来说明动态记忆已经跑通了。3.3 Codex 与 Qoder 接入同一个记忆库如果只有 Claude Code 能访问 Memory Server那还是不够毕竟很多人主力工具其实是 Codex 或者 Qoder。Codex 的新版本支持配置 MCP 服务方式是在它的配置文件里声明一个 mcp server。不同版本的配置字段略有差异但语义都是同一个指定 command 为 npxargs 指向modelcontextprotocol/server-memoryenv 里带上 MEMORY_FILE_PATH。Qoder 则在设置面板里通常有 MCP 管理入口你只需要点添加 MCP 服务器把同样的命令和参数填进去保存后重启会话。这里有一个非常重要的实操经验多个工具同时读同一个 memory.json 没问题但尽量不要同时写。如果 Claude Code 和 Codex 同时在一个会话里用同一个 memory 文件可能遇到数据覆盖或者写入冲突。我的做法是固定一个工具作为主写工具其他工具只读使用。3.4 记忆到底该放 CLAUDE.md 还是 Memory Server很多读者看到这里会纠结我到底应该把所有东西都写进 CLAUDE.md还是都丢给 Memory Server我的判断规则很简单静态的、稳定的、团队统一的放 CLAUDE.md / AGENTS.md。比如技术栈、命令、代码风格。这类信息你希望每次会话都无脑加载不依赖 AI 主动回忆。动态的、临时的、个人偏好的放 Memory Server。比如目前正在重构 user 模块这个项目禁止使用 any客户要求所有错误提示显示中文。这类信息是 AI 在对话过程中需要自己读取和更新的不适合手工维护。另外还有一个实践建议每隔一段时间让 AI 把 Memory Server 里的重要信息回填到 CLAUDE.md。我在每周五下班前会顺手做个整理把这一周沉淀下来的稳定约定固化到项目文件里这样即使 Memory Server 哪天数据坏了核心记忆也不会丢。4. 组合拳CC Switch、环境变量与多工具并联4.1 CC Switch 的定位和使用心得先说明一下 CC Switch 是干嘛的。它是一个开源配置切换工具解决的是 Claude Code 多套 API 后端配置的管理问题。什么场景需要它比如你平时用官方接口偶尔想试试本地 Ollama 模型又或者团队里接入了 DeepSeek、MiniMax 这类第三方模型。这些后端配置各不相同手动改环境变量容易改错、改乱CC Switch 这类工具就是把这些配置集中管理一键切换。和记忆组合起来可以玩出更细的搭配。比如你切到 Ollama 本地模型时上下文窗口较小就让 Claude Code 少加载一些记忆文件切到云端强模型时记忆文件可以写得更多更细。虽然这个粒度控制需要手动调整但思路是完全可行的。有不少人切换后端后遇到连接失败请求端点报错之类的问题我的排查顺序很固定先看本地服务是不是正常运行端口有没有对再看配置里的后端地址有没有填对最后看认证信息有没有同步过去。多数情况下问题出在配置没写完整而不是工具本身的问题。4.2 用环境变量让四个工具指向同一套记忆想让 Claude Code、Codex、VS Code 插件、Qoder 这四类工具共享同一个动态记忆库最核心的一步就是把 Memory Server 的数据文件路径统一起来。在 Claude Code 里我们前面已经通过-e MEMORY_FILE_PATH指定了路径。如果用的是配置文件方式则是在 mcpServers 节点的 env 字段里维护同一个值。在 VS Code 里如果你希望终端里启动 Claude Code 时也能读到这套环境变量可以在.vscode/settings.json里配{ terminal.integrated.env.linux: { MEMORY_FILE_PATH: $HOME/.config/ai-memory/memory.json } }macOS 用户注意是terminal.integrated.env.osxWindows 是terminal.integrated.env.windows。配完后别忘重点 VS Code 窗口。这样做的好处是你只有一个 memory.json所有工具访问的都是同一份数据。你今天在 Claude Code 里让 AI 记住的事情明天切到 Qoder 里问它它依然知道。4.3 团队共享记忆的正确姿势单人使用记忆是一回事团队协作又是另一回事。这里有几个我踩过坑后的建议。项目级的 CLAUDE.md 和 AGENTS.md 一定要纳入 Git 仓库。这是团队的核心资产新人拉下来代码启动 AI 工具自动获得项目所有约定不用再靠口口相传。本地记忆文件比如 memory.json默认不要入库。因为里面很可能混入了个人偏好、临时状态、甚至敏感信息。如果你确实想让团队共享一份动态记忆库可以考虑把它放到统一的内网存储路径上而不是每个人的电脑里各存一份。还有一条个人偏好放全局文件团队约定放项目文件。我见过有人把个人偏好写进项目 CLAUDE.md结果提交后整个团队都被迫接受某一个人的代码风格气氛一度非常尴尬。5. 问题排查与我的实测心得5.1 两分钟完整流程速查最后把整套流程压缩成一个速查版本第一次配置照着做两分钟左右能跑完。第一步创建静态记忆文件。全局文件~/.claude/CLAUDE.md项目文件./CLAUDE.md或AGENTS.md先写十行核心约定。这一分钟。第二步接入动态记忆服务。执行claude mcp add memory --scope user -- npx -y modelcontextprotocol/server-memory指定一个固定的数据文件路径。半分钟。第三步验证。用claude mcp list确认服务注册成功然后重启会话让 AI 记住一条信息再开新会话让它回忆。半分钟。三步下来Claude Code 的长期记忆就已经能用了。Codex、VS Code、Qoder 无非是复用同样的记忆文件或同一份 MCP 服务额外多花一分钟配置一下入口就行。5.2 常见问题速查表现象可能原因处理方式CLAUDE.md 不生效文件路径不对或者新版本改了加载规则核对文件位置尝试换成.claude/CLAUDE.md添加 MCP 后工具提示找不到命令npx 路径不在 PATH 中用 which npx 找到绝对路径填入 command 字段Memory Server 数据一直不更新多个工具同时写同一个 memory.json固定一个主写入工具其他只读Qoder 的 MCP 连不上命令里带了 shell 语法导致解析失败删除复杂引号改用 npx 的可执行文件绝对路径切换后端后请求报连接失败本地服务没起或端口不对、认证信息没同步按服务状态、端口、认证顺序排查记忆加载后 token 消耗明显变大CLAUDE.md 内容过长精简文件把动态内容移到 Memory Server5.3 几个走弯路后总结的经验我在配置过程中踩过不少坑总结几条最值得说的。第一别一上来就追求大而全。第一次写 CLAUDE.md 时我花了一个多小时把所有能想到的规范全写进去了。结果 Claude 每次会话都要读这一大堆内容token 消耗明显增加而且它开始在细枝末节上过度较真。后来我精简到二十行效果反而更好。记忆不是越多越好而是越精准越好。第二Memory Server 的数据不会自动可视化。你很难直观看到 AI 记了什么。我的做法是每隔几天用编辑器打开 memory.json 翻一下看看里面有没有明显错误或者冗余数据。本质上它就是个普通 JSON 文件不用把它当成黑盒子。第三让 AI 自己维护记忆比手工维护高效得多。我现在每次收工前会跟 Claude Code 说一句把我们这次会话的关键进度和结论整理进记忆它就会主动调用 Memory Server 工具完成写入。第二天继续时再让它回忆一下当前进度基本能做到无缝衔接。第四所有记忆方案都建立在工具更新迭代的基础上。Claude Code 和 Codex 的配置规则变动过好几次我遇到过老版本配置文件失效的情况。建议每次升级工具后都花几分钟确认一下记忆配置是否还在生效。我把这套记忆方案跑了一个多月最直观的感受是现在打开 Claude Code 不用再贴我是谁、项目是什么、用什么命令这样的开场白了。更让我意外的收获是把项目里的隐性约定写成文本这件事本身比 AI 记住这些约定更有价值——因为团队成员之间也终于有了一个统一的、可维护的、跟随项目走的知识底座。如果你刚开始搭别急着把所有功能都上齐。先写一个只有十行的 CLAUDE.md加一个 Memory Server跑两天。等你真正感受到了AI 记得住事的爽感再慢慢扩展不迟。