Heartbeat Rules

Use heartbeat to keep ~/self-improving/ organized without creating churn or losing data.

Source of Truth

Keep the workspace HEARTBEAT.md snippet minimal. Treat this file as the stable contract for self-improving heartbeat behavior. Store mutable run state only in ~/self-improving/heartbeat-state.md.

Start of Every Heartbeat

1. Ensure ~/self-improving/heartbeat-state.md exists.
2. Write last_heartbeat_started_at immediately in ISO 8601.
3. Read the previous last_reviewed_change_at.
4. Scan ~/self-improving/ for files changed after that moment, excluding heartbeat-state.md itself.

If Nothing Changed

• Set last_heartbeat_result: HEARTBEAT_OK
• Append a short "no material change" note if you keep an action log
• Return HEARTBEAT_OK

If Something Changed

Only do conservative organization:

• refresh index.md if counts or file references drift
• compact oversized files by merging duplicates or summarizing repetitive entries
• move clearly misplaced notes to the right namespace only when the target is unambiguous
• preserve confirmed rules and explicit corrections exactly
• update last_reviewed_change_at only after the review finishes cleanly

Safety Rules

• Most heartbeat runs should do nothing
• Prefer append, summarize, or index fixes over large rewrites
• Never delete data, empty files, or overwrite uncertain text
• Never reorganize files outside ~/self-improving/
• If scope is ambiguous, leave files untouched and record a suggested follow-up instead

State Fields

Keep ~/self-improving/heartbeat-state.md simple:

• last_heartbeat_started_at
• last_reviewed_change_at
• last_heartbeat_result
• last_actions

Behavior Standard

Heartbeat exists to keep the memory system tidy and trustworthy. If no rule is clearly violated, do nothing.