用了一周 Claude Code 自动记忆，终于不用每次重复交代了

之前用 Claude Code 写代码有个习惯：每次开新会话，先花两分钟把项目背景交代一遍。用 pnpm 不用 npm，测试跑 vitest，API 路由放 src/api/ 下面。每次都说，每次都烦。

Anthropic 加了个自动记忆功能，Claude 会自己记笔记。

两套记忆系统

先说个容易混的事。

CLAUDE.md 是你写给 Claude 看的指令文件。项目规范、构建命令、编码约定，你手动维护，Claude 每次启动读一遍。这个之前就有。

新加的是 MEMORY.md。这个文件 Claude 自己写自己维护。它在干活的过程中，觉得某条信息下次还能用上，就自己记下来。

打个比方，CLAUDE.md 是你给新同事写的入职文档，MEMORY.md 是这个同事自己的工作笔记。

它会记什么

不是所有东西都记。我观察了一下，它倾向于记这些：

你纠正过它的地方（比如"别用 var，用 const"）
项目的构建和测试命令
调试时踩过的坑
你明确让它记住的东西

最后一个挺方便。直接说"记住我们用 pnpm"，它就写进去了。比自己去编辑配置文件省事。

但它不是每次会话都写。有几次我纠正了比较细的东西，下次会话发现它没记。这个判断逻辑不完全透明。

存储细节

记忆文件在本地：~/.claude/projects/<项目名>/memory/。

~/.claude/projects/<项目名>/memory/ ├── MEMORY.md # 索引，启动时加载前 200 行 ├── debugging.md # 按主题拆分的笔记 ├── api-conventions.md └── ...

MEMORY.md 是入口，会话启动时只读前 200 行。多出来的内容 Claude 会拆到独立的主题文件里，用到时再去读。

同一个 git 仓库的所有 worktree 共享一份记忆。跨机器不共享，纯本地。

顺便说说 CLAUDE.md 的组织

很多人只在项目根目录放一个 CLAUDE.md，其实它支持好几个位置：

./CLAUDE.md — 项目级，团队共享，进版本控制
~/.claude/CLAUDE.md — 个人级，所有项目通用
./CLAUDE.local.md — 项目内的个人偏好，不进 git
系统目录（Windows 上 C:\Program Files\ClaudeCode\CLAUDE.md） — 组织级，IT 统一部署

写指令有个原则：越具体越好。"缩进用 2 个空格"比"代码格式要好"管用。文件别超过 200 行，太长了遵守率会下降。另外注意别在不同文件里写矛盾的指令，Claude 遇到冲突会随机选一个。

按文件类型加载规则

项目大了以后，.claude/rules/ 目录可以按文件类型分别加载规则。

比如只在编辑 TypeScript API 文件时生效的规则：

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

# API 开发规则

- 所有端点必须做输入校验
- 使用统一的错误响应格式

有 paths 的规则只在 Claude 读到匹配文件时才加载，没有的全局生效。

引用外部文件

CLAUDE.md 里可以用 @ 语法引用别的文件：

项目概述见 @README，npm 命令见 @package.json。

# 额外说明

- git 工作流 @docs/git-instructions.md

路径相对于当前文件解析，最多递归 5 层。

跨 worktree 的话，可以引用 home 目录下的文件让所有 worktree 共享配置：

- @~/.claude/my-project-instructions.md

日常操作

会话里输入 /memory 可以开关自动记忆、查看已加载的文件、直接打开编辑。记忆文件就是普通 markdown，想改就改，想删就删。

想让 Claude 记住什么，直接用自然语言说就行。"记住 API 测试需要本地 Redis"，它自己写进去。

踩过的坑

Claude 有时候不按 CLAUDE.md 办事。这个文件是上下文，不是强制配置。先用 /memory 确认文件确实加载了，再检查有没有互相矛盾的指令。

用 /compact 压缩上下文后，如果发现某条指令消失了，多半是因为它只在对话里提过，没写进 CLAUDE.md。压缩后 CLAUDE.md 会从磁盘重新读取，不会丢。

在大型 monorepo 里，可能会加载到别的团队的 CLAUDE.md。用 claudeMdExcludes 排除：

{
    "claudeMdExcludes": ["**/other-team/CLAUDE.md"]
}

用了一周之后

我最直观的感受是，第三四天开始，开会话时的重复交代明显少了。Claude 记住了项目的构建命令和我的一些偏好，不用每次从头说。

但也不是万能的。它记的是碎片化的经验，不是对项目的整体理解。有时候它记住了某个 API 的调用方式，但对整个模块的设计思路还是一无所知。

另外我发现记忆文件偶尔需要手动清理。Claude 记了一些过时的信息（重构前的文件路径之类的），反而会误导后续会话。定期用 /memory 看一眼，删掉不对的条目，是个好习惯。