Skip to main content
Trinity
Updated Oct 7, 2026dev@a515497
Guides/Agent Self-Reminders

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

•Reminder — A one-shot, durable, self-scheduled task. An agent sets a reminder on itself with a message and a fire time. At that time, Trinity runs a normal execution of the agent with that message.
•Self-only — An agent can set, list, and cancel only its own reminders. A reminder against a sibling agent is rejected (403).
•Durable — Reminders survive a restart. The fire time is stored, not held in memory, and re-armed on boot. A reminder due during a restart fires when the service comes back rather than being lost.
•Autonomy-gated — Reminders only fire while the agent's autonomy mode is on, the same master switch that governs schedules. Autonomy is off by default on a newly created agent.

Reminder vs. Loop vs. Schedule

Pick by when and how often the work should run:

ToolCardinalityTimingDurable across restart
ReminderOnceA future instant you chooseYes
LoopUp to max_runs timesBack-to-back, starting nowYes
ScheduleRecurringA cron cadenceYes

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:

•The create response and 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.
•The scheduler logs a count each reconcile pass, e.g. 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.

The Operations page Executions tab with a running execution tagged reminder alongside room, public, and event triggers

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

ToolDescription
set_reminderSchedule a one-shot self-reminder. Args: message, plus fire_at (ISO timestamp) or delay_seconds — exactly one. Optional: model, timeout_seconds, allowed_tools
list_remindersList the agent's reminders (pending by default; status: "all" for every state), soonest fire first
cancel_reminderCancel 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

EndpointMethodDescription
/api/agents/{name}/remindersPOSTCreate a one-shot reminder; returns 201 with the reminder
/api/agents/{name}/remindersGETList reminders (?status=pending default, ?status=all for every state)
/api/agents/{name}/reminders/{id}/cancelPOSTCancel 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

•Self-only — An agent can set, list, and cancel only its own reminders. A reminder targeting another agent returns 403.
•One-shot — A reminder fires exactly once. For a recurring cadence, use a schedule; for repeated passes now, use a loop.
•Delay bounds — The fire time must be at least 60 seconds and at most 30 days out.
•Per-agent caps — At most 25 pending reminders and 100 created per day per agent. Beyond either, set_reminder returns 429.
•Timeout cap — A per-reminder timeout_secondscannot exceed the agent's execution timeout cap.
•New call chain — A fired reminder starts a new agent-to-agent call chain; it does not inherit the depth of the turn that set it.
•No web UI — Reminders are set and managed by the agent; there is no dashboard form. The result of a fired reminder is visible in Executions.

See Also

•Agent Loops — Bounded sequential repetition; the immediate sibling of reminders.
•Scheduling — Cron-based recurring tasks; the durable, recurring counterpart.
•Executions — Where a fired reminder appears.
•Agent Configuration — Execution timeout and parallel task limits.