Claude Code 记忆系统全解析：6 层记忆架构、@import 语法与 Rules 模块化

Claude Code AI 开发工具 Anthropic 原创

Anthropic 今天更新了 Claude Code 的记忆管理文档，同时正式推出了 Auto Memory 功能。Claude Code 负责人 Thariq 在 Twitter 上给出了一句精准定义：

CLAUDE.md 是你对 Claude 的指令，MEMORY.md 是 Claude 自己的记忆草稿本。

这句话背后，是一套比大多数人想象的更复杂的记忆体系。

为什么需要记忆系统

用 Claude Code 的人都踩过同一个坑：每次开新 session，Claude 什么都不记得。

你花了一小时解释项目架构、调试了一个诡异的并发 bug、告诉它"我们用 pnpm 不用 npm"——关掉终端，全部归零。

Twitter 用户 @sooyoon_eth 说得直接：

你给 AI agent 解释同样的架构决策，每个 session 都来一遍。如果你的 AI 过了 30 条消息就忘了核心模式，那它不是智能——是个贵的记事本。

Claude Code 的记忆系统就是为了解决这个问题。但它的设计比"加个记忆文件"要深思熟虑得多。

6 层记忆架构

这是整个系统最值得细看的部分。Claude Code 的记忆不是一个文件，而是 6 层结构，每层解决不同的问题：

Layer 1 — 组织策略 → 组织内所有人可见 /Library/Application Support/ClaudeCode/CLAUDE.md 公司统一的编码标准和安全策略，由 IT/DevOps 部署。

Layer 2 — 项目记忆 → 通过 Git 共享给团队 ./CLAUDE.md 或 ./.claude/CLAUDE.md 团队共享的项目指令——架构规范、编码标准、常用工作流。

