claude-mem 中文文档

Appearance

渐进披露：Claude-Mem 的上下文启动哲学 ​

核心原则 ​

首先显示存在的内容及其获取成本。让代理根据相关性和需求决定要获取的内容。

什么是渐进式披露？ ​

渐进式披露是一种信息架构模式，它通过逐步展示复杂性而不是一次性全部呈现。在人工智能代理的背景下，这意味着：

  1. 第1层（索引）：显示轻量级元数据（标题、日期、类型、token 数量）
  2. 第2层（详情）：仅在需要时获取完整内容
  3. 第3层（深入探索）：如有需要，请阅读原始源文件

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

问题：上下文污染 ​

传统的RAG（检索增强生成）系统会预先获取所有内容：

❌ Traditional Approach:
┌─────────────────────────────────────┐
│ Session Start                        │
│                                      │
│ [15,000 个 token of past sessions]    │
│ [8,000 个 token of observations]      │
│ [12,000 个 token of file summaries]   │
│                                      │
│ Total: 35,000 个 token                │
│ 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 个 token                   │
│ Relevant: 920 个 token (100%)         │
└─────────────────────────────────────┘

好处：

  • 代理控制其自身的上下文消耗
  • 与当前任务直接相关
  • 如有需要可以取更多
  • 如果不相关可以跳过所有内容
  • 为每个检索决策明确成本/收益

在 Claude-Mem 中的工作原理 ​

索引格式 ​

每个 SessionStart 钩子都提供一个紧凑的索引：

markdown
### 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

目的：

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

渐进式披露说明 ​

索引包括使用指南：

markdown
💡 **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预算视为金钱 ​

把上下文窗口想象成一个银行账户：

方法比喻结果
倾倒一切把整个月的工资都花在你可能将来需要的杂货上浪费、杂乱，买不起你真正需要的东西
一无所获拒绝花任何钱饥饿，无法完成任务
渐进式披露检查你的储藏室，列一个购物清单，只买你需要的东西效率，预留应对意外需求的空间

注意力预算 ​

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

  • 每个标记都会关注每个其他标记（n² 关系）
  • 100,000 个标记窗口 ≠ 100,000 个有用注意力标记
  • 当窗户充满时，发生“腐烂”的情况
  • 后来的标记比前面的标记得到的注意力少

Claude-Mem 的方法：

  • 从大约 1,000 个索引标记开始
  • 代理有 99,000 个token可用于任务
  • 代理在需要时获取约 200 个 token
  • 最终预算：实际工作约 98,000 个token

自主设计 ​

随着模型的改进，让它们表现得更加智能

渐进式披露将代理视为智能信息觅食者，而不是被动接收预先选择的上下文。

传统 RAG：

System → [Decides relevance] → Agent
        ↑
   Hope this helps!

渐进披露:

System → [Shows index] → Agent → [Decides relevance] → [Fetches details]
                          ↑
                   You know best!

代理知道：

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

我们不。

实施原则 ​

1. 让成本可见 ​

索引中的每一项都显示 token 计数：

| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
                                                        ^^^^
                                                    Retrieval cost

为什么：

  • 代理可以做出明智的投资回报决策
  • 小型观测（约50个标记）“便宜”获取
  • 大量观察（约500个标记）需要更有力的理由
  • 符合人类对努力的思考方式

2. 使用语义压缩 ​

标题将完整的观察压缩为约10个字：

糟糕的标题：

Observation about a thing

好标题：

🔴 Hook timeout issue: 60s default too short for npm install

一个好标题的要素：

  • 具体：确定确切问题
  • 可操作的：明确该做什么
  • 独立完整：不需要阅读观察
  • 可搜索：包含关键术语（hook、timeout、npm）
  • 分类：图标表示类型

3. 按上下文分组 ​

观测按以下方式分组：

  • 日期：时间上下文
  • 文件路径：空间上下文（针对特定文件工作）
  • 项目：逻辑上下文
markdown
**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 |

好处： 如果代理正在处理 src/hooks/context-hook.ts，相关的观察结果已经被归类在一起。

4. 提供检索工具 ​

没有检索机制，索引是无用的：

markdown
*Use claude-mem MCP search to access records with the given ID*

可用的 MCP 工具:

  • search - 搜索内存索引（第1层：获取ID）
  • timeline - 获取时间顺序背景（第2层：查看叙事弧）
  • get_observations - 获取完整详情（第3层：深入探索）

三层工作流程确保渐进式展示：索引 → 上下文 → 细节。

现实世界的例子 ​

场景：代理被要求修复 hooks 中的一个错误 ​

未使用渐进式披露：

SessionStart injects 25,000 个 token 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%

索引条目 ​

markdown
| #2543 | 2:14 PM | 🔴 | Hook timeout: 60s too short for npm install | ~155 |

代理在不获取信息时学到的内容：

  • 关于钩子超时有一个已知的问题（🔴）
  • 这与 npm install 运行过慢有关
  • 完整详情约为155个标记（便宜）
  • 发生在下午2:14（最近）

决策树：

Is my task related to hooks? → YES
Is my task related to timeouts? → YES
Is my task related to npm? → YES
155 个 token is cheap → FETCH IT

三层工作流 ​

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

第1层：搜索（索引） ​

首先通过搜索获取一个带有 ID 的紧凑索引：

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

返回:

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 价值： 代理可以扫描并决定哪些观察是相关的

第2层：时间线（上下文） ​

获取有关有趣观察的时间顺序背景：

typescript
timeline({
  anchor: 2543,  // Observation ID from search
  depth_before: 3,
  depth_after: 3
})

返回值: 按时间顺序显示在观测 #2543 之前/期间/之后发生的情况

费用： 根据深度而变化 价值: 理解叙事弧线和背景

