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.
Public MCP tool
reflect
Purpose
Run a bounded Dream/Reflection maintenance pass that reports consolidation and memory-lifecycle decisions, optionally applying the selected writes.
When to use
- An authorized operator or maintenance worker needs to summarize recent episodic memories into semantic reflection records.
- You need to inspect repeated episodic evidence before deciding whether it should become a durable semantic fact.
- You need an explicit, bounded expiry, importance-decay, or archive pass over an authorized owner/team/scope boundary.
When NOT to use
- Do not use it for an ordinary user-requested durable fact; use remember or an SDK capture helper.
- Do not use it as a general search, context-recall, or hard-delete tool; use recall_context, search_memory, or the governed forget surface.
- Do not omit dry_run when the caller is only evaluating candidates or is not explicitly authorized to mutate memory.
- Do not describe this tool as the broader Light/REM/Deep Dream design or as an autonomous scheduler; the shipped surface is these five actions only.
Required scope
- dry_run=true requires memory:read; a write run requires memory:write.
- The catalog classifies reflect as an internal maintenance surface, not as a minimal public marketplace-app tool. Use it only through an authorized maintenance or direct MCP context.
- Owner, bucket, scope, team, bound-space, and agent authorization are resolved by the server; caller filters cannot expand that boundary.
Parameters
| Name | Type | Description |
|---|---|---|
actions_csv | string · 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 · default: false | When true, calculate candidates and counts without consolidation or lifecycle writes; prefer it for review. |
time_window_hours | number · default: 24.0 | Positive lookback window for episodic summarize/promote selection; since overrides it when supplied. |
since / until | string · default: empty | Optional ISO 8601 bounds for the reflection window; malformed timestamps are rejected. |
path_filter / owner_filter | string · default: % / authenticated owner | Logical path and owner filters. The server resolves the owner filter against the authenticated context. |
bucket / scope / team_id | string · default: % / empty / empty | Optional memory boundary filters; an explicit team_id must match the bound/authenticated team context. |
limit | integer · default: 500 | Maximum candidate budget passed to the compactor; the implementation bounds it to its supported range. |
Return schema
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.
Examples
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
})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.
Related tools
- recall_context — Read a bounded context pack before deciding whether maintenance is needed.
- remember — Persist one explicitly requested durable fact without running a consolidation pass.
- search_memory — Search authorized memories when you need retrieval rather than lifecycle maintenance.
Source: Dream / Reflection