Claude Code 记忆结构图

⚡ Claude Code 进程启动 claude 命令执行

每次运行 claude 命令，都会开启一个全新的上下文窗口（200K tokens）。记忆系统会在启动阶段自动收集所有相关 md 文件，注入到这个上下文里。

全新上下文 200K tokens

🔒 ① 系统提示 System Prompt Anthropic 服务端

由 Anthropic 在服务端注入，用户无法看到或修改。定义了 Claude 的基础行为、安全规则、工具使用方式等。占用约 ~20,000 tokens。

不可修改 ~20K tokens

📂 ② 记忆文件层（核心）文件系统扫描

Claude Code 按固定规则扫描文件系统，自动收集多个 md 文件，合并注入上下文。这才是"记忆系统"的核心机制——文件即记忆。

可配置多文件合并

🌍 全局 CLAUDE.md ~/.claude/CLAUDE.md

适用范围：你的所有项目。存放个人偏好、跨项目通用规范。

~/.claude/CLAUDE.md

## 我的全局偏好
- 包管理器统一使用 pnpm
- TypeScript strict mode 强制开启
- 提交前必须运行 lint + typecheck
- 回复使用中文

## 全局禁止
- 禁止使用 var
- 禁止内联 CSS

个人专属跨项目生效 git不同步

📁 项目 CLAUDE.md（递归向上搜索） ./CLAUDE.md 或 ./.claude/CLAUDE.md

关键机制：从当前工作目录出发，一路向上查找所有 CLAUDE.md，全部合并加载（不覆盖，而是叠加）。

子目录的 CLAUDE.md 是按需加载的——只有当 Claude 读取该子目录的文件时，才会加载它对应的 CLAUDE.md。

搜索路径示例：当前目录在 ~/projects/app/src

# Claude 会依次搜索并全部加载：
~/projects/app/src/CLAUDE.md   ← 子目录规则（按需）
~/projects/app/CLAUDE.md       ← 项目级规则 ✓ 加载
~/projects/CLAUDE.md           ← 父目录规则 ✓ 加载
~/.claude/CLAUDE.md            ← 全局规则 ✓ 加载
# 越靠近工作目录，权重越高

递归向上多层叠加团队共享

            🏠
            根目录 CLAUDE.md
            ~/project/CLAUDE.md
          

            团队共享的项目规范：架构约定、技术栈、命令脚本、安全规则等。通常提交到 git，团队所有人共享。
            ~/project/CLAUDE.md
## Project Overview
电商平台后端服务，Node.js + PostgreSQL。
优先保证：稳定性 > 性能 > 新功能

## Tech Stack
- Node 20 / TypeScript / Prisma
- PostgreSQL 16

## Commands
- npm run dev    开发服务器
- npm test       运行测试

## Safety Rules
除非明确要求，禁止：
- 修改数据库 schema
- 修改认证逻辑

              提交到 git
              团队共享
            

            🙈
            本地私有 CLAUDE.local.md
            ~/project/CLAUDE.local.md
          

            仅自己可见，加入 .gitignore。存放本人特有的偏好或临时笔记，不影响团队其他人。
            ~/project/CLAUDE.local.md
## 我的本地偏好
- 我的测试数据库端口是 5433
- 本地 Redis 不需要密码
- 调试时打印详细日志

              .gitignore
              个人专属
            

            🧩
            子目录 CLAUDE.md（按需加载）
            ~/project/frontend/CLAUDE.md
          
大型 monorepo 必备。子目录有自己的规则，只有 Claude 在处理该目录的文件时才触发加载，不会无条件占用上下文。
            ~/project/frontend/CLAUDE.md
## Frontend 特有规则
- 组件库只用 shadcn/ui
- 状态管理用 Zustand
- 图标只用 lucide-react

# 不要在这里重复根目录的内容！

              按需加载
              monorepo 神器
            

⚡ Auto Memory（自动记忆） ~/.claude/projects/{id}/memory/

Claude 自己写的记忆，不需要你手动维护。Claude 会在对话中判断哪些信息值得记录，比如：重要决策、已知问题、调试经验。

加载规则：MEMORY.md 的前 200行 / 25KB（取先到者）在会话开始时加载，其他主题文件只有被主动读取时才加载。

~/.claude/projects/xxx/memory/MEMORY.md（自动生成）

## 重要决策
- 选 Prisma 而非 TypeORM：类型安全更好
- 选 Vercel 部署：CI/CD 更简单

## 已知问题
- 移动端 Safari 的 backdrop-filter 兼容性差
- Gemini API 有 60req/min 限制，需重试

## 用户偏好
- 喜欢简洁回复，不要冗长解释
- 提交前总是忘记跑测试

# 以下文件需按需加载：
→ debugging.md    调试经验详情
→ api-design.md   API 设计决策

Claude 自动写入只加载前 200行主题文件按需读

📦 模块化规则 .claude/rules/ ./.claude/rules/*.md

把 CLAUDE.md 里的规则按主题拆分到独立文件，更容易维护。支持路径特定规则：只有 Claude 处理匹配的文件时才加载对应规则，极大节省上下文。

            ✏️
            coding-standards.md
            .claude/rules/coding-standards.md
          
.claude/rules/coding-standards.md
## TypeScript
- strict mode 强制
- 禁止 any 类型
- 接口名 PascalCase

## 函数规范
- 函数不超过 50 行
- 复杂嵌套超 3 层必须提取
- 条件分支用早期返回

            🔌
            api-guidelines.md（路径特定规则）
            .claude/rules/api-guidelines.md
          

            使用 YAML 前置元数据指定路径，只有读取 src/api/ 下的文件时才加载。其他场景完全不占上下文！
            .claude/rules/api-guidelines.md
---
paths:
  - "src/api/**/*.ts"
---
## API 规范
- 所有端点必须有输入校验
- 统一使用标准错误响应格式
- RESTful 命名：/users/:id

              路径触发加载
              节省 tokens
            

            🔐
            security.md
            .claude/rules/security.md
          
.claude/rules/security.md
## 安全规则
- 所有用户输入必须经过 Zod 验证
- 密钥只从环境变量读取，禁止硬编码
- SQL 禁止拼接字符串，使用参数化查询
- 敏感日志不输出到控制台

💬 ③ 对话上下文（实时增长）会话进行中持续追加

用户输入 + Claude 回复 + 工具调用结果（读取的代码、命令输出等）会在会话中不断追加。这是唯一会动态增长的部分。

当对话历史消耗超过 64-75% 上下文时，Claude Code 会自动触发压缩，把历史对话总结成摘要继续。

动态增长 ~114K 可用超 75% 自动压缩

💡 关键点再强调： 这些文件不是"通过索引相互引用"的关系——它们是各自独立的 md 文件，Claude Code 在启动时按规则找到它们、读入内容、合并成一个大的上下文字符串，然后作为 system prompt 的一部分传给模型。

唯一例外是 @ 导入语法：你可以在 CLAUDE.md 里写 @docs/api.md 让它引入另一个文件，这才是类似"索引"的机制，但这只是可选功能，不是默认行为。

🧠 Claude Code 记忆结构图

📐 四层作用域一览