Claude Code 的记忆系统

引言

每个 Claude Code 会话都从一个全新的上下文窗口开始，上一次会话中交代的项目背景、编码规范和调试经验在新会话中不复存在。为了对抗这种上下文无状态性，Claude Code 设计了一套多层级的记忆系统，使其能够跨会话保留项目知识。本文将对这套记忆系统进行学习及探讨

记忆系统总览

Claude Code 的记忆由两个互补机制组成，两者都在每次对话开始时加载

维度	CLAUDE.md 文件	自动记忆（Auto Memory）
谁来编写	用户	Claude
包含内容	指令和规则	学习到的模式和见解
作用范围	项目、用户或组织	每个工作树（worktree）
加载方式	每次会话完整加载	每次会话加载前 200 行
典型内容	编码标准、工作流、项目架构	构建命令、调试经验、偏好发现

简单来说：CLAUDE.md 是用户给 Claude 的指令，MEMORY.md 是 Claude 给自己的笔记本

除此之外，Claude Code 还拥有上下文压缩机制来管理单次会话内的记忆，以及 Auto Dream 机制来对跨会话的记忆进行整合与清洗。下面逐一展开

CLAUDE.md 文件

CLAUDE.md 是纯 Markdown 文件，用于为 Claude 提供持久指令。Claude 在每个会话开始时读取这些文件，将其作为上下文注入

层级体系

CLAUDE.md 并不是一个单一文件，而是一个层级化的指令体系，更具体的位置优先于更广泛的位置

层级	位置	目的	共享范围
托管策略	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` Linux: `/etc/claude-code/CLAUDE.md`	组织范围的强制指令（IT/DevOps 管理）	组织中所有用户
项目指令	`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	团队共享的项目规范	通过版本控制共享
用户指令	`~/.claude/CLAUDE.md`	个人偏好，跨项目生效	仅自己

加载机制：

Claude Code 从当前工作目录向上遍历目录树，检查沿途每个目录中的 CLAUDE.md，在启动时完整加载
子目录中的 CLAUDE.md 则在 Claude 读取该目录下的文件时按需加载，而非启动时全部载入
可以运行 /init 让 Claude 分析代码库并自动生成起始 CLAUDE.md，如果文件已存在，/init 会建议改进而不是覆盖

编写有效指令

CLAUDE.md 的内容在会话开始时注入上下文窗口，与对话一起消耗 Token。因为它是上下文而非强制配置，指令的编写方式直接影响 Claude 的遵守度

大小：每个文件控制在 200 行以内，较长的文件消耗更多上下文并降低遵守度。如果指令变得很大，用导入或 .claude/rules/ 进行分割
结构：使用 Markdown 标题和项目符号分组相关指令，有组织的部分比密集段落更容易遵循
具体性：写到可验证的程度

- "格式化代码要规范"
+ "使用 2 空格缩进，行宽限制 100 字符"

- "测试你的更改"
+ "提交前运行 npm test，确保覆盖率不低于 80%"

一致性：如果两条规则相互矛盾，Claude 可能会任意选择一条。定期审查跨文件的指令一致性

导入机制

CLAUDE.md 支持通过 @path/to/file 语法导入外部文件，导入内容在启动时展开并加载到上下文。相对路径相对于包含导入的文件解析，支持递归导入（最大深度 5 层）

有关项目概述，请参阅 @README.md
有关可用的 npm 命令，请参阅 @package.json

# 个人偏好
- @~/.claude/my-project-instructions.md

首次遇到外部导入时 Claude Code 会弹出批准对话框，拒绝后导入保持禁用状态，对话框不会再出现

.claude/rules/ 模块化规则

对于大型项目，将所有指令堆进一个 CLAUDE.md 不太现实。.claude/rules/ 目录允许将规则按主题拆分为独立的 Markdown 文件，所有 .md 文件都被递归发现

your-project/
├── .claude/
│   ├── CLAUDE.md              # 主指令（核心规范）
│   └── rules/
│       ├── code-style.md      # 代码风格
│       ├── testing.md         # 测试约定
│       ├── security.md        # 安全要求
│       └── api/
│           └── api-design.md  # API 设计规范

规则文件支持通过 YAML frontmatter 实现路径级条件加载——只有当 Claude 处理匹配文件时，相应规则才会注入上下文：

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

# API 开发规则

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

没有 paths 字段的规则无条件加载。路径支持 glob 模式：

模式	匹配
`*/.ts`	任何目录中的所有 TypeScript 文件
`src/*/`	`src/` 目录下的所有文件
`*.md`	项目根目录中的 Markdown 文件
`src/components/*.tsx`	特定目录中的 React 组件

多个模式可以用大括号扩展：src/**/*.{ts,tsx}

此外，.claude/rules/ 目录支持符号链接，可以维护一组共享规则并链接到多个项目中：

1 2	ln -s ~/shared-claude-rules .claude/rules/shared ln -s ~/company-standards/security.md .claude/rules/security.md

用户级规则：~/.claude/rules/ 中的个人规则适用于机器上的每个项目，用户级规则在项目规则之前加载，项目规则优先级更高

排除特定 CLAUDE.md

在大型 monorepo 中，祖先 CLAUDE.md 文件可能包含与当前工作无关的指令。claudeMdExcludes 设置可以按路径或 glob 模式跳过特定文件，将其添加到 .claude/settings.local.json 中：

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

托管策略 CLAUDE.md 文件不能被排除，确保组织范围指令始终生效

自动记忆（Auto Memory）

工作机制

