Agent Self-Reminders
Let a running agent schedule a one-shot future re-invocation of itselfwith a message it writes — “check this PR in 2 hours”, “review the deploy tomorrow at 9am”. When the timer fires, Trinity dispatches a normal execution of that same agent carrying the reminder message. Nothing is held open in between; the reminder is a durable row that fires once, later.
Reminders are the time-deferred sibling of Agent Loops. A loop runs iterations back-to-back now; a reminder fires once, at a chosen time. Both are durable: a reminder is persisted and re-armed automatically, so it still fires after a backend or scheduler restart.
There is no web UI for reminders. They are a backend and MCP primitive that agents drive themselves. Fired reminders show up in the standard Executions list and the agent's Overview timeline under a distinct Reminders category.
Concepts
403).Reminder vs. Loop vs. Schedule
Pick by when and how often the work should run:
| Tool | Cardinality | Timing | Durable across restart |
|---|---|---|---|
| Reminder | Once | A future instant you choose | Yes |
| Loop | Up to max_runs times | Back-to-back, starting now | Yes |
| Schedule | Recurring | A cron cadence | Yes |
Reminders are the agent-initiated, one-shot, durable counterpart to cron schedules — use a reminder for a single deferred follow-up, a schedule for a recurring cadence.
Checking back on delegated work
The delegation contract every agent is taught names reminders as the way to finish later. When an agent hands work to another agent and gets back a receipt (an execution_id) instead of a result, it sets a reminder whose message names that execution_id, then ends its turn. When the reminder fires, it reads the outcome with get_execution_result instead of re-sending the work. See Agent Network.
How It Works
An agent sets a reminder one of two ways — pick exactly one:
delay_seconds — fire this many seconds from now (e.g. 7200 for two hours). Best for relative follow-ups.fire_at — an absolute ISO 8601 timestamp (e.g. 2026-07-25T09:00:00Z). Best for “tomorrow at 9am”.Optional per-reminder overrides — model, timeout_seconds, and allowed_tools— apply to the execution that fires, exactly as they would for a one-off task. When the reminder fires, the resulting execution shares the agent's normal capacity budget alongside chat, schedules, and loops.
Listing returns pending reminders by default (soonest fire first); pass a status filter of all to see fired, cancelled, and failed reminders too.
Cancelling a still-pending reminder stops it from firing. Cancelling an already-cancelled reminder is a no-op success; a reminder that has already fired, is mid-fire, or has failed cannot be cancelled (409). An unknown reminder id returns 404.
Autonomy must be on
A reminder set on an agent whose autonomy mode is off is accepted and held: it stays pending, is never armed, and does not fire — even once its fire time passes. Turn autonomy on and it fires past-due within about a minute. Nothing is lost, but nothing happens either.
Because autonomy defaults to off on a new agent, this is the usual reason a first reminder “never fires”.
How to tell:
list_reminders set autonomy_hold: true on any reminder in this state, and the set_reminder tool result adds an explicit warning. An agent should relay that to the user rather than reporting the reminder as scheduled.2 reminder(s) held: their agent's autonomy is disabled.Chat is notautonomy-gated, so an agent can be mid-conversation, accept “remind me in an hour”, and still be unable to fire it. Check autonomy when a user asks for a reminder.
Where fired reminders appear — a fired reminder is a normal execution row (with triggered_by: "reminder"), so it appears on the Executions page, in per-execution detail, and as its own Reminderscategory in the agent's analytics timeline — never folded into Scheduled.

For Agents
Agents drive reminders via MCP tools or REST. The self-only rule holds on both surfaces: an agent-scoped key may act only on the agent it is bound to.
MCP Tools
| Tool | Description |
|---|---|
| set_reminder | Schedule a one-shot self-reminder. Args: message, plus fire_at (ISO timestamp) or delay_seconds — exactly one. Optional: model, timeout_seconds, allowed_tools |
| list_reminders | List the agent's reminders (pending by default; status: "all" for every state), soonest fire first |
| cancel_reminder | Cancel a pending reminder by id |
mcp__trinity__set_reminder({
agent_name: "my-agent",
message: "Re-check the open PR — is CI green yet? If so, merge it.",
delay_seconds: 7200
})
// → { success: true, reminder: { id: "rem_...", status: "pending", fire_at: "..." } }REST API
| Endpoint | Method | Description |
|---|---|---|
| /api/agents/{name}/reminders | POST | Create a one-shot reminder; returns 201 with the reminder |
| /api/agents/{name}/reminders | GET | List reminders (?status=pending default, ?status=all for every state) |
| /api/agents/{name}/reminders/{id}/cancel | POST | Cancel a pending reminder |
curl -X POST http://localhost:8000/api/agents/my-agent/reminders \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": "Review the deploy health dashboard and report anomalies.",
"fire_at": "2026-07-25T09:00:00Z"
}'Both create boundaries accept an optional Idempotency-Key header, so a naive retry does not schedule a duplicate reminder.
See the Backend API Docs (/docs on your instance) for full request and response schemas.
Limitations
403.set_reminder returns 429.timeout_secondscannot exceed the agent's execution timeout cap.