渐进式披露 - Claude-Mem

来源 (中文翻译版): https://docs.claude-mem.ai/progressive-disclosure 抓取时间: 2026-07-21 16:19:30

本页内容

• 渐进式披露：Claude-Mem 的上下文预加载哲学
• 核心原则
• 什么是渐进式披露？
• 问题：上下文污染
• Claude-Mem 的解决方案：渐进式披露
• 在 Claude-Mem 中的工作原理
  • 索引格式
  • 图例系统
  • 渐进式披露说明
• 哲学：上下文即货币
  • 思维模型：令牌预算即金钱
  • 注意力预算
  • 为自主性设计
• 实现原则
  • 1. 使成本可见
  • 2. 使用语义压缩
  • 3. 按上下文分组
  • 4. 提供检索工具
• 实际示例
  • 场景：智能体被要求修复 hooks 中的 bug
  • 索引条目
• 三层工作流程
  • 第一层：搜索（索引）
  • 第二层：时间线（上下文）
  • 第三层：获取观察（详情）
• 认知负荷理论
  • 内在负荷
  • 外在负荷
  • 相关负荷
• 需要避免的反模式
  • ❌ 冗长的标题
  • ❌ 隐藏成本
  • ❌ 无检索路径
  • ❌ 跳过索引层
• 关键设计决策
  • 为什么用令牌计数？
  • 为什么用图标而不是文本标签？
  • 为什么索引优先，而不是智能预取？
  • 为什么按文件路径分组？
• 衡量成功
  • ✅ 低浪费率
  • ✅ 选择性获取
  • ✅ 快速任务完成
  • ✅ 适当的深度
• 未来增强
  • 自适应索引大小
  • 相关性评分
  • 成本预测
  • 渐进式细节级别
• 要点总结
• 记住
• 延伸阅读

最佳实践

渐进式披露

复制页面复制页面 复制页面复制页面

渐进式披露：Claude-Mem 的上下文预加载哲学

核心原则 先展示存在的内容及其检索成本。让智能体根据相关性和需求决定获取什么。

什么是渐进式披露？ 渐进式披露是一种信息架构模式，你逐渐揭示复杂性，而不是一次性全部展示。在人工智能智能体的上下文中，这意味着：

1. 第一层（索引）：展示轻量级元数据（标题、日期、类型、令牌计数）
2. 第二层（详情）：仅在需要时获取完整内容
3. 第三层（深度挖掘）：如果需要，读取原始源文件

这反映了人类的工作方式：我们在阅读文章前先浏览标题，在深入章节前先查看目录，在打开文件前先检查文件名。

问题：上下文污染 传统的 RAG（检索增强生成）系统预先获取所有内容：

❌ 传统方法：
┌─────────────────────────────────────┐
│ 会话开始                             │
│                                      │
│ [15,000 个令牌的过去会话]        │
│ [8,000 个令牌的观察]              │
│ [12,000 个令牌的文件摘要]        │
│                                      │
│ 总计：35,000 个令牌                 │
│ 相关：~2,000 个令牌（6%）           │
└─────────────────────────────────────┘

问题：

• 在不相关的上下文中浪费了 94% 的注意力预算
• 用户提示被历史的大山掩埋
• 智能体必须先处理所有内容才能理解任务
• 在阅读之前无法知道什么真正有用

Claude-Mem 的解决方案：渐进式披露

✅ 渐进式披露方法：
┌─────────────────────────────────────┐
│ 会话开始                              │
│                                      │
│ 50 条观察的索引：~800 个令牌       │
│ ↓                                    │
│ 智能体看到："🔴 Hook 超时问题"       │
│ 智能体决定："相关！"                 │
│ ↓                                    │
│ 获取观察 #2543：~120 个令牌        │
│                                      │
│ 总计：920 个令牌                     │
│ 相关：920 个令牌（100%）            │
└─────────────────────────────────────┘

优势：

• 智能体控制自己的上下文消耗
• 与当前任务直接相关
• 可以在需要时获取更多
• 如果不相关可以跳过所有内容
• 每个检索决策都有明确的成本/收益

在 Claude-Mem 中的工作原理

索引格式 每个 SessionStart hook 提供一个紧凑的索引：

### 2025年10月26日

**常规**
| ID | 时间 | T | 标题 | 令牌 |
|----|------|---|------|------|
| #2586 | 12:58 AM | 🔵 | 上下文 hook 文件存在但为空 | ~51 |
| #2587 | ″ | 🔵 | 上下文 hook 脚本文件为空 | ~46 |
| #2589 | ″ | 🟡 | 调查了 hook 调试输出文档 | ~105 |

