> ## Documentation Index > Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt > Use this file to discover all available pages before exploring further. # Reminders > Schedule one-shot time-based prompts with optional follow-up chains for progressive nudging. Reminders are one-shot time-based prompts that fire after a delay. Unlike routines, they execute once and are then removed. Reminders support **chaining** — a reminder with `max-chain` set can spawn follow-ups via the `follow_up_chain` MCP tool, letting the agent continue a task across multiple steps. ## Overview A reminder tells ollim-bot to run a prompt at a specific future time. When created, you specify either a delay in minutes or an absolute time, and the scheduler computes when to fire. Like routines, reminders can run in the foreground (sending you a DM) or in the background (running silently in a fork). Reminders default to background mode. Reminders are stored as markdown files in `~/.ollim-bot/reminders/`. The scheduler polls this directory every 10 seconds. After a reminder fires, it is removed automatically (unless it chains into a follow-up). The agent manages reminders through three MCP tools — `add_reminder`, `list_reminders`, and `cancel_reminder`. You can also ask the agent in natural conversation and it calls the right tool. After creating a reminder, the agent confirms the scheduled time in one line (e.g. "reminder set for 3:00 PM"). ## File format Each reminder is a `.md` file in `~/.ollim-bot/reminders/`. The `message` field is the markdown body after the closing `---`; all other fields go in the YAML frontmatter. Only non-default fields are written to the frontmatter. ```yaml title="reminders/check-on-deployment.md" theme={null} --- id: "f4a9c1e2" run-at: "2026-02-24T15:30:00+01:00" description: "Check deployment status" --- Check if the deployment completed successfully. If there were errors, send me an embed with the details. ``` The `message` field does not appear in the frontmatter — it is the markdown body below the closing `---`. ### Frontmatter fields | Field | Type | Default | Description | | --------------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | `id` | `str` | — | Auto-generated 8-char hex ID | | `run-at` | `str` | — | ISO datetime (computed from delay) | | `description` | `str` | `""` | Short summary for `reminder list` | | `background` | `bool` | `true` | Run in a background fork | | `chain-depth` | `int` | `0` | Current position in a chain | | `max-chain` | `int` | `0` | Max follow-up depth (0 = plain one-shot) | | `chain-parent` | `str \| null` | `null` | ID of the chain root | | `model` | `str` | `null` | Model override (background only) | | `thinking` | `bool` | `true` | Extended thinking (background only) | | `isolated` | `bool` | `false` | Fresh context, not forked (background only) | | `update-main-session` | `str` | `"on_ping"` | Sync mode: `always` / `on_ping` / `freely` / `blocked` | | `allow-ping` | `bool` | `true` | Allow pings and embeds (background only) | | `allowed-tools` | `list[str]` | `null` | Additional tools merged with default background tools (background only) | | `skills` | `list[str]` | `null` | [Skills](/extending/skills) to load at fire time | | `reflect` | `bool` | `true` | Write a [reflection trace](/scheduling/background-forks#reflections) when the background fork finishes (background only) | ### File naming Filenames are slugified from the message text (lowercase, hyphens, max 50 characters). The `id` field in the YAML frontmatter is authoritative — filenames are for human readability only. Collisions append `-2`, `-3`, etc. ## Managing reminders The agent uses three [MCP tools](/extending/mcp-tools) to manage reminders. You interact through natural conversation — the agent picks the right tool. * "Remind me in 30 minutes to check on the deployment" * "Set a reminder for 3pm to check my email" * "What reminders do I have?" * "Cancel the deployment reminder" | Tool | What it does | | --------------------------------------------------------- | -------------------------------------------------------------------------- | | [`add_reminder`](/extending/mcp-tools#add_reminder) | Schedule a reminder by delay (`delay_minutes`) or absolute time (`run_at`) | | [`list_reminders`](/extending/mcp-tools#list_reminders) | Show all pending reminders with IDs, times, and descriptions | | [`cancel_reminder`](/extending/mcp-tools#cancel_reminder) | Cancel a pending reminder by ID | See the [Discord tools reference](/extending/mcp-tools#reminder-tools) for full parameter details. ## Follow-up chains A plain reminder (`max-chain: 0`) fires once and is removed. A **chainable** reminder (`max-chain: N`) can spawn follow-ups: when the agent runs the reminder, it can call the `follow_up_chain` MCP tool to schedule a continuation at `chain-depth + 1`. Chains end when: * The agent decides not to call `follow_up_chain` (task complete, nothing to report) * `chain-depth` reaches `max-chain` — the agent receives an error with recovery guidance: "follow-up limit reached — this was the last check. If the task still needs attention, ping the user now." (see [`follow_up_chain`](/extending/mcp-tools#follow_up_chain)) This lets the agent monitor something over time — check for an email reply, wait for a build to finish, or follow up on an unanswered question — without creating an open-ended loop. ### Chain behavior When a chain reminder fires, the agent is instructed to briefly acknowledge the follow-up nature in any pings — phrasing like "checking in again" or "follow-up on earlier" — so you know the notification is an intentional continuation, not a duplicate. On the **final check** (last link in the chain), the agent applies a **regret heuristic**: it pings only if the task is still unresolved *and* you would regret missing it. Otherwise, it reports findings to the main session via `report_updates`. This prevents unnecessary notifications at the end of a chain while still escalating when it matters. ```yaml title="reminders/check-email-response.md" theme={null} --- id: "b7d3e8a1" run-at: "2026-02-24T16:00:00+01:00" description: "Check for email response" max-chain: 3 chain-depth: 0 chain-parent: "b7d3e8a1" --- Check if there's a response to the email I sent to the team. If no response yet, chain a follow-up. If they replied, send me an embed. ``` When the agent chains, the next reminder inherits the `chain-parent` and increments `chain-depth`. Chain reminders also inherit tool restrictions and skills from the parent. ## Background vs foreground By default, reminders run in the **background** — silently in a disposable fork. Text output is discarded — the agent must use `ping_user` or `discord_embed` to reach you. Set `foreground: true` when calling `add_reminder` (or `background: false` in the YAML file) to run the reminder in the foreground instead. Use foreground only when you want to watch the agent's tool actions stream in real time. For notifications, alerts, and nudges, background with `ping_user` is the right choice — replying to a background ping starts an interactive fork if you want to discuss the result. The reminder runs in a forked session. Background reminders support additional configuration for model, thinking, isolation, and tool restrictions. ```yaml title="reminders/check-deployment.md" theme={null} --- id: "f4a9c1e2" run-at: "2026-02-24T15:30:00+01:00" description: "Check deployment status" isolated: true model: "haiku" --- Check if the deployment completed successfully. If there were errors, send me an embed with the details. ``` The reminder fires and the agent sends you a DM with its response, just like a normal conversation. ```yaml title="reminders/standup-prep.md" theme={null} --- id: "a2b3c4d5" run-at: "2026-02-24T09:45:00+01:00" description: "Standup prep" background: false --- What should I mention in standup? Check my recent tasks and calendar. ``` Add `max-chain` for monitoring tasks. The agent checks periodically in the background and only pings you when there is something to report. ## Overdue reminders When a reminder's scheduled time has already passed by the time the scheduler processes it — for example, after a restart — the reminder fires immediately with an **overdue signal** injected into the prompt: ```text theme={null} [late: was scheduled for 3:00 PM, running now] ``` This tells the agent the reminder is stale, so it can adjust its behavior accordingly — a "take your medication" ping that fires two hours late may warrant different wording than one arriving on time. ## Examples ### Simple one-shot reminder (foreground) ```yaml title="reminders/take-a-break.md" theme={null} --- id: "e1f2a3b4" run-at: "2026-02-24T14:00:00+01:00" description: "Break reminder" background: false --- Time for a break. What have I been working on for the last 2 hours? ``` ### Background monitoring with chain ```yaml title="reminders/wait-for-ci.md" theme={null} --- id: "c5d6e7f8" run-at: "2026-02-24T13:00:00+01:00" description: "CI pipeline check" isolated: true max-chain: 5 chain-depth: 0 chain-parent: "c5d6e7f8" allowed-tools: - "mcp__discord__*" update-main-session: "on_ping" --- Check the CI pipeline status. If still running, chain a follow-up in 15 minutes. If passed, send me an embed. If failed, ping me with the error. ``` ### Quiet background check (no pings) ```yaml title="reminders/inbox-scan.md" theme={null} --- id: "a8b9c0d1" run-at: "2026-02-24T12:00:00+01:00" description: "Inbox scan" isolated: true allow-ping: false allowed-tools: - "Bash(ollim-bot gmail *)" update-main-session: "always" --- Scan my inbox for anything urgent. Save a summary to pending updates. ``` ## Next steps Recurring cron-based schedules for daily and weekly prompts. Deep dive into background fork configuration and behavior. How notification rate limiting works for background tasks. One-shot, future-dated, and chain reminder examples from an actual data directory.