heartbeat · diff
git:20260409.2507e2a to git:20260413.da6f796
46 added, 42 removed. Audit A to A.
---
name: heartbeat
- description: Run agent heartbeat checks — memory consolidation, proactive checks, session review. Triggers on /agent:heartbeat, "heartbeat", "heartbeat check", "periodic check", "consolidar memoria".
+ description: Run agent heartbeat — periodic checks, memory consolidation, proactive work. Triggers on /agent:heartbeat, "heartbeat", "heartbeat check", "periodic check", "consolidar memoria".
user-invocable: true
---
- # Heartbeat Check
+ # Heartbeat
- Run the agent's periodic checks and memory consolidation.
+ Run the agent's periodic checks. Triggered every 30 minutes by a local cron, or manually.
- ## Active Hours
+ ## How it works
- Heartbeats should only run during the user's active hours. Check `agent-config.json` for:
- ```json
- "heartbeat": {
- "activeHours": {
- "start": "08:00",
- "end": "23:00",
- "timezone": "America/Santiago"
- }
- }
- ```
+ 1. **Check active hours** — read `agent-config.json` for `heartbeat.activeHours`. If outside the window, skip silently.
- If current time is outside active hours, skip the heartbeat silently.
+ 2. **Load state** — read `memory/heartbeat-state.json` (if exists) to know when each check last ran. Avoid repeating checks done less than 30 min ago.
- ## Steps
+ 3. **Read HEARTBEAT.md** — this is the checklist. Follow it strictly. Do not infer or repeat old tasks from prior conversations. If nothing in the checklist needs attention, skip to step 6.
- 1. **Check active hours** — if outside the configured window, do nothing.
+ 4. **Execute checks** — rotate through the items in HEARTBEAT.md, doing 2-4 per heartbeat (not all every time). For each:
+ - Memory consolidation: review last 3 daily logs → distill insights → update MEMORY.md
+ - Dream review: `dream(action='status')` → note high-recall items not yet promoted
+ - Custom checks: whatever the user added to HEARTBEAT.md (emails, health, projects, etc.)
- 2. **Read HEARTBEAT.md** from the project root (if it exists) for specific check instructions.
+ 5. **Proactive work** (do without asking):
+ - Organize memory files
+ - Remove outdated entries from MEMORY.md
+ - Check `IMPORT_BACKLOG.md` if it exists — remind user about pending items
+ - Verify installed skills are accessible
- 3. **Review recent daily files:**
- - Read `memory/YYYY-MM-DD.md` (today) and yesterday's
- - Look for items that need attention, follow-ups, or consolidation
+ 6. **Update state** — write `memory/heartbeat-state.json` with timestamps for each check performed.
- 4. **Memory consolidation:**
- a. Read through recent daily files (last 3 days)
- b. Identify significant events, lessons, or insights worth keeping long-term
- c. Update `memory/MEMORY.md` with distilled learnings
- d. Remove outdated info from MEMORY.md
+ 7. **Notify or stay quiet:**
+ - If something needs the user's attention → notify (via reply tool if on a messaging channel, or print if CLI)
+ - If nothing noteworthy → do nothing. No "heartbeat completed" messages.
- Think of it like reviewing a journal and updating your mental model.
- Daily files = raw notes. MEMORY.md = curated wisdom.
+ ## Self-managing the checklist
- 5. **Dream review** (optional):
- - Run `dream(action='status')` to check dreaming state
- - If there are high-recall memories not yet in MEMORY.md, note them
+ The agent should **edit HEARTBEAT.md during normal conversations** when something needs periodic attention:
- 6. **Report findings** to the user only if something needs attention.
- If nothing noteworthy, do nothing — don't announce routine heartbeats.
+ - User says "revísame los emails cada rato" → agent adds `- **Email inbox** — check for urgent unread` to HEARTBEAT.md
+ - User installs a new skill with periodic needs → agent adds a check for it
+ - A reminder is due daily → agent adds it to HEARTBEAT.md instead of creating a separate cron
+ - When a check is no longer needed → agent removes it from HEARTBEAT.md
- ## Scheduling
+ **Rule:** batch similar checks into HEARTBEAT.md instead of creating multiple cron jobs. Heartbeats are cheaper (one turn, multiple checks) than separate crons (one turn each).
- The heartbeat cron is created automatically on first session:
- - Default: every 30 minutes
- - Only runs while Claude Code is open and REPL is idle
- - Durable (survives Claude Code restarts within 7 days)
+ ## Active hours
- To change schedule: update via `/agent:settings` and recreate the cron.
+ ```json
+ {
+ "heartbeat": {
+ "activeHours": {
+ "start": "08:00",
+ "end": "23:00",
+ "timezone": "America/Santiago"
+ }
+ }
+ }
+ ```
- ## Nightly Dreaming
+ Outside this window, heartbeats skip silently. Configure via `/agent:settings`.
- A separate nightly cron (3 AM) triggers `dream(action='run')` for full memory consolidation.
- This is independent of heartbeats — dreaming handles promotion to MEMORY.md via weighted scoring.
+ ## Scheduling
+
+ Created automatically on first session (SessionStart hook):
+ - Default: `*/30 * * * *` (every 30 minutes)
+ - Only fires while Claude Code is open and REPL is idle
+ - For 24/7 heartbeats, use `/agent:service install`