# reflect

通过 dry-run planning 和 audit evidence 执行有界的 consolidation 与 memory-lifecycle maintenance pass。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/reflect
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 7afa4b8d44fff19ccfcb601c0e34865481552d9859f6c34ad606585ce7cba9a4
- Edition-Digest: 055ea758c60362f258687892c2d0de5c41e55470ddd30e8ef6078980a4ff8464
- Source-Revision: sha256:fba63cf2a719e03b0aeff710b1b21a15473a175f8e5efc7000cc9bc6ebb7792a

## Tool Reference: `reflect`

### Purpose

执行有界的 Dream/Reflection maintenance pass，报告 consolidation 和 memory-lifecycle decisions，并可选择应用选定的 writes。

### Parameters

- `actions_csv` (string, optional, default: summarize,promote,expire,decay,archive): 逗号分隔的 actions。已发布的 actions 是 summarize、promote、expire、decay 和 archive；summary、promotion、expiry、importance_decay 等 alias 会由 compactor 规范化。
- `dry_run` (boolean, optional, default: false): 为 true 时计算 candidates 和 counts，但不执行 consolidation 或 lifecycle writes；review 时优先使用。
- `time_window_hours` (number, optional, default: 24.0): 用于 episodic summarize/promote 选择的正数回溯窗口；提供 since 时会覆盖它。
- `since / until` (string, optional, default: empty): reflection window 的可选 ISO 8601 边界；格式错误的 timestamp 会被拒绝。
- `path_filter / owner_filter` (string, optional, default: % / authenticated owner): Logical path 和 owner filters。server 会根据认证 context 解析 owner filter。
- `bucket / scope / team_id` (string, optional, default: % / empty / empty): 可选的 memory boundary filters；显式 team_id 必须匹配 bound/authenticated team context。
- `limit` (integer, optional, default: 500): 传给 compactor 的最大 candidate budget；实现会将其限制在支持的范围内。

### Returns

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。

### Errors

- 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。

### Examples

#### 预览完整的 maintenance pass



```typescript
reflect({
  actions_csv: "summarize,promote,expire,decay,archive",
  dry_run: true,
  time_window_hours: 24,
  limit: 500
})
```

#### 应用一个明确授权的 lifecycle action



```typescript
reflect({
  actions_csv: "archive",
  dry_run: false,
  bucket: "personal",
  limit: 100
})
```

### Related Tools

- [recall_context](/docs/tools/recall-context): 在决定是否需要 maintenance 前读取有界的 context pack。
- [remember](/docs/tools/remember): 无需 consolidation pass 时，持久化一个明确请求的 durable fact。
- [search_memory](/docs/tools/search): 需要 retrieval 而不是 lifecycle maintenance 时搜索已授权的 memory。

## 修改 memory 前先预览

使用 dry_run=true 检查已发布的五种 reflection action、各自的 counts 和 candidate details，然后再允许 summary、promotion、expiry、decay 或 archive write。