ai-safe2-framework

HEARTBEAT.md

OpenClaw Heartbeat Protocol — AI SAFE² Engage & Monitor Standard

Load context: Every session if heartbeats are enabled. During heartbeat turns, this file governs all behavior.
Governed by: AI SAFE² Framework · Dual License MIT + CC-BY-SA
AI SAFE² Pillar: E — Engage & Monitor


1. What a Heartbeat Is

A heartbeat is a scheduled, autonomous health check the agent runs periodically (typically every 30–60 minutes) to verify system integrity, sync state, and catch failures the user would otherwise miss. It is not a conversation turn. It is a maintenance run.

Default output: NO_REPLY — the heartbeat completes silently unless it finds something requiring user attention. A heartbeat that messages the user on every run defeats the purpose (notification fatigue is itself a security risk — it trains users to ignore alerts).

Exception: Send a direct message when the notifier path itself is broken and the user needs to intervene, or when a critical-priority finding requires immediate action.


2. Every Heartbeat

Run these checks on every heartbeat cycle:

2.1 State File Integrity

// Expected structure of memory/heartbeat-state.json
{
  "lastChecks": {
    "errorLog": null,
    "securityAudit": null,
    "lastDailyChecks": null,
    "weeklyGatewayVerify": null
  }
}

If heartbeat-state.json is missing or corrupted, replace with the default above and alert the user once.

Update timestamps for every check performed during this run.

2.2 Git Backup / Workspace Sync

2.3 Gateway Usage Sync

2.4 System Health Check

2.5 Cron Failure Deltas

2.6 Persistent Failure Check

2.7 AI SAFE² Security Scan (Quick)

Run the AI SAFE² scanner in quick mode:

python3 scanner.py --target ./openclaw-data --quick

Flag and alert on any finding that scores 8.0+ (Critical) or represents a new finding since last scan:


3. Once Daily

Run these additional checks once per day (use lastDailyChecks timestamp to gate):

3.1 Data Collection Health

3.2 Repository Size Check

3.3 Memory Index Coverage

3.4 Memory Synthesis Opportunity

3.5 Love Equation Alignment Check

Tally the session’s C (cooperation) and D (defection) events from today’s memory log. Report if:

This keeps the alignment score visible and prevents silent drift.


4. Once Weekly

Run these on the first heartbeat of each week (use weeklyGatewayVerify timestamp to gate):

4.1 Gateway Security Verification

If any check fails, alert the user immediately regardless of time of day.

4.2 Skill Inventory Review

4.3 Sub-Agent Activity Summary


5. Heartbeat Failure Handling

If the heartbeat itself fails mid-run:

  1. Log how far it got to heartbeat-state.json.
  2. Send a direct message to the user: “Heartbeat failed at <checkpoint>. Partial results logged. Manual review recommended.”
  3. Do not retry automatically until the next scheduled cycle.
  4. On the next run, re-run all checks that did not complete, regardless of their schedule tier.

6. Notification Standards for Heartbeats

All heartbeat notifications follow the standard priority queue from TOOLS.md:

Finding Priority
Gateway security misconfiguration Critical — immediate
Secret or credential found in logs Critical — immediate
Persistent failure (3+ recurrences) High — hourly batch
New cron failure High — hourly batch
Memory index below 80% Medium — 3-hour batch
Repo size warning Medium — 3-hour batch
Memory synthesis opportunity Low — daily digest
Love Equation drift indicator Medium — 3-hour batch

7. Why This File Exists

Misconfigured heartbeats can quietly burn through API budgets — but heartbeats with no health checks are worse. They run silently while the system accumulates failures, credential leaks, and alignment drift that nobody sees.

HEARTBEAT.md operationalizes AI SAFE²’s Engage & Monitor pillar into a concrete, scheduled protocol. The difference between monitoring and forensics is whether you find the problem before or after it causes harm. Heartbeats done correctly are the mechanism that turns “we noticed eventually” into “we caught it the next cycle.”


Part of the AI SAFE² OpenClaw Core File Standard.
AI SAFE² = Sanitize & Isolate · Audit & Inventory · Fail-Safe & Recovery · Engage & Monitor · Evolve & Educate