Claude Code 技术分析——Memory机制

目录

1. 概述
2. Memory 体系架构
3. Auto Memory 核心模块深度分析
4. Memory 数据流全链路
5. 后台 Memory 提取机制（Extract Memories）
6. Memory 相关性检索（Relevant Memories）
7. 自动整合机制（Auto Dream）
8. Agent Memory 子系统
9. Team Memory 团队记忆
10. Memory 文件格式与类型分类学
11. 安全机制与权限控制
12. 性能优化策略
13. 关键文件索引

---

1. 概述

Claude Code 的 Auto Memory 是一个持久化的、基于文件的 AI 记忆系统，它让 Claude 能够跨会话记住用户的偏好、项目背景、工作习惯等信息。该系统不是简单的键值存储，而是一个多层次的、具有智能提取和检索能力的记忆架构。

核心设计原则

原则	说明
文件即记忆	所有记忆以 Markdown 文件存储在磁盘上，用户可直接查看和编辑
两阶段存储	记忆内容存于独立 topic 文件，索引存于 MEMORY.md 入口文件
自动提取	后台子代理在每轮对话结束后自动从会话中提取值得记住的信息
智能检索	使用 Sonnet 模型进行相关性判断，仅注入最相关的记忆
四类分类法	严格的四种记忆类型：user / feedback / project / reference

---

2. Memory 体系架构

Claude Code 的 Memory 系统包含多个层次，按优先级从低到高加载：

