Claude Code 的记忆系统通过 CLAUDE.md 文件实现跨会话的上下文持久化，其核心是遵循严格优先级顺序的 7 层层级架构。本文将深度解析这套架构，涵盖从 /init 命令初始化、/memory 编辑，到路径特定规则、自动记忆目录自定义等全部关键操作，并提供生产级的配置模板与排错指南。

Claude Code 记忆系统深度指南：7 层层级架构与 CLAUDE.md 最佳实践 #

Claude Code 的记忆系统与临时对话窗口不同，它通过文件系统中的 CLAUDE.md 文件提供持久化上下文。这套系统允许你共享项目标准、存储个人偏好、维护目录特定规则，并将记忆作为项目的一部分进行版本控制。理解其多层架构和正确配置方法，是高效使用 Claude Code 的基础。

核心架构：7 层记忆层级 #

Claude Code 在启动时会自动加载记忆文件，遵循严格的优先级顺序。层级越高，其内容对 Claude 的影响力越大。

graph TD
    A["Managed Policy<br/>/Library/.../ClaudeCode/CLAUDE.md"] -->|highest priority| A2["Managed Drop-ins<br/>managed-settings.d/"]
    A2 --> B["Project Memory<br/>./CLAUDE.md"]
    B --> C["Project Rules<br/>./.claude/rules/*.md"]
    C --> D["User Memory<br/>~/.claude/CLAUDE.md"]
    D --> E["User Rules<br/>~/.claude/rules/*.md"]
    E --> F["Local Project Memory<br/>./CLAUDE.local.md"]
    F --> G["Auto Memory<br/>~/.claude/projects/.../memory/"]

下表详细列出了每一层的位置、作用域和典型用途。

关键点：当不同层级的记忆指令发生冲突时，高优先级层级的指令会覆盖低优先级的。例如，Project Memory（优先级2）中的规则会覆盖 User Memory（优先级4）中的同名规则。

快速上手：初始化与编辑记忆 #

使用 /init 命令快速初始化 #

/init 是为新项目创建记忆文件的最快方式。

标准用法：

# 在项目根目录执行
/init

此命令会创建一个包含基础模板的 CLAUDE.md 文件。

交互式初始化流程（v2.1.117+）： 设置环境变量 CLAUDE_CODE_NEW_INIT=1 可以启用更详细的交互式向导。

CLAUDE_CODE_NEW_INIT=1 claude
/init

这个向导会逐步引导你完成项目设置，例如询问项目技术栈、团队规模等，并将信息写入生成的 CLAUDE.md 中。

验证方法：执行后，检查项目根目录是否生成了 CLAUDE.md 文件，文件内容应包含根据你输入生成的项目概述和开发标准章节。

使用 /memory 命令编辑记忆 #

/memory 命令用于在会话中直接打开并编辑已有的记忆文件。

操作步骤：

1. 在 Claude Code 会话中输入 /memory。
2. Claude 会列出可编辑的记忆文件选项（例如：项目记忆、用户记忆）。
3. 选择一项，系统默认编辑器将打开对应的 CLAUDE.md 文件。
4. 直接修改、保存并关闭编辑器。Claude 会自动重新加载更新后的记忆。

对话式添加记忆： 你也可以直接用自然语言要求 Claude 记住某些信息。

记住：在这个项目中，我们总是使用 TypeScript 严格模式。
请将这条规则添加到记忆中：所有 API 端点都必须包含输入验证。

Claude 会将请求写入合适的 CLAUDE.md 文件（通常是项目记忆）。

高级配置与特性 #

导入外部文档 (@ 语法) #

在 CLAUDE.md 文件中，你可以使用 @path/to/file 语法导入外部文件内容，避免内容重复。

# 项目文档
@README.md
@docs/architecture.md
@package.json
# 使用绝对路径导入用户目录下的文件
@~/.claude/my-global-instructions.md

导入特性：

• 支持相对和绝对路径。
• 支持递归导入，最大深度为 5 层。
• 首次从外部位置导入时，会触发安全审批对话框。
• 在 Markdown 代码块或行内代码中，导入指令不会被解析。

排除特定 CLAUDE.md 文件 (claudeMdExcludes) #

在大型单体仓库中，某些 CLAUDE.md 文件可能与你当前的工作无关。通过 claudeMdExcludes 设置可以排除它们，节省上下文窗口。

// ~/.claude/settings.json 或 .claude/settings.json
{
  "claudeMdExcludes": [
    "packages/legacy-app/CLAUDE.md",
    "vendors/**/CLAUDE.md"
  ]
}

模式匹配相对于项目根目录的路径。这对排除不相关子项目、第三方或过时的记忆文件非常有效。

