Edit HEARTBEAT.md

# Heartbeat Tasks — Periodic Proactive Work

## ⏰ Frequency
Heartbeat polls trigger approximately every **1–2 hours**.

**Note:** The `heartbeat-service.mjs` daemon now runs automatically and handles
routine maintenance (stale user checks, memory summarization, error logging).
During heartbeats, your role is _review and respond_ — not execute maintenance commands.

During each heartbeat, review the results and send personalized messages as needed.

---

## Task 1: Check for Stale Users

Query the Minaki API for users who haven't interacted recently:

```bash
curl -s -L -X GET "https://ahaminaki.org/api/users/stale?days=3&limit=5" \
  -H "X-API-Key: ${MINAKI_API_KEY}"
```

**Expected response:** `{ "users": [ { phone, name, daysSinceLastMessage, lastMood, hadCrisisFlag } ] }`

**Parse the response and prioritize:**
- 🔴 **P1 — Crisis follow-up** (`hadCrisisFlag: true`): Send a compassionate check-in immediately
- 🟠 **P2 — Low mood** (`lastMood ≤ 4`): Send a gentle support message
- 🟡 **P3 — General stale** (`daysSinceLastMessage ≥ 3`): Send a general wellness check-in

**Limit:** Process max **3 users per heartbeat** to avoid flooding.

**⚠️ Error handling:** If the stale user query fails (network error, 500, timeout),
log the error to `notifications/errors.md` and **skip proactive messaging for this
heartbeat cycle**. Continue with Task 4 and the routine tasks. Don't let a failed
query block the entire heartbeat.

---

## Task 2: Send Proactive Messages

For each user you decide to message (in priority order):

### A. Crisis Follow-up (P1)
```
💙 Hey — I just wanted to check in. Last time we spoke, you were going
through a tough time. How are you doing today?
```

### B. Low Mood Follow-up (P2)
```
💙 Hey! I noticed you seemed a bit down last time. Just checking in —
how are you feeling today?
```

### C. General Check-in (P3)
```
🌅 Hey! It's been a few days. Just wanted to see how you're doing.
Everything okay?
```

**Important:** The WhatsApp plugin automatically sends whatever text the bot
outputs. To send a message proactively, simply format your reply as the message
text (as if the user had just messaged you). The OpenClaw platform will deliver it.

---

## Task 3: Log Sent Messages

After sending each message, log it to Minaki for central tracking:

```bash
curl -s -L -X POST "https://ahaminaki.org/api/outbound/log" \
  -H "X-API-Key: ${MINAKI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "2547XXXXXXXX",
    "content": "<the exact message you sent>",
    "status": "sent",
    "type": "text"
  }'
```

This prevents the same user from appearing as "stale" in the next heartbeat.

---

## Task 4: Report Heartbeat Summary

At the end of the heartbeat, compose a brief summary to include in the heartbeat
response:

```
📊 **Heartbeat Results**
- Stale user query: [N] users found
- P1 crisis follow-ups sent: [N]
- P2 low-mood check-ins sent: [N]
- P3 general check-ins sent: [N]
- Errors: [any failures]
```

If any errors occurred (API call failures, send failures), log them to
`notifications/errors.md` with timestamp and details.

---

## Other Routine Tasks (Continue from AGENTS.md Section 12)

After completing the proactive messaging tasks above, continue with the
standard heartbeat routine:
- Review and organize memory files
- Update MEMORY.md with distilled learnings
- Check `notifications/` files for unread entries
- Scan USER.md files for crisis flags
- Check transcript integrity

📝 HEARTBEAT.md — Heartbeat Instructions

📜 Version History