Reference

reflect

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

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

Preview a full maintenance pass

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

Apply one explicitly authorized lifecycle action

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.

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