**src/hooks/context-hook.ts**
| ID | 时间 | T | 标题 | 令牌 |
|----|------|---|------|------|
| #2591 | 1:15 AM | ⚖️ | 放弃了标准错误消息传递 | ~155 |
| #2592 | 1:16 AM | ⚖️ | 重新设计了 Web UI 策略 | ~193 |

智能体看到的内容：

• 存在什么：观察标题提供语义含义
• 何时发生：时间戳提供时间上下文
• 什么类型：图标指示观察类别
• 检索成本：令牌计数用于明智决策
• 在哪里获取：底部引用的 MCP 搜索工具

图例系统

🎯 session-request  - 用户的原始目标
🔴 gotcha          - 关键边缘情况或陷阱
🟡 problem-solution - Bug 修复或变通方法
🔵 how-it-works    - 技术说明
🟢 what-changed    - 代码/架构变更
🟣 discovery       - 学习或洞察
🟠 why-it-exists   - 设计原理
🟤 decision        - 架构决策
⚖️ trade-off       - 深思熟虑的折衷

目的：

• 视觉扫描（人类和人工智能都受益）
• 语义分类
• 优先级信号（🔴 陷阱更关键）
• 跨会话的模式识别

渐进式披露说明 索引包含使用指南：

💡 **渐进式披露：** 此索引显示存在什么以及检索成本。
- 使用 MCP 搜索工具按需获取完整的观察详情
- 优先搜索观察而不是重新阅读代码以了解过去的决策
- 关键类型（🔴 陷阱、🟤 决策、⚖️ 折衷）通常值得立即获取

这实现的作用：

• 教智能体模式
• 建议何时获取（关键类型）
• 推荐搜索而非代码重读（效率）
• 使系统自我文档化

哲学：上下文即货币

思维模型：令牌预算即金钱 将上下文窗口视为银行账户：

注意力预算 大语言模型的注意力是有限的：

• 每个令牌都关注其他每个令牌（n² 关系）
• 100,000 令牌窗口 ≠ 100,000 个有用的注意力令牌
• 窗口填满时会发生上下文"腐烂"
• 后期令牌获得的注意力少于早期令牌

Claude-Mem 的方法：

• 从约 1,000 个令牌的索引开始
• 智能体有 99,000 个令牌可用于任务
• 智能体在需要时获取约 200 个令牌
• 最终预算：约 98,000 个令牌用于实际工作

为自主性设计

"随着模型的改进，让它们智能地行动" 渐进式披露将智能体视为智能的信息搜寻者，而不是预先选择上下文的被动接收者。 传统 RAG：

系统 → [决定相关性] → 智能体
        ↑
   希望这有帮助！

渐进式披露：

系统 → [显示索引] → 智能体 → [决定相关性] → [获取详情]
                          ↑
                   你最了解！

智能体知道：

• 当前任务上下文
• 什么信息会有帮助
• 要花多少预算
• 何时停止搜索

我们不知道。

实现原则

1. 使成本可见 索引中的每个项目都显示令牌计数：

   | #2591 | 1:15 AM | ⚖️ | 放弃了标准错误消息传递 | ~155 | ^^^^ 检索成本

为什么：

• 智能体可以做出明智的投资回报率决策
• 小观察（~50 令牌）获取"便宜"
• 大观察（~500 令牌）需要更强的理由
• 匹配人类对努力的思考方式

2. 使用语义压缩 标题将完整观察压缩为约 10 个词： 糟糕的标题：

   关于某件事的观察

好的标题：

🔴 Hook 超时问题：60 秒默认值对于 npm 安装太短

好标题的要素：

• 具体：识别确切问题
• 可操作：明确要做什么
• 自包含：不需要阅读观察
• 可搜索：包含关键术语（hook、timeout、npm）
• 分类：图标指示类型

3. 按上下文分组 观察按以下方式分组：

• 日期：时间上下文

• 文件路径：空间上下文（处理特定文件）

• 项目：逻辑上下文

  src/hooks/context-hook.ts

  ID	时间	T	标题	令牌
  #2591	1:15 AM	⚖️	放弃了标准错误消息传递	~155
  #2594	1:17 AM	🟠	从文档中删除了 stderr 部分	~93

好处： 如果智能体正在处理 src/hooks/context-hook.ts，相关观察已经分组在一起。

4. 提供检索工具 没有检索机制，索引就毫无用处：

   使用 claude-mem MCP 搜索访问给定 ID 的记录

可用的 MCP 工具：

• search - 搜索内存索引（第一层：获取 ID）
• timeline - 获取按时间顺序的上下文（第二层：查看叙事弧）
• get_observations - 获取完整详情（第三层：深度挖掘）

