1. 为什么你的 Claude Code 总是“失忆”从一次 Sub-agent 翻车说起如果你正在用 Claude Code 跑 Sub-agents大概率遇到过这种场景主会话里明明交代过“这个项目用 pnpm测试前先起本地 Redis”结果切到一个负责写 API 测试的 Sub-agent它张口就是npm install还问你 Redis 端口是多少。你不得不把同样的上下文再喂一遍喂完发现另一个 Sub-agent 又忘了。这不是模型笨而是 Claude Code 的记忆系统本身是分层的而 Sub-agents 的记忆和主会话的记忆在物理上是隔离的。很多人只听说过CLAUDE.md却不知道 Claude Code 还有一套 Auto Memory 机制——AI 自己给自己记笔记。两者一个是你写给 Claude 的确定性指令一个是 Claude 在工作过程中自己积累的经验协作起来才能让 Sub-agents 真正“记住事”。这篇内容聚焦 Claude Code 的 Auto Memory 与 CLAUDE.md 如何协同工作面向已经在用 Sub-agents 的开发者。我会给出 CLAUDE.md 的分层配置示例、Auto Memory 的触发条件与验证步骤把记忆写入与读取的完整链路拆开讲清楚。读完你能做到知道每条记忆存在哪、什么时候被加载、Sub-agent 怎么拿到属于自己的记忆以及怎么用配置和命令去控制它。先说结论性的认知Claude Code 的记忆不是“越多越好”。每次启动这些内容都会被塞进 system prompt占的是你的上下文窗口。写得精准、组织得清楚比写得多重要得多。下面从记忆类型讲起一路讲到 Sub-agents 的独立记忆目录。2. 两种记忆类型与六层结构CLAUDE.md 和 Auto Memory 到底谁管什么Claude Code 的记忆机制不只有 Auto Memory 一个功能它是一整套分层体系。理解这套体系的关键是先分清两种记忆类型。CLAUDE.md是你写给 Claude 的指令由用户手动维护放在项目目录或用户目录。你可以把它类比成项目的.editorconfig或.eslintrc——用自然语言写的确定性规则。Auto Memory 则是 Claude 自己写给自己的笔记由 AI 自动维护存放在~/.claude/projects/project/memory/下。它记录的是工作过程中发现的项目模式、踩过的坑、你的偏好。这两者的分工可以用一句话概括CLAUDE.md 是“你必须这样做”Auto Memory 是“我观察到事情是这样的”。再往上看Claude Code 实际有六层记忆结构从全局到局部优先级递增层级位置谁维护共享范围优先级组织策略/Library/Application Support/ClaudeCode/CLAUDE.mdIT/DevOps组织内所有人最低项目记忆./CLAUDE.md或./.claude/CLAUDE.md团队通过 Git 共享↑项目规则./.claude/rules/*.md团队通过 Git 共享↑用户记忆~/.claude/CLAUDE.md个人所有项目↑项目本地./CLAUDE.local.md个人仅当前项目↑Auto Memory~/.claude/projects/project/memory/Claude 自己仅你自己最高核心原则是越具体的层级优先级越高。项目规则覆盖用户偏好本地配置覆盖项目配置。这跟 Git 的配置层级--system → --global → --local是一个思路。这里有个容易被忽略的点Auto Memory 的优先级是最高的。也就是说如果 Claude 自己在笔记里记了“这个项目测试要连本地 Redis”而你的CLAUDE.md里没写那 Auto Memory 的内容会生效。反过来如果两者冲突具体层级更高的 Auto Memory 可能压过你的项目指令——这也是为什么后面要强调“定期检查 MEMORY.md 有没有记错”。对于用 Sub-agents 的开发者理解这六层尤其重要主会话加载的是工作目录往上的所有 CLAUDE.md、CLAUDE.local.md、~/.claude/rules/*.md以及 Auto Memory 的 MEMORY.md 前 200 行。而 Sub-agent 有自己的记忆作用域不会自动继承主会话的全部上下文。这个差异就是“主会话记得、Sub-agent 不记得”的根因。3. 可复制配置CLAUDE.md 分层写法与 Auto Memory 开关这一节给可直接抄的配置。先讲 CLAUDE.md 的写法再讲 Auto Memory 的开关最后给 Sub-agent 的记忆目录配置。3.1 CLAUDE.md 基本格式与模块化拆分一个能用的项目CLAUDE.md长这样# 项目约定 - 使用 pnpm不要用 npm - 测试命令pnpm test - 提交前必须跑 lint # 代码风格 - TypeScript 严格模式 - 组件用 PascalCase工具函数用 camelCase - 不要自动加注释和 docstring写 CLAUDE.md 有几个实用建议。把常用命令写进去Claude Code 就不用每次都翻package.json。写具体的约定不写模糊的要求——“函数不超过 30 行”比“代码要简洁”更有约束力。还可以用/init自动生成Claude Code 会扫描项目结构生成基础 CLAUDE.md。当项目变大一个 CLAUDE.md 会变得又长又杂。这时用.claude/rules/目录按主题拆分.claude/rules/ ├── frontend/ │ ├── react.md │ └── styles.md ├── backend/ │ ├── api.md │ └── database.md └── testing.md条件规则用 YAML frontmatter 限定只在处理特定文件时生效--- paths: - src/api/**/*.ts --- # API 开发规则 - 所有端点必须做输入校验 - 使用标准错误响应格式这样处理src/api/下的文件时规则才加载不占用其他场景的上下文。3.2 Auto Memory 的开关控制Auto Memory 默认是开的但你可以从多个层级关掉它。优先级从低到高对话命令用/memory打开编辑器管理记忆。用户设置改~/.claude/settings.json{ autoMemoryEnabled: false }项目设置改.claude/settings.json字段一样{ autoMemoryEnabled: false }环境变量优先级最高适合 CI 场景export CLAUDE_CODE_DISABLE_AUTO_MEMORY1在 CI 里跑 Claude Code 时我建议直接用环境变量关掉 Auto Memory避免构建过程写入不确定的笔记。3.3 Sub-agent 记忆目录配置Sub-agents 可以拥有独立的持久化记忆与主会话的 Auto Memory 物理隔离。作用域分三种作用域存储路径用途user~/.claude/agent-memory/name/跨项目保留适用于通用编码风格project.claude/agent-memory/name/项目相关可通过 Git 共享local.claude/agent-memory-local/name/本地私有不提交到版本控制启用后Claude Code 会自动在子智能体的 System Prompt 中加入读写记忆目录的指令自动加载 MEMORY.md 前 200 行并自动启用 Read、Write、Edit 工具。你不需要手动写这些指令只要把目录建好、把 Sub-agent 的 name 对上即可。如果你要把 Claude Code 接到自己的模型服务上跑这些配置Base URL、Key、Model ID 三件套要写全。Base URL 用https://taotoken.net/apiKey 在控制台生成Model ID 按你选的模型填。这三样缺一个Sub-agent 启动时就会报鉴权或模型找不到的错。4. 验证请求Auto Memory 触发条件与完整读写链路配置写完得验证它真的在工作。这一节给可执行的验证步骤把记忆写入和读取的链路走一遍。4.1 触发 Auto Memory 写入Auto Memory 的触发有两种方式被动积累和主动指令。被动积累是 Claude 在工作过程中自己判断值得记的东西。比如你反复纠正它“测试要连本地 Redis”它可能就把这条记进debugging.md。主动指令则是你直接说记住我们用 pnpm 不用 npm 保存到记忆API 测试需要本地 Redis 忘掉之前关于 Redis 的记忆执行完这几句去看存储目录ls -la ~/.claude/projects/project/memory/正常会看到这样的结构~/.claude/projects/project/memory/ ├── MEMORY.md # 索引文件每次启动加载前 200 行 ├── debugging.md # 调试相关笔记 ├── api-conventions.md # API 设计决策 └── ...MEMORY.md是索引文件启动时只加载前 200 行。主题文件如debugging.md按需加载Claude 需要时才读。如果 MEMORY.md 超过 200 行系统会提示 Claude 自行精简把详细内容移到子文件。4.2 验证读取链路验证读取最直接的办法是开一个新会话问一个只有记忆里才有答案的问题。比如你之前让它记了“API 测试需要本地 Redis”新会话里直接问API 测试需要什么前置依赖如果它答出本地 Redis说明 Auto Memory 的读取链路通了。如果没答出来先确认MEMORY.md里确实有这条再确认当前会话的工作目录和记忆目录的 project 名对得上。4.3 验证 Sub-agent 记忆隔离Sub-agent 的记忆验证要单独做。建一个测试用的 Sub-agent让它记一条只属于它的信息然后在主会话里问同样的问题。如果主会话答不出来说明隔离生效了——这正是我们想要的。反过来如果你希望某个 Sub-agent 跨项目保留通用编码风格就把它的记忆放到 user 作用域~/.claude/agent-memory/name/。如果只跟当前项目相关放 project 作用域还能通过 Git 共享给团队。4.4 文件导入语法验证CLAUDE.md 支持path/to/file语法导入其他文件参考 README 了解项目概况package.json 查看可用命令。 # 额外指令 - Git 工作流 docs/git-instructions.md - 个人偏好 ~/.claude/my-project-instructions.md相对路径基于当前文件所在目录解析支持递归导入最深 5 层。验证方法是改一下被导入的文件看新会话里 Claude 是否感知到变化。5. 本篇常见错排查401、local proxy failed 与记忆不生效配置和验证过程中最容易撞上的是鉴权、网络和记忆加载三类问题。逐个对照排查。5.1 401 鉴权失败报错长这样API Error: 401 Unauthorized先查 Key 有没有过期或复制时带了空格。再确认 Base URL 写的是https://taotoken.net/api不要多加路径或斜杠。如果你用的是 Claude Code 的settings.json配置检查env段里的ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY是否都填了。三件套里少任何一个都会 401。5.2 local proxy failed报错类似Error: local proxy failed to start这类问题通常出在本地端口被占用或配置里指向了一个不存在的本地服务。检查你的settings.json里有没有残留的本地代理地址把它改成正确的 Base URL。如果你在 CI 里跑确认环境变量没有覆盖掉配置文件里的地址。5.3 reading choices 报错Error: reading choices: unexpected end of JSON input这通常是响应体被截断或返回了非预期格式。先确认 Model ID 填对了——填了一个服务端不认识的模型名返回的就不是标准结构。再确认没有中间层篡改响应。把 Model ID 换成明确支持的型号重试。5.4 OAuth 相关报错OAuth token expired or invalid如果你用的是 OAuth 方式登录token 过期后需要重新授权。但如果你走的是 API Key 方式就不该出现 OAuth 报错——出现说明配置里混用了两种鉴权方式。清掉 OAuth 相关字段统一用 API Key。5.5 记忆不生效记忆写了但 Claude 不读按这个顺序查第一确认autoMemoryEnabled没被环境变量CLAUDE_CODE_DISABLE_AUTO_MEMORY1关掉第二确认MEMORY.md没超过 200 行被截断第三确认当前工作目录对应的 project 名和记忆目录一致第四如果是 Sub-agent确认它的记忆作用域和 name 对得上。还有一个高频坑CLAUDE.md 里已经写了“用 pnpm”Auto Memory 又记一遍这就是噪音。定期检查 MEMORY.md把和 CLAUDE.md 重复的条目删掉。记忆越多不代表越好每次启动都塞进 system prompt占的是你的上下文窗口。6. 把记忆链路接进你的工作流讲完机制和排障回到实际使用。我的做法是项目 CLAUDE.md 写团队共识——构建命令、代码规范、架构决策提交到 GitCLAUDE.local.md 写个人偏好——测试数据路径、沙箱 URL自动加到.gitignoreAuto Memory 让它自己跑但每周花五分钟检查 MEMORY.md 有没有记错的。Sub-agents 的记忆按用途分通用编码风格放 user 作用域跨项目复用项目相关的放 project 作用域跟 Git 走本地私有的放 local 作用域不提交。这样主会话和各个 Sub-agent 各记各的不会互相污染。如果你还没配好接入层先去控制台生成 API KeyBase URL 用https://taotoken.net/apiModel ID 按需选。配置和排障过程中卡住了接入文档里有完整的字段说明和示例。想先验证模型对话效果可以直接在模型对话里试几条记忆指令确认读写链路通了再往 Sub-agents 上铺。长期跑编码和 Agent 任务的话Coding Plan 更适合持续使用。记忆系统的价值不在于记得多而在于记得准、取得对。把 CLAUDE.md 的确定性指令和 Auto Memory 的自动积累分清楚再让 Sub-agents 各管各的记忆你的 Claude Code 才算真正“记住事”了。