在 AI 编码代理的工程实践中，上下文窗口的高效利用始终是核心挑战。传统方案倾向于在会话开始时注入大量历史上下文，然而这种方式往往导致注意力分散与 token 浪费。Claude-Mem 作为 Claude Code 的持久记忆插件，提出了一种名为「渐进式披露」（Progressive Disclosure）的上下文 priming 哲学，其核心思想是将上下文视为可消费的资源，让代理自主决定何时获取何种信息。这一设计不仅重新定义了记忆注入的时机，更为 AI 代理的上下文窗口调度提供了可复用的工程范式。

渐进式披露的核心原则

渐进式披露源于信息架构中的渐进式展开模式，其核心论点是：系统应当首先展示元数据而非完整内容，让智能体自行判断信息的相关性。在 Claude-Mem 的实现中，这一原则被具体化为三个层次的递进结构。第一层是索引层（Index），仅展示轻量级的元数据，包括观察记录的标题、发生时间、类型标记和预估 token 消耗；第二层是时间线层（Timeline），获取特定观察记录周围的时序上下文；第三层是详情层（Deep Dive），仅在代理明确判断相关性后，才获取完整的观察细节。

这种设计背后的认知基础源自认知负荷理论。传统 RAG 系统在会话启动时注入数以万计的 token，期望覆盖所有可能的场景，然而由于代理无法预知当前任务的具体需求，大量上下文沦为噪声。渐进式披露将 intrinsic load（任务本身的难度）与 extraneous load（信息呈现方式导致的额外负担）分离，通过控制信息呈现的粒度，最大限度地减少代理在无关信息上的注意力消耗。实践表明，采用渐进式披露后，上下文有效利用率可从传统方式的约 6% 提升至 80% 以上。

三层工作流的技术实现

Claude-Mem 的三层工作流通过 MCP 工具实现无缝衔接。在索引阶段，search 工具接收自然语言查询，返回包含 ID、日期、类型和标题的紧凑结果集，每个结果仅消耗约 50 至 100 token。代理扫描索引后，根据当前任务上下文判断哪些观察记录值得深入了解。若需要时序背景，可调用 timeline 工具获取目标观察前后各 N 条记录的上下文链，形成叙事弧线。最后，代理使用 get_observations 工具批量获取选定 ID 的完整细节，每次调用约消耗 155 至 500 token。

这一工作流的关键在于将检索决策权下放给代理本身。系统在会话启动时仅提供约 800 token 的索引，代理拥有 99,200 token 的可用预算用于当前任务。当代理识别到特定观察与任务相关时，才会主动触发获取操作。这种机制与传统的预取式 RAG 形成鲜明对比：后者由系统预先筛选并注入上下文，前者将相关性判断的能力赋予代理，尊重其对自身任务的理解。

记忆分层与上下文窗口调度

除了渐进式披露机制，Claude-Mem 还实现了多层次的记忆管理体系。在存储层面，系统采用 SQLite 作为结构化数据持久化引擎，使用 Chroma 向量数据库支持语义搜索能力。观察记录根据类型被标记为不同的视觉符号：🔴 表示关键陷阱（gotcha），🟡 表示问题解决方案，🔵 表示技术解释，🟢 表示代码变更，⚖️ 表示权衡决策。这种分类方式既便于人类开发者快速扫描，也为代理提供了优先级信号。

在上下文注入层面，Claude-Mem 的 SessionStart hook 负责在每次新会话启动时生成并注入记忆索引。索引的生成遵循语义压缩原则：原始观察被凝练为约 10 个词的标题，包含具体问题描述、可操作建议和检索成本信息。例如，「Hook timeout: 60s too short for npm install」这一标题在无需获取完整记录的情况下，即可传达关键信息。索引还按照文件路径和日期双重维度分组，当代理在特定文件上工作时，相关观察已被预先聚类，进一步降低了检索成本。

工程实践中的调度参数

基于 Claude-Mem 的架构设计，开发者在实现类似的上下文调度系统时可参考以下工程参数。索引大小建议控制在 800 至 1200 token 范围内，确保在会话启动时不占用过多注意力预算。观察记录的 token 阈值可设为 200 token 以下为「cheap」，200 至 500 token 为「medium」，500 token 以上为「expensive」，代理据此计算检索 ROI。三层工作流的典型调用比例为：search 返回 10 至 20 个候选，timeline 调用 2 至 3 次，get_observations 最终获取 2 至 5 个完整记录。

对于上下文窗口的调度时机，实践表明在任务切换（如用户提出新需求）或遇到错误（代理主动搜索类似问题的历史解决方案）时触发主动检索效果最佳。此外，延迟注入（lazy injection）策略值得借鉴：不在会话开始时预加载所有可能相关的记忆，而是根据代理的实际请求动态拉取，这种按需加载模式能够适应多样化的任务场景。

渐进式披露机制为 AI 编码代理的上下文管理提供了一条务实的技术路径。它不追求在有限的上下文窗口中塞入更多信息，而是通过控制信息流动的节奏，使代理能够自主管理注意力资源。随着模型上下文窗口容量的持续扩展，这种调度策略的价值将进一步凸显 —— 在注意力有限的前提下，智能化地选择「何时获取」与「获取什么」，可能比单纯扩大窗口容量更为重要。

资料来源：Claude-Mem 官方文档（docs.claude-mem.ai/progressive-disclosure）