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. 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.

Update, 24 July 2026: PR #113165 completed the semantic change deferred below: legacy tasks: blocks now migrate into independent cron jobs and are no longer parsed at runtime. Later fixes also repaired lossy Doctor auth migration and SQLite upgrade hazards. Source-build operators should read our current migration safety report and use a post-fix revision before running openclaw doctor --fix.

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: commit 3e2b3ea4 alone is no longer a safe migration floor. Back up the complete OpenClaw state boundary and use a later revision containing the task, auth and database migration fixes described in the update above.
• 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 had not changed at this merge

At commit 3e2b3ea4, this merge did not turn every tasks: entry into a standalone cron job; the pull request explicitly deferred that semantic change. PR #113165 completed it later on 23 July. This section records the earlier commit’s contract rather than current main behaviour.

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; when a release containing the full migration sequence reaches your installation, use Doctor—not a hand-written move—and verify database scratch, migrated cron jobs, authentication 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, then updated the chronology on 24 July after PR #113165 and adjacent migration fixes merged. 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.