Periodically consolidate episodic evidence into semantic memory and apply explicit expiry, decay, and archive policies.
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.
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.
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.
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.
Persona flows
ChatGPT user
Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.
Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.
Copilot / Codex developer
Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.
Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.
Team / enterprise pilot owner
Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.
Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.