Skip to main content

Scheduling

Mercury can schedule tasks using cron expressions or one-shot delays.

Recurring tasks​

Tell Mercury in conversation:

  • "Remind me every day at 9am to check the server"
  • "Schedule a weekly summary every Monday at 10am"

One-shot delays​

  • "Remind me in 15 minutes to take a break"
  • "Ping me in 2 hours about the deployment"

Tasks persist to ~/.mercury/schedules.yaml and restore on restart. Responses route back to the channel (CLI or Telegram) where the task was created.

Time zones and overlap​

Use a timezone for recurring work, for example: “Every weekday at 9am in America/New_York, brief me on my calendar.” The schedule_task tool accepts an IANA timezone; the Schedules editor exposes the same setting. Existing schedules without one continue using the host timezone. Cron follows that zone's local clock, including daylight-saving changes.

A schedule never queues another main-agent run while its previous run is still queued or running. Overlapping ticks are skipped, rather than accumulated for later. Recurring ticks missed while Mercury was offline are not replayed.

Offline and interrupted work​

One-shot tasks have an explicit missed_run_policy:

  • skip (default, including older schedules): keep a skipped record when Mercury starts after the due time.
  • run_once: start the overdue task once after restart, provided no run had begun.

This policy does not retry failed or interrupted work. Mercury records a run before invoking it. If the process stops before the outcome is confirmed, the run becomes interrupted and the schedule pauses. Failed runs also pause, because an external action may have succeeded before its response was lost.

Check the prior run's effects before repeating it. In Schedules → Edit, choose Schedule again to explicitly resume. For a one-shot, the delay starts again from when you save. Editing only a description or policy does not repeat the work. The API equivalent is PUT /api/schedules/:id with {"resume": true} and, for a one-shot, the desired delaySeconds. Running tasks cannot be edited.

Run outcomes​

The Schedules page and list_scheduled_tasks show pending, running, completed, failed, interrupted, skipped, or dispatched status. Completed means the main agent finished its turn; inspect its response for the actual task result. Bot schedules show dispatched after their separate queue accepts them; inspect the bot's run history for completion. Scheduled bot jobs whose run or retry was interrupted go to the dead-letter queue (DLQ) instead of replaying automatically; future routines pause. Check their effects, then use /bots start <id> to resume future routines or /bots replay <id> <jobId> to explicitly repeat that job. A fresh queued bot job that never started can still resume. Manual/chat bot jobs keep their existing recovery behavior.

Run records are stored with the schedule in ~/.mercury/schedules.yaml, using an atomic replacement. The latest run is kept for each recurring task. The most recent 100 resolved one-shot records are retained; active work and unresolved failures are kept until you remove them. These safeguards prevent automatic scheduler replay; they cannot guarantee exactly-once behavior from external services.