Claude Code Memory 深潜：CLAUDE.md、Auto Memory 与渐进式上下文披露

0.1 本文要回答的十个问题#

1. CLAUDE.md、Auto Memory 和 Conversation Compaction 分别解决什么问题？
2. Managed、User、Project、Local 与 Nested Instructions 如何组合？
3. 为什么“离当前目录更近”不等于数据库式覆盖？
4. @path Import 是模块化，还是 Token 优化？
5. .claude/rules/ 如何实现路径级渐进披露？
6. 为什么 MEMORY.md 只加载前 200 行或 25 KB？
7. Topic Files 如何把 Hot Index 和 Cold Evidence 分开？
8. /compact 之后哪些指令会恢复，哪些需要再次触发？
9. 文件记忆如何被审计、污染、冲突或跨 Worktree 共享？
10. 大型 Monorepo 应如何设计一套可测试的 Instruction Architecture？

1.1 Control Plane、Data Plane 与 Working Set#

可以把三类机制进一步映射为：

1
Managed Settings / Permission Rules
2
        → Enforcement Control Plane
3

4
CLAUDE.md / .claude/rules
5
        → Behavioral Instruction Plane
6

7
Auto Memory
8
        → Learned Experience Plane
9

10
Conversation + Tool Results + Compaction
11
        → Current Working Set

官方明确说明：Managed Settings 可以禁止工具、路径或命令，CLAUDE.md 只是在 Context 中塑造行为，并不是客户端强制执行层。[C1][C3]

这条边界非常关键：

Policy 必须由 Runtime Enforcement 保证；Memory 只能影响模型决策，不能替代权限系统。

2.1 五种 Scope 不是五种优先级覆盖表#

Managed Policy 的“不可由个人排除”来自客户端设置层，而不是因为它在 Prompt 中拥有某种不可违背的系统消息权重。[C1][C3]

2.2 启动加载与按需加载必须区分#

官方行为契约给出两条路径：[C1]

1
祖先目录中的 CLAUDE.md
2
→ 启动时完整加载
3

4
当前目录之下子目录中的 CLAUDE.md
5
→ Claude 读取该子目录文件时按需加载

这是一种典型的 Progressive Disclosure：

• 仓库根规则进入 Hot Context；
• 子模块规则保持 Cold；
• 文件访问事件成为加载触发器；
• 同一个会话的可见指令集会随工作路径变化。

如果把全部子项目规则都塞进根文件，Monorepo 的 Instruction Cost 会接近：

$C_{startup}=\sum_{i=1}^{N} tokens(rule_i)$

按路径触发后，启动成本更接近：

$C_{startup}=tokens(root)+tokens(shared)$

而任务增量成本为：

$C_{task}=\sum_{i \in matched\ paths} tokens(rule_i)$

2.3 一个行为级 Loader 还原#

下面是依据官方发现与拼接规则整理的行为级伪代码，不是 Claude Code 原始源码：

1
def build_startup_instructions(cwd, settings):
2
    project_root = resolve_project_root(cwd)
3
    layers = []
4

5
    layers += load_managed_policy(settings)
6
    layers += load_user_instructions("~/.claude/CLAUDE.md", settings)
7
    layers += load_unscoped_rules("~/.claude/rules", settings)
8

9
    for directory in walk_from_fs_root_to(cwd):
10
        # 项目根还支持 .claude/CLAUDE.md 这一存放形式。
11
        for path in discover_directory_instructions(directory, project_root):
12
            if exists(path) and not excluded(path, settings):
13
                layers += expand_imports(path, max_depth=4)
14

15
    layers += load_unscoped_rules(project_root / ".claude/rules", settings)
16
    return concatenate(layers)
17

18

19
def on_file_read(path):
20
    load_nested_claude_files_for(path)
21
    activate_path_scoped_rules_matching(path)

这个模型揭示了一个常被忽略的问题：Context 不是启动时一次性固定的。Nested Instructions 让 Instruction Set 成为随工具访问动态变化的工作集。

3.1 为什么相对路径基准很重要#

假设：

1
repo/
2
├── CLAUDE.md
3
└── docs/
4
    ├── agent.md
5
    └── rules/
6
        └── testing.md

docs/agent.md 中写：

1
@rules/testing.md

正确解析目标是：

1
repo/docs/rules/testing.md

如果错误地以 repo/ 或进程 CWD 为基准，同一指令文件在不同启动位置会加载不同内容，Instruction Build 将不再可复现。

3.2 Import 不降低 Token 成本#