三层工作流程确保渐进式披露：索引 → 上下文 → 详情。

实际示例

场景：智能体被要求修复 hooks 中的 bug 没有渐进式披露：

SessionStart 注入 25,000 个令牌的过去上下文
智能体阅读所有内容
智能体找到 1 条相关观察（埋在中间）
消耗的总令牌：25,000
相关令牌：~200
效率：0.8%

有渐进式披露：

SessionStart 显示索引：~800 令牌
智能体看到标题："🔴 Hook 超时问题：60 秒太短"
智能体想："这看起来与我的 bug 相关！"
智能体获取观察 #2543：~155 令牌
消耗的总令牌：955
相关令牌：955
效率：100%

索引条目

| #2543 | 2:14 PM | 🔴 | Hook 超时：60 秒对于 npm 安装太短 | ~155 |

智能体无需获取即可学到的内容：

• 有一个已知的陷阱（🔴）关于 hook 超时
• 与 npm 安装时间太长有关
• 完整详情约 155 令牌（便宜）
• 发生在下午 2:14（最近）

决策树：

我的任务与 hooks 相关吗？→ 是
我的任务与超时相关吗？→ 是
我的任务与 npm 相关吗？→ 是
155 令牌很便宜 → 获取它

三层工作流程 Claude-Mem 通过三层工作流程模式实现渐进式披露：

第一层：搜索（索引） 首先搜索以获取带有 ID 的紧凑索引：

search({
  query: "hook timeout",
  limit: 10
})

返回：

找到 3 条匹配 "hook timeout" 的观察：

| ID | 日期 | 类型 | 标题 |
|----|------|------|------|
| #2543 | 10月26日 | gotcha | Hook 超时：60 秒太短 |
| #2891 | 10月25日 | how-it-works | Hook 超时配置 |
| #2102 | 10月20日 | problem-solution | 修复了 CI 中的超时 |

成本： 每条结果约 50-100 令牌 价值： 智能体可以扫描并决定哪些观察相关

第二层：时间线（上下文） 获取有趣观察周围的按时间顺序的上下文：

timeline({
  anchor: 2543,  // 来自搜索的观察 ID
  depth_before: 3,
  depth_after: 3
})

返回： 按时间顺序的视图，显示观察 #2543 之前/期间/之后发生的事情 成本： 基于深度可变 价值： 理解叙事弧和上下文

第三层：获取观察（详情） 仅为相关观察获取完整详情：

get_observations({
  ids: [2543, 2102]  // 从搜索结果中选择
})

返回：

#2543 🔴 Hook 超时：60 秒对于 npm 安装太短
─────────────────────────────────────────────────
日期：2025年10月26日 下午2:14
类型：gotcha
项目：claude-mem

叙述：
发现默认的 60 秒 hook 超时对于
npm 安装操作不足，特别是在依赖树较大
或网络条件较慢时。这导致 SessionStart hook 静默
失败，阻止上下文注入。

事实：
- 默认超时：60 秒
- 冷缓存下的 npm 安装：约 90 秒
- 配置的超时：plugin/hooks/hooks.json:25 中的 120 秒

修改的文件：
- plugin/hooks/hooks.json

概念：hooks、timeout、npm、configuration

成本： 完整详情约 155 令牌 价值： 完全理解问题

认知负荷理论 渐进式披露基于认知负荷理论：

内在负荷 任务本身的固有难度。 示例： "修复认证 bug"

• 必须理解认证系统
• 必须理解 bug
• 必须编写修复

这种负荷是不可避免的。

外在负荷 信息呈现不佳带来的认知负担。 传统 RAG 增加了外在负荷：

• 扫描不相关的观察
• 过滤掉噪音
• 记住要忽略什么
• 每个部分后重新上下文

渐进式披露最小化外在负荷：

• 扫描标题（低努力）
• 仅获取相关内容（有针对性的努力）
• 全神贯注于当前任务

相关负荷 构建心智模型和模式的努力。 渐进式披露支持相关负荷：

• 一致的结构（图例、分组）
• 清晰的分类（类型、图标）
• 语义压缩（好标题）
• 明确的成本（令牌计数）

需要避免的反模式

❌ 冗长的标题 糟糕：

| #2543 | 2:14 PM | 🔴 | 关于 hooks 超时问题的调查 | ~155 |

好：

| #2543 | 2:14 PM | 🔴 | Hook 超时：60 秒对于 npm 安装太短 | ~155 |

❌ 隐藏成本 糟糕：

| #2543 | 2:14 PM | 🔴 | Hook 超时问题 |

