记忆系统（Memory System）
概述
Claude Code 有两套互补的记忆系统：CLAUDE.md（你写的指令）和自动记忆（Claude 自己学到的模式）。两者在每次会话启动时加载。
双记忆系统对比
| CLAUDE.md | 自动记忆（Auto Memory） | |
|---|---|---|
| 谁写 | 你 | Claude |
| 内容 | 指令和规则 | 学到的模式和偏好 |
| 范围 | 项目、用户或组织 | 按工作树 |
| 加载 | 每次会话 | 每次会话（前 200 行） |
| 用途 | 标准、工作流、架构 | 构建命令、调试经验、偏好 |
CLAUDE.md 位置与范围
| 范围 | 位置 | 共享范围 |
|---|---|---|
| 托管策略 | /Library/Application Support/ClaudeCode/CLAUDE.md（macOS） |
组织内所有用户 |
| 项目级 | ./CLAUDE.md 或 ./.claude/CLAUDE.md |
团队（通过版本控制） |
| 用户级 | ~/.claude/CLAUDE.md |
仅你自己（所有项目） |
@导入语法
在 CLAUDE.md 中引用其他文件：
参见 @README.md 了解项目概览，@package.json 查看可用命令。
- Git 工作流：@docs/git-instructions.md
- 个人覆盖：@~/.claude/my-project-instructions.md
- 相对路径基于包含文件的目录解析
- 最大深度：5 层跳转
.claude/rules/ 目录
将指令组织为按主题分类的文件。支持路径限定规则：
---
paths:
- "src/api/**/*.ts"
---
# API 开发规则
- 所有端点必须包含输入验证
- 使用 Zod schema 进行请求体校验
- 错误响应必须遵循统一格式
支持的模式：
- Glob 模式：
src/**/*.ts - 花括号展开：
*.{ts,tsx} - 符号链接：跨项目共享规则
自动记忆
工作机制
- 默认启用（通过
/memory或autoMemoryEnabled设置切换） - 存储位置：
~/.claude/projects/<project>/memory/ - 同一仓库的所有工作树共享同一目录
MEMORY.md作为索引，前 200 行在会话启动时加载- 主题文件按需加载
- 可通过
autoMemoryDirectory设置自定义位置 - 通过
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1禁用
记忆类型
Claude 自动保存以下类型的记忆：
| 类型 | 说明 |
|---|---|
user |
用户角色、偏好、技能水平 |
feedback |
用户对 Claude 行为的纠正和反馈 |
project |
项目的目标、决策、时间线 |
reference |
外部系统的信息指针（Jira、Slack 等） |
CLAUDE.md 最佳实践
应该包含的内容
| 包含 | 原因 |
|---|---|
| Claude 猜不到的 Bash 命令 | 项目特有的构建/测试命令 |
| 偏离默认的代码风格规则 | 团队约定 |
| 测试指令 | 如何运行、如何验证 |
| 仓库礼仪 | 分支策略、提交规范 |
| 架构决策 | 关键设计选择的背景 |
| 环境特殊情况 | 平台/依赖的注意事项 |
| 常见陷阱 | 避免踩坑 |
不应该包含的内容
| 排除 | 原因 |
|---|---|
| Claude 可以从代码推断的信息 | 冗余，浪费上下文 |
| 标准语言惯例 | Claude 已经知道 |
| 详细 API 文档 | 太长，用链接代替 |
| 频繁变化的信息 | 容易过时 |
| 冗长解释 | 保持精简 |
| 逐文件描述 | Claude 可以自己读 |
| 不言自明的实践 | 没有信息增量 |
核心原则
- 目标 200 行以内：精简胜于冗长
- 用
/init生成起始模板：避免从零开始 - CLAUDE.md 在
/compact后完整保留：从磁盘重新读取 - 脚本中用
--append-system-prompt：添加系统提示级指令 - 用
InstructionsLoadedHook 调试：确认哪些文件被加载
claudeMdExcludes 设置
在大型 Monorepo 中跳过特定 CLAUDE.md：
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}
子代理记忆
子代理也可以拥有持久记忆：
memory: project # 或 user、local
存储位置：
user→~/.claude/agent-memory/<name>/project→.claude/agent-memory/<name>/local→.claude/agent-memory-local/<name>/
启用后子代理自动获得 Read/Write/Edit 工具访问权限。