Remindme

Validation Checkpoint (before calling cron.add)

Before proceeding to Step 3, verify:

1. The computed timestamp is in the future (not the past).
2. The duration makes sense (e.g. "in 0 minutes" should be rejected).
3. For recurring: the cron expression or interval is valid (no everyMs: 0).
4. Echo back the parsed time to the user in the confirmation (Step 5) so they can catch errors.

Step 3: Detect the Delivery Channel

Reminders are useless if the user never sees them. The delivery channel determines WHERE the reminder appears when it fires.

Priority order:

1. Explicit override — if the user says "on telegram" / "on discord" / "on slack" / "on whatsapp" in their message, use that channel.
2. Current channel — if the user is messaging from an external channel (Telegram, Discord, Slack, etc.), deliver there.
3. Preferred channel — if the user has a preferred reminder channel saved in MEMORY.md, use that.
4. Last external channel — use channel: "last" to deliver to the last place the user interacted externally.
5. No external channel available — if the user is on CLI/webchat and has NO external channels configured, stop and ask: "Where should I deliver this reminder? I need an external channel (Telegram, Discord, Slack, WhatsApp, Signal, or iMessage) since the CLI won't be open when the reminder fires."

Step 4: Call cron.add

One-shot reminder:

{
  "name": "Reminder: <short description>",
  "schedule": {
    "kind": "at",
    "at": "<ISO 8601 timestamp>"
  },
  "sessionTarget": "isolated",
  "wakeMode": "now",
  "payload": {
    "kind": "agentTurn",
    "message": "REMINDER: <the user's reminder message>. Deliver this reminder to the user now."
  },
  "delivery": {
    "mode": "announce",
    "channel": "<detected channel>",
    "to": "<detected target>",
    "bestEffort": true
  },
  "deleteAfterRun": true
}

Recurring reminder:

{
  "name": "Recurring: <short description>",
  "schedule": {
    "kind": "cron",
    "expr": "<cron expression>",
    "tz": "<IANA timezone>"
  },
  "sessionTarget": "isolated",
  "wakeMode": "now",
  "payload": {
    "kind": "agentTurn",
    "message": "RECURRING REMINDER: <the user's reminder message>. Deliver this reminder to the user now."
  },
  "delivery": {
    "mode": "announce",
    "channel": "<detected channel>",
    "to": "<detected target>",
    "bestEffort": true
  }
}

Fixed-interval recurring reminder (e.g. "every 2 hours"):

{
  "name": "Recurring: <short description>",
  "schedule": {
    "kind": "every",
    "everyMs": <interval in milliseconds>
  },
  "sessionTarget": "isolated",
  "wakeMode": "now",
  "payload": {
    "kind": "agentTurn",
    "message": "RECURRING REMINDER: <the user's reminder message>. Deliver this reminder to the user now."
  },
  "delivery": {
    "mode": "announce",
    "channel": "<detected channel>",
    "to": "<detected target>",
    "bestEffort": true
  }
}

Step 5: Confirm to User

After cron.add succeeds, reply with:

Reminder set!
"<reminder message>"
<friendly time description> (<ISO timestamp or cron expression>)
Will deliver to: <channel>
Job ID: <jobId> (use "/remindme cancel <jobId>" to remove)

Rules

1. ALWAYS use deleteAfterRun: true for one-shot reminders. Omit it for recurring.
2. ALWAYS use delivery.mode: "announce" — without this, the user never sees the reminder.
3. ALWAYS use sessionTarget: "isolated" — reminders run in their own session.
4. ALWAYS use wakeMode: "now" — ensures immediate delivery at the scheduled time.
5. ALWAYS use delivery.bestEffort: true — prevents job failure if delivery has a transient issue.
6. NEVER use act:wait or loops for delays longer than 1 minute. Cron handles timing.
7. NEVER deliver to localhost/webchat/CLI — the user won't be there when the reminder fires. If on CLI with no external channels, ask the user where to deliver.
8. Always use the user's local timezone (system timezone). Never default to UTC. If MEMORY.md has a timezone override, use that instead.
9. For recurring reminders, do NOT set deleteAfterRun.
10. Always return the jobId so the user can cancel later.
11. If the user says "on telegram/discord/slack/etc", override the auto-detected channel with the explicit one.

Troubleshooting

• Reminder didn't fire? → cron.list to check. Verify gateway was running at the scheduled time.
• Delivered to wrong chat? → Use explicit chat/channel ID, not "last".
• Too many old jobs? → Install the Janitor (see references/TEMPLATES.md).
• Recurring job keeps delaying? → After consecutive failures, cron applies exponential backoff (30s → 1m → 5m → 15m → 60m). Backoff resets after a successful run.

References

See references/TEMPLATES.md for copy-paste templates and the Janitor auto-cleanup setup.