修改 memory 前先预览
使用 dry_run=true 检查已发布的五种 reflection action、各自的 counts 和 candidate details，然后再允许 summary、promotion、expiry、decay 或 archive write。
公开 MCP 工具
reflect
用途
执行有界的 Dream/Reflection maintenance pass，报告 consolidation 和 memory-lifecycle decisions，并可选择应用选定的 writes。
适用场景
- 已授权 operator 或 maintenance worker 需要将近期 episodic memories 汇总为 semantic reflection records。
- 需要检查重复的 episodic evidence，再决定它是否应成为持久 semantic fact。
- 需要在已授权的 owner/team/scope boundary 上执行明确且有界的 expiry、importance-decay 或 archive pass。
不适用场景
- 不要用于普通的用户请求持久 fact；请使用 remember 或 SDK capture helper。
- 不要将它当作通用 search、context-recall 或 hard-delete tool；请使用 recall_context、search_memory 或受治理的 forget surface。
- 当调用者只是在评估 candidates，或没有被明确授权修改 memory 时，不要省略 dry_run。
- 不要把这个工具描述为更广泛的 Light/REM/Deep Dream design 或 autonomous scheduler；已发布的 surface 只有这五种 action。
所需权限范围
- dry_run=true 需要 memory:read；写入运行需要 memory:write。
- catalog 将 reflect 归类为 internal maintenance surface，而非最小 public marketplace-app tool。只能通过已授权的 maintenance 或 direct MCP context 使用。
- Owner、bucket、scope、team、bound-space 和 agent authorization 由 server 解析；caller filters 不能扩大该 boundary。
参数列表
| 参数名 | 类型 | 描述 |
|---|---|---|
actions_csv | string · 默认值: summarize,promote,expire,decay,archive | 逗号分隔的 actions。已发布的 actions 是 summarize、promote、expire、decay 和 archive；summary、promotion、expiry、importance_decay 等 alias 会由 compactor 规范化。 |
dry_run | boolean · 默认值: false | 为 true 时计算 candidates 和 counts，但不执行 consolidation 或 lifecycle writes；review 时优先使用。 |
time_window_hours | number · 默认值: 24.0 | 用于 episodic summarize/promote 选择的正数回溯窗口；提供 since 时会覆盖它。 |
since / until | string · 默认值: empty | reflection window 的可选 ISO 8601 边界；格式错误的 timestamp 会被拒绝。 |
path_filter / owner_filter | string · 默认值: % / authenticated owner | Logical path 和 owner filters。server 会根据认证 context 解析 owner filter。 |
bucket / scope / team_id | string · 默认值: % / empty / empty | 可选的 memory boundary filters；显式 team_id 必须匹配 bound/authenticated team context。 |
limit | integer · 默认值: 500 | 传给 compactor 的最大 candidate budget；实现会将其限制在支持的范围内。 |
返回模式
compactor 会构建包含 dry_run、normalized actions、filters、summaries、promotions、lifecycle details、counts.summarized/promoted/expired/decayed/archived 和 audit_record_ids 的 report。MCP text response 以 '### Memory Reflect Report' 开头，并渲染 Dry Run、Actions、全部五个 counts、Audit Records 和最多前 20 个 Audit IDs。
使用示例
reflect({
actions_csv: "summarize,promote,expire,decay,archive",
dry_run: true,
time_window_hours: 24,
limit: 500
})reflect({
actions_csv: "archive",
dry_run: false,
bucket: "personal",
limit: 100
})错误信息
- 401/403：caller 缺少 dry_run 所需的 read scope 或 mutation run 所需的 write scope，或请求的 owner/team/bound space 未获授权。
- Validation failure：action 不受支持、time_window_hours 不是正数、since/until 不是 ISO 8601，或 boundary/limit 值无效。
- Team authorization failure：未获授权的 team lifecycle mutation 会被拒绝，而不是静默应用。
- Concurrency or audit failure：changed memory、不完整的 status transition 或失败的 consolidation audit 会被回滚或报告为 error。
关联工具
- recall_context — 在决定是否需要 maintenance 前读取有界的 context pack。
- remember — 无需 consolidation pass 时，持久化一个明确请求的 durable fact。
- search_memory — 需要 retrieval 而不是 lifecycle maintenance 时搜索已授权的 memory。