官方明确提醒：Import 适合组织内容，但被引入文件仍在启动时展开并进入 Context。[C1]

所以：

1
Split by @import
2
→ improves maintainability
3
→ does not automatically reduce startup tokens

如果目标是减少 Context，应该使用：

• Nested CLAUDE.md 的目录触发；
• .claude/rules/ 的 paths Frontmatter；
• Auto Memory 的 Topic Files；
• Agent 主动读取而不是 Always-on 注入。

3.3 Import 是一个供应链入口#

外部绝对路径 Import 能把 Home Directory、共享配置或工作区外规则引入 Prompt。这带来三个风险：

1. 内容漂移：外部文件变化不经过当前仓库 Review；
2. 信任扩散：项目成员看到 @path，却未必拥有同一文件；
3. Prompt Supply Chain：被引入内容可以改变工具决策，但不会出现在当前仓库 Diff 中。

外部 Import 首次审批是一道重要信任门，但生产治理还应记录：

1
source_path
2
content_hash
3
approved_by
4
approved_at
5
loaded_at

官方目前承诺的是审批行为，不等于提供完整的版本锁定与变更审计。

4.1 Rules 是 Retrieval Router，不只是文件拆分#

可以把路径规则理解成一个确定性 Retriever：

1
Current File Path
2
→ Glob Match
3
→ Applicable Instruction Set
4
→ Context Injection

它和 Vector Retrieval 的差别是：

对于 Coding Agent，文件路径本身携带强结构信号，因此确定性 Routing 往往比“把所有规范做 Embedding”更可靠。

4.2 Symlink 与大型仓库边界#

官方文档说明 .claude/rules/ 支持 Symlink，循环 Symlink 会被检测；新版本还支持通过指向项目的 Symlink Path 触发 paths 匹配。[C1]

这意味着规则匹配不能只比较未经规范化的字符串路径。一个合理的行为模型至少需要：

1
Input Path
2
→ Resolve / Normalize
3
→ Detect Symlink Cycle
4
→ Establish Project Boundary
5
→ Glob Match

在大型 Monorepo 中，claudeMdExcludes 可以跳过无关祖先文件或其他团队的规则目录；Managed Policy 文件不能被排除。[C1]

5.1 MEMORY.md 是 Index，不是无限正文#

每次新会话启动时，只加载 MEMORY.md 的：

1
前 200 行
2
或
3
前 25 KB
4
取先到者

这个限制只针对 Auto Memory 的 MEMORY.md。CLAUDE.md 仍会完整加载，只是官方建议每个文件尽量低于 200 行以减少 Context 成本和规则失遵。[C1]

MEMORY.md 的工程角色更接近：

1
Compact Registry
2
+ Routing Summary
3
+ Most Valuable Always-on Lessons

详细信息移动到 Topic Files 后，由 Agent 根据索引按需读取。

5.2 两级读取路径#

1
flowchart LR
2
    S["Session Start"] --> C["CLAUDE.md Loader"]
3
    S --> M["MEMORY.md: first 200 lines or 25 KB"]
4
    C --> H["Hot Context"]
5
    M --> H
6
    H --> D{"Need detailed memory?"}
7
    D -->|"yes"| T["Read topic file on demand"]
8
    T --> W["Current working context"]
9
    D -->|"no"| W
10
    F["File access"] --> R["Load nested rules"]
11
    R --> W

这是一种非常实用的 Cache Hierarchy：

5.3 一个行为级 Write Path#

官方没有公开完整内部写路径。根据其行为契约，只能严谨还原到：

1
Conversation / Tool Observation
2
→ Claude judges future usefulness
3
→ Write or update MEMORY.md / topic file
4
→ Future session loads bounded index
5
→ Agent may read topic file on demand

生产系统还需要但官方文档未承诺的能力包括：

• 多进程 File Lock；
• Optimistic Version Check；
• Mutation Log；
• Write-time Secret Detection；
• Topic File Garbage Collection；
• 跨机器同步冲突解决。

这些不能被写成 Claude Code 已实现，只能作为 File Memory 的生产化补强。

5.4 /memory 是最小治理面#

/memory 会列出当前会话加载的 CLAUDE.md、CLAUDE.local.md 和 Rules 文件，并提供 Auto Memory 开关与目录入口。Auto Memory 文件是普通 Markdown，可由用户审计、编辑或删除。[C1]

这使系统获得三个重要性质：

• Inspectable：人可以看到 Agent 记了什么；
• Correctable：错误记忆可直接修正；
• Deletable：不需要调用专有数据库 API 才能删除。

