2.Memory

简介

在ClaudeCode中，我们每开一个新会话都要重新灌输一遍上下文，一遍又一遍的重复目录职责，技术选型等。
针对这个问题，ClaudeCode提供了一个解法，自动加载的持久指令层。

把指令写进文件，让它的生命周期从"跟随会话生灭"变成"跟随项目存在"。这就是本章的主题，记忆（Memory）。

本章讲的记忆都是写成文件后由Claude Code自动注入的持久指令——多数在启动时就位，个别（带paths的规则文件、子目录CLAUDE.md）在Claude触及相关文件时注入；需要Claude在任务中主动选用的"按需能力"是另一套机制，留给下一章，这里不展开。

官方文档：https://code.claude.com/docs/en/memory

记忆的三种形态

按"谁写、什么时候加载"划分，Claude Code的记忆有三种形态：CLAUDE.md是我们写给Claude的项目手册；规则文件（Rules）也是我们写的，但可以按路径条件加载；自动记忆（Auto Memory）反过来，是Claude写给自己的笔记。

形态	谁写	位置	加载时机
CLAUDE.md	我们写给Claude	企业、用户、项目等多个层级	启动时注入；子目录的按需
规则文件	我们写给Claude	.claude/rules/*.md或~/.claude/rules/	未声明paths的启动时加载；声明了paths的在Claude读取匹配文件时加载
自动记忆	Claude写给自己	~/.claude/projects/<project>/memory/	启动时加载MEMORY.md的前200行或25KB

三者解决同一个问题的三个侧面：CLAUDE.md承载稳定的事实与约定；规则文件把只与部分代码相关的规范从常驻上下文中拆出去；自动记忆让Claude把会话中学到的经验沉淀下来，不必每次重新踩坑。下面逐一展开。

CLAUDE.md

先说位置。CLAUDE.md不止一个，Claude Code启动时会从多个层级收集：

层级	位置	作用范围	说明
企业策略	Linux/WSL为/etc/claude-code/CLAUDE.md，macOS为/Library/Application Support/ClaudeCode/CLAUDE.md，Windows为C:\Program Files\ClaudeCode\CLAUDE.md	组织内所有开发者	IT统一管理，无法被排除
用户	~/.claude/CLAUDE.md	该用户的所有项目	跨项目的个人偏好
项目	./CLAUDE.md或./.claude/CLAUDE.md	当前项目	提交进版本库，团队共享
项目本地	./CLAUDE.local.md	当前项目，仅本机	个人补充，加入.gitignore
子目录	如./src/CLAUDE.md	对应子目录	按需加载，Claude访问该目录下的文件时才注入

加载顺序有两条规则：目录树方向上，从文件系统根一路加载到当前工作目录，离工作目录越近的越靠后；同一目录内，CLAUDE.md先于CLAUDE.local.md。前四级都在启动时注入，子目录一级是例外——Claude没有实际访问该目录下的文件，它就不会被加载，这一点在"经验"一节还会再提。

再说内容。判断一条信息该不该进CLAUDE.md，标准只有一个：这是不是Claude无法自行推断、而做错了会有实际代价的事实。构建与测试命令、目录职责、接口约定、"用什么、不用什么"的技术选型，属于该写的；通用编程常识和项目背景故事属于不该写的，Claude要么本来就知道，要么不需要知道；"第一步做什么、第二步做什么"式的操作流程也不该写——那是工作流，只在特定任务时才有用，不该常驻在每一次会话里。

一份短而事实型的项目级CLAUDE.md大致长这样。

示例代码：

# 项目约定

## 常用命令

- 构建：`npm run build`，产物输出到`dist/`
- 测试：`npm test`，提交前必须全部通过
- 本地启动：`npm run dev`，监听3000端口

## 代码约定

- TypeScript严格模式，2空格缩进，Prettier统一格式化
- API统一返回`{ success, data, error }`结构

## 架构

- 架构说明见 @docs/architecture.md

每一行都在陈述事实，没有解释，没有寒暄。CLAUDE.md的每个字都会出现在每一次会话的上下文里，写它的心态应该更接近写配置文件，而不是写文档。

示例最后一行的@docs/architecture.md用到了导入语法，下一节展开。

导入语法

CLAUDE.md里可以用@路径引用其他文件，被引用文件的内容会一并加载。

示例代码：

@docs/setup.md         # 相对路径，相对于导入文件所在目录
@~/.claude/shared.md   # 绝对路径，~表示主目录
概览见 @README，环境搭建见 @docs/setup.md。
`@README`              # 反引号包裹时不导入，保留字面文本

四条规则：

• 相对路径相对于导入文件所在目录解析，也支持绝对路径与~。
• 导入可以递归，被导入的文件里还可以再写@，最大深度4跳。
• Markdown代码块与代码跨度内的@路径会被跳过，不触发导入；想在正文里字面展示一个@路径，用反引号包裹即可。
• 被导入的文件同样在启动时完整加载。

一个典型用法：团队还在用其他AI工具时，把@AGENTS.md写进CLAUDE.md，让多套工具共用同一份规则文件。

注意：导入不节省token。把一大份CLAUDE.md拆成主文件加若干@导入，得到的是组织上的清晰，不是上下文上的节省——所有被导入的内容仍会在启动时全部注入。真正减少常驻消耗的手段是下一节的规则文件。

规则文件

CLAUDE.md的内容对所有任务无差别常驻，但很多规则只与一部分代码相关：API设计规范只在改接口时有用，测试规范只在写测试时有用。让它们常驻，平时是白付的token，还稀释了真正通用的约定。

规则文件解决这个问题。在项目的.claude/rules/目录（或用户级的~/.claude/rules/）下放置多个Markdown文件，每个文件在YAML front matter的paths字段里声明自己关心的路径。

示例代码（.claude/rules/api-design.md）：

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.{ts,tsx}"
---

# API设计规范

- 校验所有输入
- 错误响应使用统一格式

paths支持常见的glob写法：**/*.ts、src/**/*、*.md、src/components/*.tsx。

触发时机是关键：声明了paths的规则文件，在Claude读取到匹配文件时才加载，而不是每次工具调用都注入；未声明paths的规则文件则在启动时加载，效果等同于拆成多个文件的CLAUDE.md。所以规则文件的价值全在paths上——它是"减少启动常驻"的正解：与其把两百行各领域规范全部塞进CLAUDE.md，不如让每份规范只在相关文件被触碰时出现。

自动记忆

前两种记忆都是我们写给Claude的。自动记忆方向相反：Claude在工作中把学到的东西写成笔记，留给未来会话中的自己。

它的位置在~/.claude/projects/<project>/memory/目录（<project>由git仓库路径派生，非git项目则按项目根目录路径派生），核心文件是MEMORY.md，此外还有Claude按主题拆分的独立文件。每次会话启动时，MEMORY.md的前200行或25KB会被自动加载。里面沉淀的往往是踩坑经验：某个脚本的隐藏前提、某份文档与实际行为的出入——这些东西我们自己都未必想得起来写进CLAUDE.md。

两点边界要清楚：

• 自动记忆是机器本地的，不跨机器、不跨云环境同步。
• 同一项目的多个worktree共享同一个memory目录。

自动记忆和CLAUDE.md的关系可以这样理解：前者是Claude的草稿本，后者是我们的定稿。自动记忆里长期有效的结论，值得经我们审核后升格写进项目CLAUDE.md——后者进版本库、随团队共享，前者只留在本机。

自动记忆默认开启，可以在/memory面板里切换，也可以用配置字段或环境变量控制，见下一节。

相关命令与配置

两条斜杠命令。

• /init
  分析当前代码库，生成一份初始CLAUDE.md；若已存在，则给出改进建议。它还能识别AGENTS.md、.cursorrules等其他工具的规则文件并合并。设置环境变量CLAUDE_CODE_NEW_INIT=1后，/init变为交互式的多阶段流程。
• /memory
  列出当前已加载的所有记忆——各级CLAUDE.md、CLAUDE.local.md、规则文件、自动记忆——可以就地选择编辑，也可以切换自动记忆的开关。发现Claude又犯了某个纠正过的错误时，用/memory把对应约定写进项目CLAUDE.md，下次会话即生效。

配置字段如下，写在settings.json中（claudeMd仅用于managed-settings.json），其层级与优先级见《1.概述》。

字段	类型	默认值	说明
autoMemoryEnabled	boolean	true	启用或禁用自动记忆
autoMemoryDirectory	string	~/.claude/projects/<project>/memory/	自定义自动记忆的存储位置
claudeMdExcludes	string[]	[]	用glob模式排除特定的记忆文件（CLAUDE.md、规则文件），模式匹配的是绝对路径，对企业策略层无效
claudeMd	string	—	在managed-settings.json中直接内嵌CLAUDE.md内容

示例代码（.claude/settings.local.json，排除遗留目录里的记忆文件）：

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

记忆相关的环境变量：

环境变量	说明
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1	禁用自动记忆
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1	加载--add-dir额外目录中的记忆文件（CLAUDE.md、.claude/CLAUDE.md、规则文件、CLAUDE.local.md）
CLAUDE_CODE_NEW_INIT=1	启用/init的交互式流程

经验

• 保持短
  超过200行的CLAUDE.md不仅消耗更多token，还可能降低遵守率——内容越多，单条指令被严格执行的概率越低。只与部分路径相关的规范，搬进带paths的规则文件。
• 矛盾会被随机化解
  多个层级的CLAUDE.md或多份规则文件给出矛盾指导时，Claude可能任选其一执行。像维护代码一样定期审核记忆：合并重复，删除过期。
• 子目录CLAUDE.md有两个易踩的点
  一是按需加载，Claude没访问过该目录的文件，它就等于不存在；二是/compact之后不会自动重新注入。跨目录都要遵守的关键约定，放在项目根的CLAUDE.md里。
• 分清建议与强制
  CLAUDE.md是注入上下文的指导，Claude大概率遵守，但不保证；settings.json里的权限与限制才是硬约束。行为习惯写CLAUDE.md，技术红线写settings；必须百分之百发生的事，交给Hook（钩子），见《5.Hooks》。
• 工作流是不该常驻的信号
  如果CLAUDE.md的某一节从"事实与约定"长成了"第一步、第二步、第三步"的工作流，说明它不该常驻——这类按需加载的指令属于Skill（技能），也就是下一章《3.Skills》要解决的问题。