HoRain云--Claude Code 记忆系统（Memory）实战：CLAUDE.md 与 Auto Memory 配置指南

1. 多项目并行时Claude Code 为什么总像“第一次见我”如果你同时维护三四个仓库一定遇到过这种场面上午在 A 项目里跟 Claude Code 反复强调“这个仓库用 pnpm别用 npm”下午切到 B 项目它又开始 npm install昨天刚解释完“我们的日期统一 ISO 8601”今天新开一个会话它照样给你写成2024/5/1。这不是模型变笨了而是 Claude Code 默认没有跨会话记忆——每个新会话都从一个干净的上下文窗口开始上一轮你辛苦调教出来的约定会话一关就归零。Claude Code 的 Memory 系统就是来解决这件事的。它由两条互补的机制组成一条是你手写的CLAUDE.md用来固化项目规范、构建命令、团队约定另一条是 Auto Memory由 Claude 自己在工作过程中把纠正、偏好、调试发现写进本地记忆目录。两者在每次会话启动时都会被加载进上下文让 Claude 一上来就“记得”这个项目的脾气。这套东西适合谁适合手里有多个仓库、经常开新会话、又不想每次重复交代背景的开发者。尤其是团队协作场景把CLAUDE.md提交进 Git所有人的 Claude 助手读到的规范就是同一份。下面我会从记忆层级讲起给出可直接复制的CLAUDE.md结构、Auto Memory 的开关配置再演示一次记忆写入和跨会话召回最后把常见报错挨个排掉。全程围绕 Claude Code、Memory、CLAUDE.md、Auto Memory 这几个关键词展开跟着做就能搭出一层可维护的记忆。需要说明的是Claude Code 走的是 Anthropic 官方接口国内直连偶尔会碰到网络抖动或鉴权失败。我这边习惯用 TaoToken 做一层统一的 API 接入把 Base URL 和 Key 集中管理后面配置里会带上你也可以换成自己的接入方式。2. 记忆层级与 CLAUDE.md 目录结构把项目规范写进文件Claude Code 的记忆不是单一文件而是一个四层优先级结构从高到低依次是企业级配置Enterprise policy只读最高优先级、用户级~/.claude/CLAUDE.md对你所有项目生效、项目级CLAUDE.md放在项目根目录随 Git 共享给团队、子目录级CLAUDE.md放在src/、api/、tests/等目录按上下文加载。规则越具体越优先子目录的CLAUDE.md会覆盖上层的同类规则。这个设计的好处是分层解耦个人偏好放用户级团队规范放项目级模块细节放子目录级。你不用把所有东西塞进一个文件Claude 只在处理对应目录的文件时才加载子目录记忆既省 token 又更精准。先看一个我实测下来比较顺手的目录结构my-project/ ├── CLAUDE.md # 项目级技术栈、命令、全局约定 ├── src/ │ └── CLAUDE.md # 前端组件规范仅处理 src/ 时加载 ├── api/ │ └── CLAUDE.md # API 路由与错误格式约定 ├── tests/ │ └── CLAUDE.md # 测试规则、fixture 约定 └── .claude/ └── settings.json # Auto Memory 等开关项目级CLAUDE.md建议控制在 200 行以内因为超出部分不会在会话启动时加载。写法上用祈使句和短列表别写叙述性段落带上具体版本号和命令能放代码示例就放——5 行示例胜过 50 字说明。下面这份可以直接抄改# 项目约定 ## 技术栈 - 前端Next.js 15、TypeScript 5.7、Tailwind CSS 4 - 后端Node.js 22、Prisma 6 - 测试Vitest 3.2 ## 代码规范 - 始终使用函数式 React 组件 - 文件名使用 kebab-case - 测试文件与源码放在同一目录 ## 常用命令 - 构建pnpm build - 测试pnpm test - 启动开发服务器pnpm dev ## API 约定 - 所有 API 路由以 /api/v1/ 开头 - 错误响应格式{ error: string, code: number }要避免的是“遵循最佳实践”“写干净的代码”这类模糊指令它们对 Claude 几乎没有约束力。也别把通用规则堆进来只放这个项目独有的约定。过时信息记得每月审一次否则 Claude 会照着旧规范干活。创建CLAUDE.md有两条路。一是用/init命令自动生成在项目根目录启动 Claude Code输入/init它会分析目录结构、检测框架和测试工具几十秒内生成一份八成完整度的骨架你再手动补细节。二是直接touch CLAUDE.md手写。我一般先用/init打底再按上面的结构重排。子目录CLAUDE.md是省 token 的关键。比如api/CLAUDE.md里只写 API 相关约定Claude 在处理api/下的文件时才加载它处理前端组件时完全不读。多项目并行时这套层级让你在 A 项目强调 pnpm、在 B 项目强调 npm互不干扰。3. 可复制配置Auto Memory 开关与 settings.json 片段Auto Memory 是 Claude 自己写的那一半记忆。它在工作过程中判断哪些信息未来有用然后自动保存包括构建命令、调试技巧、架构决策、代码风格偏好、工作流习惯。它不会每次都写只有觉得值得留存才落盘。存储位置在用户目录下~/.claude/projects/project/memory/ ├── MEMORY.md # 索引文件每次会话加载前 200 行 ├── debugging.md # 调试模式详细笔记 ├── api-conventions.md # API 设计决策 └── ... # Claude 创建的其他主题文件MEMORY.md是整个记忆目录的索引Claude 靠它追踪各文件存了什么。注意 Auto Memory 是本地机器级别的同一 Git 仓库的所有 worktree 和子目录共享一个记忆目录但不会跨机器或云环境同步——换台电脑就得重新积累。开关 Auto Memory 有三种方式。第一种是在会话里用/memory命令切换这个命令还能查看当前加载的所有CLAUDE.md和规则文件、打开记忆文件夹、选择文件在编辑器里编辑。第二种是在项目设置里配置路径是.claude/settings.json{ autoMemoryEnabled: false }把false改成true就是开启。第三种是环境变量适合临时关掉export CLAUDE_CODE_DISABLE_AUTO_MEMORY1如果你用 TaoToken 统一接入 Claude Code配置集中在环境变量里Base URL 指向https://taotoken.net/apiKey 从控制台生成。这样多项目共用一套鉴权切换仓库时不用反复改配置。模型 ID 按你订阅的套餐填比如 Claude 系列对应的模型标识。三件套Base URL Key Model ID配齐后Claude Code 才能正常发起请求Auto Memory 也才有会话可写。还有一个隐藏效率技巧在会话里按#键直接输入想记住的内容再回车Claude Code 会自动把它写进对应的CLAUDE.md。适合快速记录项目约定、常用 Bash 命令、代码风格细节。如果你明确想写进CLAUDE.md而不是 Auto Memory直接说“把这条加到 CLAUDE.md”即可。需要提醒的是Auto Memory 写的是本地文件团队协作时它不会自动共享。团队规范该进项目级CLAUDE.md并提交 Git个人习惯才交给 Auto Memory。4. 验证请求一次记忆写入与跨会话召回实测配置完得验证它真的生效不然你以为记住了、实际没加载白折腾。下面走一遍完整流程。第一步初始化项目记忆。在项目根目录启动 Claude Code执行/init生成骨架然后手动补上你的技术栈和命令。完成后用/memory确认文件已被加载——列表里应该能看到项目级CLAUDE.md。第二步触发一次 Auto Memory 写入。在会话里直接告诉它一条偏好你始终使用 pnpm不要用 npm 你记住 API 测试需要本地运行 Redis 实例 你我们的日期格式统一用 ISO 8601Claude 会判断这些值得留存写进~/.claude/projects/project/memory/下的主题文件并更新MEMORY.md索引。你可以打开那个目录看文件是否真的多出来。第三步验证跨会话召回。完全退出当前会话重新claude启动一个新会话然后问它你这个项目用什么包管理器API 测试有什么前置依赖如果记忆生效它会答出 pnpm 和 Redis 依赖而不是泛泛地说“通常用 npm”。这一步是整套机制的核心验证点——新会话的上下文窗口是干净的能答对说明记忆确实被加载了。第四步验证项目级CLAUDE.md的约束力。在CLAUDE.md里写一条“所有 API 路由以/api/v1/开头”新开会话让它生成一个路由文件看它是否遵守前缀约定。遵守说明项目级记忆加载正常。第五步验证子目录记忆的按需加载。在api/CLAUDE.md写一条 API 专属约定然后分别在处理src/文件和处理api/文件时观察 Claude 的行为差异。处理src/时它不该引用 API 约定处理api/时才加载。实测下来这套验证跑通后多项目切换的体验会明显不同A 项目的 pnpm 约定、B 项目的 npm 约定各自待在自己的记忆层里新会话一开就各就各位。如果你在验证时发现召回失败先别怀疑机制多半是加载或路径问题下一节挨个排。5. 常见报错排查401、local proxy failed 与记忆不加载配置过程中最容易卡在鉴权和加载两类问题上下面按真实报错逐个拆。报错一401 Unauthorized。这是鉴权失败通常有三种原因Key 没配、Key 过期、Base URL 写错。先确认环境变量里的 Key 和控制台生成的一致再确认 Base URL 指向https://taotoken.net/api注意不要多加路径后缀。如果你用的是 Claude Code 的 OAuth 登录方式检查登录态是否过期必要时重新走一遍授权。401 和记忆系统无关但鉴权不过会话根本起不来记忆自然无从加载。报错二local proxy failed。这个报错说明本地代理层没起来或端口被占。检查你的接入配置里代理地址和端口是否和实际监听一致确认没有其他进程占用同一端口。如果你在settings.json里配了代理相关字段核对拼写。这个错和网络环境有关和记忆文件本身无关排掉之后会话才能正常建立。报错三reading choices 相关错误。这类报错一般出现在响应解析阶段常见于模型 ID 填错或接口返回格式和客户端预期不匹配。核对三件套里的 Model ID 是否和你订阅的套餐对应Base URL 是否完整。如果用的是 Codex 的auth.json方式接入检查文件里的字段名和层级是否正确auth.json里通常要写全 Base URL、Key、Model ID 三项缺一项就可能解析失败。报错四Claude 忽略了 CLAUDE.md 的指令。这不是报错但最让人抓狂。排查顺序先运行/memory确认文件已被加载再确认 Claude Code 是在CLAUDE.md所在目录或其子目录中运行路径不对就不会加载然后检查指令是否够具体“遵循最佳实践”太模糊“使用具名导入以兼容 tree-shaking”才有效最后看文件是否超过 200 行超出部分不加载。还要理解一点CLAUDE.md是上下文不是强制执行Claude 读取并尽力遵循但指令模糊或相互冲突时没有严格合规保证。把它当“工作指南”而非“不可违反的规则”。报错五Auto Memory 不写入。先确认autoMemoryEnabled没被设成false环境变量CLAUDE_CODE_DISABLE_AUTO_MEMORY没被设成1。再确认你告知的内容确实值得留存——Claude 会判断不是每句都写。如果换了机器记忆目录不会同步需要重新积累。报错六CC Switch / Cline MCP 配置后记忆不生效。如果你用 CC Switch 或 Cline 的 MCP 方式接入务必写全三件套Base URL、Key、Model ID。少任何一项会话可能能起但行为异常记忆加载也会受影响。MCP 直连生产库这种操作要避免记忆配置只在开发环境调。排完这些记忆系统基本就稳了。鉴权类问题去 API Keys 页面核对接入细节看接入文档两处配合能覆盖大部分场景。6. 把记忆层用起来从接入到长期编码记忆系统搭好之后日常怎么用才不浪费我的习惯是分三层维护团队共享的规范进项目根目录CLAUDE.md并提交 Git个人偏好进~/.claude/CLAUDE.md模块特定规则进子目录CLAUDE.md。让 Claude 自学的部分交给 Auto Memory口头告知偏好即可。临时上下文用docs/filename.md按需引用别一股脑塞进CLAUDE.md。任务跟踪就在 Markdown 文件里用[ ]复选框Claude 读得到也改得动。如果你还在纠结接入方式鉴权和排障相关的配置去 API Keys 页面生成 Key接入细节对照接入文档一步步来想先验证模型对话效果可以在模型对话里试几轮确认响应正常再落到项目里长期编码和 Agent 场景用 Coding Plan 更省心多项目切换时记忆层配合套餐一起用上下文保持的体验会顺很多。最后留一个我踩过的坑CLAUDE.md别写成大段散文Claude 对短列表和代码示例的遵循度明显更高。还有Auto Memory 是本地机器级别的换电脑不会跟着走重要约定一定要落到项目级CLAUDE.md并提交 Git别全指望它自己记。