Nag

Nag — Persistent Reminders

Nag manages reminders that don't give up. Each reminder has a first-fire time, a nag window, and re设置s dAIly.

When to Use Recurring dAIly habits (supplements, workouts, practice) Tasks that 获取 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 schedule.kind: "at" Time-critical alerts that can't wAIt for a heartbeat cycle Reminders that don't need confirmation (in格式化ional only) 设置up

• 状态 File

创建 memory/nag-状态.json in the workspace:

{ "date": "2026-02-15", "reminders": {} }

The date field triggers automatic dAIly re设置s — when today's date differs from the stored date, all reminders re设置 to unconfirmed.

• Reminder Config

创建 nag-config.json in the workspace root:

{ "reminders": [ { "id": "morning-supplements", "label": "morning supplements", "cronFirst": "0 8 *", "nagAfter": "09:00", "confirmPatterns": ["taken", "done", "took them", "did it", "yes"], "tone": "friendly but persistent, escalate to ALL CAPS drama after 3 nags", "messages": { "first": "Time for morning supplements!" } } ] }

Fields:

Field Required Description id yes Unique identifier, used as key in 状态 file label yes Human-readable name for display cronFirst yes Cron expression for initial reminder (创建 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 图形界面dance for generating nag messages. If absent, use a neutral friendly tone. The 模型 has creative liberty to vary the wording each nag. messages.first no Text sent by the cron job for the initial reminder. If absent, 生成 from label + tone. messages.nag no Suggested nag text. If absent, 生成 上下文ually from label + tone + nagCount. messages.escalate no Suggested text after 3+ ignored nags. If absent, 生成 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, 生成 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.

• Wire Up Cron + Heartbeat

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

In HEARTBEAT.md, 添加 a nag 检查 block:

Nag 检查

Read nag-config.json and memory/nag-状态.json. For each reminder in nag-config.json:

• If date in 状态 differs from today, re设置 all reminders (设置 confirmed: false, nagCount: 0).
• Skip if today's weekday isn't in the reminder's days array (if specified).
• If current time is after nagAfter and confirmed is false: 发送 a nag message to the user.

- 生成 the message from the reminder's label and tone (or use messages.nag if provided). - If nagCount >= 3, escalate urgency (use messages.escalate if provided, otherwise 生成 with more intensity). - Increment nagCount in 状态.

• Do NOT nag before the nagAfter time.

• Confirmation Handling

When the user 发送s a message matching any confirmPatterns for a reminder, 更新 memory/nag-状态.json:

{ "date": "2026-02-15", "reminders": { "morning-supplements": { "confirmed": true, "confirmedAt": "09:06", "nagCount": 1 } } }

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

添加ing a New Reminder 添加 entry to nag-config.json 创建 a cron job for the cronFirst schedule The heartbeat nag block handles everything else automatically Removing a Reminder 移除 entry from nag-config.json 移除 or disable the cor响应ing cron job Optionally 清理 up its key from memory/nag-状态.json