Nag — Persistent Reminders

Nag manages reminders that don't give up. Each reminder has a first-fire time, a nag window, and resets daily.

When to Use

• - Recurring daily habits (supplements, workouts, practice)
• Tasks that get ignored/forgotten without follow-up
• Anything where "remind me once" isn't enough

When NOT to Use

• - One-shot reminders ("remind me in 20 minutes") — use a cron job with INLINECODE0
• Time-critical alerts that can't wait for a heartbeat cycle
• Reminders that don't need confirmation (informational only)

Setup

1. State File

Create memory/nag-state.json in the workspace:

CODEBLOCK0

The date field triggers automatic daily resets — when today's date differs from the stored date, all reminders reset to unconfirmed.

2. Reminder Config

Create nag-config.json in the workspace root:

CODEBLOCK1

Fields:

Field	Required	Description
INLINECODE3	yes	Unique identifier, used as key in state file
INLINECODE4

yes | Human-readable name for display |
| cronFirst | yes | Cron expression for initial reminder (create a cron job for this) |
| nagAfter | yes | Time (HH:MM, 24h) after which heartbeat nags begin |
| confirmPatterns | yes | Array of phrases that mark the reminder as done (case-insensitive, substring match) |
| tone | no | Personality guidance for generating nag messages. If absent, use a neutral friendly tone. The model has creative liberty to vary the wording each nag. |
| messages.first | no | Text sent by the cron job for the initial reminder. If absent, generate from label + tone. |
| messages.nag | no | Suggested nag text. If absent, generate contextually from label + tone + nagCount. |
| messages.escalate | no | Suggested text after 3+ ignored nags. If absent, generate with increased urgency from tone. |
| days | no | Array of weekday names to restrict when this reminder fires (e.g. ["monday", "wednesday", "friday"]). Omit for every day. |

For more examples, see references/config-examples.md.

Message generation: When messages.nag or messages.escalate are absent, generate them on the fly using the label and tone fields. Vary the wording each time — don't repeat the same nag verbatim. Use nagCount to calibrate urgency: low count = gentle, 3+ = escalated.

3. Wire Up Cron + Heartbeat

For each reminder, create a cron job that fires messages.first at the cronFirst schedule.

In HEARTBEAT.md, add a nag check block:

CODEBLOCK2

4. Confirmation Handling

When the user sends a message matching any confirmPatterns for a reminder, update memory/nag-state.json:

CODEBLOCK3

Match confirmation by checking if any pattern appears as a substring (case-insensitive) in the user's message. When ambiguous (multiple reminders could match), match the one currently in its nag window.

Adding a New Reminder

1. 1. Add entry to INLINECODE22
2. Create a cron job for the cronFirst schedule
3. The heartbeat nag block handles everything else automatically

Removing a Reminder

1. 1. Remove entry from INLINECODE24
2. Remove or disable the corresponding cron job
3. Optionally clean up its key from INLINECODE25