OpenClaw Moves HEARTBEAT.md into SQLite-Backed Monitor Scratch

OpenClaw merged a significant heartbeat storage change into main on 23 July 2026: the checklist and context previously read from each agent workspace’s HEARTBEAT.md now belong to the agent’s system-managed heartbeat cron job as private, SQLite-backed monitor scratch.

This is an operational migration, not merely a renamed file. Existing source-build operators should run the supported Doctor migration when they adopt a build containing PR #112967, then verify the scratch and archived source. Packaged users should wait for a release that explicitly includes the merged commit; at verification time, npm latest remained 2026.7.1-2, npm beta remained 2026.7.2-beta.3, and the latest GitHub release was v2026.7.1, all predating this merge.

Operator decision

• Current packaged installs: do not delete or relocate HEARTBEAT.md because this change exists on GitHub. A merged pull request is not proof that your installed package understands monitor scratch.
• Source builds containing commit 3e2b3ea4: back up OpenClaw state, run openclaw doctor --fix, and inspect the migrated heartbeat monitor before removing any backup evidence.
• Automation wrappers: stop treating the workspace file as the long-term writable authority. Use openclaw cron scratch or the admin-only scratch RPC once your build supports it.
• Teams storing secrets in heartbeat context: remove them before migration. Scratch is private from ordinary cron listing surfaces, but its contents are still inserted into model prompt context.

What changed

Heartbeat cadence had already moved under the Gateway’s cron scheduler: one system-owned monitor job exists for each heartbeat-enabled agent. This merge moves the monitor’s context into that same ownership boundary.

The new cron_job_scratch table stores one scratch document per job in the shared state database. Upstream describes three safeguards that matter operationally:

1. A 256 KiB size cap prevents an accidentally huge checklist from becoming unbounded prompt context.
2. Compare-and-swap revisions allow an editor to reject a write when another actor changed the scratch after it was read.
3. Revision tombstones keep revision history monotonic after an unset-and-recreate cycle, preventing an old writer from restoring stale content with a reused revision.

The heartbeat runner now reads monitor scratch rather than performing a steady-state workspace file read. Scratch can contain ordinary prose or the existing structured tasks: block. The agent can also replace its own future scratch through the heartbeat response tool; upstream says the replacement content is kept out of model-visible tool output and channel payloads.

That is the deeper design change: heartbeat context is no longer general workspace bootstrap material. It is scheduler-owned automation state with explicit concurrency and lifecycle rules.

The supported migration path

For an enrolled agent with a legacy file, the documented command is:

openclaw doctor --fix

According to the merged pull request and versioned heartbeat documentation, Doctor imports the file into that agent monitor’s scratch, verifies the database write, archives the original under the OpenClaw state directory at backups/heartbeat-migration/, and then removes the workspace copy.

The migration is deliberately conservative. It refuses several inputs rather than guessing, including files larger than 256 KiB, non-UTF-8 content, hard-linked files, and symlinks escaping the workspace. It also does not overwrite scratch an operator has already edited. Re-running Doctor is intended to be idempotent.

For one stated upgrade window, an unmigrated file remains a read-only fallback when no scratch revision exists, accompanied by a Gateway warning. That fallback is migration insurance, not a reason to keep editing the file indefinitely. New workspaces no longer seed HEARTBEAT.md, and completed migrations use database scratch.

Do not reproduce the move manually with a database editor. The supported path includes provenance, revision handling, post-write verification and archival semantics that a copy-and-delete script would bypass.

How to verify the result

First find the system-managed monitor. Disabled jobs are hidden by the default list view, so include all jobs:

openclaw cron list --all

The merged docs describe the monitor name as Heartbeat (agent-id). Use its job ID to inspect scratch and revision metadata:

openclaw cron scratch <jobId> --json

Then perform four checks:

1. The scratch content matches the intended checklist or tasks: block.
2. The original file is no longer being treated as live writable state.
3. The archived source exists under the migration backup directory before you prune anything.
4. A later heartbeat behaves as expected within configured cadence, active hours, cooldown and delivery policy.

To update scratch safely from a file:

openclaw cron scratch <jobId> --file notes.md --expected-revision <revision>

The explicit revision turns an unnoticed concurrent overwrite into a failed command. Other supported operations include --set, --unset, and reading the current value without a mutation flag.

Scratch is intentionally absent from cron list, cron get, and cron runs output. That reduces accidental disclosure in routine diagnostics, but it does not make scratch a secret store. The heartbeat runner appends it to a model prompt, so credentials, tokens, private keys and unnecessary personal data do not belong there.

What does not change

This merge does not turn every tasks: entry into a standalone cron job; the pull request explicitly defers that semantic change. A heartbeat remains a periodic agent turn subject to heartbeat-specific guards. The scheduler owns cadence, but the heartbeat runner can still skip a tick because of active hours, cooldown, busy lanes, empty effective scratch, or no due tasks.

Disabling heartbeat with an interval of 0m also does not delete its context. The system monitor remains disabled and its scratch survives so it can be reused after re-enabling. Removing the owning job, by contrast, prunes its scratch.

The accepted configuration value agents.defaults.skipOptionalBootstrapFiles: ["HEARTBEAT.md"] remains as a no-op for compatibility. Operators should not mistake accepted legacy configuration for evidence that the file is still authoritative.

Why this matters

Interpretation: this is the final ownership step in a larger automation consolidation. OpenClaw has already moved cron definitions, runtime state and history into SQLite. Making heartbeat context belong to the monitor job aligns the checklist, cadence and lifecycle under one transactional system instead of splitting them between a database row and an editable workspace file.

That should make concurrent edits and disable/re-enable cycles safer. It also changes backup and recovery expectations. A workspace-only backup will no longer contain the live heartbeat checklist after migration; operators need to include OpenClaw’s shared state database and migration archives in their state-protection plan.

The immediate instruction is narrow: do nothing on an older package; use Doctor—not a hand-written move—when a release or source build containing this commit reaches your installation; then verify both database scratch and the archived original.

Verification note: OpenClaw Academy checked the merged pull request, merge commit, documentation at that exact commit, GitHub release metadata and npm distribution tags on 23 July 2026. We did not run the unreleased source build or execute the migration against a live workspace. Migration behaviour and upstream test outcomes are therefore attributed to the primary sources.