Claude Code Memory 系统：完整设计与源码分析

基于 Claude Code npm 包 source map 泄露快照 (2026-03-31) 的源码分析。
适用于团队内部分享，理解 AI Agent 记忆系统的设计范式。

一、设计哲学

源码注释（src/memdir/memoryTypes.ts:1-12）开宗明义：

Memories are constrained to four types capturing context NOT derivable from the current project state. Code patterns, architecture, git history, and file structure are derivable (via grep/git/CLAUDE.md) and should NOT be saved as memories.

核心原则：记忆只存储「从代码中读不出来」的信息。代码模式、架构、文件结构可以 grep/git 获得，不需要记忆。

二、三层记忆架构

Claude Code 不是一层记忆，而是三个独立系统解决不同时间尺度的问题：

三层架构解决不同时间尺度的记忆问题：永久指令 → 跨会话知识 → 会话恢复

2.1 CLAUDE.md：指令层

发现机制（src/utils/claudemd.ts）：

从 CWD 向上遍历到根目录，按顺序加载。源码注释（第 9 行）明确说明：

Files are loaded in reverse order of priority, i.e. the latest files are highest priority with the model paying more attention to them.

加载顺序与优先级（后加载 = 在 prompt 中更靠后 = 模型更关注 = 优先级更高）：

后加载 = prompt 中更靠后 = 模型更关注 = 优先级更高。dirs.reverse() 实现从根→CWD 遍历。

关键源码（claudemd.ts:878）：dirs.reverse() 让遍历从根目录→CWD，离 CWD 越近的文件越后加载。

优先级设计意图：

• Managed 优先级最低但有措辞保障：企业策略用 IMPORTANT: OVERRIDE 措辞弥补位置劣势
• Local 优先级最高：CLAUDE.local.md 是 gitignore 的个人文件，可以覆盖项目级规则
• Project 按距离分级：CWD 层的规则覆盖根目录的规则（monorepo 子项目可有独立规则）

注入方式：通过 getUserContext() 一次性加载（记忆化），作为系统提示的一部分，带硬性指令头：

"Codebase and user instructions are shown below. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written."

2.2 Auto Memory：知识层

文件系统结构：

2.3 Session Memory：压缩恢复层

三、四种记忆类型：闭合分类法

3.1 总览

闭合四类分类法覆盖「不可从代码推导的上下文」的完整谱系：谁 · 怎么做 · 在做什么 · 去哪看

3.2 Type 1: User（用户画像）

源码定义（memoryTypes.ts:46-56）：

<type>
    <name>user</name>
    <scope>always private</scope>
    <description>Contain information about the user's role, goals,
    responsibilities, and knowledge. Your goal is to build up an
    understanding of who the user is and how you can be most helpful
    to them specifically.</description>
    <when_to_save>When you learn any details about the user's role,
    preferences, responsibilities, or knowledge</when_to_save>
    <how_to_use>When your work should be informed by the user's
    profile or perspective.</how_to_use>
</type>

实际样例（ones-testing-infra 项目）：

---
name: Sean 用户画像
description: 用户角色、技术背景和协作偏好
type: user
---

- QA/测试工程方向的技术负责人，关注测试质量保障自动化
- 熟悉 ONES 平台（内部产品）、Claude Code、Codex CLI 插件生态
- 偏好先出文档再写代码（Doc First），重视方案设计的严谨性
- 对产品定位要求精确：会纠正范围蔓延
- 习惯追问设计细节和 tradeoff，期望得到有深度的思考而非直接套模板

设计规则：

3.3 Type 2: Feedback（行为反馈）

源码定义（memoryTypes.ts:57-73）：

<type>
    <name>feedback</name>
    <scope>default to private. Save as team only when the guidance
    is clearly a project-wide convention.</scope>
    <description>Guidance the user has given you about how to approach
    work — both what to avoid and what to keep doing. Record from
    failure AND success.</description>
    <when_to_save>Any time the user corrects your approach OR confirms
    a non-obvious approach worked. Corrections are easy to notice;
    confirmations are quieter — watch for them.</when_to_save>
    <body_structure>Lead with the rule itself, then a **Why:** line
    and a **How to apply:** line. Knowing *why* lets you judge edge
    cases instead of blindly following the rule.</body_structure>
</type>

实际样例：

---
name: 设计沟通反馈
description: 用户对方案设计过程的反馈和偏好
type: feedback
---

