渐进式披露：Claude-Mem 的上下文预热哲学¶
核心原则¶
首先展示已存在的内容及其检索成本。让智能体根据相关性和需求自行决定获取什么。
什么是渐进式披露？¶
渐进式披露是一种信息架构模式，它逐步揭示复杂性，而不是一次性全部展开。在 AI 智能体的语境下，它意味着：
- 第 1 层（索引）：展示轻量级元数据（标题、日期、类型、Token 数量）
- 第 2 层（详情）：仅在需要时获取完整内容
- 第 3 层（深入研究）：必要时阅读原始源文件
这与人类的工作方式相似：我们在读文章前先浏览标题，在深入章节前先查看目录，在打开文件前先查看文件名。
问题：上下文污染¶
传统的 RAG（Retrieval-Augmented Generation，检索增强生成）系统会预先获取所有内容：
❌ Traditional Approach:
┌─────────────────────────────────────┐
│ Session Start │
│ │
│ [15,000 tokens of past sessions] │
│ [8,000 tokens of observations] │
│ [12,000 tokens of file summaries] │
│ │
│ Total: 35,000 tokens │
│ Relevant: ~2,000 tokens (6%) │
└─────────────────────────────────────┘
问题：
- 在无关上下文上浪费了 94% 的注意力预算
- 用户提示被淹没在大量的历史记录之下
- 智能体必须先处理所有内容，然后才能理解任务
- 在阅读之前，无从知晓哪些内容真正有用
Claude-Mem 的解决方案：渐进式披露¶
✅ Progressive Disclosure Approach:
┌─────────────────────────────────────┐
│ Session Start │
│ │
│ Index of 50 observations: ~800 tokens│
│ ↓ │
│ Agent sees: "🔴 Hook timeout issue" │
│ Agent decides: "Relevant!" │
│ ↓ │
│ Fetch observation #2543: ~120 tokens│
│ │
│ Total: 920 tokens │
│ Relevant: 920 tokens (100%) │
└─────────────────────────────────────┘
优势：
- 智能体自行掌控其上下文消耗
- 与当前任务直接相关
- 需要时可以获取更多
- 不相关时可以完全跳过
- 每次检索决策都有清晰的成本/收益对比
它在 Claude-Mem 中如何运作¶
索引格式¶
每个 SessionStart 钩子都会提供一个紧凑的索引：
### Oct 26, 2025
**General**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2586 | 12:58 AM | 🔵 | Context hook file exists but is empty | ~51 |
| #2587 | ″ | 🔵 | Context hook script file is empty | ~46 |
| #2589 | ″ | 🟡 | Investigated hook debug output docs | ~105 |
**src/hooks/context-hook.ts**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
| #2592 | 1:16 AM | ⚖️ | Web UI strategy redesigned | ~193 |
智能体看到的内容：
- 已存在什么：观察记录的标题提供语义含义
- 何时发生：时间戳提供时间上下文
- 什么类型：图标表示观察记录类别
- 检索成本：Token 数量用于做出明智决策
- 从哪里获取：底部引用 MCP 搜索工具
图例系统¶
🎯 session-request - User's original goal
🔴 gotcha - Critical edge case or pitfall
🟡 problem-solution - Bug fix or workaround
🔵 how-it-works - Technical explanation
🟢 what-changed - Code/architecture change
🟣 discovery - Learning or insight
🟠 why-it-exists - Design rationale
🟤 decision - Architecture decision
⚖️ trade-off - Deliberate compromise
用途：
- 视觉扫描（人类和 AI 同样受益）
- 语义分类
- 优先级信号（🔴 gotcha 类观察记录更关键）
- 跨会话的模式识别
渐进式披露说明¶
索引中包含使用指南：
💡 **Progressive Disclosure:** This index shows WHAT exists and retrieval COST.
- Use MCP search tools to fetch full observation details on-demand
- Prefer searching observations over re-reading code for past decisions
- Critical types (🔴 gotcha, 🟤 decision, ⚖️ trade-off) often worth fetching immediately
它的作用：
- 让智能体学会这种模式
- 建议何时获取（关键类型）
- 建议优先搜索而非重新阅读代码（更高效）
- 让系统具备自我文档化能力
核心理念：上下文即货币¶
心智模型：Token 预算如金钱¶
将上下文窗口想象成一个银行账户：
| 方法 | 比喻 | 结果 |
|---|---|---|
| 全部倾倒 | 把整张工资支票花在也许某天会用到的杂货上 | 浪费、杂乱，无法负担真正需要的东西 |
| 不获取任何内容 | 拒绝花任何钱 | 挨饿，无法完成任务 |
| 渐进式披露 | 检查储藏室、列出购物清单、只买需要的东西 | 高效，为意外需求留有空间 |
注意力预算¶
LLM（大语言模型）的注意力是有限的：
- 每个 Token 都会关注其他每一个 Token（n² 关系）
- 100,000 Token 的窗口 ≠ 100,000 Token 的有效注意力
- 随着窗口被填满，上下文会出现“退化”
- 后面的 Token 获得的关注度低于前面的 Token
Claude-Mem 的做法：
- 从约 1,000 Token 的索引开始
- 智能体有 99,000 Token 可用于任务
- 智能体在需要时获取约 200 Token
- 最终预算：约 98,000 Token 用于实际工作
为自主性而设计¶
“随着模型的不断改进，让它们智能地行动。”
渐进式披露将智能体视为智能信息觅食者，而非预先选定上下文的被动接收者。
传统 RAG：
渐进式披露：
Agent 知道： - 当前任务上下文 - 哪些信息会有帮助 - 该花费多少预算 - 何时停止搜索
我们不知道。
实现原则¶
1. 让成本可见¶
索引中的每一项都显示 token 数量：
原因： - Agent 可以做出明智的 ROI 决策 - 小型观察记录（约 50 token）获取起来很“便宜” - 大型观察记录（约 500 token）需要更有力的理由 - 符合人类对付出成本的思考方式
2. 使用语义压缩¶
标题将完整观察记录压缩为约 10 个词：
不好的标题：
好的标题：
好的标题具备什么特征： - 具体：明确指出具体问题 - 可操作：清楚知道该怎么做 - 自包含：无需阅读观察记录本身 - 可搜索：包含关键术语（hook、timeout、npm） - 已分类：用图标指示类型
3. 按上下文分组¶
观察记录按以下方式分组： - 日期：时间上下文 - 文件路径：空间上下文（针对特定文件的工作） - 项目：逻辑上下文
**src/hooks/context-hook.ts**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
| #2594 | 1:17 AM | 🟠 | Removed stderr section from docs | ~93 |
好处：如果 Agent 正在处理 src/hooks/context-hook.ts，相关的观察记录已经聚合在一起。
4. 提供检索工具¶
没有检索机制，索引就是无用的：
可用的 MCP 工具：
- search - 搜索记忆索引（第 1 层：获取 ID）
- timeline - 获取时间上下文（第 2 层：查看叙事脉络）
- get_observations - 获取完整详情（第 3 层：深入探究）
- get_tool_uses - 获取原始的 tool_input / tool_response（第 4 层：原始证据）
分层工作流确保了渐进式披露：索引 → 上下文 → 详情 → 原始证据。
实际示例¶
场景：Agent 被要求修复 hooks 中的 bug¶
没有渐进式披露时：
SessionStart injects 25,000 tokens of past context
Agent reads everything
Agent finds 1 relevant observation (buried in middle)
Total tokens consumed: 25,000
Relevant tokens: ~200
Efficiency: 0.8%
使用渐进式披露时：
SessionStart shows index: ~800 tokens
Agent sees title: "🔴 Hook timeout issue: 60s too short"
Agent thinks: "This looks relevant to my bug!"
Agent fetches observation #2543: ~155 tokens
Total tokens consumed: 955
Relevant tokens: 955
Efficiency: 100%
索引条目¶
Agent 不进行获取时能了解到什么： - 存在一个与 hook 超时相关的已知陷阱（🔴） - 它与 npm install 耗时过长有关 - 完整详情约 155 token（成本低） - 发生在 2:14 PM（较近）
决策树：
Is my task related to hooks? → YES
Is my task related to timeouts? → YES
Is my task related to npm? → YES
155 tokens is cheap → FETCH IT
分层工作流¶
Claude-Mem 通过分层工作流模式实现渐进式披露。第 1-3 层是日常路径；第 4 层用于摘要不足以作为证据的罕见情况。
第 1 层：搜索（索引）¶
首先进行搜索，获取带有 ID 的紧凑索引：
返回：
Found 3 observations matching "hook timeout":
| ID | Date | Type | Title |
|----|------|------|-------|
| #2543 | Oct 26 | gotcha | Hook timeout: 60s too short |
| #2891 | Oct 25 | how-it-works | Hook timeout configuration |
| #2102 | Oct 20 | problem-solution | Fixed timeout in CI |
成本：每个结果约 50-100 token 价值：Agent 可以快速浏览并判断哪些观察记录是相关的
第 2 层：时间线（上下文）¶
获取感兴趣观察记录周围的时间上下文：
返回：按时间顺序的视图，展示观察记录 #2543 之前/期间/之后发生的事情
成本：随深度变化 价值：理解叙事脉络与上下文
第 3 层：获取观察记录（详情）¶
仅获取相关观察记录的完整详情：
返回：
#2543 🔴 Hook timeout: 60s too short for npm install
─────────────────────────────────────────────────
Date: Oct 26, 2025 2:14 PM
Type: gotcha
Project: claude-mem
Narrative:
Discovered that the default 60-second hook timeout is insufficient
for npm install operations, especially with large dependency trees
or slow network conditions. This causes SessionStart hook to fail
silently, preventing context injection.
Facts:
- Default timeout: 60 seconds
- npm install with cold cache: ~90 seconds
- Configured timeout: 120 seconds in plugin/hooks/hooks.json:25
Files Modified:
- plugin/hooks/hooks.json
Concepts: hooks, timeout, npm, configuration
成本：完整详情约 155 token 价值：对问题的完整理解
第 4 层：获取工具使用记录（原始证据）¶
观察记录是工具所执行操作的压缩摘要。有时，压缩恰恰不是你想要的——你需要的是字面意义上的原始字节：实际应用的精确 diff、构建打印出的精确 stderr、API 返回的精确 JSON。
Claude-mem 将这些原始数据保存在 tool_uses 表中，而这一层是读取它们的唯一途径：
返回：这些调用所存储的 tool_input / tool_response，以及工具名称、会话 ID，以及该调用被归入的观察记录。
成本： 每行最高 64 KB —— 目前成本最高的层 价值： 未经摘要的真相，仅当且仅当摘要不足时才使用
Warning
绝不要从这里开始，也绝不要在没有从第 1-3 层获取 ID 的情况下调用 get_tool_uses。原始工具正文正是本页其余部分要避免的上下文污染；有意披露少数几条是渐进式披露，默认披露全部则只是一份更大的转录稿。
大于 64 KB 的载荷在写入时会被截断，并带有 …[truncated: N bytes] 标记，因此被截断的正文可以区别于合法结束的正文。
认知负荷理论¶
渐进式披露基于认知负荷理论：
内在负荷¶
任务本身的固有难度。
示例："修复认证 bug" - 必须理解认证系统 - 必须理解 bug - 必须编写修复代码
这种负荷是无法避免的。
无关负荷¶
信息呈现不佳所带来的认知负担。
传统 RAG 会增加无关负荷： - 浏览无关的观察结果 - 过滤噪声 - 记住哪些内容需要忽略 - 在每个部分之后重新建立上下文
渐进式披露可最大限度地减少无关负荷： - 浏览标题（低付出） - 仅获取相关内容（有针对性的付出） - 将全部注意力集中在当前任务上
相关负荷¶
构建心智模型和图式的认知付出。
渐进式披露支持相关负荷： - 一致的结构（图例、分组） - 清晰的分类（类型、图标） - 语义压缩（好的标题） - 明确的成本（token 数量）
应避免的反模式¶
❌ 冗长标题¶
差：
好：
❌ 隐藏成本¶
差：
好：
❌ 没有检索路径¶
差：
好：
❌ 跳过索引层¶
差：
好：
// 遵循 3 层工作流程
// 第 1 层：搜索索引
search({
query: "hooks",
limit: 20
})
// 第 2 层：查看某个相关索引结果周围的上下文
timeline({
anchor: 2543,
depth_before: 3,
depth_after: 3
})
// 阅读时间线后，仅保留仍然相关的 ID
// 第 3 层：仅获取相关的观察结果
get_observations({
ids: [2543, 2891] // 仅最相关的部分
})
关键设计决策¶
为什么使用 token 数量？¶
决策： 显示近似 token 数量（~155、~203），而不是精确数量。
理由： - 传达规模（50 与 500）而不提供虚假的精度 - 符合人类直觉（小/中/大） - 使 agent 能够分配注意力预算 - 鼓励注重成本的检索
为什么使用图标而不是文本标签？¶
决策： 使用表情符号图标（🔴、🟡、🔵）而不是文本（GOTCHA、PROBLEM、HOWTO）。
理由： - 视觉扫描（模式识别） - token 高效（1 个字符 vs 10 个字符） - 与语言无关 - 视觉上易于区分 - 对人类和 AI 都适用
为什么索引优先，而不是智能预取？¶
决策： 始终先显示索引，即使我们"知道"哪些是相关的。
理由： - 我们不可能比 agent 更了解什么才是相关的 - 预取意味着我们假设自己理解了任务 - Agent 知道当前上下文，而我们不知道 - 尊重 agent 的自主性 - 优雅地失败（随时可以获取更多）
为什么按文件路径分组？¶
决策： 除按日期分组外，还按文件路径对观察结果进行分组。
理由： - 空间局部性：对文件 X 的操作很可能需要关于文件 X 的上下文 - 减少扫描付出 - 符合开发者的思维方式 - 清晰的语义边界
衡量成功¶
当以下情况出现时，渐进式披露正在发挥作用：
✅ 低浪费率¶
消耗的大部分上下文实际上是可用的。
✅ 选择性获取¶
Agent 在选择性获取，而不是获取一切。
✅ 快速完成任务¶
达到相关信息的时间更短。
✅ 适当的深度¶
深度随任务复杂度伸缩。
未来增强¶
自适应索引大小¶
// 根据会话类型调整索引大小
SessionStart({ source: "startup" }):
→ 显示最近 10 个会话（小索引）
SessionStart({ source: "resume" }):
→ 仅显示当前会话（微索引）
SessionStart({ source: "compact" }):
→ 显示最近 20 个会话（较大索引）
相关性评分¶
成本预测¶
渐进式详情级别¶
关键要点¶
- 展示，而非告知：索引揭示存在什么，而不强迫消费
- 注重成本：让检索成本可见，以便做出明智决策
- Agent 自主性：让 agent 决定什么是相关的
- 语义压缩：好的标题决定系统成败
- 一致的结构：模式能降低认知负荷
- 一切分两层：先索引，详情按需获取
- 上下文即货币：明智地花在高价值信息上
记住¶
“最好的界面是在不需要时消失、在需要时恰好出现的界面。”
渐进式披露尊重智能体的智慧与自主性。我们提供地图，由智能体自行选择路径。
延伸阅读¶
- 面向 AI 智能体的上下文工程 - 基础原理
- Claude-Mem 架构 - 各部分如何组合在一起
- 认知负荷理论（Sweller, 1988）
- 信息觅食理论（Pirolli & Card, 1999）
- 渐进式披露（Nielsen Norman Group）
这一理念源自 Claude-Mem 在数百次真实编码会话中的实践。该模式之所以有效，是因为它与人类认知以及 LLM 的注意力机制相契合。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem