Claude Code 记忆系统详解

一、核心背景：为什么需要记忆系统

Claude Code 默认每个会话是全新空白上下文，关闭终端、新建会话之后，项目规范、技术栈、踩坑经验全部丢失。团队协作场景下，对话内的约束无法共享，新人需要反复对齐项目规则。/memory整套记忆体系就是用来实现跨会话持久记忆，不用每次重新交代背景信息。

/memory是内置交互命令，执行后查看当前会话加载全部记忆文件，也可以开关自动记忆、打开记忆目录编辑。

二、两套互补记忆体系

1. CLAUDE.md：用户手动编写的指令手册

由开发者手写 Markdown 文件，会话启动自动注入系统提示词，人为定义规则、约束，支持多层级，部分层级可提交 Git 实现团队共享。

项目	CLAUDE.md	Auto Memory（自动记忆）
编写者	用户手动编写	Claude 自动记录
存储位置	全局 / 项目目录	~/.claude/projects/<项目>/memory/
Git 版本	可提交共享（CLAUDE.local.md 除外）	本地私有，不上 Git
适用内容	项目架构、编码规范、提交规范、禁止修改目录	用户偏好、调试踩坑记录、纠正的错误、项目临时发现

CLAUDE.md 多层级加载（优先级越具体越高）

1. **全局记忆 ~/.claude/CLAUDE.md**：本机全部项目通用，写回复语言、通用编码习惯。
2. **项目记忆 ./CLAUDE.md**：项目根目录，提交 Git，团队所有人共享，最常用。
3. **本地个人记忆 ./CLAUDE.local.md**：加入 gitignore，个人私有配置，不污染团队。
4. 模块化规则 .claude/rules/\*.md：拆分臃肿规则，支持 glob 路径匹配，条件按需加载，仅匹配对应文件 / 目录才启用这条规则，节省上下文。
5. 子目录 CLAUDE.md：monorepo 多包场景，进入子目录自动加载子目录的规则。

加载逻辑：启动时向上遍历目录读取；压缩上下文之后会重新从磁盘读取文件，不会丢失规则。

辅助命令

• /init：自动扫描项目，生成 CLAUDE.md 初始模板；
• #前缀：对话中快速追加记忆，选择保存到全局或项目记忆文件；
• @imports：在 md 内引入外部规则文件，拆分大文件。

2. Auto Memory：Claude 自动写的私有笔记

本地私有存储，不会提交仓库。当用户纠正错误、明确说出 “记住 / 别忘了”、多次重复模式、识别项目关键命令时，Claude 自动写入记忆文件。

文件结构：

• MEMORY.md：主索引文件，会话启动自动加载前 200 行；
• 主题拆分文件（debugging.md、patterns.md）：不会启动加载，AI 需要时按需读取，控制上下文开销。

触发关键词：中文 “记住、别忘了”，英文remember / don't forget。

三、.claude/rules 模块化规则（大型项目关键能力）

1. 将大量规范拆分为多个 md 文件，避免单份 CLAUDE.md 过于庞大。
2. 文件头部 frontmatter 写paths/globs glob 通配符，实现条件加载：例如paths: src/api/**/*.ts，只有编辑 api 目录 ts 文件，这条 API 规范才生效，其他场景不占用 token。
3. 无 paths 字段的规则，全局每次会话加载。
4. 适合 Monorepo 多子包，不同子包应用不同编码规范。

四、典型业务使用场景

1. 团队规范沉淀：把代码规范、commit 规范写进项目 CLAUDE.md 提交 Git，新人 clone 项目自动生效，替代 wiki 文档。
2. 个人偏好持久化：放在 CLAUDE.local.md 或者 Auto Memory，只作用于自己，不影响团队。
3. Monorepo 分域管理：.claude/rules + glob 匹配，前端、后端、共享工具包加载各自独立规则。
4. 科研项目（第二篇博客重点）：提供科研项目完整 CLAUDE.md 模板，记录 conda 环境、数据目录约束、实验配置、MLflow 追踪、NetCDF 数据处理约束，科研人员开箱即用。
5. 新人上手：代码拉取完成，Claude 自动读取全部项目约束，减少人工培训成本。

五、最佳实践技巧

1. 200 行法则：CLAUDE.md、MEMORY.md 建议控制 200 行以内；文件越长，模型遵守度越低；复杂内容拆分到 rules 模块化文件。
2. 命令式写规则：正例所有新文件必须使用TS strict模式；错例项目使用TypeScript。描述性语句仅作为参考，命令式才会被当做强制规则。
3. 维护 Auto Memory：定期/memory查看清理过时记录；稳定有效的自动记忆，升级迁移到 CLAUDE.md 作为团队规则。
4. 定期复审记忆文件：删除过期、互相冲突规则，防止 AI 随机执行矛盾指令。