┌─────────────────────────────────────────────────────┐
│  1. Managed Memory                                  │
│     /etc/claude-code/CLAUDE.md                      │
│     (管理员级别的全局策略指令，所有用户都会加载)        │
├─────────────────────────────────────────────────────┤
│  2. User Memory                                     │
│     ~/.claude/CLAUDE.md                             │
│     ~/.claude/rules/*.md                            │
│     (用户私有全局指令，适用于所有项目)                 │
├─────────────────────────────────────────────────────┤
│  3. Project Memory                                  │
│     CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md │
│     (项目级指令，会提交到代码仓库)                     │
├─────────────────────────────────────────────────────┤
│  4. Local Memory                                    │
│     CLAUDE.local.md                                 │
│     (项目级私有指令，不提交到仓库)                     │
├─────────────────────────────────────────────────────┤
│  5. Auto Memory (AutoMem)      ← 本报告核心分析对象   │
│     ~/.claude/projects/<path>/memory/               │
│     (AI 自主管理的持久化记忆系统)                      │
├─────────────────────────────────────────────────────┤
│  6. Team Memory (TeamMem)                           │
│     ~/.claude/projects/<path>/memory/team/          │
│     (团队共享记忆，跨用户同步)                        │
├─────────────────────────────────────────────────────┤
│  7. Agent Memory                                    │
│     ~/.claude/agent-memory/<agentType>/             │
│     <cwd>/.claude/agent-memory/<agentType>/         │
│     (子代理的持久化记忆，按 agent 类型隔离)            │
└─────────────────────────────────────────────────────┘

加载顺序：Managed → User → Project（从根目录到 CWD 遍历）→ Local → AutoMem → TeamMem

优先级规则：后加载的文件优先级更高，离当前工作目录越近的文件越后加载，因此具有更高优先级。

MemoryType 类型定义

// src/utils/memory/types.ts
export const MEMORY_TYPE_VALUES = [
  'User',       // 用户全局指令
  'Project',    // 项目级指令
  'Local',      // 项目级私有指令
  'Managed',    // 管理员策略指令
  'AutoMem',    // AI 自动记忆
  'TeamMem',    // 团队共享记忆
] as const

---

3. Auto Memory 核心模块深度分析

3.1 路径管理（src/memdir/paths.ts）

Auto Memory 的存储路径遵循以下解析链：

解析顺序（第一匹配生效）：
1. CLAUDE_CODE_REMOTE_MEMORY_DIR 环境变量        → 用于远程模式
2. CLAUDE_COWORK_MEMORY_PATH_OVERRIDE 环境变量    → 用于 Cowork 场景
3. settings.json 中的 autoMemoryDirectory         → 用户自定义路径
4. 默认路径：~/.claude/projects/<sanitized-git-root>/memory/

关键函数：

// 判断 Auto Memory 是否启用
export function isAutoMemoryEnabled(): boolean {
  // 优先级链：
  // 1. CLAUDE_CODE_DISABLE_AUTO_MEMORY 环境变量
  // 2. CLAUDE_CODE_SIMPLE (--bare) 模式 → 关闭
  // 3. 远程模式无持久存储 → 关闭
  // 4. settings.json 中的 autoMemoryEnabled 设置
  // 5. 默认：启用
}

// 获取 Auto Memory 目录路径（带缓存）
export const getAutoMemPath = memoize((): string => {
  const override = getAutoMemPathOverride() ?? getAutoMemPathSetting()
  if (override) return override
  const projectsDir = join(getMemoryBaseDir(), 'projects')
  return join(projectsDir, sanitizePath(getAutoMemBase()), 'memory') + sep
})

// 获取入口文件路径
export function getAutoMemEntrypoint(): string {
  return join(getAutoMemPath(), 'MEMORY.md')
}

存储目录结构示例：

~/.claude/projects/
  github.com_anthropics_claude-code/
    memory/                        ← Auto Memory 根目录
      MEMORY.md                    ← 索引入口文件
      user_role.md                 ← 用户角色记忆
      feedback_testing.md          ← 反馈记忆
      project_auth_rewrite.md      ← 项目背景记忆
      team/                        ← Team Memory 子目录
        MEMORY.md
        deploy_policy.md
      logs/                        ← KAIROS 模式下的日志
        2026/
          04/
            2026-04-01.md

3.2 入口文件管理（src/memdir/memdir.ts）

MEMORY.md 索引文件

MEMORY.md 是 Auto Memory 的索引文件，不是记忆内容本身。它充当目录角色：

- [User Role](user_role.md) — senior data scientist focused on observability
- [Testing Policy](feedback_testing.md) — integration tests must hit real DB
- [Auth Rewrite](project_auth_rewrite.md) — compliance-driven middleware replacement

限制：

• 最大 200 行
• 最大 25,000 字节
• 超出部分会被截断并附加警告

// src/memdir/memdir.ts
export const MAX_ENTRYPOINT_LINES = 200
export const MAX_ENTRYPOINT_BYTES = 25_000

export function truncateEntrypointContent(raw: string): EntrypointTruncation {
  // 先按行数截断，再按字节数截断
  // 截断后附加警告信息
}

Prompt 构建

Auto Memory 的行为指令通过 buildMemoryLines() 和 buildMemoryPrompt() 构建：

// 为主会话构建（不含内容，内容通过 user context 注入）
buildMemoryLines(displayName, memoryDir, extraGuidelines, skipIndex)

// 为 Agent 构建（包含 MEMORY.md 内容，同步读取嵌入）
buildMemoryPrompt({ displayName, memoryDir, extraGuidelines })

3.3 Memory 类型分类学（src/memdir/memoryTypes.ts）

所有记忆被严格分为四种类型，每种类型有明确的存储时机、使用方式和示例：

四种记忆类型

类型	用途	示例
user	用户角色、目标、偏好	“用户是高级数据科学家，关注可观测性”
feedback	用户给出的行为指导	“集成测试必须用真实数据库，不要 mock”
project	不可从代码推导的项目背景	“合并冻结从 2026-03-05 开始”
reference	外部系统的指针	“流水线 bug 在 Linear 项目 INGEST 中追踪”

Frontmatter 格式

每个记忆文件使用 YAML frontmatter：

---
name: Testing Policy
description: Integration tests must hit a real database, not mocks
type: feedback
---

Integration tests must hit a real database, not mocks.

**Why:** Prior incident where mock/prod divergence masked a broken migration.

**How to apply:** When writing tests that touch the database layer, always configure
them to connect to a real test database instance rather than using in-memory mocks.

不应保存的内容

系统明确定义了不应作为记忆保存的内容（WHAT_NOT_TO_SAVE_SECTION）：

• 代码模式、约定、架构（可通过读取代码推导）
• Git 历史（可通过 git log 获取）
• 调试解决方案（修复已在代码中）
• 已在 CLAUDE.md 中记录的内容
• 临时任务细节

3.4 Memory 文件扫描（src/memdir/memoryScan.ts）

扫描 memory 目录下的所有 .md 文件，读取 frontmatter 头部信息，返回排序后的文件清单：

export async function scanMemoryFiles(
  memoryDir: string,
  signal: AbortSignal,
): Promise<MemoryHeader[]> {
  // 1. 递归读取目录中的 .md 文件（排除 MEMORY.md）
  // 2. 并行读取每个文件的前 30 行（frontmatter 区域）
  // 3. 解析 frontmatter 提取 name/description/type
  // 4. 按 mtime 降序排序
  // 5. 最多返回 200 个文件
}

输出的 Manifest 格式供选择器使用：

- [feedback] feedback_testing.md (2026-03-15T10:00:00.000Z): Integration tests must hit real DB
- [user] user_role.md (2026-03-10T08:00:00.000Z): Senior data scientist

3.5 Memory 新鲜度管理（src/memdir/memoryAge.ts）

记忆可能过时，系统通过新鲜度标记帮助模型判断记忆的可靠性：

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...`
}

超过 30 天的记忆会被标记为 “stale”：

(stale - over 30 days old)
Memory: /path/to/memory.md

---

4. Memory 数据流全链路

4.1 写入流程

用户对话中产生有价值信息
         │
         ├──→ 主代理直接写入（主代理 prompt 包含完整的保存指令）
         │         │
         │         └──→ hasMemoryWritesSince() 检测到直接写入
         │              → extractMemories 跳过该轮
         │
         └──→ 主代理未写入
              │
              └──→ extractMemories 后台子代理
                    │
                    ├──→ scanMemoryFiles() 获取现有记忆清单
                    ├──→ buildExtractAutoOnlyPrompt() / buildExtractCombinedPrompt()
                    ├──→ runForkedAgent() 运行提取子代理（最多 5 轮）
                    │       │
                    │       ├──→ 读取可能需要更新的文件
                    │       └──→ 写入/更新记忆文件 + 更新 MEMORY.md
                    │
                    └──→ createMemorySavedMessage() 通知 UI

4.2 读取/注入流程

用户发送消息
       │
       ├─[并行]─→ startRelevantMemoryPrefetch()
       │              │
       │              ├──→ scanMemoryFiles() 扫描记忆文件头
       │              ├──→ findRelevantMemories()
       │              │       │
       │              │       └──→ selectRelevantMemories()
       │              │               │
       │              │               └──→ sideQuery(Sonnet)
       │              │                   "选择最相关的5个记忆文件"
       │              │
       │              └──→ readMemoriesForSurfacing()
       │                      │
       │                      └──→ 读取文件内容（带行数/字节截断）
       │
       ├─→ 主模型运行（工具执行等）
       │
       └─→ 工具执行后：poll prefetch.settledAt
              │
              ├──→ filterDuplicateMemoryAttachments() 去重
              └──→ 注入 system-reminder 消息
                    "Memory (saved 3 days ago): /path/to/file.md
                     <记忆内容>"

4.3 CLAUDE.md 加载流程

getMemoryFiles()（带 memoize 缓存）
       │
       ├──→ 加载 Managed 文件 (/etc/claude-code/CLAUDE.md)
       ├──→ 加载 Managed rules (/etc/claude-code/rules/*.md)
       ├──→ 加载 User 文件 (~/.claude/CLAUDE.md)
       ├──→ 加载 User rules (~/.claude/rules/*.md)
       ├──→ 从 root 到 CWD 遍历每个目录：
       │       ├──→ CLAUDE.md (Project)
       │       ├──→ .claude/CLAUDE.md (Project)
       │       ├──→ .claude/rules/*.md (Project)
       │       └──→ CLAUDE.local.md (Local)
       ├──→ 加载 AutoMem 入口 (MEMORY.md)
       └──→ 加载 TeamMem 入口

---

5. 后台 Memory 提取机制（Extract Memories）

5.1 概述

extractMemories 是一个在每轮对话结束后自动运行的后台子代理，它分析最近的对话内容，提取值得跨会话持久化的信息并写入 memory 目录。

源文件：src/services/extractMemories/extractMemories.ts（615 行）

5.2 运行机制

handleStopHooks (stopHooks.ts)
       │
       └──→ executeExtractMemories(context, appendSystemMessage)
              │
              ├──→ 检查条件：
              │     - 仅主代理运行（非子代理）
              │     - feature flag 'tengu_passport_quail' 启用
              │     - autoMemory 已启用
              │     - 非远程模式
              │
              ├──→ 互斥检测：
              │     hasMemoryWritesSince() 检查主代理是否已直接写入
              │     → 如果是，跳过并推进游标
              │
              ├──→ 节流控制：
              │     turnsSinceLastExtraction 计数器
              │     由 'tengu_bramble_lintel' 控制（默认每轮都运行）
              │
              ├──→ 运行 forked agent：
              │     runForkedAgent({
              │       promptMessages: [提取 prompt],
              │       maxTurns: 5,      // 最多5轮
              │       querySource: 'extract_memories',
              │       skipTranscript: true,
              │     })
              │
              └──→ 后续处理：
                    - 提取写入的文件路径
                    - 发送 'tengu_extract_memories_extraction' 遥测事件
                    - 通过 appendSystemMessage 通知 UI

5.3 工具权限沙箱

提取子代理的权限被严格限制：

export function createAutoMemCanUseTool(memoryDir: string): CanUseToolFn {
  // 允许：Read、Grep、Glob（无限制，只读）
  // 允许：Bash（仅只读命令：ls/find/cat/stat/wc/head/tail）
  // 允许：Edit/Write（仅限 memoryDir 内的路径）
  // 拒绝：所有其他工具（MCP、Agent、写操作 Bash 等）
}

5.4 闭包作用域状态管理

提取器使用闭包作用域管理内部状态（而非模块级变量），便于测试隔离：

export function initExtractMemories(): void {
  const inFlightExtractions = new Set<Promise<void>>()
  let lastMemoryMessageUuid: string | undefined  // 游标
  let inProgress = false                          // 互斥锁
  let turnsSinceLastExtraction = 0                // 节流计数
  let pendingContext                              // 暂存上下文

  // ... 内部函数定义 ...
  extractor = async (context, appendSystemMessage) => { ... }
}

5.5 尾随执行（Trailing Run）

当提取正在运行时，新到的请求会被暂存。当前提取完成后，会自动执行一次尾随提取：

// 在 runExtraction 的 finally 块中
const trailing = pendingContext
pendingContext = undefined
if (trailing) {
  await runExtraction({
    context: trailing.context,
    isTrailingRun: true,  // 跳过节流检查
  })
}

---

6. Memory 相关性检索（Relevant Memories）

6.1 概述

findRelevantMemories 使用 AI 模型（Sonnet）从大量记忆文件中筛选出与当前用户查询最相关的前 5 个。

源文件：src/memdir/findRelevantMemories.ts（141 行）

6.2 工作流程

1. scanMemoryFiles() → 扫描所有记忆文件头
2. 过滤已展示过的文件（alreadySurfaced）
3. formatMemoryManifest() → 格式化为文本清单
4. selectRelevantMemories() → 发送 side query 给 Sonnet
5. 验证返回的文件名是否有效
6. 返回选中文件的路径 + mtimeMs

6.3 Sonnet 选择器 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."

输入包含：用户查询 + 记忆清单 + 最近使用的工具列表。

6.4 去重机制

// src/utils/attachments.ts
export function filterDuplicateMemoryAttachments(
  attachments: Attachment[],
  readFileState: FileStateCache,
): Attachment[] {
  // 过滤掉模型已通过 FileRead/FileEdit/FileWrite 访问过的文件
  // 将新的记忆文件标记到 readFileState（100 条 LRU 缓存）
}

---

7. 自动整合机制（Auto Dream）

7.1 概述

Auto Dream 是一个后台记忆整合服务，它会定期运行 forked agent 来清理、合并和优化记忆文件。

源文件：src/services/autoDream/autoDream.ts

7.2 触发条件（三重门控）

门控	条件	默认值
时间门控	距上次整合 ≥ minHours	24 小时
会话门控	距上次整合的会话数 ≥ minSessions	5 次
锁门控	没有其他进程正在进行整合	—

7.3 整合流程（四阶段）

Phase 1: Orient（定位）
  ├── ls memory 目录
  └── 读取 MEMORY.md 索引

Phase 2: Gather（收集）
  ├── 检查日志文件
  ├── 识别已漂移的记忆
  └── 搜索会话转录记录

Phase 3: Consolidate（整合）
  ├── 写入/更新主题文件
  ├── 合并信号
  └── 修复矛盾

Phase 4: Prune and Index（清理与索引）
  ├── 保持 MEMORY.md 在限制内
  └── 移除过时指针

7.4 /dream 和 /remember 技能

用户可主动调用的两个内置 Skill：

• /dream：触发记忆整合（在此 recovery build 中不可用）
• /remember：审查所有 memory 层级，生成变更提案报告（不直接修改）

/remember 的流程：

1. 收集所有 memory 层（CLAUDE.md + CLAUDE.local.md + Auto Memory）
2. 对每个 auto-memory 条目分类目标位置
3. 识别重复、过时、冲突条目
4. 生成结构化报告供用户审批

---

8. Agent Memory 子系统

8.1 概述

Agent Memory 是为**子代理（Sub-Agent）**设计的独立记忆系统，按代理类型隔离，与主会话的 Auto Memory 分离。

源文件：src/tools/AgentTool/agentMemory.ts

8.2 三种作用域

作用域	路径	特点
user	~/.claude/agent-memory/<agentType>/	跨项目，仅限当前用户
project	<cwd>/.claude/agent-memory/<agentType>/	版本控制，团队共享
local	<cwd>/.claude/agent-memory-local/<agentType>/	项目级但不在 VCS 中

8.3 快照初始化

Agent Memory 支持快照种子化机制（agentMemorySnapshot.ts）：

.claude/agent-memory-snapshots/<agentType>/snapshot.json

当项目配置了快照时：

• initialize：本地无记忆时，从快照复制初始文件
• prompt-update：本地记忆存在但快照更新时，提示更新
• none：已同步或无快照

这使得团队可以预配置 Agent 的"起始记忆"。

8.4 注入方式

Agent Memory 与主会话 Memory 的关键区别：

	主会话 Auto Memory	Agent Memory
内容注入	通过 user context 消息	同步读取并嵌入 system prompt 字符串
Prompt 构建器	buildMemoryLines()	buildMemoryPrompt()（含同步文件读取）
Team Memory 支持	是	否
提取机制	extractMemories 后台子代理	无（依赖 Agent 自行写入）

---

9. Team Memory 团队记忆

9.1 概述

Team Memory 是 Auto Memory 的扩展，支持团队成员之间共享记忆。

源文件：src/memdir/teamMemPaths.ts

9.2 启用条件

isTeamMemoryEnabled() = isAutoMemoryEnabled() && feature('tengu_herring_clock')

需要同时满足：Auto Memory 已启用 + feature flag 开启。

9.3 存储结构

~/.claude/projects/<path>/memory/       ← 私有记忆
                               team/     ← 团队记忆（子目录）
                                 MEMORY.md
                                 deploy_policy.md

9.4 安全验证

Team Memory 的写入路径经过多层安全检查：

validateTeamMemWritePath(filePath) {
  // 1. 空字节拒绝
  // 2. 路径遍历检测（.. 段）
  // 3. URL 编码遍历检测
  // 4. Unicode 标准化攻击（NFKC 全角字符）
  // 5. 符号链接逃逸检测（realpathDeepestExisting）
}

---

10. Memory 文件格式与类型分类学

10.1 CLAUDE.md 系列

文件	用途	提交到 VCS
CLAUDE.md	项目级公开指令	是
.claude/CLAUDE.md	项目级公开指令（替代位置）	是
.claude/rules/*.md	条件规则（支持 frontmatter paths）	是
CLAUDE.local.md	项目级私有指令	否（gitignore）
~/.claude/CLAUDE.md	用户全局指令	N/A

10.2 条件规则（Conditional Rules）

.claude/rules/ 目录下的 .md 文件可包含 frontmatter 中的 paths 字段，指定该规则仅对匹配的文件路径生效：

---
paths:
  - "src/api/**"
  - "src/routes/**"
---

API 路由使用 kebab-case 命名约定。
所有 API 响应必须包含 request-id 头。

10.3 @include 指令

Memory 文件支持通过 @ 语法引入其他文件：

@include 语法：
  @path             → 相对路径
  @./relative/path  → 相对路径
  @~/home/path      → 主目录路径
  @/absolute/path   → 绝对路径

特性：

• 最大嵌套深度：5 层
• 循环引用检测通过 processedPaths Set 实现
• 仅支持文本文件扩展名（白名单机制，包含 80+ 种格式）
• 忽略代码块和代码字符串中的 @ 引用

10.4 排除机制

用户可通过 claudeMdExcludes 设置排除特定的 CLAUDE.md 文件：

{
  "claudeMdExcludes": [
    "/home/user/monorepo/CLAUDE.md",
    "**/code/CLAUDE.md"
  ]
}