好：

| #2543 | 2:14 PM | 🔴 | Hook 超时问题 | ~155 |

❌ 无检索路径 糟糕：

这里有 10 条观察。[没有关于如何获取完整详情的说明]

好：

这里有 10 条观察。
*使用 MCP 搜索工具按需获取完整的观察详情*

❌ 跳过索引层 糟糕：

// 立即获取完整详情
get_observations({
  ids: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]  // 猜测哪些相关
})

好：

// 遵循三层工作流程
// 第一层：搜索索引
search({
  query: "hooks",
  limit: 20
})

// 第二层：查看索引，识别 2-3 个相关 ID

// 第三层：仅获取相关观察
get_observations({
  ids: [2543, 2891]  // 只获取最相关的
})

关键设计决策

为什么用令牌计数？ 决策： 显示近似令牌计数（~155、~203）而不是精确计数。 理由：

• 传达规模（50 vs 500）而没有虚假精度
• 映射到人类直觉（小/中/大）
• 允许智能体预算注意力
• 鼓励有成本意识的检索

为什么用图标而不是文本标签？ 决策： 使用表情符号图标（🔴、🟡、🔵）而不是文本（GOTCHA、PROBLEM、HOWTO）。 理由：

• 视觉扫描（模式识别）
• 令牌高效（1 字符 vs 10 字符）
• 语言无关
• 美学上不同
• 对人类和人工智能都有效

为什么索引优先，而不是智能预取？ 决策： 总是先显示索引，即使我们"知道"什么是相关的。 理由：

• 我们不可能比智能体更了解什么相关
• 预取假设我们理解任务
• 智能体知道当前上下文，我们不知道
• 尊重智能体自主性
• 优雅地失败（总能获取更多）

为什么按文件路径分组？ 决策： 除了日期之外，还按文件路径对观察进行分组。 理由：

• 空间局部性：处理文件 X 可能需要关于文件 X 的上下文
• 减少扫描努力
• 匹配开发者的思考方式
• 清晰的语义边界

衡量成功 渐进式披露在以下情况下有效：

✅ 低浪费率

相关令牌 / 总上下文令牌 > 80%

消耗的大部分上下文实际上是有用的。

✅ 选择性获取

显示的索引：50 条观察
获取的详情：2-3 条观察

智能体正在选择性地获取，而不是获取所有内容。

✅ 快速任务完成

有索引的会话：30 秒找到相关上下文
没有索引的会话：90 秒扫描所有上下文

找到相关信息的时间更快。

✅ 适当的深度

简单任务：只需要索引
中等任务：获取 1-2 条观察
复杂任务：5-10 条观察 + 代码读取

深度随任务复杂性而扩展。

未来增强

自适应索引大小

// 根据会话类型改变索引大小
SessionStart({ source: "startup" }):
  → 显示最后 10 个会话（小索引）

SessionStart({ source: "resume" }):
  → 只显示当前会话（微索引）

SessionStart({ source: "compact" }):
  → 显示最后 20 个会话（较大索引）

相关性评分

// 使用嵌入按相关性对索引预排序
search({
  query: "authentication bug",
  orderBy: "relevance"  // 基于语义相似性（未来增强）
})

成本预测

💡 **预算估计：**
- 获取所有 🔴 陷阱：约 450 令牌
- 获取所有文件相关：约 1,200 令牌
- 获取所有内容：约 8,500 令牌

渐进式细节级别

第一层：索引（仅标题）
第二层：摘要（2-3 句话）
第三层：完整详情（完整观察）
第四层：源文件（引用的代码）

要点总结

1. 展示，不要告知：索引揭示存在的内容而不强制消费
2. 成本意识：使检索成本可见以便明智决策
3. 智能体自主性：让智能体决定什么相关
4. 语义压缩：好标题决定系统的成败
5. 一致的结构：模式减少认知负荷
6. 双层一切：先索引，按需详情
7. 上下文即货币：明智地花在高价值信息上

记住

"最好的界面是在不需要时消失，在需要时准确出现。" 渐进式披露尊重智能体的智能和自主性。我们提供地图；智能体选择路径。

延伸阅读

• 人工智能智能体的上下文工程 - 基本原则
• Claude-Mem 架构 - 一切如何组合在一起
• 认知负荷理论（Sweller，1988）
• 信息搜寻理论（Pirolli & Card，1999）
• 渐进式披露（Nielsen Norman Group）

这一哲学源于 Claude-Mem 在数百个编码会话中的实际使用。这种模式有效，因为它既符合人类认知，又符合大语言模型注意力机制。 上下文工程文件读取门 ⌘I