Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Feature]: Add staggerMs option to dreaming cron schedule [1 pull requests]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Allow configuring a random stagger window for the dreaming cron schedule so that multiple OpenClaw instances do not fire dreaming sweeps at the exact same time.

Root Cause

Allow configuring a random stagger window for the dreaming cron schedule so that multiple OpenClaw instances do not fire dreaming sweeps at the exact same time.

Fix Action

Fixed

PR fix notes

PR #69548: feat(memory): add staggerMs option to dreaming cron schedule

Description (problem / solution / changelog)

Summary

  • Problem: Multiple OpenClaw instances sharing the same dreaming cron expression fire dreaming sweeps simultaneously, causing redundant concurrent work, I/O spikes, and potential race conditions on shared storage.
  • Why it matters: Operators in replicated/HA deployments have no built-in way to stagger dreaming execution across instances.
  • What changed: Added optional staggerMs config field to dreaming schedule, wired through the existing cron stagger infrastructure. Affects extensions/memory-core/openclaw.json, extensions/memory-core/src/dreaming.ts, and src/memory-host-sdk/dreaming.ts.
  • What did NOT change: Dreaming behavior when staggerMs is unset (falls back to cron service default). No changes to non-dreaming cron jobs, storage logic, or other plugin surfaces.

Change Type (select all)

  • Feature

Scope (select all touched areas)

  • Memory / storage

Linked Issue/PR

  • Related #69531

Root Cause (if applicable)

N/A — new feature, not a bug fix.

Regression Test Plan (if applicable)

N/A

User-visible / Behavior Changes

  • New optional config field dreaming.staggerMs in plugin config (openclaw.json), allowing operators to set a random stagger window (in ms) for the dreaming cron schedule.
  • When unset, behavior is unchanged (cron service default stagger applies).

Diagram (if applicable)

N/A — config-only change, no UI or non-trivial logic flow.

Security Impact (required)

  • New permissions/capabilities? No
  • Secrets/tokens handling changed? No
  • New/changed network calls? No
  • Command/tool execution surface changed? No
  • Data access scope changed? No

Repro + Verification

Environment

  • OS: macOS
  • Runtime: Node 22+
  • Integration: memory-core plugin

Steps

  1. Configure multiple OpenClaw instances with the same dreaming cron (e.g., 0 3 * * *)
  2. Set dreaming.staggerMs: 300000 in one instance
  3. Observe that the instance with staggerMs delays execution by a random offset within the window

Expected

Instances with staggerMs configured fire at random offsets within the window instead of all at the exact cron time.

Actual

Before this change, all instances fire simultaneously at the cron time.

Evidence

  • Trace/log snippets — verbose dreaming log now includes staggerMs value

Human Verification (required)

  • Verified scenarios: Config schema validates staggerMs as optional integer with minimum 0; unset values produce no stagger field in cron schedule; set values propagate through buildManagedDreamingCronJob and resolveShortTermPromotionDreamingConfig.
  • Edge cases checked: staggerMs: 0 is valid and explicitly passed; undefined is omitted (no stagger override).
  • What I did not verify: Full E2E test with multiple live instances (requires multi-instance setup).

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? Yes — new optional field dreaming.staggerMs
  • Migration needed? No

Risks and Mitigations

  • Risk: Operators set very large staggerMs values, causing dreaming to fire significantly later than the cron expression suggests.
    • Mitigation: The minimum: 0 schema constraint is in place; no upper bound is enforced, matching the existing cron stagger convention where operators are trusted to set reasonable values.

AI-Assisted

  • This PR is AI-assisted (Claude Code)
  • Testing degree: lightly tested (config propagation verified locally; no multi-instance E2E)
  • I confirm I understand what the code does

Changed files

  • extensions/memory-core/openclaw.plugin.json (modified, +9/-0)
  • extensions/memory-core/src/dreaming.ts (modified, +12/-3)
  • src/memory-host-sdk/dreaming.ts (modified, +16/-0)
RAW_BUFFERClick to expand / collapse

Summary

Allow configuring a random stagger window for the dreaming cron schedule so that multiple OpenClaw instances do not fire dreaming sweeps at the exact same time.

Problem to solve

When running multiple OpenClaw instances (e.g., in a replicated or HA deployment), all instances sharing the same dreaming cron expression (e.g., 0 3 * * *) trigger the dreaming sweep simultaneously. This causes:

  • Redundant concurrent work across instances performing the same promotion pass
  • Spikes in memory/storage I/O and compute load at cron fire time
  • Potential race conditions on shared storage backends

The cron subsystem already supports staggerMs in CronSchedule (src/cron/types.ts) with a default 5-minute stagger for top-of-hour schedules, but the dreaming feature does not expose or pass through this capability.

Proposed solution

Add an optional staggerMs configuration field to the dreaming schedule, wired through the existing cron stagger infrastructure:

  • dreaming.staggerMs in plugin config (openclaw.json) — optional integer, minimum 0
  • Thread staggerMs through CronSchedule, ShortTermPromotionDreamingConfig, MemoryDreamingConfig, and the managed cron job builder
  • When unset, the cron service default behavior applies (5-min stagger for top-of-hour schedules)
  • Fully backward compatible — no config migration needed

Impact

  • Affected users: Anyone running multiple OpenClaw instances with dreaming enabled
  • Severity: Medium — dreaming still works, but concurrent execution wastes resources and can degrade storage performance
  • Frequency: Every cron fire in multi-instance deployments
  • Consequence: Without this, operators must either accept redundant concurrent dreaming sweeps or implement ad-hoc jitter outside OpenClaw

Evidence/examples

The underlying staggerMs field already exists in src/cron/types.ts and src/cron/stagger.ts. This feature simply wires it through to the dreaming configuration surface.

extent analysis

TL;DR

Add an optional staggerMs configuration field to the dreaming schedule to introduce a random stagger window and prevent concurrent dreaming sweeps across multiple OpenClaw instances.

Guidance

  • Review the existing staggerMs field in src/cron/types.ts and its usage in src/cron/stagger.ts to understand the current stagger implementation.
  • Introduce the staggerMs field in the dreaming schedule configuration (openclaw.json) with a minimum value of 0, allowing users to customize the stagger window.
  • Thread the staggerMs value through the relevant configuration objects (CronSchedule, ShortTermPromotionDreamingConfig, MemoryDreamingConfig) to the managed cron job builder.
  • Verify that the default 5-minute stagger for top-of-hour schedules applies when staggerMs is unset, ensuring backward compatibility.

Example

// Example configuration with staggerMs
{
  "dreaming": {
    "staggerMs": 300000 // 5 minutes in milliseconds
  }
}

Notes

The proposed solution builds upon the existing staggerMs field in the cron subsystem, minimizing the introduction of new code and ensuring a consistent implementation.

Recommendation

Apply the proposed workaround by adding the staggerMs configuration field to the dreaming schedule, as it provides a flexible and backward-compatible solution to prevent concurrent dreaming sweeps.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#API rate limit#retriever error#indexing error#inference speed#output truncation

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix [Feature]: Add staggerMs option to dreaming cron schedule [1 pull requests]