Merged
Size
L
Change Breakdown
Feature70%
Bug Fix30%
#61540feat(memory-core): add REM preview and safe promotion replay

Memory promotion preview and replay-safe deduplication added

Memory promotion preview and replay-safe deduplication added

Developers can now preview what REM surfaces before trusting it live, inspect promotion scores for any candidate, and rerun deep promotion safely without duplicating MEMORY.md entries.

The memory system's phased dreaming architecture was missing a preview layer for REM candidate truths and a safeguard against duplicate entries on promotion replay. Before this change, running deep promotion twice could append the same durable entries to MEMORY.md, and there was no way to inspect what REM was planning to surface.

Two new CLI commands address this. The rem-harness command previews current REM reflections alongside possible lasting truths and deep promotion candidates—all without writing anything. Developers can run this against their workspace to see what the system has captured and scored before any changes land. The promote-explain command takes a selector (key, path fragment, or snippet) and outputs a detailed score breakdown for any candidate, showing exactly why it would or would not promote based on frequency, relevance, diversity, recency, consolidation, and conceptual components.

Deep promotion now embeds markers in MEMORY.md when entries are written. On replay, the system reads existing markers and skips appending entries that are already present, counting them as reconciled instead. The CLI output reflects both metrics—how many entries were appended and how many were recognized as already written. This closes the duplicate-entry failure mode without requiring external state management.

View Original GitHub Description

Summary

  • Problem: phased dreaming on main did not yet have a good preview loop for REM candidate truths, and deep promotion replay could still duplicate durable entries on rerun.
  • Why it matters: we are close to shipping memory work, and we need a way to inspect what REM is surfacing before trusting it live while keeping MEMORY.md safe under retries.
  • What changed: added REM preview/candidate-truth output, openclaw memory rem-harness, openclaw memory promote-explain, and replay-safe deep promotion markers/dedupe.
  • What did NOT change (scope boundary): no Telegram review flow, no old pre-phase dreaming model, no broad heuristic/rule-based memory routing.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

  • Closes #
  • Related #60569
  • This PR fixes a bug or regression

Root Cause (if applicable)

  • Root cause: phased dreaming had the architecture split, but it was still missing three practical surfaces: REM candidate-truth preview, explainability for deep promotion, and replay-safe durable writes.
  • Missing detection / guardrail: no dedicated harness/explain path for REM and no marker-based reconciliation in MEMORY.md.
  • Contributing context (if known): earlier branch work solved this against the old dreaming model, but that functionality had not yet been ported onto the new light/deep/rem structure.

Regression Test Plan (if applicable)

  • Coverage level that should have caught this:
    • Unit test
    • Seam / integration test
    • End-to-end test
    • Existing coverage already sufficient
  • Target test or file: extensions/memory-core/src/short-term-promotion.test.ts
  • Scenario the test should lock in: rerunning deep promotion after partial state loss should reconcile an existing MEMORY.md entry instead of appending a duplicate.
  • Why this is the smallest reliable guardrail: the failure mode is local to deep-promotion apply/replay behavior.
  • Existing test that already covers this (if any): none
  • If no new test is added, why not: N/A

User-visible / Behavior Changes

  • openclaw memory rem-harness previews current REM reflections plus possible lasting truths and deep candidates.
  • openclaw memory promote-explain <selector> explains why a deep candidate scores the way it does.
  • Deep promotion reruns reconcile previously written candidates instead of duplicating MEMORY.md entries.

Diagram (if applicable)

Before:
recent recalls -> REM phase writes reflection themes
recent recalls -> deep promotion appends durable entries
rerun after partial state loss -> duplicate durable entry possible

After:
recent recalls -> REM phase writes reflections + possible lasting truths
recent recalls -> rem-harness / promote-explain preview the pipeline
recent recalls -> deep promotion writes marker-backed durable entries
rerun after partial state loss -> existing durable entry is reconciled, not duplicated

Security Impact (required)

  • New permissions/capabilities? (No)
  • Secrets/tokens handling changed? (No)
  • New/changed network calls? (No)
  • Command/tool execution surface changed? (Yes)
  • Data access scope changed? (No)
  • If any Yes, explain risk + mitigation: adds local memory CLI commands only; no new remote execution path or broader access scope.

Repro + Verification

Environment

  • OS: macOS
  • Runtime/container: local dev worktree
  • Model/provider: N/A
  • Integration/channel (if any): memory-core CLI / dreaming
  • Relevant config (redacted): default memory-core experimental dreaming config

Steps

  1. Record short-term recall entries for daily memory notes.
  2. Run openclaw memory rem-harness --json and inspect REM reflections + possible lasting truths.
  3. Run openclaw memory promote --apply twice against the same candidate set.

Expected

  • REM preview shows reflections plus possible lasting truths.
  • Deep promotion appends once and reconciles on replay.

Actual

  • Matches expected on the targeted short-term-promotion / dreaming-command test surfaces.

Evidence

  • Failing test/log before + passing after
  • Trace/log snippets
  • Screenshot/recording
  • Perf numbers (if relevant)

Human Verification (required)

  • Verified scenarios: targeted serial runs for extensions/memory-core/src/short-term-promotion.test.ts and extensions/memory-core/src/dreaming-command.test.ts; manual inspection of the new CLI/help surfaces and replay-safe marker path.
  • Edge cases checked: duplicate replay after loss of promotedAt, zero-candidate harness output, selector-based explain output.
  • What you did not verify: extensions/memory-core/src/cli.test.ts is currently hanging in this fresh worktree even when isolating an older preexisting test, so that lane still needs follow-up.

Review Conversations

  • I replied to or resolved every bot review conversation I addressed in this PR.
  • I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

  • Backward compatible? (Yes)
  • Config/env changes? (No)
  • Migration needed? (No)
  • If yes, exact upgrade steps:

Risks and Mitigations

  • Risk: REM candidate truths are still heuristic and may surface low-value warm-memory items.
    • Mitigation: keep this as preview/harness tooling plus REM-note output, not direct auto-promotion logic.
  • Risk: the CLI verification lane is not fully green yet.
    • Mitigation: PR is draft, and the known cli.test.ts hang is called out explicitly instead of being hidden.
© 2026 · via Gitpulse