Claude Code 记忆系统文档
完整的记忆系统使用指南和实现原理文档
📚 文档目录
01-usage-guide.md — 使用指南
面向用户的完整使用手册，涵盖：
- 四种记忆类型：User（用户画像）、Feedback（行为反馈）、Project（项目动态）、Reference（外部引用）
- 四种触发方式：自动提取、显式请求、
/memory命令、/remember命令 - 存储格式：YAML frontmatter + Markdown 内容
- 管理操作：遗忘、忽略、手动编辑、禁用、自定义目录
- 生命周期：从学习到注入，新鲜度管理
适合人群：所有 Claude Code 用户
02-implementation.md — 实现原理
面向开发者的技术深度解析，涵盖：
- 5 大核心模块：路径解析、提示词构建、记忆扫描、智能检索、自动提取
- 路径解析系统：优先级链、安全校验、启用条件
- 系统提示词注入：
loadMemoryPrompt()→buildMemoryLines()，MEMORY.md 截断策略 - 自动记忆提取：分叉代理、互斥机制、工具权限、合并机制
- 智能检索：
scanMemoryFiles()→ Sonnet 选择 → 新鲜度警告 - 代理记忆：三级作用域（user/project/local）
- 团队记忆同步：Pull/Push API、合并语义
- 完整数据流：从会话启动到上下文注入
适合人群：贡献者、架构师、想深入了解实现的开发者
03-autodream.md — AutoDream 记忆整合
Claude 的"做梦"机制——后台静默整合记忆的深度解析，涵盖：
- 核心概念：像人类睡眠整理记忆一样，定期回顾多个会话整合知识
- 五重门控：功能开关 → 时间门控(24h) → 扫描节流(10min) → 会话门控(5个) → 锁门控
- 四阶段流程：Orient（定向）→ Gather（收集）→ Consolidate（整合）→ Prune（修剪）
- 安全限制：Bash 只读、写操作仅限记忆目录、PID 锁文件互斥
- UI 展示：底部 "dreaming" 标签、Shift+Down 详情对话框、完成通知
- 配置控制：settings.json 本地开关 + GrowthBook 远程 feature flag
- 与 extractMemories 对比：白天记笔记 vs 睡觉整理笔记本
适合人群：贡献者、架构师、对 Claude 自动化记忆管理感兴趣的开发者
🖼️ 配图说明
所有配图采用深色背景（#1a1a2e）+ Anthropic 品牌橙铜色（#D97757）风格，与 Claude Code 官方文档一致。
| 图片 | 说明 | 尺寸 |
|---|---|---|
01-memory-overview.png | 记忆系统概览 — 四层架构（触发/类型/存储/检索） | 632 KB |
02-memory-types.png | 四种记忆类型 — 2x2 网格展示 User/Feedback/Project/Reference | 507 KB |
03-memory-trigger.png | 记忆触发流程 — 从对话到存储的四种路径 | 474 KB |
04-memory-lifecycle.png | 记忆生命周期 — 完整循环流程 + 新鲜度判断 | 1.0 MB |
05-architecture-overview.png | 实现架构总览 — 5 个核心模块 + 辅助模块 | 3.5 MB |
06-path-resolution.png | 路径解析流程 — 三层优先级 + 安全校验 | 1.0 MB |
07-prompt-injection.png | 提示词注入流程 — loadMemoryPrompt 分发逻辑 | 1.1 MB |
08-auto-extraction.png | 自动提取流程 — 分叉代理完整流程 | 1.2 MB |
09-memory-retrieval.png | 智能检索流程 — Sonnet 选择 + 新鲜度管理 | 816 KB |
10-agent-memory.png | 代理记忆作用域 — 三级嵌套结构 | 523 KB |
11-autodream-overview.png | AutoDream 概览 — 做梦机制的核心架构与人类睡眠类比 | 777 KB |
12-autodream-trigger.png | AutoDream 触发流程 — 五重门控检查链 | 493 KB |
13-autodream-phases.png | AutoDream 四阶段 — Orient/Gather/Consolidate/Prune | 602 KB |
🚀 快速开始
用户
- 阅读 使用指南
- 了解四种记忆类型和触发方式
- 尝试
/memory和/remember命令
开发者
- 阅读 实现原理
- 查看源码位置：
src/memdir/paths.ts— 路径解析src/memdir/memdir.ts— 提示词构建src/memdir/memoryScan.ts— 记忆扫描src/memdir/findRelevantMemories.ts— 智能检索src/services/extractMemories/— 自动提取
- 理解数据流和模块交互
📝 核心概念速查
| 概念 | 说明 |
|---|---|
| MEMORY.md | 索引文件，始终加载到上下文（最多 200 行 / 25KB） |
| 主题文件 | *.md 文件，包含 frontmatter + 内容 |
| 自动提取 | 每次回复后后台运行，分叉代理分析对话 |
| AutoDream | 每 24h + 5 个会话后，后台整合/去重/修剪全部记忆 |
| 智能检索 | Sonnet 模型从所有记忆中选择最多 5 个相关的 |
| 新鲜度 | ≤1 天无警告，>1 天附带陈旧警告 |
| 分叉代理 | 共享提示词缓存，限制工具权限，最多 5 turns |
| 三级作用域 | 代理记忆：user（全局）> project（项目）> local（本地） |