从产品经理视角，结合官方文档与源码实现，全面拆解 Claude Code 的记忆架构、加载策略、存储机制与最佳实践。
Claude Code 的每一次会话都从全新的上下文窗口开始——没有任何历史记忆。记忆系统的核心使命是：跨会话传递知识，让 AI 在不同对话间保持对项目、用户和团队的理解。
两套互补的记忆机制在每次对话开始时加载。人类编写指令，AI 积累学习——二者协同工作。
| 维度 | CLAUDE.md 文件 | 自动记忆 (Auto Memory) |
|---|---|---|
| 编写者 | 用户 / 团队 | Claude 自主编写 |
| 内容类型 | 指令和规则 | 学习到的模式和偏好 |
| 作用范围 | 项目、用户或组织 | 每个工作树 (worktree) |
| 加载方式 | 完整加载（不论长度） | 前 200 行或 25KB |
| 典型内容 | 编码标准、工作流、架构 | 构建命令、调试经验、偏好 |
| 持久化位置 | 项目目录 / 用户目录 | ~/.claude/projects/<project>/memory/ |
| 源码入口 | utils/claudemd.ts | memdir/memdir.ts |
constants/prompts.ts:495 中，通过 systemPromptSection('memory', () => loadMemoryPrompt()) 将记忆注入系统提示。上下文构建在 context.ts:155-189 的 getUserContext() 函数中完成。
CLAUDE.md 的加载遵循严格的层级顺序。更具体的位置覆盖更广泛的位置。源码中的 getMemoryFiles() 函数定义了完整的发现和优先级逻辑。
utils/claudemd.ts:790-1074 的 getMemoryFiles() 中，加载顺序为：Managed → User → Project（含向上遍历父目录）→ Local → AutoMem → TeamMem。此外发现还有 团队记忆（TeamMem）存储于 <autoMemPath>/team/MEMORY.md，由 Feature Flag tengu_herring_clock 控制。
记忆的加载并非简单的"全部读取"——它涉及发现、解析、截断、注入等多个精密步骤。
以下内容在会话开始时即完整加载：
.claude/CLAUDE.md 和 .claude/rules/*.md（无 paths: frontmatter 的文件）~/.claude/CLAUDE.md以下内容仅在需要时才加载：
paths: frontmatter 的 .claude/rules/*.md（当读取匹配文件时触发）debugging.md、patterns.md），由相关性选择引擎决定--add-dir 附加目录中的文件（需设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1）CLAUDE.md 支持 @path/to/file 语法导入外部文件。
在注入上下文前，块级 HTML 注释会被自动移除——可用于给人类维护者留备注而不消耗 token。
自动记忆的入口文件有严格的大小限制：
自动记忆是 Claude Code 最具"产品力"的功能之一——AI 在工作中主动积累知识，无需用户手动操作。
Claude 在会话中发现值得记住的信息（用户纠正、非显而易见的偏好、项目模式等），基于"对未来对话是否有用"判断是否保存。
使用 FileWriteTool 将记忆写入独立的 .md 文件（如 feedback_testing.md），包含 YAML frontmatter（name, description, type）。
在 MEMORY.md 中添加一行索引指针：- [Title](file.md) — 一行描述，控制在 150 字符以内。
MEMORY.md 索引在新会话启动时自动加载（前 200 行）。主题文件按需通过相关性引擎召回。
~/.claude/projects/<sanitized-git-root>/memory/，同一 Git 仓库的所有 worktree 共享记忆。
memdir/teamMemPaths.ts:109-150 实现了符号链接攻击防护——在创建团队记忆目录前检测 symlink 是否指向不安全路径。autoMemoryDirectory 设置也刻意不从项目级 settings.json 读取（memdir/paths.ts），防止恶意项目重定向记忆存储。
自动记忆不是无序的笔记堆——它遵循严格的四类分类法，每种类型有明确的触发场景、存储格式和使用方式。
用户的角色、目标、职责和知识水平。帮助 Claude 在未来对话中量身定制行为——对资深工程师和初学者的协作方式完全不同。
用户对工作方式的纠正和确认。包含 Why（原因）和 How to apply（应用方式）。不仅记录错误，也记录验证通过的非显而易见做法。
从代码或 Git 历史中无法推导的项目信息：谁在做什么、为什么、截止何时。注意将相对日期转换为绝对日期（"周四" → "2026-03-05"）。
指向外部系统中信息位置的指针。让 Claude 知道去哪里找最新信息（而非缓存过时的内容）。
每个记忆文件遵循统一的 YAML frontmatter + Markdown 正文格式：
git log / git blame 是权威来源并非所有记忆文件都在每次会话中加载。系统使用 AI 驱动的相关性选择来决定哪些主题文件最有价值。
对于大型项目，可将指令拆分为多个规则文件，支持按文件路径模式条件触发——仅在处理匹配文件时才加载到上下文中。
| 模式 | 匹配范围 |
|---|---|
**/*.ts |
任意目录中的 TypeScript 文件 |
src/**/* |
src/ 下的所有文件 |
src/components/*.tsx |
特定目录中的 React 组件 |
src/**/*.{ts,tsx} |
大括号扩展匹配多扩展名 |
utils/claudemd.ts:1354-1397，条件规则使用 ignore 库（类似 .gitignore 语法）对相对路径做匹配。规则触发时机是 Claude 读取匹配文件时（而非每次工具调用时）。规则文件也支持符号链接——可在多项目间共享。
记忆系统的行为可通过 settings.json 和环境变量精细控制。源码中还存在多个 Feature Flag 控制实验性功能。
| 配置项 | 类型 | 作用 | 源码位置 |
|---|---|---|---|
autoMemoryEnabled |
boolean | 开启/关闭自动记忆（默认 true） | settings/types.ts:938 |
autoMemoryDirectory |
string | 自定义记忆存储路径（支持 ~/ 展开） | settings/types.ts:944 |
autoDreamEnabled |
boolean | 启用后台记忆整合（"dream"模式） | settings/types.ts:950 |
claudeMdExcludes |
string[] | 排除特定 CLAUDE.md 文件（glob 语法） | settings/types.ts:1053 |
CLAUDE_CODE_DISABLE_AUTO_MEMORY |
env var | 环境变量级关闭自动记忆 | memdir/paths.ts:31-37 |
以下是在源码中找到的与记忆系统相关的实验性标志，揭示了产品演进方向：
控制团队记忆功能。启用后在自动记忆目录下创建 team/ 子目录，允许多人协作的记忆共享。
控制 MEMORY.md 注入方式切换——从直接注入转为附件预取（attachment prefetch），可能是上下文优化策略。
启用后台记忆提取代理，可能在会话结束后自动分析对话并提取值得记住的信息。
控制每日日志模式（Daily Log），为 Assistant 模式提供追加式的日志记忆。
getMemoryFiles 使用 memoize 缓存（单次会话仅调用一次，除非显式清理）。系统提示的记忆部分也会被缓存，直到 /clear 或 /compact 时才刷新。在 constants/prompts.ts:573，记忆内容位于动态边界处用于 prefix caching。
综合官方文档与源码实现，以下是使用 Claude Code 记忆系统的最佳实践。
虽然文件会完整加载，但过长的文件消耗上下文且降低遵循度。详细内容拆分到 @import 引用或 .claude/rules/ 文件中。用 HTML 注释 <!-- --> 给维护者留备注而不消耗 token。
✅ "使用 2 空格缩进" ✅ "提交前运行 npm test" ✅ "API 处理程序位于 src/api/handlers/"
❌ "正确格式化代码" ❌ "测试你的更改" ❌ "保持文件有组织"
托管策略放安全合规（全组织）→ 用户级放个人偏好 → 项目级放团队规范 → 本地放个人项目配置 → 自动记忆让 AI 自主积累。每层各司其职，避免重复。
使用 paths: frontmatter 让规则仅在处理匹配文件时加载。在 monorepo 中用 claudeMdExcludes 排除其他团队的 CLAUDE.md。条件规则 = 更少的上下文噪音 + 更精准的指令。
使用 /memory 命令浏览 Claude 保存的内容。记忆文件是纯 Markdown，可随时编辑或删除。注意清理过时的项目动态（project 类型），它们衰减最快。
记忆：跨会话有用的信息（偏好、模式、外部指针）。Plan：当前任务的实现方案（需要用户确认）。Todo：当前会话的离散工作步骤。不要把临时任务信息存入记忆。
运行 /init 自动生成初始 CLAUDE.md。设置 CLAUDE_CODE_NEW_INIT=1 启用交互式多阶段流程，使用 subagent 探索代码库并生成可审查的提案。从生成结果开始迭代，添加 AI 不会自己发现的指令。
CLAUDE.md 是行为指导（非强制）——真正的安全控制用 settings.json 的 permissions.deny。autoMemoryDirectory 刻意不从项目 settings 读取，防止恶意重定向。团队记忆有 symlink 攻击防护。托管策略 CLAUDE.md 无法被 claudeMdExcludes 排除。