PR #65589: feat(memory-core): dreaming circuit breaker to prevent runaway cost and data corruption

• Repository: openclaw/openclaw
• Author: bahadorkhaleghi1982
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/65589

Description (problem / solution / changelog)

Summary

• Adds a DreamingBudgetEnforcer module to the memory-core plugin that prevents dreaming runaway loops from burning unbounded API costs and corrupting daily notes
• Implements three independent safety layers: per-cycle deduplication, sliding-window cost circuit breaker, and confidence-gated candidate filtering
• Includes an integration helper (filterCandidatesThroughEnforcer) showing exactly how the enforcer plugs into the existing dreaming.ts pipeline
• Covers all functionality with 51 unit tests including boundary conditions, persistence round-trips, and edge cases

Motivation

Issue #65550 documents a real production incident where the dreaming system entered an uncontrolled loop:

• 94 LLM subagent sessions spawned in 65 minutes
• $4.35 burned on API calls producing entirely garbage output
• 302 lines of dream fragments overwrote real daily notes (data corruption)
• All candidates had confidence: 0.00, recalls: 0 — zero-value entries that should never have been processed
• 76 of 94 sessions reprocessed the same stale data with no deduplication

Root causes identified:

1. No per-cycle deduplication — same candidates reprocessed in tight loops
2. No cost tracking or budget cap — no awareness of accumulated API spend
3. No candidate quality gate — zero-confidence entries passed through to expensive LLM calls

Users' only recourse is disabling dreaming entirely (dreaming.enabled: false), losing the long-term memory consolidation feature that is a core differentiator of OpenClaw.

Design

DreamingBudgetEnforcer (dreaming-budget.ts)

A stateful class instantiated at the start of each dreaming cycle with three guard methods:

Plus a composite checkCandidate() that runs all three checks in priority order (budget > quality > dedup).

Persistence: Budget state is saved to memory/.dreams/dreaming-budget.json via atomic write (temp file + rename) so it survives SIGUSR1 restarts. Uses the same file I/O patterns as short-term-promotion.ts.

Configuration: All thresholds are configurable via the plugin config schema under dreaming.budget:

{
  "dreaming": {
    "budget": {
      "maxCostUsd": 1.0,
      "windowMs": 3600000,
      "minConfidence": 0.05,
      "minRecalls": 1
    }
  }
}

Integration guide (dreaming-budget-integration.ts)

Documents the 6 exact integration points in the existing dreaming.ts pipeline with code snippets showing where each enforcer call is inserted. Also exports filterCandidatesThroughEnforcer() — a helper that filters ranked promotion candidates through all three safety layers and returns a breakdown of skip reasons.

Test plan

• 51 vitest unit tests covering:
  • Fingerprinting: consistency, normalization, uniqueness, format validation
  • Deduplication: first/second encounter, case variants, cross-instance independence
  • Quality gate: zero confidence, zero recall, NaN, negative, custom thresholds
  • Cost breaker: under/over budget, latching behavior, window reset, default cost, invalid values
  • Composite check: priority ordering (budget > quality > dedup)
  • Persistence: save/load round-trip, missing file, corrupt JSON, wrong version, restart survival
  • Integration filter: valid candidates, duplicates, low quality, budget exceeded, empty list
  • Boundary conditions: exactly-at-threshold for confidence/cost, latch persistence through window expiry, state immutability
• Verify existing dreaming.test.ts tests still pass after integration
• Manual test: enable dreaming with budget.maxCostUsd: 0.10 and verify the cycle halts at the budget with a warning log

Closes #65550

Changed files

• extensions/memory-core/src/dreaming-budget-integration.ts (added, +167/-0)
• extensions/memory-core/src/dreaming-budget.test.ts (added, +541/-0)
• extensions/memory-core/src/dreaming-budget.ts (added, +245/-0)