排除仅适用于 User、Project、Local 类型，不适用于 Managed、AutoMem、TeamMem。

---

11. 安全机制与权限控制

11.1 文件系统权限沙箱

Auto Memory 文件享有特殊的文件系统写入权限（绕过 DANGEROUS_DIRECTORIES 限制）：

// filesystem.ts 中的写入豁免
// isAutoMemPath(filePath) 为 true 时允许写入
// 但当 CLAUDE_COWORK_MEMORY_PATH_OVERRIDE 设置时不适用此豁免

11.2 路径验证（validateMemoryPath）

function validateMemoryPath(raw, expandTilde): string | undefined {
  // 拒绝：相对路径、根路径、Windows 驱动器根、UNC 路径、空字节
  // 支持 ~/ 展开但拒绝展开到 HOME 或其祖先的路径
}

11.3 Settings 安全层级

autoMemoryDirectory 设置仅接受来自可信源的配置：

function getAutoMemPathSetting(): string | undefined {
  // 接受的源（按优先级）：
  // 1. policySettings（管理员策略）
  // 2. flagSettings（功能标志）
  // 3. localSettings（本地配置）
  // 4. userSettings（用户配置）
  // ❌ 不接受 projectSettings（.claude/settings.json 提交到仓库）
  //    防止恶意仓库将记忆路径指向 ~/.ssh 等敏感目录
}