但“文件已删除”是否等于“当前 Context 已清除”仍要区分：已经注入本轮 Context 的内容不会因为磁盘文件删除而自动从模型输入中撤回。

同一套有界索引模式还可以隔离到 Subagent。Subagent Frontmatter 可声明 memory: user|project|local，Claude Code 会按 Subagent 名称建立独立目录，在启动时注入其 MEMORY.md 的前 200 行或 25 KB，并自动开放 Read、Write、Edit 工具供其维护记忆。[C5] 这让代码审查、测试或架构分析等角色可以分别积累经验，而不是把所有角色状态混入主 Agent；其中 project Scope 可进入版本控制，也应按仓库贡献者可修改的输入来治理。

6.1 Worktree 共享会产生并发写入面#

官方说明同一 Git Repository 的 Worktree 和子目录共享一个 Auto Memory Directory。[C1]

如果两个 Claude Code Session 同时更新 MEMORY.md：

1
Session A reads v1
2
Session B reads v1
3
Session A writes v2
4
Session B writes v3 based on v1

没有锁或版本校验时，A 的更新可能被覆盖。这是由官方存储边界推导出的并发风险，不代表官方文档确认存在该 Bug。

一个生产级写入协议应至少是：

1
Read(content, hash)
2
→ Build mutation
3
→ Lock project memory
4
→ Re-read current hash
5
→ Reject or merge on drift
6
→ Atomic replace
7
→ Append audit event

6.2 机器本地意味着可用性优先于分布式一致性#

Auto Memory 没有形成多副本分布式系统，因此严格来说这不是 CAP 定理中的一致性取舍。它做的是更直接的产品选择：用无跨机器协调换取本地可用性和低延迟，代价是没有跨机器一致性：

• 本地读写简单、低延迟；
• 不需要中央服务；
• 离线可用；
• 但换机器后没有相同经验；
• 团队无法天然共享 Agent 自己积累的知识；
• 备份与删除证明由本地文件系统负责。

需要跨机器共享的团队事实应该优先进入 Version-controlled CLAUDE.md、Rules、文档或受治理的外部 Memory Service，而不是假设 Auto Memory 是团队知识库。

6.3 Index Drift#

当 MEMORY.md 指向已经删除、改名或内容漂移的 Topic File，会产生：

1
Registry says memory exists
2
but evidence cannot be loaded

可观测指标应包括：

1
broken_topic_link_count
2
orphan_topic_file_count
3
memory_index_bytes
4
memory_index_lines
5
topic_read_hit_rate
6
stale_memory_correction_rate

7.1 三类状态的恢复语义#

因此，希望跨会话或跨 Compaction 稳定存在的关键约束，不应只出现在 Conversation 中。

8.1 信任域必须分层#

1
Managed Policy
2
→ organization-controlled
3

4
Repository CLAUDE.md / Rules
5
→ repository contributor-controlled
6

7
CLAUDE.local.md
8
→ local user-controlled
9

10
Auto Memory
11
→ model-written from observed content
12

13
External Import
14
→ external file owner-controlled

最危险的错误是把所有层都当成“可信系统提示词”。

8.2 Auto Memory Poisoning#

可能的攻击链：

1
Untrusted issue / webpage / repository text
2
→ model treats instruction as useful lesson
3
→ writes persistent auto memory
4
→ malicious guidance survives future sessions
5
→ later tool decision is influenced

文件可读可删降低了恢复难度，但不能阻止写入发生。生产化防护应包括：

• 写入时标注来源类型与 Trust Label；
• 外部内容不得直接升级为行为指令；
• Secret / Credential Pattern 检测；
• 高风险 Mutation 进入 Quarantine；
• 周期性 Diff 与异常写入速率告警；
• 工具权限独立于 Memory 内容执行。

这些措施对应的是持久化 Prompt Injection 的分层防护，而不是依赖某一个字符串过滤器证明 Memory 安全。[C6]

8.3 Managed Settings 与 Managed Instructions 的职责#

“禁止”与“建议”不能只靠措辞强度区分，必须由不同 Runtime 层承载。

9.1 推荐目录#

1
repo/
2
├── CLAUDE.md                  # 全局不变量、路由索引、关键命令
3
├── .claude/
4
│   ├── rules/
5
│   │   ├── security.md        # Always-on
6
│   │   ├── java.md            # paths: **/*.java
7
│   │   ├── frontend.md        # paths: apps/web/**
8
│   │   └── database.md        # paths: migrations/**
9
│   └── settings.json
10
├── services/
11
│   ├── billing/CLAUDE.md      # Billing 局部不变量
12
│   └── identity/CLAUDE.md     # Identity 局部不变量
13
└── AGENTS.md                  # 通过根 CLAUDE.md 显式导入