不要被现有实现限制思路，先想清楚"正确的做法是什么"再考虑兼容。

**Why:** 用户多次要求"不用局限于目前 skill 的限制"、"你认为正确的做法是什么"，
期望先从第一性原理思考，再考虑向后兼容。

**How to apply:** 设计新方案时，先提出理想方案，再说明与现有实现的兼容策略。
不要一开始就被现有代码/目录结构束缚。

---

Plugin 不是 MCP Server。用户明确纠正过"我说的是插件形态，不是 mcp"。

**Why:** Claude Code Plugin 和 MCP Server 是不同概念。Plugin 包含 skills、agents、
MCP 声明等；MCP Server 只是 Plugin 的一个组成部分。

**How to apply:** 讨论 Plugin 时使用正确术语，区分 Plugin（整体）和 MCP Server
（Plugin 内的工具服务）。

设计规则：

「记录成功」是最精妙的设计洞察。源码给的例子：

user: yeah the single bundled PR was the right call here, splitting
      this one would've just been churn
assistant: [saves feedback memory: for refactors in this area, user
           prefers one bundled PR over many small ones. Confirmed after
           I chose this approach — a validated judgment call, not a
           correction]

3.4 Type 3: Project（项目状态）

源码定义（memoryTypes.ts:75-88）：

<type>
    <name>project</name>
    <scope>private or team, but strongly bias toward team</scope>
    <description>Information about ongoing work, goals, initiatives,
    bugs, or incidents NOT derivable from code or git history.</description>
    <when_to_save>When you learn who is doing what, why, or by when.
    Always convert relative dates to absolute dates (e.g., "Thursday"
    → "2026-03-05").</when_to_save>
    <body_structure>Lead with the fact or decision, then **Why:** and
    **How to apply:**. Project memories decay fast, so the why helps
    future-you judge whether the memory is still load-bearing.</body_structure>
</type>

实际样例：

---
name: QABOT Plugin 项目状态
description: QABOT Plugin 从 CLI 迁移为 Claude Code/Codex Plugin 的项目进展
type: project
---

QABOT 正在从独立 CLI 迁移为 Claude Code / Codex Plugin 形态，聚焦 ONES 测试质量保障。

**Why:** CLI 维护成本高（~3000行基础设施代码），Plugin 形态可复用宿主的 Agent Loop/LLM/REPL。

**How to apply:** Plugin 代码在 /workspace/.../plugin/ 下独立开发，不修改现有 CLI。

## 已完成（截至 2026-03-27）
- [x] plugin/.specs/prd.md — PRD
- [x] plugin/.specs/architecture.md — 技术架构
...

## 待办
### M1：Plugin 骨架 + 环境管理
- [ ] 创建双平台 Plugin 结构
...

设计规则：

3.5 Type 4: Reference（外部指针）

源码定义（memoryTypes.ts:89-103）：

<type>
    <name>reference</name>
    <scope>usually team</scope>
    <description>Stores pointers to where information can be found
    in external systems.</description>
    <when_to_save>When you learn about resources in external systems
    and their purpose.</when_to_save>
</type>

设计规则：最轻量的类型，不需要 Why / How to apply 结构。价值在于「告诉模型去哪找」。默认 team——外部系统的位置信息对整个团队有用。

四、排除规则：什么不该存

源码定义了明确的反面清单（memoryTypes.ts:183-195）：

export const WHAT_NOT_TO_SAVE_SECTION: readonly string[] = [
  '## What NOT to save in memory',
  '',
  '- Code patterns, conventions, architecture, file paths, or project structure '
  + '— these can be derived by reading the current project state.',
  '- Git history, recent changes, or who-changed-what — `git log` / `git blame` are authoritative.',
  '- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context.',
  '- Anything already documented in CLAUDE.md files.',
  '- Ephemeral task details: in-progress work, temporary state, current conversation context.',
  '',
  // H2: eval-validated (memory-prompt-iteration case 3, 0/2 → 3/3)
  'These exclusions apply even when the user explicitly asks you to save. '
  + 'If they ask you to save a PR list or activity summary, ask what was '
  + '*surprising* or *non-obvious* about it — that is the part worth keeping.',
]