第3层：获取观察（详细信息） ​

仅获取相关观察的完整详细信息：

typescript
get_observations({
  ids: [2543, 2102]  // Selected from search results
})

返回:

#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 价值: 对问题的全面理解

认知负荷理论 ​

渐进式揭示的基础是认知负荷理论：

内在负荷 ​

任务本身的固有困难。

示例: "修复身份验证错误"

  • 必须了解认证系统
  • 必须理解这个漏洞
  • 必须写修复

这个负载是不可避免的。

额外负荷 ​

呈现不佳的信息所带来的认知负担。

传统 RAG 增加了额外负担：

  • 扫描无关的观察
  • 过滤噪音
  • 记住该忽略的事情
  • 在每一部分之后重新置入语境

渐进式披露可减少额外负担：

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

相关负载 ​

构建心理模型和图式的努力。

渐进式披露支持相关认知负荷：

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

应避免的反模式 ​

❌ 冗长的标题 ​

坏:

| #2543 | 2:14 PM | 🔴 | Investigation into the issue where hooks time out | ~155 |

好：

| #2543 | 2:14 PM | 🔴 | Hook timeout: 60s too short for npm install | ~155 |

❌ 隐藏费用 ​

坏:

| #2543 | 2:14 PM | 🔴 | Hook timeout issue |

好：

| #2543 | 2:14 PM | 🔴 | Hook timeout issue | ~155 |

❌ 无检索路径 ​

坏:

Here are 10 observations. [No instructions on how to get full details]

好：

Here are 10 observations.
*Use MCP search tools to fetch full observation details on-demand*

❌ 跳过索引层 ​

坏:

typescript
// Fetching full details immediately
get_observations({
  ids: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]  // Guessing which are relevant
})

好：

typescript
// Follow the 3-layer workflow
// Layer 1: Search for index
search({
  query: "hooks",
  limit: 20
})

// Layer 2: Review index, identify 2-3 relevant IDs

// Layer 3: Fetch only relevant observations
get_observations({
  ids: [2543, 2891]  // Just the most relevant
})

关键设计决策 ​

为什么要计算 token 数量？ ​

**决定：**显示大致的 token 数量（约 155、约 203），而不是精确数量。

理由：

  • 传达规模（50 对 500）而不产生虚假精确性
  • 符合人类直觉（小/中/大）
  • 允许代理分配注意力
  • 鼓励注重成本的检索

为什么使用图标而不是文字标签？ ​

决策： 使用表情符号图标（🔴, 🟡, 🔵）而不是文字（GOTCHA, PROBLEM, HOWTO）。

理由：

  • 视觉扫描（模式识别）
  • token 高效（1 个字符 vs 10 个字符）
  • 与语言无关
  • 在美学上独特
  • 适用于人类和人工智能

为什么先索引，而不是智能预取？ ​

决定: 总是先显示索引，即使我们“知道”什么是相关的。

理由：

  • 我们无法比代理更清楚什么是相关的
  • 预取假设我们理解任务
  • 代理知道当前的上下文，我们不知道
  • 尊重代理人的自主性
  • 优雅地失败（总是可以获取更多）

为什么按文件路径分组？ ​

决策: 除日期外，还按文件路径对观察进行分组。

理由：

  • 空间局部性：处理文件 X 可能需要关于文件 X 的上下文
  • 减少扫描工作量
  • 与开发者思维相匹配
  • 清晰的语义边界

衡量成功 ​

渐进式披露在以下情况下有效：

✅ 低废料率 ​

Relevant Tokens / Total Context Tokens > 80%

大多数消耗的上下文实际上是有用的。

✅ 选择性提取 ​

Index Shown: 50 observations
Details Fetched: 2-3 observations

代理正在有选择地处理，而不是获取所有内容。

✅ 快速完成任务 ​

Session with index: 30 seconds to find relevant context
Session without: 90 seconds scanning all context

获取相关信息的时间更快。

✅ 适当深度 ​

Simple task: Only index needed
Medium task: 1-2 observations fetched
Complex task: 5-10 observations + code reads

深度随任务复杂性增长。

未来改进 ​

自适应索引大小 ​

typescript
// Vary index size based on session type
SessionStart({ source: "startup" }):
  → Show last 10 sessions (small index)

SessionStart({ source: "resume" }):
  → Show only current session (micro index)

SessionStart({ source: "compact" }):
  → Show last 20 sessions (larger index)

相关性评分 ​

typescript
// Use embeddings to pre-sort index by relevance
search({
  query: "authentication bug",
  orderBy: "relevance"  // Based on semantic similarity (future enhancement)
})

成本预测 ​

markdown
💡 **Budget Estimate:**
- Fetching all 🔴 gotchas: ~450 tokens
- Fetching all file-related: ~1,200 tokens
- Fetching everything: ~8,500 tokens

渐进细节级别 ​

Layer 1: Index (titles only)
Layer 2: Summaries (2-3 sentences)
Layer 3: Full details (complete observation)
Layer 4: Source files (referenced code)

关键要点 ​

  1. 展示，而不是说明：索引显示存在的事物，而不强制消费
  2. 注重成本：让检索成本可见，以便做出明智的决策
  3. 代理自主性：让代理决定什么是相关的
  4. 语义压缩：好的标题成就或破坏系统
  5. 一致的结构：模式减少认知负担
  6. 两级一切：先索引，按需查看详情
  7. 作为货币的情境：明智地花费在高价值信息上

记住 ​

“最好的界面是在不需要时消失，在需要时恰好出现。”

渐进式披露尊重代理的智慧和自主性。我们提供地图；代理选择路径。

进一步阅读 ​

这一理念源自Claude-Mem在数百次编码会话中的实际使用。该模式有效，因为它同时符合人类认知和大型语言模型注意力机制。