11.4 提取子代理权限

提取子代理的工具使用权限：

✅ Read / Grep / Glob — 无限制
✅ Bash — 仅只读命令
✅ Edit / Write — 仅限 memory 目录内
❌ MCP、Agent、写操作 Bash 等 — 全部拒绝
❌ Bash rm — 不允许删除

---

12. 性能优化策略

12.1 Memoize 缓存

// getMemoryFiles 使用 lodash memoize
export const getMemoryFiles = memoize(async (): Promise<MemoryFileInfo[]> => {
  // 只在首次调用或缓存清除后重新加载
})

// getAutoMemPath 使用 lodash memoize（按 projectRoot 为 key）
export const getAutoMemPath = memoize((): string => {
  // 按 projectRoot 缓存，测试中可手动清除
})

12.2 预取并行

Relevant memories 的检索与主模型运行并行执行：

// src/query.ts
using pendingMemoryPrefetch = startRelevantMemoryPrefetch(messages, context)
// 主模型运行...
// 工具执行后 poll prefetch.settledAt（非阻塞）

12.3 入口文件截断

// MEMORY.md 双重限制
MAX_ENTRYPOINT_LINES = 200    // 行数限制
MAX_ENTRYPOINT_BYTES = 25_000 // 字节限制

12.4 扫描优化

