Your HEARTBEAT.md should be boring

A good HEARTBEAT.md is a small monitoring checklist for one context-aware agent turn. It says what to glance at, what deserves interruption, and when to stay quiet. Recurring jobs belong in OpenClaw Automations, not in an ever-growing heartbeat file.

Boring is a feature here. The heartbeat is read often. Every paragraph competes for attention, tokens, and judgment on every wake. If the file becomes your scheduler, project manager, incident system, and diary, it will eventually become bad at all four.

What belongs in HEARTBEAT.md

• Two or three small checks that benefit from the same recent conversation context.
• Clear thresholds for when the user should be interrupted.
• A quiet success path, usually HEARTBEAT_OK when nothing needs attention.
• References to deeper task instructions stored elsewhere.
• Active-hours or quiet-hours guidance when alerts are not urgent.

What does not belong in HEARTBEAT.md

• Independent recurring schedules. Create Automations for those.
• Long implementation playbooks copied in full.
• Multi-hour research, builds, migrations, or deployments.
• Mutable last-run logic that marks work complete before it is verified.
• A complete backlog that gets reread every 30 minutes.
• Checks a deterministic script can perform without a model.

The scheduler and executor should be different things

A heartbeat can notice that the content queue is low. It should then point to a bounded marketing workflow or create a tracked task. The heartbeat should not research five markets, draft twenty posts, run eight builds, deploy eight sites, and somehow remain the thing that notices your calendar meeting in 40 minutes.

This separation gives each layer a simple contract. Heartbeat detects. Automation schedules. A task executes. The task artifact proves the result. If one layer fails, you know where to look.

A compact example

# HEARTBEAT.md

Check the monitor items below in one short turn.

- Inbox: alert only for messages that need action today.
- Calendar: alert for events starting within two hours that need preparation.
- Background work: surface only a new failure, blocker, or completed artifact awaiting review.

Quiet hours: 11pm to 8am unless an issue is genuinely urgent.
If nothing needs attention, reply HEARTBEAT_OK.

There are no faux cron expressions in that file. The Gateway heartbeat cadence controls when the monitor turn happens. Independent daily or weekly work gets its own Automation and task record.

Keep detailed task prompts out of the hot path

If a monitor item needs twenty lines of instructions, put those instructions in a separate file and link to it. Load the deeper file only when the condition is met. This is progressive disclosure for your agent's context: cheap awareness first, expensive execution only when needed.

- Product queue health: if any active product has fewer than five future posts or no post due within four days, run `memory/heartbeat-tasks/marketing-queue-health.md`. Otherwise skip.

The linked task can contain repository paths, validation commands, queue rules, and closeout requirements. The heartbeat pays for one sentence until there is actual work to do.

Write notification thresholds like a human

The heartbeat's job is not to prove it woke up. It is to preserve signal. Repeating 'three emails arrived' every half hour trains the user to ignore the channel that should carry important news.

How to test a heartbeat

1. Run it when nothing is happening. It should stay quiet.
2. Create one clearly actionable condition. It should report that condition and no unrelated trivia.
3. Create two monitor findings. It should combine them into one concise update.
4. Make a linked task fail. It should surface the blocker without claiming the work completed.
5. Measure the file after a month. If it has grown into a manual, split it again.

The rule of thumb

If the work deserves its own cadence, timeout, run history, or delivery target, it deserves an Automation. If it is a brief glance that benefits from the main session's current context, heartbeat is a good home. Keep that home tidy.