Claude Code Auto Memory 索引结构

📁 文件结构

📂 ~/.claude/projects/{project-id}/ 项目记忆根目录

📄 MEMORY.md 中央索引 · 自动加载

📄 user.md 用户信息 · 按需读取

📄 project.md 项目上下文 · 按需读取

📄 debugging.md 调试经验 · 按需读取

📄 api-design.md API设计 · 按需读取

中央索引

📄 MEMORY.md 的作用

MEMORY.md 是 Auto Memory 系统的「目录」和「导航」。它本身内容精简（只加载前 200 行），但通过 Markdown 链接告诉 Claude：「还有哪些记忆文件存在，它们各自存储什么主题」。 Claude 根据当前对话内容，决定是否需要深入读取某个主题文件。

📄 ~/.claude/projects/xxx/memory/MEMORY.md
# Visuals Project Memory

# 这是所有记忆的中央索引
# Claude 每次会话自动加载此文件的前 200 行

## Memory Files

# 以下文件不会自动加载，Claude 按需读取：

- [user.md](user.md) - User information and preferences
  # 包含：用户偏好、回复风格、常用工具

- [project.md](project.md) - Project context and recent work
  # 包含：项目架构、最近修改、技术决策

- [debugging.md](debugging.md) - Debugging notes and solutions
  # 包含：已知 bug、绕过方法、调试技巧

- [api-design.md](api-design.md) - API design decisions
  # 包含：接口规范、版本变更、兼容性说明

## Quick Reference
# 快速参考：最重要的信息放在这里
- 当前技术栈：React + TypeScript + Vite
- 主要分支：main (生产), dev (开发)
- 部署平台：Vercel

## About
Last updated: 2026-05-08

🔄 加载机制：索引 vs 数据分离

会话启动：自动加载 MEMORY.md

Claude Code 启动时，只读取 MEMORY.md 的前 200 行或 25KB（取先到者）。这个文件很小，不会占用太多上下文空间。

加载后，Claude 知道了：「哦，还有 user.md、project.md、debugging.md 这几个文件」

按需读取：根据对话内容加载主题文件

当对话涉及特定主题时，Claude 会主动读取对应的主题文件：

• 聊到用户偏好 → 读取 user.md
• 聊到项目架构 → 读取 project.md
• 聊到调试问题 → 读取 debugging.md
• 聊到 API 设计 → 读取 api-design.md

动态更新：Claude 自动写入新记忆

对话中 Claude 发现值得记住的信息，会自动更新相应文件：

• 发现新的用户偏好 → 追加到 user.md
• 做出重要技术决策 → 追加到 project.md
• 解决棘手 bug → 记录到 debugging.md

🔗 索引与数据的关系

📄 MEMORY.md

中央索引 · 自动加载

「我知道有这些文件，按需读取」

↓

👤 user.md

用户偏好

📁 project.md

项目上下文

🐛 debugging.md

调试经验

🔌 api-design.md

API设计

关键设计： MEMORY.md 作为「轻量级目录」常驻上下文，主题文件「按需加载」节省 tokens

📊 MEMORY.md vs 主题文件对比

特性	MEMORY.md（索引）	user.md / project.md 等（主题）
加载时机	会话启动自动加载	按需读取
加载量	前 200 行 / 25KB	完整文件内容
内容作用	目录、索引、快速参考	详细内容、完整记录
更新频率	较少（结构稳定）	频繁（持续积累）
文件大小	通常 < 5KB	可能很大（无限制）
类比	书的目录页	书的各章节内容

📝 主题文件内容示例

📄 user.md - 用户偏好（Claude 自动学习）
## User Preferences

### Communication Style
- Prefers concise responses over verbose explanations
- Likes code examples with inline comments
- Prefers Chinese language responses

### Technical Preferences
- Favorite package manager: pnpm
- Prefers functional components over class components
- Likes to use TypeScript strict mode

### Habits
- Often forgets to run tests before committing
- Likes to explore implementation details
- Prefers dark theme for all outputs

## Last Updated
2026-05-08 - Added preference for Chinese responses

📄 project.md - 项目上下文
## Project Context

### Architecture Decisions
- Chose Vite over Create React App for faster HMR
- Using Zustand instead of Redux for state management
- Decided against using CSS-in-JS, sticking with Tailwind

### Current Status
- Main branch is stable, deployed to production
- Working on feature/auth branch for OAuth integration
- Known issue: Safari backdrop-filter not working

### Recent Work
2026-05-07 - Refactored API layer to use React Query
2026-05-06 - Fixed memory leak in WebSocket connection
2026-05-05 - Added dark mode toggle

### Tech Stack
- React 18 + TypeScript 5
- Vite + Tailwind CSS
- React Query + Zustand
- Deployed on Vercel

✅ 总结：你的理解完全正确

📇

中央索引

MEMORY.md 作为「目录页」，列出所有主题文件，会话启动时自动加载

📚

分布式存储

user.md、project.md 等主题文件按需读取，避免一次性加载过多内容

🤖

自动管理

Claude 自动判断哪些信息值得记录，自动更新相应主题文件

⚡

节省 Tokens

轻量级索引常驻上下文，详细内容按需加载，优化上下文使用效率

⚡ Claude Code Auto Memory 索引结构

📊 MEMORY.md vs 主题文件对比

📝 主题文件内容示例

✅ 总结：你的理解完全正确