最后一条是最强硬的：即使用户说「保存这个 PR 列表」，模型也不应该直接存——而是追问「这里面什么是意外的或不明显的？那部分才值得记住。」这条规则经过 eval 验证（0/2 → 3/3），专门针对「活动日志噪声」问题。

与其他持久化机制的边界

// memdir.ts:254-257
'## Memory and other forms of persistence',
'- When to use or update a plan instead of memory: ...',
'- When to use or update tasks instead of memory: ...',

五、召回侧规则：用记忆时的纪律

5.1 验证优于信任

源码（memoryTypes.ts:240-256），eval 验证 H1: 0/2 → 3/3：

export const TRUSTING_RECALL_SECTION: readonly string[] = [
  '## Before recommending from memory',
  '',
  'A memory that names a specific function, file, or flag is a claim that it '
  + 'existed *when the memory was written*. It may have been renamed, removed, '
  + 'or never merged. Before recommending it:',
  '',
  '- If the memory names a file path: check the file exists.',
  '- If the memory names a function or flag: grep for it.',
  '- If the user is about to act on your recommendation, verify first.',
  '',
  '"The memory says X exists" is not the same as "X exists now."',
  '',
  'A memory that summarizes repo state (activity logs, architecture snapshots) '
  + 'is frozen in time. If the user asks about *recent* or *current* state, '
  + 'prefer `git log` or reading the code over recalling the snapshot.',
]

设计意图：源码注释记录了失败模式——模型会直接推荐记忆中的文件路径，即使该文件已被移动/删除。header 措辞从「Trusting what you recall」改为「Before recommending from memory」后通过率从 0/3 → 3/3，因为后者是 action cue（在决策点触发），前者太抽象。

5.2 新鲜度漂移警告

源码（memoryTypes.ts:201-202）：

export const MEMORY_DRIFT_CAVEAT =
  'Memory records can become stale over time. Use memory as context for what '
  + 'was true at a given point in time. Before answering the user or building '
  + 'assumptions based solely on information in memory records, verify that '
  + 'the memory is still correct and up-to-date...'

配合 memoryAge.ts 的时间标注系统：

// 模型不善于日期计算——原始 ISO 时间戳不会触发过时推理
// 但 "47 days ago" 会
export function memoryAge(mtimeMs: number): string {
  const d = memoryAgeDays(mtimeMs)
  if (d === 0) return 'today'
  if (d === 1) return 'yesterday'
  return `${d} days ago`
}

// 超过 1 天的记忆附带 staleness caveat
export function memoryFreshnessText(mtimeMs: number): string {
  const d = memoryAgeDays(mtimeMs)
  if (d <= 1) return ''
  return `This memory is ${d} days old. Memories are point-in-time observations, `
    + `not live state — claims about code behavior or file:line citations may be `
    + `outdated. Verify against current code before asserting as fact.`
}

5.3 忽略指令

源码（memoryTypes.ts:216-222），eval 验证 H6: case 5 1/3：

'- If the user says to *ignore* or *not use* memory: proceed as if '
+ 'MEMORY.md were empty. Do not apply remembered facts, cite, compare '
+ 'against, or mention memory content.',

失败模式：用户说「忽略关于 X 的记忆」→ 模型读代码给出正确答案，但加了一句「not Y as noted in memory」——把记忆内容提了出来。规则要求完全不提及。

六、六种记忆的产生规则与加载机制

Claude Code 中存在六种不同来源的记忆内容，各自有独立的产生规则和加载时机：

6.0 总览

六种记忆在会话时序中的加载位置：越靠右越是「按需」加载

6.1 CLAUDE.md —— 指令级记忆

产生规则：用户在项目中手写 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md 等文件。

加载机制（src/utils/claudemd.ts → src/context.ts）：

关键特性：

• 一次性加载，不随对话轮次更新（除非 compact 后重新注入）
• 支持 @include 指令引用其他文件
• 支持条件规则（glob 匹配文件路径才加载）
• 后加载 = 高优先级：利用 LLM 的 recency bias，prompt 越靠后的指令越受关注

6.2 MEMORY.md 索引 —— 知识入口

产生规则：

• 模型在用户要求「记住 X」时创建/更新
• 后台提取 Agent 自动创建/更新
• 两步保存：先写独立文件 → 再在 MEMORY.md 添加索引

加载机制（src/memdir/memdir.ts）：

关键特性：

• 始终在系统提示中，每次 API 调用都可见
• 只存索引（一行一条 ~150 字符），实际内容在独立文件中
• 200 行上限强制保持精简

