Proposal: complete Dream lifecycle with scoped observations and reversible maintenance #2560

Proposal: complete the Dream memory lifecycle with scoped observations and reversible maintenance

I would like to align on the module boundary before implementing the larger change requested by the contribution guide. This follows the lifecycle direction in #1704, which is closed but still has an implementation gap in the inspected source.

Current evidence

At main d326a6419467c2205041b58533b0ebfdf4f38173, src/memos/dream/maintenance.py contains a contribution guide but no executable implementation. DreamMemoryLifecycle is declared in types.py but is not consumed elsewhere in the production package. The versioned dev branches also retain the same maintenance stub.

There is also a concrete storage contract failure in the existing Dream persistence path: _write_memory_archive passes update_node(id, None, metadata, user_name=...), while the base and current graph backends expose update_node(id, fields, user_name=None). A narrow native-method reproduction with a signature-conformant backend makes zero writes and logs a TypeError. UPDATE/merged-source paths need the same contract audit. I can include the reproduction in the eventual patch; this report does not claim a live backend integration run.

Proposed coherent scope

• Opt-in lifecycle policy using UTC-normalized event time, an injected clock, never-hit grace, explicit pin/exemption, bounded reinforcement and idempotent decay evaluation.
• Cube/memory/event-scoped retrieval and attributed-outcome evidence; final returned IDs are observed after filtering/reranking, and retrieval is not treated as proof of usefulness.
• Correct native persistence wiring and metadata initialization after successful writes. Preserve existing confidence, source IDs and activated/archived semantics.
• Bounded paginated maintenance, dry-run, resumable cursor, archive reasons and deliberate recovery. No hard deletion or automatic semantic contradiction detector.
• An explicit backend capability contract for conditional lifecycle updates/idempotency. A process-local lock will not be presented as a multi-worker guarantee.
• A successful-feedback observation seam that does not compete with the existing single-provider version hook.

Default behavior remains unchanged until enabled. I propose no new public API route, no model training, no new web UI, and no generic event platform.

Verification plan

Native Dream pipeline tests with fake clocks and deterministic provider boundaries, duplicate/delayed feedback, cross-cube isolation, retrieval-vs-archive races, recovery/retraction order and interruption/resume. Backend concurrency behavior will be tested against the actual initially supported services. Chronological retrieval/retention comparisons can use independently held-out LongMemEval/LoCoMo histories; engineering tests or synthetic histories will not be advertised as real-agent quality gains.

Decisions requested

1. Is this full lifecycle boundary appropriate, or is an existing maintainer implementation underway?
2. Which graph backend(s) should define the first conditional-update/idempotency contract?
3. Is a post-success feedback observer the desired extension seam?
4. Which branch should be targeted? The contribution guide says dev, but no bare dev ref exists; current default is main with versioned dev-v2.0.* branches.

The proposed implementation is a substantial module and can be split if that is the maintainers' preference. No acceptance or performance improvement is assumed. Research, reproduction and this proposal were prepared by OpenAI Codex at the account owner's request; the account owner has not personally verified the code. No product implementation has been submitted for this proposal.