// 单次扫描：readFileInRange 内部 stat 并返回 mtimeMs
// 避免 stat-sort-read 的双倍系统调用
const MAX_MEMORY_FILES = 200       // 文件数上限
const FRONTMATTER_MAX_LINES = 30   // 仅读取前30行获取 frontmatter

12.5 Prompt Cache 友好

• 相关性检索使用预计算的 header（header 字段），保持跨轮次稳定，提高 prompt cache 命中率
• systemPromptSection('memory', ...) 缓存 prompt 构建
• 提取子代理使用 runForkedAgent 共享父级 prompt cache

12.6 节流与合并

// 提取器
turnsSinceLastExtraction++         // 节流
if (inProgress) pendingContext = ... // 合并：暂存最新上下文
// finally: 执行 trailing run

---

13. 关键文件索引

文件路径	行数	职责
src/memdir/paths.ts	278	Auto Memory 路径解析、启停控制
src/memdir/memdir.ts	507	Prompt 构建、目录管理、入口文件截断
src/memdir/memoryTypes.ts	271	四种记忆类型定义与 prompt 段落
src/memdir/findRelevantMemories.ts	141	Sonnet 相关性选择器
src/memdir/memoryScan.ts	94	记忆文件扫描与清单格式化
src/memdir/memoryAge.ts	53	记忆新鲜度计算与警告文本
src/memdir/teamMemPaths.ts	—	Team Memory 路径与安全验证
src/memdir/teamMemPrompts.ts	—	组合模式 prompt 构建
src/utils/claudemd.ts	1479	CLAUDE.md 加载核心（所有层级）
src/utils/memoryFileDetection.ts	289	记忆文件检测与分类
src/utils/memory/types.ts	12	MemoryType 类型定义
src/utils/attachments.ts	~2500	记忆附件注入、预取、去重
src/services/extractMemories/extractMemories.ts	615	后台记忆提取子代理
src/services/extractMemories/prompts.ts	154	提取 prompt 模板
src/services/autoDream/autoDream.ts	324	自动记忆整合
src/tools/AgentTool/agentMemory.ts	—	子代理记忆系统
src/tools/AgentTool/agentMemorySnapshot.ts	—	代理记忆快照种子化
src/skills/bundled/remember.ts	82	/remember 技能
src/skills/bundled/dream.ts	15	/dream 技能（recovery build）
src/commands/memory/memory.tsx	90	/memory 命令 UI

---

总结

Claude Code 的 Auto Memory 系统是一个精心设计的多层记忆架构，其核心特点：

1. 多层次设计：从系统管理到个人偏好，从项目级到团队级，每个层次都有明确的职责和作用域
2. AI 驱动的提取与检索：不是简单的全文搜索，而是使用 Sonnet 模型进行语义级的相关性判断
3. 严格的类型约束：四种记忆类型确保系统存储的是真正有价值的、不可从代码推导的上下文
4. 安全优先：多层安全验证、权限沙箱、路径校验确保记忆系统不被滥用
5. 性能优化：memoize 缓存、并行预取、prompt cache 友好设计、节流合并等策略
6. 可观测性：丰富的遥测事件覆盖记忆系统的每个关键操作

该系统体现了"让 AI 自主管理知识"的设计哲学——AI 自己决定什么值得记住、什么时候检索、何时整合优化，同时通过严格的类型约束和安全机制保持可控性。