6.3 Relevant Memories —— 按需语义召回

产生规则：不主动产生，而是从已有记忆文件中按需选择。

加载机制（src/utils/attachments.ts → src/memdir/findRelevantMemories.ts）：

关键特性：

• 异步非阻塞：与主模型流式输出并行，通过 Disposable 模式管理生命周期
• 预算控制：单次 5x4KB=20KB，会话累计 60KB 后停止预取
• 去重：alreadySurfaced Set + readFileState LRU cache 双重去重
• Agent 隔离：如果用户 @mention 了特定 agent，只搜索该 agent 的记忆目录

6.4 Nested Memory —— 文件触发的上下文注入

产生规则：不产生新记忆，而是在模型操作文件时，加载该文件路径相关的 CLAUDE.md 规则。

加载机制（src/utils/attachments.ts）：

关键特性：

• 按需触发：只有工具操作特定文件时才加载相关规则
• 条件规则：.claude/rules/*.md 可以带 glob 条件，只对匹配的文件生效
• 双重去重：loadedNestedMemoryPaths（不驱逐）防止 LRU cache 驱逐后重复注入
• 顺序依赖：必须在 userInputAttachments 之后运行（等待 triggers 填充）

6.5 Auto-extracted Memories —— 后台智能提取

产生规则：Fork Agent 分析对话内容，自动创建/更新记忆文件。

加载机制：不直接加载——写入文件后，通过 6.2（MEMORY.md 索引）和 6.3（语义召回）间接加载。

6.6 Session Memory —— 压缩恢复专用

产生规则：后台 post-sampling hook 自动维护结构化笔记。

加载机制：不注入对话——压缩时替代 API 摘要调用。

七、MEMORY.md 索引机制详解

7.1 加载与截断

文件：src/memdir/memdir.ts

export const MAX_ENTRYPOINT_LINES = 200
export const MAX_ENTRYPOINT_BYTES = 25_000  // ~125 chars/line at 200 lines

export function truncateEntrypointContent(raw: string): EntrypointTruncation {
  const contentLines = trimmed.split('\n')

  // ① 先按行截断（200 行上限）
  if (lineCount > MAX_ENTRYPOINT_LINES) {
    truncated = contentLines.slice(0, 200).join('\n')
  }

  // ② 再按字节截断（25KB 上限，在最后一个换行处切断）
  if (truncated.length > MAX_ENTRYPOINT_BYTES) {
    const cutAt = truncated.lastIndexOf('\n', MAX_ENTRYPOINT_BYTES)
    truncated = truncated.slice(0, cutAt > 0 ? cutAt : MAX_ENTRYPOINT_BYTES)
  }

  // ③ 附加警告
  return {
    content: truncated + `\nWARNING: MEMORY.md is ${reason}. Only part of it was loaded.`,
    ...
  }
}

7.2 两步保存流程

系统提示指导模型的保存行为（memdir.ts:218-234）：

Step 1: 写入独立文件（如 user_role.md, feedback_testing.md），使用 frontmatter：
  ---
  name: {{memory name}}
  description: {{one-line description — used to decide relevance}}
  type: {{user, feedback, project, reference}}
  ---
  {{content}}

Step 2: 在 MEMORY.md 中添加索引条目，每条一行，~150 字符以内：
  - [Title](file.md) — one-line hook

为什么分两步：MEMORY.md 始终在系统提示中（200 行限制），所以只存索引。实际内容在独立文件中，通过语义召回按需加载。

7.3 目录自动创建

// memdir.ts:129-147
export async function ensureMemoryDirExists(memoryDir: string): Promise<void> {
  const fs = getFsImplementation()
  try {
    await fs.mkdir(memoryDir)  // recursive by default, swallows EEXIST
  } catch (e) {
    // 权限错误只 log，不阻塞。模型的 Write 调用会展示真正的错误
  }
}

系统提示告诉模型目录已存在：

export const DIR_EXISTS_GUIDANCE =
  'This directory already exists — write to it directly with the Write tool '
  + '(do not run mkdir or check for its existence).'

设计意图：源码注释说「Claude was burning turns on ls/mkdir -p before writing」——模型浪费对话轮次去检查目录是否存在。现在系统保证目录存在，模型直接写。

八、语义记忆召回

8.1 召回流程

文件：src/memdir/findRelevantMemories.ts

语义召回使用 Sonnet 做选择（非 embedding），与主模型流式输出并行执行

8.2 选择器 prompt

const SELECT_MEMORIES_SYSTEM_PROMPT =
  `You are selecting memories that will be useful to Claude Code as it `
  + `processes a user's query. Return a list of filenames for the memories `
  + `that will clearly be useful (up to 5). Only include memories that you `
  + `are certain will be helpful. If there are no memories that would clearly `
  + `be useful, return an empty list.`
  + `If a list of recently-used tools is provided, do not select memories `
  + `that are usage reference for those tools — DO still select warnings, `
  + `gotchas, or known issues about those tools.`

8.3 记忆清单格式

// memoryScan.ts:84-94
export function formatMemoryManifest(memories: MemoryHeader[]): string {
  return memories.map(m => {
    const tag = m.type ? `[${m.type}] ` : ''
    const ts = new Date(m.mtimeMs).toISOString()
    return m.description
      ? `- ${tag}${m.filename} (${ts}): ${m.description}`
      : `- ${tag}${m.filename} (${ts})`
  }).join('\n')
}

输出示例：

- [user] user_seandong.md (2026-03-27T10:30:00Z): 用户角色、技术背景和协作偏好
- [feedback] feedback_design_approach.md (2026-03-27T10:30:00Z): 设计方案时的沟通偏好
- [project] project_plugin_status.md (2026-03-27T10:30:00Z): QABOT Plugin 迁移项目状态

8.4 为什么用 Sonnet 而不是 Embedding

记忆文件通常 < 50 个，frontmatter 的 description 就是人工/AI 写的摘要。用 Sonnet 做几十个候选的语义匹配，比维护 embedding 索引更简单、无额外基础设施依赖。

8.5 去重与预算控制

九、自动记忆提取

9.1 架构

文件：src/services/extractMemories/extractMemories.ts

核心设计：不在主对话中提取，而是 fork 一个后台子 agent。

后台 Fork Agent 不干扰主对话，共享 prompt cache 实现近零额外成本

9.2 关键设计决策

9.3 Feature Gates

十、团队记忆同步

10.1 架构

文件：src/services/teamMemorySync/

10.2 安全机制

路径遍历防护（teamMemPaths.ts）：

// 多层防御
function sanitizePathKey(key: string): string {
  // ① null 字节检测（可在 C 层截断路径）
  if (key.includes('\0')) throw new PathTraversalError(...)
  // ② URL 编码遍历检测（%2e%2e%2f = ../)
  const decoded = decodeURIComponent(key)
  if (decoded !== key && (decoded.includes('..') || decoded.includes('/')))
    throw new PathTraversalError(...)
  // ③ Unicode 标准化攻击（全角 ．．／ → ASCII ../ under NFKC）
  const normalized = key.normalize('NFKC')
  if (normalized !== key && normalized.includes('..'))
    throw new PathTraversalError(...)
  // ④ 反斜杠、绝对路径拒绝
}

// 写入前 symlink 验证
async function validateTeamMemWritePath(filePath: string): Promise<string> {
  // Pass 1: path.resolve() 消除 .. 段，字符串级检查
  // Pass 2: realpath() 解析 symlink，验证真实路径在 team 目录内
  //   → 防止 symlink 指向 ~/.ssh/authorized_keys 的攻击
}

凭据扫描：推送前用 30+ 条 gitleaks 规则扫描每个文件（AWS key、GitHub PAT、Anthropic key、Slack token 等）。发现密钥的文件静默跳过，永远不上传到服务器。

十一、记忆的完整生命周期

完整生命周期：创建（3 种方式）→ 存储 → 召回（3 种方式）→ 注入 → 使用 → 清理（3 种方式）

十二、与上下文压缩的协同

12.1 压缩时的记忆保护

12.2 Session Memory 替代 API 调用

Session Memory 在上下文压缩中扮演关键角色——它是预计算的摘要。当 auto-compact 触发时：

1. 有 Session Memory → 用它做摘要，保留最近 10K-40K token 的消息。零额外 API 调用。
2. 无 Session Memory → 调用 API 生成摘要（Fork agent，共享 cache）。

十三、关键源码文件清单

十四、可借鉴的设计模式

文件来源：Claude Code npm 包 source map 泄露快照 (2026-03-31)