# reflect

Run a bounded consolidation and memory-lifecycle maintenance pass with dry-run planning and audit evidence.

- Canonical: https://docs.xmemo.dev/docs/tools/reflect
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 7afa4b8d44fff19ccfcb601c0e34865481552d9859f6c34ad606585ce7cba9a4
- Edition-Digest: d05d99be58f169efa9b5e69ef5a3ac782a21c5acc1af24758d01d35bd935a3af
- Source-Revision: sha256:fba63cf2a719e03b0aeff710b1b21a15473a175f8e5efc7000cc9bc6ebb7792a

## Tool Reference: `reflect`

### Purpose

Run a bounded Dream/Reflection maintenance pass that reports consolidation and memory-lifecycle decisions, optionally applying the selected writes.

### Parameters

- `actions_csv` (string, optional, default: summarize,promote,expire,decay,archive): Comma-separated actions. The shipped actions are summarize, promote, expire, decay, and archive; aliases such as summary, promotion, expiry, and importance_decay are normalized by the compactor.
- `dry_run` (boolean, optional, default: false): When true, calculate candidates and counts without consolidation or lifecycle writes; prefer it for review.
- `time_window_hours` (number, optional, default: 24.0): Positive lookback window for episodic summarize/promote selection; since overrides it when supplied.
- `since / until` (string, optional, default: empty): Optional ISO 8601 bounds for the reflection window; malformed timestamps are rejected.
- `path_filter / owner_filter` (string, optional, default: % / authenticated owner): Logical path and owner filters. The server resolves the owner filter against the authenticated context.
- `bucket / scope / team_id` (string, optional, default: % / empty / empty): Optional memory boundary filters; an explicit team_id must match the bound/authenticated team context.
- `limit` (integer, optional, default: 500): Maximum candidate budget passed to the compactor; the implementation bounds it to its supported range.

### Returns

The compactor builds a report with dry_run, normalized actions, filters, summaries, promotions, lifecycle details, counts.summarized/promoted/expired/decayed/archived, and audit_record_ids. The MCP text response begins with '### Memory Reflect Report' and renders Dry Run, Actions, all five counts, Audit Records, and up to the first 20 Audit IDs.

### Errors

- 401/403: the caller lacks the read scope for dry_run or write scope for a mutating run, or the requested owner/team/bound space is not authorized.
- Validation failure: an action is unsupported, time_window_hours is not positive, since/until is not ISO 8601, or a boundary/limit value is invalid.
- Team authorization failure: a non-authorized team lifecycle mutation is rejected rather than silently applied.
- Concurrency or audit failure: a changed memory, incomplete status transition, or failed consolidation audit is rolled back or reported as an error.

### Examples

#### Preview a full maintenance pass



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

#### Apply one explicitly authorized lifecycle action



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

### Related Tools

- [recall_context](/docs/tools/recall-context): Read a bounded context pack before deciding whether maintenance is needed.
- [remember](/docs/tools/remember): Persist one explicitly requested durable fact without running a consolidation pass.
- [search_memory](/docs/tools/search): Search authorized memories when you need retrieval rather than lifecycle maintenance.

## Preview before changing memory

Use dry_run=true to inspect the five released reflection actions, their counts, and candidate details before allowing a summary, promotion, expiry, decay, or archive write.