设置文件优先级 #

包括 autoMemoryDirectory、claudeMdExcludes 在内的设置，遵循 5 级优先级：

注意 (v2.1.119+)：通过 /config 命令进行的更改现在会持久化到 ~/.claude/settings.json，并参与上述优先级链。

自动记忆与自定义目录 #

自动记忆是 Claude 在工作过程中自动记录的笔记和见解。

自动记忆架构：

graph TD
    A["Claude 会话开始"] --> B["加载 MEMORY.md<br/>(前 200 行 / 25KB)"]
    B --> C["会话进行中"]
    C --> D["Claude 发现<br/>模式与见解"]
    D --> E{"写入<br/>自动记忆"}
    E -->|通用笔记| F["MEMORY.md"]
    E -->|主题特定| G["debugging.md"]
    E -->|主题特定| H["api-conventions.md"]
    C --> I["按需加载<br/>主题文件"]
    I --> C

自定义自动记忆目录 (autoMemoryDirectory)： 默认情况下，自动记忆存储在 ~/.claude/projects/<project>/memory/。你可以通过 autoMemoryDirectory 设置（v2.1.74+）更改此位置。

// 仅可在用户级或本地设置中配置
// ~/.claude/settings.json 或 .claude/settings.local.json
{
  "autoMemoryDirectory": "/path/to/custom/memory/directory"
}

适用场景：将记忆存储在共享或同步位置，或将其与默认 Claude 配置目录分离。

路径特定规则与模块化规则系统 #

使用 .claude/rules/ 目录创建组织良好的、路径特定的规则。规则可以定义在项目级和用户级。

目录结构示例：

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── api/                  # 支持子目录
│           ├── conventions.md
│           └── validation.md

使用 YAML Frontmatter 定义路径特定规则： 通过在规则文件的开头添加 YAML 前置块，可以限制规则仅应用于特定文件路径。

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

# API 开发规则

- 所有 API 端点必须包含输入验证
- 使用 Zod 进行架构验证
- 记录所有参数和响应类型
- 为所有操作包含错误处理

paths 字段支持 glob 模式，例如 **/*.ts、src/**/* 或 {src,lib}/**/*.ts。

清理设置 (cleanupPeriodDays) #

控制磁盘上临时文件的保留时间。自 v2.1.117 起，cleanupPeriodDays 应用于以下四类缓存：

1. ~/.claude/checkpoints/（检查点）
2. ~/.claude/tasks/（任务）
3. ~/.claude/shell-snapshots/（Shell 快照）
4. ~/.claude/backups/（备份）

早于该时间窗口的文件将在启动时被清理。

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 14 // 保留 14 天内的临时文件
}

最佳实践总结 #

1. 正确选择层级：将公司安全策略放入托管策略层，团队代码风格放入项目记忆层，个人编辑器偏好放入用户记忆层。
2. 善用导入：使用 @ 语法引用现有文档（如 @README.md），而非复制粘贴，避免内容不同步。
3. 版本控制：将项目级 CLAUDE.md 和 .claude/rules/ 目录提交到 Git，让整个团队受益。
4. 保持精炼：单个记忆文件建议控制在 500 行以内。使用模块化规则目录来组织大量规则。
5. 安全第一：绝对不要在 CLAUDE.md 中存储 API 密钥、密码或其他敏感信息。

FAQ #

Q: 如果我同时设置了项目记忆和用户记忆，且内容冲突，会怎样？ A: 项目记忆（优先级 2/3）会覆盖用户记忆（优先级 4/5）中的同名指令。更高优先级层级的记忆拥有最终决定权。

Q: 自动记忆（Auto Memory）和手动编写的 CLAUDE.md 有什么区别？ A: CLAUDE.md 由你手动创建和维护，用于定义明确的规则和标准。自动记忆由 Claude 在会话中自动生成，用于记录其在工作过程中发现的模式、见解和项目特定知识，位于 ~/.claude/projects/<project>/memory/ 目录。

Q: 如何让子代理（Subagent）只使用特定的记忆范围？ A: 在子代理定义的 frontmatter 中，使用 memory 字段指定要加载的记忆范围，例如 memory: project（仅加载项目记忆）或 memory: user（仅加载用户记忆）。这允许子代理使用聚焦的上下文，而非继承完整的记忆层级。

Q: 更新 CLAUDE.md 文件后，需要重启 Claude Code 才能生效吗？ A: 不需要。使用 /memory 命令或在会话中让 Claude 以对话方式更新记忆后，Claude 会自动重新加载更新后的文件。但直接通过外部编辑器手动修改文件后，可能需要开始一个新的会话来确保完全加载。