自动记忆让 Claude 跨会话积累知识（需要 Claude Code v2.1.59+，默认开启）。与 CLAUDE.md 的”被动接收指令”不同，自动记忆是 Claude 主动学习的产物

Claude 在工作过程中为自己保存笔记：构建命令、调试见解、架构笔记、代码样式偏好和工作流习惯
Claude 不会每次会话都写记忆，它根据信息在未来对话中是否有用来决定什么值得记住
当在界面中看到 “Writing memory” 或 “Recalled memory” 时，Claude 正在主动更新或读取记忆文件

存储结构

每个项目拥有独立的记忆目录，路径基于 Git 仓库推导，同一仓库中的所有 worktree 和子目录共享一个记忆目录

~/.claude/projects/<project-path>/memory/
├── MEMORY.md            # 简洁索引，每次会话加载前 200 行
├── debugging.md         # 调试模式笔记
├── api-conventions.md   # API 设计决策
└── ...                  # 其他 Claude 创建的主题文件

关键约束：

MEMORY.md 的前 200 行在每次会话开始时自动加载，超出 200 行的部分不会在启动时加载
此 200 行限制仅适用于 MEMORY.md，CLAUDE.md 文件无论长度如何都完整加载
Claude 通过将详细内容拆分到独立的主题文件（如 debugging.md、patterns.md）来维持 MEMORY.md 的精简，主题文件在需要时按需读取
自动记忆是机器本地的，不会跨机器或云环境同步

可以通过设置 autoMemoryDirectory 自定义存储位置：

1
2
3

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

启用与禁用

开关控制：在会话中运行 /memory 使用自动记忆切换，或在项目设置中设置 autoMemoryEnabled: false
环境变量：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 适用于 CI/CD 等自动化场景

上下文压缩

即使有了跨会话的持久化记忆，单次会话内的上下文窗口也是有限的。Claude Code 采用三层压缩策略来管理会话内的记忆

微压缩（Micro-compact）

每轮对话自动执行，将 3 轮以上的旧工具调用结果替换为占位符：

1 2	[Previous: used Read tool on src/index.ts] [Previous: used Bash tool]

保留最近的工具结果以维持上下文连贯性，同时大幅减少历史 Token 占用

自动压缩（Auto-compact）

当 Token 估算超过阈值时自动触发：

将完整对话历史保存到 .transcripts/ 目录（无信息丢失）
由 LLM 生成当前对话的结构化摘要
用摘要替换所有历史消息，释放上下文空间

手动压缩

通过 /compact 命令手动触发相同的摘要机制

需要注意：CLAUDE.md 内容在压缩后会完整存活，Claude 会从磁盘重新读取并注入到压缩后的会话中。但仅在对话中口头给出的指令（未写入 CLAUDE.md 的）则会在压缩中丢失

这套三层压缩策略使得 Claude Code 理论上可以支持无限长度的会话

Auto Dream：记忆的整合与清洗

Auto Dream 负责对自动记忆进行周期性的整合与维护，工作包括：

合并新信息：将新会话中产生的记忆条目融入已有的主题文件
时间锚定：将相对时间转换为绝对时间（如 “昨天决定用 Redis” → “2026-03-24 决定用 Redis”）
清除过时条目：删除与已删文件相关的调试笔记等过期内容
去除矛盾：当新发现与旧记忆冲突时，更新为最新的事实
合并重复：将多个会话中产生的重叠条目合并为一条

Auto Dream 的触发有双重门控：必须经历足够多的会话 且 跨越足够长的时间。单次超长会话不会触发（会话数不足），短时间内的大量短会话也不会触发（时间跨度不足）

使用 /memory 查看和编辑

/memory 命令列出当前会话中加载的所有 CLAUDE.md 和规则文件，同时提供以下功能：

切换自动记忆的开关
打开自动记忆文件夹的链接
选择任何文件在编辑器中打开

当要求 Claude 记住某些内容时（如 “总是使用 pnpm 而不是 npm”），Claude 会将其保存到自动记忆。如果想添加指令到 CLAUDE.md，需要直接说明（如 “将其添加到 CLAUDE.md”），或通过 /memory 自己编辑文件

故障排除

Claude 不遵循 CLAUDE.md

CLAUDE.md 内容作为用户消息传递，而不是系统提示本身的一部分，没有严格遵守的保证

运行 /memory 验证 CLAUDE.md 文件是否被加载，如果文件未列出说明 Claude 看不到它
检查文件是否在正确的加载位置
使指令更具体，”使用 2 空格缩进”比”格式化代码要规范”效果更好
查找跨 CLAUDE.md 文件的冲突指令

/compact 后指令丢失

CLAUDE.md 在压缩后完全存活。如果指令在压缩后消失，说明它仅在对话中口头给出，未写入 CLAUDE.md。将其添加到 CLAUDE.md 即可使其持久化

CLAUDE.md 太大

超过 200 行的文件消耗更多上下文并可能降低遵守度。将详细内容移到用 @path 导入的单独文件中，或拆分到 .claude/rules/ 文件中

Claude Code 的记忆系统

Claude Code 的记忆系统

引言

记忆系统总览

CLAUDE.md 文件

层级体系

编写有效指令

导入机制

.claude/rules/ 模块化规则

排除特定 CLAUDE.md

自动记忆（Auto Memory）

工作机制

存储结构

启用与禁用

上下文压缩

微压缩（Micro-compact）

自动压缩（Auto-compact）

手动压缩

Auto Dream：记忆的整合与清洗

使用 /memory 查看和编辑

故障排除

Claude 不遵循 CLAUDE.md

/compact 后指令丢失

CLAUDE.md 太大

参考文献

FEATURED TAGS