9.2 根文件只保留“不可从代码廉价推导”的信息#

适合保留：

• 构建或测试中的反直觉前置条件；
• 容易造成生产事故的架构约束；
• 团队明确选择及其理由；
• 常见失败路径；
• 进入详细规则的路由说明。

不适合长期重复：

• 可由 package.json、Gradle 或目录结构直接读出的事实；
• 生成后很快漂移的文件清单；
• 每个模块的完整 API 文档；
• 没有明确行为影响的背景介绍。

9.3 Conflict Matrix#

每条重要规则应能回答：

如果一条规则只有 Prompt 文本、没有测试或 Runtime Enforcement，就应明确标注为 Best-effort Instruction。

10.1 建议记录的事件字段#

1
{
2
  "session_id": "...",
3
  "instruction_path": "...",
4
  "scope": "project|local|nested|rule|managed",
5
  "load_reason": "startup|path_match|post_compaction|manual",
6
  "content_hash": "sha256:...",
7
  "bytes": 2310,
8
  "loaded_at": "..."
9
}

10.2 必须做的测试#

10.3 指标不能只看 Token#

1
startup_instruction_tokens
2
path_rule_activation_count
3
instruction_conflict_rate
4
instruction_adherence_rate
5
auto_memory_write_rate
6
auto_memory_correction_rate
7
topic_file_read_hit_rate
8
post_compaction_instruction_miss_rate

Token 降低但关键规则漏载，不是优化；规则全部加载但冲突率上升，也不是成功。

11.1 优势#

• 与 Coding Agent 的文件世界天然一致；
• 人类可读、可审计、可修改；
• Project Instructions 可进入 Git Review；
• Directory 与 Glob 提供确定性 Routing；
• Hot Index + Topic Files 支持渐进披露；
• 不依赖独立 Vector DB 才能形成有效长期上下文。

11.2 边界#

• 自然语言冲突没有数据库式确定性覆盖；
• CLAUDE.md 是 Best-effort 行为指令，不是权限执行层；
• Auto Memory 机器本地，不能天然充当团队知识库；
• 文件共享会引入多 Session 并发和 Drift 问题；
• Topic Index 可能出现断链与过期；
• 对模糊跨项目语义召回，纯路径结构不一定足够；
• 动态事实的有效时间与冲突历史需要额外 Temporal Model。

11.3 最准确的架构定义#

Claude Code Memory 不是：

1
Markdown instead of Vector DB

而是：

1
Hierarchical Instruction Loader
2
+ Path-triggered Retrieval
3
+ Bounded Auto-memory Index
4
+ Agentic Topic-file Read
5
+ Human-auditable Local Storage
6
+ Compaction-aware Reinjection

它最值得学习的不是“用文件就够了”，而是：

利用代码仓库现有的目录、路径、版本控制和文件工具，把 Memory Retrieval 变成可解释的 Progressive Disclosure。

[C1] Anthropic：How Claude remembers your project#

• How Claude remembers your project
• Markdown 原文
• 核对内容：CLAUDE.md Scope 与加载顺序、Nested Lazy Load、@ Import、四层递归、外部审批、Rules、claudeMdExcludes、Auto Memory 位置、200 行 / 25 KB、Worktree 共享、/memory、Compaction 后 Root / Nested 恢复差异。

[C2] Anthropic：Manage context and compaction#

• Context window
• 核对内容：Context Working Set、Compaction 目的与跨会话 Memory 的职责差异。

[C3] Anthropic：Settings and permissions#

• Settings
• Permissions
• 核对内容：Managed Settings、权限拒绝、Sandbox 与 CLAUDE.md Best-effort 行为指令的边界。

[C4] Anthropic：Hooks#

• Hooks reference
• 核对内容：InstructionsLoaded 事件与指令加载可观测性。

[C5] Anthropic：Subagents#

• Subagents
• 核对内容：Subagent 可维护独立持久 Memory，避免把所有角色经验混入主 Agent。

[C6] OWASP：Agent Memory Security#

• OWASP Agent Memory Guard
• AI Agent Security Cheat Sheet
• 核对内容：Memory Poisoning、持久化 Prompt Injection、来源与审计边界。

上一篇：Codex Memory 源码深潜 · 下一篇：Hermes Memory 源码深潜