# HEARTBEAT.md - Efficient Proactive Check

**Target:** <3 second checks using state tracking. Don't repeat work.

---

## Quick State Check (Read First)

```bash
# Check when each area was last reviewed
if [ -f memory/heartbeat-state.json ]; then
  cat memory/heartbeat-state.json
fi
```

**Skip if checked <4 hours ago unless urgent.**

---

## Rotating Check Schedule

Only check 1-2 items per heartbeat to stay under 3s:

| Check | Frequency | Last Check |
|-------|-----------|------------|
| Mission Control | Every 8h | See state |
| Email | Every 12h | See state |
| Calendar | Every 6h | See state |
| Memory Maintenance | Weekly | See state |
| Git Status | Every 4h | See state |

---

## Check Procedures (<30s each)

### Mission Control Scan (30s max)
1. Open http://localhost:3001 or https://mission-control.twisteddevices.com
2. Check: Overdue tasks, upcoming deadlines, blocked items
3. If found → Log to `memory/YYYY-MM-DD.md` with action needed
4. Update state: `"missionControl": [timestamp]`

### Email Quick Check (20s max)
1. Use email-assistant skill to check unread count
2. If urgent (>3 unread or flagged) → Note in memory file
3. Don't read full emails unless flagged urgent
4. Update state: `"email": [timestamp]`

### Calendar Check (20s max)
1. Check next 24h for events
2. If event <2h away → Alert user
3. Update state: `"calendar": [timestamp]`

### Git Status (15s max)
1. Check `git status` in workspace
2. If uncommitted changes >1 day old → Commit reminder
3. Update state: `"git": [timestamp]`

---

## State File Format

**File:** `memory/heartbeat-state.json`

```json
{
  "lastChecks": {
    "missionControl": 1740267600,
    "email": 1740256800,
    "calendar": 1740264000,
    "git": 1740267600,
    "memoryMaintenance": 1739922000
  },
  "alertsGiven": [],
  "version": 1
}
```

---

## When to Reply HEARTBEAT_OK

**Reply OK when:**
- All checks done within last 4h
- No urgent items found
- Late night (23:00-08:00) unless critical
- User clearly busy in conversation

**Don't reply OK when:**
- Found overdue task with deadline <24h
- Calendar event in <2h
- Uncommitted work >1 day old
- Memory maintenance overdue (>7 days)

---

## Night Check (22:00 CST)

**Different from daytime checks:**
1. Read `USER.md` - Refresh on goals/projects
2. Read `SOUL.md` - Remember The Mission
3. Scan Mission Control for next-day priorities
4. Pick ONE high-impact task for tomorrow
5. Log suggestion to `memory/YYYY-MM-DD.md`

**Format:**
```
🌙 Nightly Check — [Date]

📊 Status:
- Active tasks: X
- Overdue: X
- Tomorrow's priority: [Task name]

🎯 Suggestion:
[One specific action for tomorrow]
```

---

## Memory Maintenance (Weekly)

**During one heartbeat per week:**

1. Read last 7 days of `memory/YYYY-MM-DD.md` files
2. Identify 3-5 key learnings/insights
3. Update `MEMORY.md` with distilled wisdom
4. Remove outdated entries (>30 days old)
5. Update `BRAIN.md` active projects list
6. Reset state: `"memoryMaintenance": [timestamp]`

**Goal:** Keep MEMORY.md <100 lines, BRAIN.md current.

---

## Efficiency Rules

1. **Timebox each check** - Use 30s max, interrupt if longer
2. **Don't duplicate work** - Check state file first
3. **Batch when possible** - One web session for multiple checks
4. **Write immediately** - Don't hold in memory, log to file
5. **Prioritize** - Mission Control > Calendar > Email > Git

**Remember:** The goal is helpful presence, not exhaustive monitoring. Quality > quantity.