🧠 Claude Code 记忆系统

深度解析六层记忆架构与持久化上下文机制

为什么需要记忆系统？

Claude Code 每次启动都会开启一个全新的上下文窗口，之前会话中积累的项目知识、编码偏好、调试经验会随之消失。记忆系统正是为了让 AI 能够在跨会话记住项目规范和个人偏好。

📁

CLAUDE.md 手动记忆

在项目根目录创建 CLAUDE.md 文件，定义项目上下文、编码规范、技术栈等，Claude 每次会话都会读取。

⚡

Auto Memory 自动记忆

Claude 会自动学习项目中的重要决策和模式，积累到 ~/.claude/projects/ 目录，无需手动维护。

📦

.claude/rules 模块化规则

将不同类型的规则拆分为独立文件，如 coding-standards.md、api-design.md，便于维护和复用。

🌲

递归加载机制

从当前目录向上递归到根目录，读取所有 CLAUDE.md 文件并叠加生效，覆盖粒度可精细到每个子目录。

六层记忆架构

Claude Code 采用类似操作系统的分层记忆模型，从全局到项目逐层覆盖：

1 优先级最高

系统提示 System Prompt

Anthropic 内置基础行为定义

Claude Code 的核心能力边界和安全规则，由 Anthropic 官方定义，不可修改。

2 用户级

全局 CLAUDE.md

~/.claude/CLAUDE.md

适用于所有项目的通用规则，如编码风格、Git 提交规范、测试要求等。

3 项目级

项目 CLAUDE.md

/project/CLAUDE.md

项目特有的上下文，包括项目概述、技术栈、目录结构、特定业务规则等。

4 会话级

Auto Memory 自动记忆

~/.claude/projects/{project-id}/auto-memory.md

Claude 自动学习的重要决策：为什么选择某技术方案、已知问题、绕过方法等。

5 模块级

.claude/rules 规则集

/project/.claude/rules/*.md

模块化的规则文件，可按功能分类，如 api-guidelines.md、security.md、testing.md。

6 会话级

对话历史 Context

当前会话的对话上下文

当前会话中的用户指令、Claude 的思考和回复，是实时信息的主要来源。

加载流程

Claude Code 启动时的完整加载顺序：

Step 1
系统提示
Anthropic 内置
→
Step 2
CLAUDE.md
递归向上加载
→
Step 3
Auto Memory
~/.claude/projects/
→
Step 4
Rules
.claude/rules/
→
Step 5
对话历史
Context 窗口

关键特性：

文件结构

Claude Code 在项目中的典型文件结构：

📁 ~ 用户主目录
📁 .claude
📄 CLAUDE.md 全局记忆（所有项目共享）
📁 projects
📁 {project-id} 项目级自动记忆
📄 auto-memory.md Claude 自动学习的知识

📁 /project 具体项目目录
📄 CLAUDE.md 项目记忆（项目特有）
📁 .claude
📁 rules 模块化规则
📄 coding-standards.md
📄 api-guidelines.md
📄 security.md
📄 testing.md

CLAUDE.md 最佳实践

推荐章节结构

章节 说明 优先级
Project Overview 项目定位、核心用户、优先级 高
Coding Conventions 可执行的编码规范（函数行数限制、命名规则等） 高
Tech Stack 技术栈版本、包管理器、禁止使用的库 中
Architecture 目录结构、模块划分、组件层级 中
Commands 常用命令脚本（dev、build、test 等） 中
Safety Rules 禁止操作（不修改 schema、不重命名 API 等） 低

规则质量对比

✅ 可执行规则
函数不超过 50 行
每个文件只导出一个组件
条件分支使用早期返回
禁止使用 var
测试覆盖率不低于 80%
❌ 模糊原则
写干净、可维护的代码
遵循最佳实践
性能优先
保持代码优雅
注意代码质量

文件大小参考

大小 效果 建议
< 1KB 太简略，遗漏关键信息 补充核心内容
1~5KB 理想范围 保持
5~10KB 良好，部分规则可能被稀释 检查冗余
> 10KB Claude 可能忽略部分规则 精简到前 80%

与其他工具对比

工具 配置文件 定位 持久化方式
Claude Code CLAUDE.md 项目级上下文提示 手动 + 自动
Cursor .cursorrules 项目级规则 手动
GitHub Copilot 无标准文件 代码分析 无
Cline/Roo Code CLINE.md / .clinerules 类似 CLAUDE.md 手动

核心要点总结

🎯

清晰优于全面

300~800 字最佳区间。太短不够用，太长 Claude 的关注力会被稀释。

⚙️

规则要可执行

具体规则而非抽象原则。明确"怎么做"而非"追求什么"。

🚫

禁止比允许更重要

明确说什么不要做，比列举允许的行为更有效。

🔄

保持更新

随项目演进持续完善。Claude 重复犯错就添加规则，规则失效就删除。

# CLAUDE.md 模板示例

## Project Overview
这是一个[项目类型]，服务于[目标用户]。
核心功能是[核心价值]，优先保证[优先级]。

## Tech Stack
- [主要语言/框架]
- [数据库]
- [包管理器]
禁止引入：
- [禁止使用的技术]

## Coding Conventions
- 函数不超过 50 行
- 每个文件只导出一个组件
- 条件分支使用早期返回

## Commands
- 开发：npm run dev
- 构建：npm run build
- 测试：npm test

## Safety Rules
除非明确要求，否则不要：
- 修改数据库 schema
- 重构超过 3 个文件
- 引入新的依赖