# Dream / Reflection

Periodically consolidate episodic evidence into semantic memory and apply explicit expiry, decay, and archive policies.

- Canonical: https://docs.xmemo.dev/docs/concepts/dream-reflection
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 8d5d97df7d1cbcf49d6b9fe780dad2bfe26f9b775d6100578493aa4653408865
- Edition-Digest: 591b9960240752d5bcc1f89b6fff8bd4b55b54cb7500b441ac51392c2561e8c0
- Source-Revision: sha256:c80b0f9a1c6f3fc5d7c29247e10511edfbcc48425d3d841031f128c9464cbc9c

## Reflection turns recent episodes into durable context

The shipped Dream mechanism is the reflect maintenance pass. Its summarize action reads active, server-recallable episodic memories in the requested time window, groups them by owner, bucket, scope, team, session, and path, and asks the chat provider for a source-grounded summary. A stored summary is written as a semantic memory under reflections/episodic and carries the source IDs and occurrence range for lineage.

- The default window is the previous 24 hours; since and until can replace that window.
- The default limit is 500 at the MCP tool boundary; a group below min_group_size is skipped.
- Summary writes are idempotent for the same active semantic key, so a repeated pass does not create another copy.

## Promotion requires repeated, credible evidence

The promote action is the episodic-to-semantic path for recurring facts. It groups active episodic memories by path and a pattern key, which comes from promotion_key or semantic_key metadata when present and otherwise from normalized event content. By default a group needs at least 3 occurrences, average importance of at least 0.35, and average confidence of at least 0.6. The result is one semantic fact with source lineage; in a real run the source episodes are superseded by that promotion, not hard-deleted.

```text
reflect(actions_csv="promote", dry_run=true, time_window_hours=168)
# Inspect candidates first; omit dry_run only for an explicitly requested write.
```

## Lifecycle actions keep memory current without guessing

The lifecycle portion runs selected actions in this order: expire, then decay, then archive. expire changes an active memory to expired only when expires_at is present and at or before the evaluation time. decay applies only to active memories with an age signal; it uses the most recent of last_accessed_at, the trusted lifecycle activity anchor, updated_at, or created_at, then applies one or more type-specific inactivity periods down to a floor. Recent usage can preserve a decay candidate, and identity memories are exempt from the configured decay policy.

- Default decay policy: working 1 day / -0.20 / floor 0.05; episodic 14 days / -0.10 / floor 0.10; semantic 90 days / -0.03 / floor 0.20; procedural 120 days / -0.02 / floor 0.25; identity is exempt.
- archive evaluates expired, superseded, and active rows. Expired rows are eligible immediately; superseded rows after 30 days; active rows use type retention defaults of 7 / 30 / 180 / 365 days for working / episodic / semantic / procedural.
- Importance changes and status transitions retain version snapshots and write consolidation audit records; archiving also stores an archive snapshot.

## dry_run is the safe planning boundary

Set dry_run=true to calculate summaries, promotions, lifecycle decisions, counts, and candidate details without storing a summary or promotion, superseding source episodes, changing importance, changing status, or writing an archive snapshot. A non-dry run performs the selected writes and returns their consolidation audit record IDs. The MCP invocation itself is still recorded as a reflect audit event, so planning remains observable.

```text
reflect(
  actions_csv="summarize,promote,expire,decay,archive",
  dry_run=true,
  time_window_hours=24,
  limit=500,
)
# Review counts and candidates, then repeat with dry_run=false only when authorized.
```

## What this endpoint does and does not promise

reflect is the released five-action consolidation and lifecycle surface. It is not a claim that a broader Light, REM, or Deep multi-pass design, six-signal scoring model, or autonomous scheduler is exposed by this tool. XMemo distinguishes two explicit execution models: (1) the reflect API and MCP tool surface executes on demand without a scheduler; (2) background Dream scheduling is feature-flagged and plan/entitlement-dependent (presets: manual [default], daily at owner-local 03:00, or weekly), and consolidation is not synchronous with writes.

## ChatGPT user

Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.

Connect the hosted XMemo MCP server through the ChatGPT/OpenAI app OAuth flow, then approve the memory:read and memory:write grant for your XMemo account.

Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.

If OAuth fails or tools do not appear, sign out of the MCP server in the host app, reconnect the XMemo server URL, and retry before creating direct tokens.

## Copilot / Codex developer

Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.

Use OAuth for VS Code / GitHub Copilot and Gemini CLI when available. For Copilot CLI, Codex, Cursor, or other direct MCP clients, keep XMEMO_KEY in the local environment or secret store and set a stable XMEMO_AGENT_INSTANCE_ID.

Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.

If recalls are empty, verify the selected MCP config path, the XMEMO_KEY environment variable for direct clients, and any stale OAuth credential in the host app.

## Team / enterprise pilot owner

Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.

Create or enter the protected XMemo workspace, invite approved users, then connect each client through OAuth or a scoped direct credential according to the readiness badges.

Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.

If a member cannot connect, check role permissions, OAuth approval, client readiness status, and support guidance before issuing a new token.

## Autonomous agent operator

Let headless or scheduled agents record progress, retrieve prior decisions, and keep a stable non-secret instance identity.

Fetch /api/v1/mcp/config/autonomous-agent. Prefer auth_modes.oauth when the runner supports OAuth + custom headers; use auth_modes.xmemo_key with XMEMO_KEY from a secret store only for fully headless runners.

Run one synthetic task that writes progress to XMemo, restart the runner, and confirm it recalls that progress using the same XMEMO_AGENT_INSTANCE_ID.

If attribution changes or recalls split across instances, persist XMEMO_AGENT_INSTANCE_ID outside git and verify the runner is not regenerating it on every start.