Layer 3 — 项目规则 → 通过 Git 共享给团队 ./.claude/rules/*.md 模块化的规则文件，按主题拆分，支持路径限定。

Layer 4 — 用户记忆 → 仅自己（所有项目） ~/.claude/CLAUDE.md 个人偏好，对所有项目生效。

Layer 5 — 本地项目记忆 → 仅自己（自动 gitignore） ./CLAUDE.local.md 个人的项目专属设置，比如本地测试 URL、沙箱配置。

Layer 6 — 自动记忆 → 仅自己（按项目隔离） ~/.claude/projects/<project>/memory/ Claude 自己记录的笔记——调试心得、架构发现、用户偏好。

设计哲学：越具体的层级优先级越高。项目规则覆盖用户偏好，用户偏好覆盖组织策略。

这意味着公司可以设"必须写单元测试"的基线，团队在项目 CLAUDE.md 里补充"测试用 vitest"，你个人在 CLAUDE.local.md 里加"测试跑在 port 3001 的本地数据库上"。三层互不冲突，各管各的。

加载机制

不是所有文件都立即加载。这里有一个容易忽略的细节：

  • 当前目录及父目录 的 CLAUDE.md：启动时全部加载
  • 子目录 的 CLAUDE.md：按需加载——只在 Claude 读取该目录下的文件时才注入
  • Auto Memory 的 MEMORY.md：只加载前 200 行

这个"子目录按需加载"的设计很巧妙。在大型 monorepo 中，你可以在 frontend/CLAUDE.md 和 backend/CLAUDE.md 中分别写前后端的规则，Claude 只在实际处理对应代码时才加载它们，不浪费 Context Window。

新功能：@import 导入语法

这是这次文档更新中最实用的新功能。CLAUDE.md 现在支持用 @path 导入其他文件：

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

支持相对路径和绝对路径。相对路径基于包含导入的文件解析，不是工作目录。

实际用途：

把 CLAUDE.md 变成一个轻量索引，指向项目中已有的文档。不需要把 README 的内容复制粘贴进 CLAUDE.md——直接 @README 引用。

一个特别有用的场景：Git Worktree 用户。CLAUDE.local.md 只存在于一个 worktree 中，但你可以用 home 目录导入让所有 worktree 共享个人设置：

# Individual Preferences
- @~/.claude/my-project-instructions.md

导入支持递归（最多 5 层），首次遇到外部导入时会弹出审批对话框。代码块和行内代码中的 @ 不会被解析为导入——不用担心 @anthropic-ai/claude-code 这样的包名被误认。

新功能：.claude/rules/ 模块化规则

对于大型项目，一个 CLAUDE.md 塞下所有规则太臃肿。现在可以用 .claude/rules/ 目录按主题拆分：

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md     # 代码风格
│       ├── testing.md        # 测试约定
│       ├── security.md       # 安全规范
│       ├── frontend/
│       │   ├── react.md
│       │   └── styles.md
│       └── backend/
│           ├── api.md
│           └── database.md

所有 .md 文件递归发现，自动加载。支持子目录和 symlink。

路径限定规则

这是 rules 系统最精妙的部分。通过 YAML frontmatter 的 paths 字段，规则只在 Claude 处理匹配文件时生效：

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规范

- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式
- 包含 OpenAPI 文档注释

这意味着你的 API 规范不会在 Claude 修改前端组件时加载进去。支持标准 glob 模式和大括号展开（*.{ts,tsx}）。

没有 paths 字段的规则文件无条件加载。

用户级规则

个人规则可以放在 ~/.claude/rules/，对所有项目生效。加载优先级低于项目规则，所以项目规则可以覆盖你的个人偏好。

Auto Memory：Claude 的自我笔记

Auto Memory 是这套系统中唯一由 Claude 自己写 的部分。所有其他记忆文件都是人写的指令，只有 MEMORY.md 是 Claude 在工作过程中主动记录的笔记。

它记什么

  • 项目模式：构建命令、测试约定、代码风格
  • 调试心得：棘手问题的解决方案
  • 架构笔记：关键文件、模块关系
  • 用户偏好：你倾向的工作流和工具

存储结构

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 索引，前 200 行自动加载
├── debugging.md       # 调试笔记（按需读取）
├── api-conventions.md # API 决策（按需读取）
└── ...

<project> 路径基于 Git 仓库根目录。同一 repo 的所有子目录共享一个记忆目录，Git worktree 各自独立。

管理方式

  • /memory 命令：打开文件选择器，可编辑也可切换开关
  • 口头指令：“记住我们用 pnpm 不用 npm”
  • 手动编辑文件
  • 全局关闭：settings.json 中 "autoMemoryEnabled": false
  • 项目关闭：.claude/settings.json 中同样设置
  • 环境变量覆盖：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1（优先级最高，适合 CI 环境）

社区的真实反馈

功能发布当天，Twitter 上的讨论非常热烈，意见分化明显。

正面：复利效应是真的

@realtechfarmr 用了两周后的感受：

我用 Claude Code 的记忆系统做了类似的事。每个 session 它都会保存模式、陷阱和决策到 CLAUDE.md 文件中。几周后，它真的感觉像一个了解你代码库的副驾驶。复利效应是真的。

日本用户 @yukitsune_x 测算了实际收益：

跨 session 持久化后，体感 token 消耗减少 20-50%。

@xxx111god 分享了一个反直觉的发现：把 CLAUDE.md 从 427 行精简到 96 行后，token 消耗降了 78%，回答质量反而上升了。原因很简单：噪音少了，信号就清晰了。

负面：记忆污染和锁定效应

@eniwhere_ 提出了一个重要警告：

PSA: Claude Code 会在 MEMORY.md 中持久化它学到的东西——关掉它。当它走错方向时，也会持久化错误假设。意味着你未来的 session 从一开始就会建立在错误的前提上。

@borisdayma 指出了跨工具兼容性问题：

记忆存在 ~/.claude/ 里太烦了。切换到 Codex 就失去了所有上下文！以前你只需要把 Codex 指向 CLAUDE.md，现在还得记住 home 目录下的 memory 文件夹。

@G_Programming 从更高的角度看了这个问题：

这把你绑定在 Claude Code 上。明天换 Cursor、Windsurf 或 Gemini CLI，你的记忆就全丢了。记忆应该属于用户，不是属于工具。

值得一提的是，日本开发者 @nukonuko 的一条"不需要 MEMORY.md"推文获得了 97 个赞——是这个话题下的最高赞负面评价。

有趣的用法

自我修复型记忆——@olanetsoft 分享了一个 AI agent 的案例：当 agent 在交易中亏了 33 美元，它在用户推送修复之前就自己更新了记忆，从 5 次失败中总结出 3 条规则。

团队共享记忆——@oyayla_ 把记忆文件放进 Git 仓库，而不是 Claude 的默认目录。任何 pull 代码的人都自动获得完整上下文。

3 层记忆系统——@franmilla 设计了一个精巧的架构：CLAUDE.md 存规则和历史教训，一个 300 行的状态文件跟踪项目进度，再加上每日仪式（/start 读记忆，/close 更新记忆）。

最佳实践

综合官方文档和社区经验，几个共识：

1. CLAUDE.md 要精简

427 行的 CLAUDE.md 不如 96 行的好用。每条指令越具体越好——“使用 2 空格缩进"优于"规范格式化代码”。

2. 定期清理 Auto Memory

Claude 记的东西不一定都有用，错误记忆更会持续误导。@melvynxdev 专门发布了一个记忆清理 skill，号称能去掉 70% 的无用记忆。

3. 用 rules/ 替代臃肿的 CLAUDE.md

把规则按主题拆分到 .claude/rules/，用 paths 限定作用范围。前端规则不需要在处理后端代码时加载。

4. 分清指令和记忆

CLAUDE.md 是你写给 Claude 的指令——编码标准、命名约定、工作流规则。MEMORY.md 是 Claude 写给自己的笔记——它发现了什么、学到了什么。两者不要混在一起。

5. 考虑可移植性

如果你同时用多个 AI 编程工具，把核心上下文放在项目的 CLAUDE.md 或 README 里（Git 管理），而不是依赖 ~/.claude/ 下的私有记忆。

这套系统的意义

Claude Code 的 6 层记忆架构，本质上是在回答一个问题：AI 编程助手的"知识"应该由谁管理、存在哪里、何时加载？

传统的做法是一个平面文件塞下所有东西。Claude Code 的回答是分层——组织策略、团队规则、个人偏好、自动记忆各归其位，按需加载，各层之间有明确的优先级。

当然，这套系统也不是没有问题。记忆污染、Context 占用、工具锁定都是社区正在讨论的真实痛点。但作为目前 AI 编程工具中最系统化的记忆方案，它至少给出了一个清晰的架构方向。

对于每天依赖 AI 写代码的人来说，花 10 分钟理清这 6 层记忆结构，设好你的 CLAUDE.md 和 rules，长期回报远超预期。复利效应——是真的。

参考链接

☕ 如果这篇文章对你有帮助，欢迎请我喝杯咖啡，支持我继续创作更多内容。

Buy me a coffee