Claude Code 学习站
v2.1.207

Claude Code 跨会话记忆：CLAUDE.md 与自动记忆完全指南

介绍 Claude Code 两大记忆机制——CLAUDE.md 持久指令文件与 Auto memory 自动笔记——帮助开发者让 Claude 跨会话保持上下文。

本页目录13
AI 摘要 · 已核查整理于 2026-06-19原文:How Claude remembers your project(Anthropic)工作流配置
要点速览
  • Claude Code 有两套记忆机制:你手写的 CLAUDE.md 指令文件,以及 Claude 自动积累的 Auto memory 笔记
  • CLAUDE.md 支持四个作用域:组织级托管策略、用户全局、项目共享、本地私有,按从宽到窄顺序叠加加载
  • 指令文件建议控制在 200 行以内,写具体可验证的规则而非模糊描述,过长会稀释 Claude 的遵从率
  • `.claude/rules/` 目录支持按文件路径(glob)条件加载规则,适合大型项目分模块管理
  • Auto memory 默认开启,存储于 `~/.claude/projects/<project>/memory/`,同一 git 仓库的所有 worktree 共享一份
  • 用 `/memory` 命令可浏览、编辑或删除所有已加载的指令文件和自动记忆文件

本文是对 Claude Code 官方文档「How Claude remembers your project」的中文要点摘要,完整内容以原文为准:https://code.claude.com/docs/en/memory

两种记忆机制对比

Claude Code 每次会话都从空白上下文启动。为了让知识跨会话保留,官方提供两套互补机制:

CLAUDE.md 文件Auto memory
由谁写开发者手写Claude 自动写
内容指令与规则学习到的模式与偏好
作用域项目/用户/组织级按 git 仓库,所有 worktree 共享
加载时机每次会话启动时每次会话启动时(前 200 行或 25KB)
适用场景编码规范、架构决策、工作流构建命令、调试经验、Claude 发现的偏好

两套机制都只是注入到上下文窗口,Claude 会尽力遵守但无法强制执行。如果想无论 Claude 如何决策都强制拦截某个操作,应使用 PreToolUse hook。

CLAUDE.md 文件

作用域与存放位置

按加载顺序从宽到窄:

  1. 组织托管级(IT 部署,不可被个人排除)
    • macOS:/Library/Application Support/ClaudeCode/CLAUDE.md
    • Linux/WSL:/etc/claude-code/CLAUDE.md
  2. 用户全局:~/.claude/CLAUDE.md,影响你的所有项目
  3. 项目共享:./CLAUDE.md 或 ./.claude/CLAUDE.md,随代码库提交,团队共享
  4. 本地私有:./CLAUDE.local.md,加入 .gitignore,仅你本机可见

同一目录下,CLAUDE.local.md 会附加在 CLAUDE.md 之后加载;子目录的 CLAUDE.md 在 Claude 读取该目录文件时按需加载,而非启动时全量加载。

快速生成:/init

在项目根目录执行 /init,Claude 会分析代码库并自动生成包含构建命令、测试方式、项目约定的初始 CLAUDE.md。设置环境变量 CLAUDE_CODE_NEW_INIT=1 可开启交互式多阶段引导流程。

编写高效指令的原则

  • 篇幅:单个文件建议控制在 200 行以内,过长会消耗更多 context 并降低遵从率
  • 结构:使用 Markdown 标题和列表,清晰分组
  • 具体可验证:
    • ✅ 使用 2 空格缩进 ❌ 好好格式化代码
    • ✅ 提交前运行 npm test ❌ 测试你的改动
    • ✅ API handler 放在 src/api/handlers/ ❌ 保持文件整洁
  • 一致性:定期检查多个 CLAUDE.md 之间有无冲突规则

@path 导入语法

可以用 @路径 语法将其他文件引入 CLAUDE.md:

参考 @README 获取项目概述,@package.json 查看 npm 命令。

# 附加指令
- git 工作流 @docs/git-instructions.md

注意:被导入的文件在启动时同样全量加载进 context,导入只是组织形式,不能节省 token。

如果仓库已有 AGENTS.md 供其他 AI 工具使用,可在 CLAUDE.md 中用 @AGENTS.md 引入,避免重复维护两份文件。

.claude/rules/ 路径规则

对于大型项目,可将指令按主题拆分到 .claude/rules/ 目录下的多个 .md 文件,还支持通过 YAML frontmatter 指定只在特定文件类型或目录下激活:

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

# API 开发规范
- 所有接口必须做输入校验
- 使用统一的错误响应格式

不带 paths 字段的规则文件在每次会话启动时全量加载;带路径约束的规则仅在 Claude 读取匹配文件时才注入 context,可有效节省 context 空间。

个人全局规则放在 ~/.claude/rules/,优先级低于项目级规则。

Auto memory 自动记忆

工作原理

Auto memory 默认开启(需 Claude Code v2.1.59+)。Claude 会在会话中自主判断哪些信息值得记录,例如构建命令、调试经验、代码风格偏好等,并写入本地文件——它不会每次会话都写,只在信息有长期价值时才记录。

存储位置

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 索引文件,每次会话加载前 200 行或 25KB
├── debugging.md       # 调试模式详细笔记
├── api-conventions.md # API 设计决策
└── ...                # 其他 Claude 创建的主题文件
  • <project> 路径由 git 仓库根目录推导,同一仓库所有 worktree 共享同一目录
  • 可通过 autoMemoryDirectory 设置自定义存储路径
  • 自动记忆仅本机存储,不会跨机器同步

开关控制

{ "autoMemoryEnabled": false }

或设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 来关闭。

/memory 命令

在会话中执行 /memory 可以:

  • 查看当前会话已加载的所有 CLAUDE.md、CLAUDE.local.md 和 rules 文件
  • 切换 Auto memory 开关
  • 打开 auto memory 文件夹进行浏览和编辑

直接对 Claude 说「记住始终用 pnpm 而不是 npm」,Claude 会将其保存到 auto memory;如果想写入 CLAUDE.md,则明确说「把这条加到 CLAUDE.md」。

常见问题排查

问题排查思路
Claude 不遵守 CLAUDE.md 指令运行 /memory 确认文件已加载;检查指令是否足够具体;排查多文件指令冲突
不知道 auto memory 保存了什么运行 /memory → 打开 auto memory 文件夹,内容是纯 Markdown 可直接编辑
CLAUDE.md 太大使用路径规则按需加载,或剪除非每次都需要的内容
/compact 后指令消失项目根目录的 CLAUDE.md 会在 compact 后重新注入;子目录 CLAUDE.md 在下次读取该目录文件时才重载

如需在特定生命周期节点强制执行操作(如每次提交前),应使用 hook 而非 CLAUDE.md 指令。hook 以 shell 命令执行,在固定生命周期事件触发,不依赖 Claude 的判断。

查看官方原文:How Claude remembers your project← 返回 Blog