六、两套记忆分工总结

• CLAUDE.md：人定义应当怎么做，稳定、团队共享，是项目手册；
• Auto Memory：AI 记录过去踩过什么坑，动态、个人私有，是 AI 的工作笔记。

完整工作流：/init生成初始 CLAUDE.md，日常对话持续补充规则，大型项目用.claude/rules拆分；Auto Memory 自动沉淀调试经验，定期清理旧记忆。

CLAUDE.md 模板例子

Java 项目 CLAUDE.md 模板

放在项目根目录 ./CLAUDE.md，可提交 Git，团队共享。

个人本地额外配置写 CLAUDE.local.md，加入 .gitignore。

大型多模块项目，进一步拆分到 .claude/rules/ 下按 glob 条件加载。

# CLAUDE.md - Java Project Coding Rules
## 项目基础信息
- 技术栈：Java 17+, Spring Boot 3.x, Maven / Gradle
- 构建工具：【按需填写 mvn / gradle】
- 代码规范：遵循阿里巴巴Java开发手册
- 包命名：全小写，类名大驼峰，常量全大写下划线分隔
- 项目为标准分层：controller / service / repository / entity / dto / vo / config / exception

## 编码强制约束（命令式）
1. 禁止直接在 Controller 写业务逻辑，业务必须下沉到 Service 层。
2. Controller 只做参数接收、参数校验、调用Service、组装返回结果。
3. 数据库实体 Entity 只映射表结构，不要放业务逻辑；入参出参使用 DTO / VO，禁止直接返回 Entity 给前端。
4. 使用构造器注入 Spring Bean，禁止字段 @Autowired 注入。
5. 捕获异常必须处理日志 log.error，禁止空 catch{} 吞掉异常；不要使用 e.printStackTrace()。
6. 所有对外接口返回统一包装结果对象 Result<T>，不要直接返回原始数据。
7. 日期时间统一使用 java.time 包（LocalDateTime、LocalDate），禁止使用 Date。
8. SQL 写在 Mapper XML / MyBatis‑Plus，禁止在Java代码拼接SQL字符串，防止SQL注入。
9. 重写 equals / hashCode 必须成对实现。
10. 集合返回时，不要返回 null；优先返回空集合 Collections.emptyList()。

## 接口与参数校验
1. 接口入参使用 JSR‑380 校验注解 @NotNull / @NotBlank / @Size，不要手写大量if判空。
2. 全局异常处理器 @RestControllerAdvice 统一拦截业务异常、参数校验异常，不要每个Controller单独try‑catch。
3. 接口URL使用小写连字符，例如 /user/list，禁止驼峰URL；HTTP方法严格区分 GET 查询、POST新增、PUT更新、DELETE删除。

## 数据库
1. 禁止物理删除，使用逻辑删除字段 is_deleted。
2. 分页查询强制使用分页对象 Page，不要查询全表数据。
3. 更新操作优先使用 LambdaUpdateWrapper，尽量避免硬编码字段名字符串。

## 日志规范
1. 使用 slf4j + logback，不要直接使用 System.out / System.err 打印。
2. 关键业务节点打印 info；异常打印 error；调试临时日志开发完成后删除，禁止提交调试日志到仓库。

## 代码修改与重构规则
1. 修改已有代码前，先阅读相关类与调用关系，确认改动影响范围。
2. 修改前优先编写单元测试，改动后保证单元测试可运行。
3. 新增方法/类必须考虑空值、边界、异常场景。
4. 不要随意改动已有数据库实体字段；字段变更要评估数据库迁移。

## AI 行为约束
1. 生成代码尽量贴合项目现有代码风格，不要随意引入第三方依赖，新增依赖前告知用户确认。
2. 输出代码优先完整可编译片段，不要只输出片段伪代码。
3. 当你给出修改方案，同时简要说明改动点与潜在风险。
4. 如果需求存在歧义，先向我确认，不要自行做假设实现。

## 常用项目命令
# 根据你的项目实际修改
- 编译：mvn clean compile
- 单元测试：mvn test
- 打包：mvn clean package -DskipTests

补充：CLAUDE.local.md（个人本地，不要提交 git）示例

# CLAUDE.local.md 个人本地记忆，加入 .gitignore
## 个人偏好
输出代码注释使用中文
优先给出改动前后对比diff
解释尽量简洁，不要过度啰嗦

打赏