Scheduling
Schedule agents or teams to do one-time or recurring work, such as reminders, daily reports, or periodic checks, using natural language.
Create schedules with the !schedule chat command or let an agent create them with the scheduler tool.
Commands
Use !help schedule for inline help on the scheduling commands.
!schedule
Schedule a one-time or recurring task.
!schedule in 5 minutes Check the deployment
!schedule tomorrow at 3pm Send the weekly report
!schedule Every hour, @shell check server status
!schedule Daily at 9am, @finance market report
!schedule Weekly on Friday, @analyst prepare weekly summary
Include @agent_name or @team_name to choose who answers each run.
MindRoom checks that mentioned agents and teams are available in the room before it creates the task.
A task runs where it was created: in the room timeline for a room-level schedule, or in the current thread for a threaded schedule.
The task text never runs as a chat command, even when it starts with !; agents receive it as an ordinary message.
Conditional requests such as if or when become recurring polling schedules, not event subscriptions.
The condition is part of the task message, so the responder checks it on each run.
Include an explicit polling cadence for predictable behavior.
!schedule Every 5 minutes, check if I got an email about "urgent"; if so, @phone_agent call me
!schedule Every 10 minutes, check whether Bitcoin dropped below $40k; if so, @crypto_agent notify me
Add phrases to the request to change how each run behaves:
| Phrase | Effect |
|---|---|
with no history, without context, context-free |
Each run sees no prior messages; see History limits |
with only the last 5 messages of context |
Each run sees only recent messages |
silently, quietly |
Hide the trigger and post only findings; see Silent delivery |
!edit_schedule
Replace an existing task's timing and content.
MindRoom re-parses the description to update timing and content. Omitted settings stay unchanged, including the history limit, silent mode, and model. A task cannot switch between one-time and recurring; cancel it and create a new one instead. A request that would change nothing about the task is refused, and the task stays as it was.
!edit_schedule task42 keep the same schedule but restore full history
!edit_schedule task42 every weekday at 8am check build status with no history
!edit_schedule task42 keep the same schedule but make it silent
Aliases: !editschedule, !edit-schedule
!list_schedules
List pending tasks in the current room, or in the current thread when used inside one.
Each entry shows its task ID, timing, mode (Silent or Visible), and selected model if any.
Aliases: !listschedules, !list-schedules, !list_schedule, !listschedule, !list-schedule, !inspect_schedules, !inspectschedules, !inspect-schedules, !inspect_schedule, !inspectschedule, !inspect-schedule
!cancel_schedule
Cancel one task, or every task in the room.
Use !list_schedules to find task IDs.
Only a pending task can be cancelled; a one-time task that already ran, and a task that failed or was cancelled, stay as they are.
Aliases: !cancelschedule, !cancel-schedule
[scheduler]
The scheduler tool lets an agent create, edit, list, and cancel the same tasks as the chat commands.
It is included in defaults.tools by default, needs no setup, and has no tool-specific configuration fields.
It only works from a live room or thread; elsewhere it returns Scheduler tool is unavailable in this context.
| Function | Arguments |
|---|---|
schedule(request, new_thread, history_limit=None, silent=None, model=None) |
new_thread is required |
edit_schedule(task_id, request, history_limit=None, silent=None, model=None) |
Omitted arguments keep the task's current settings |
schedule_tool_call(tool_name, arguments_json, execute_at, description) |
One approval-gated call that the requester approves now; see Pre-Approved Tool Calls |
run_scheduled_call(task_id, arguments_json=None) |
Runs a pre-approved scheduled call when its task asks; see Pre-Approved Tool Calls |
list_schedules() |
|
cancel_schedule(task_id) |
new_thread=Falseposts each run in the current room or thread.new_thread=Trueposts each run as a new room-level message, and the responder answers in a new thread under it with a fresh session.history_limitcaps how many recent messages each run sees:0for none, a positive integer for that many, unset for full history.silent=Trueturns on silent delivery; unset infers the mode from the request text.modelpicks a model alias for each run; see Model selection.
schedule("tomorrow at 9am @ops check the deployment", new_thread=False)
schedule("every weekday at 8am post the on-call handoff summary", new_thread=True)
schedule("every hour @ops check deployment health", new_thread=False, history_limit=0, model="cheap")
schedule("every 5 minutes check the inbox for urgent mail", new_thread=False, history_limit=0, silent=True)
list_schedules()
edit_schedule("a1b2c3d4", "tomorrow at 10am @ops check the deployment", history_limit=5, silent=False)
cancel_schedule("a1b2c3d4")
History Limits
Scheduled runs normally use the responder's configured conversation history.
Use with no history, without context, or context-free when each run should see no prior room or thread messages; the system prompt and the task message remain available.
Use phrases such as with only the last 5 messages of context or include the last 5 messages to cap each run to recent context.
In an edit, say restore full history or use unlimited history to remove a limit.
Agents set the same limit with the tool's history_limit argument.
Silent Delivery
Schedules are visible by default.
Add silently or quietly to a request when the trigger and routine no-report results should stay out of the room timeline.
!schedule Every 5 minutes, quietly check the inbox for urgent messages and report only when one arrives
!schedule Daily at 9am, silently check whether the backup failed and report failures
A silent schedule does not show its trigger in the room.
A successful run whose final response is empty, whitespace, or has NO_REPLY (any case) alone on its last non-blank line posts no message.
A final NO_REPLY line means do not notify, so a report must not end with it.
Findings, failures, and messages that tools send explicitly remain visible.
Silent runs also show no typing indicator, progress placeholder, stop control, or streaming updates.
When a silent run pauses for a tool approval, it shows a waiting message; when the run continues after the decision with nothing to report, that message ends with the run's text and tool calls without the NO_REPLY line, or Done. when nothing else is left, and no new message is posted.
A team's silent run reports nothing only when its leader and every member do, so a member's finding stays visible, without any NO_REPLY line, even when the leader answers NO_REPLY.
After an approval, a team's run that reports nothing ends its waiting message with the leader's own text, or Done. when the leader wrote none, instead of the team's document.
With new_thread=True, a silent schedule posts any finding or failure as a new room-level message.
Say make this schedule silent or make this schedule visible in !edit_schedule to change the mode.
Silent delivery only hides messages from the room; the task text still travels through Matrix and is subject to homeserver retention.
Each silent run writes a JSON receipt to <agent-workspace>/.mindroom/scheduled_runs/, so you can check what a silent run did.
A receipt records the prompt, room, thread, status (started or completed), result (reported, no_report, or suppressed), the final response text, and UTC start and completion times.
A receipt still in started means the run began but never reached a final response.
Team runs write a receipt to each member agent's workspace, and private agents write to the requester's workspace.
Workspace knowledge indexing skips these receipts.
Model Selection
Pass model to schedule() to run each scheduled response with a model alias from models: in config.yaml, for example a cheaper model for simple recurring checks.
schedule("every hour @ops check deployment health", new_thread=False, history_limit=0, model="cheap")
edit_schedule("task42", "keep the same schedule and task", model="cheap")
edit_schedule("task42", "keep the same schedule and task", model="")
The model applies to the whole scheduled response, including a team's coordinator and members.
It takes precedence over room and thread model settings without changing them for later messages.
Omitting model on creation uses normal model selection; omitting it on an edit keeps the saved choice, and an empty string restores normal model selection.
Parsing the scheduling request itself always uses the default model.
Pre-Approved Tool Calls
An agent can store one of its own approval-gated tool calls to run later, and the requester approves it while scheduling it, so a gated action such as an external message runs at its time without a second approval.
The agent calls schedule_tool_call(tool_name, arguments_json, execute_at, description) from a thread.
tool_name must be one of that agent's own tools, arguments_json is a JSON object of the call's arguments, and execute_at is an ISO 8601 time with a UTC offset, such as 2026-10-04T09:00:00-04:00.
The tool_approval policy must require approval for the call (or the tool must ask for its own confirmation), the scheduler must be an agent rather than a team, and the agent must be able to reply to the requester in that room; otherwise the scheduler refuses it.
schedule_tool_call(
tool_name="post_slack_message",
arguments_json='{"channel": "U0123ABCD", "text": "Good morning! The report is ready."}',
execute_at="2026-10-04T09:00:00-04:00",
description="Morning report DM",
)
MindRoom stores the call and posts an approval card in the thread showing the tool, its arguments, and the send time; only the requester can approve or deny it, and it expires at the send time.
The requester approves either the stored arguments or, when the card offers it, any arguments to the same tool.
Approving any arguments lets the agent decide the arguments for that tool when the task runs, following the task's description, so choose it only when the content must be decided later.
The card offers it only when requesters approve their own calls; operators can stop offering it with tool_approval.scheduled_any_arguments, and generic MCP *_call_tool calls and tools that ask for their own confirmation are always approved exactly.
When the task runs, it asks the agent to call run_scheduled_call(task_id), which runs the stored call once with the stored arguments, without a new card, and posts an approved receipt naming who approved it, when, and for which scope.
With an any-arguments approval the agent may pass arguments_json to run_scheduled_call to replace the arguments for the same tool.
The approval can be used once, by that agent for that requester in that thread, from when the task runs until 15 minutes after its scheduled time.
If the card was not approved in time, run_scheduled_call runs nothing and the agent can call the tool directly, which asks for approval as usual.
If the requester denies the card, the task does not run, and cancelling the task withdraws the approval.
A pre-approved task cannot be edited; cancel it and schedule the call again.
The arguments are not posted in the task or its trigger message; MindRoom keeps them with the approval, and the card shows them with secrets hidden.
Recurring schedules cannot pre-approve calls.
Timezone
The top-level timezone setting (default UTC) is the IANA timezone MindRoom uses for the current date in agent prompts, message timestamps, file-memory daily notes, automation cron times, and interpreting and displaying scheduled times.
An agent's own timezone overrides it for that agent, so one install can serve people in different timezones; the router and chat commands such as !schedule use the top-level setting.
A team reply uses the timezone of the account that posts it: a configured team uses the top-level setting, and an ad hoc team uses the timezone of the agent whose account posts its reply.
An unknown timezone name fails config validation.
A schedule keeps the timezone it was created in: when atlas schedules "tomorrow at 9" with its scheduler tool, the task runs at 09:00 in Amsterdam, and later chat edits and listings use Amsterdam time too.
The dashboard's Schedules page shows dates and times in the top-level timezone, while every recurring schedule's description names the timezone it is written in, such as At 09:00 (Europe/Amsterdam).
Schedules created before agents had their own timezone keep following the top-level setting.
Recurring schedules run on UTC cron times, so their local clock time shifts when the timezone's UTC offset changes, such as at daylight-saving transitions. Edit or recreate a recurring schedule after an offset change if it must keep the same local time.
Permissions and Automatic Cancellation
Schedules belong to the room, not to their creator.
Any authorized participant in the room can edit or cancel any of its schedules by task ID, and listing inside a thread only filters the view.
Each run acts as the schedule's creator, as if the creator had sent the message, so it uses that person's access, per-user credentials, and private-agent workspace.
Editing a schedule with !edit_schedule or the scheduler tool makes the editor its new creator.
MindRoom cancels a schedule automatically once neither its creator nor any of the creator's bridge aliases is joined to the room. Bot accounts and managed identities do not count. A run waits rather than proceeding when membership cannot be confirmed.
Persistence and Missed Runs
Schedules are stored in Matrix room state and survive restarts.
In a room MindRoom did not create, a room admin may need to raise the router's power level to the room's state-event level, usually 50, before schedules can be saved; raising the router is enough for every agent, and the error names the account and the level to grant.
MindRoom only acts on schedule state written by its own router, agent, or team accounts; schedule state written by any other account, including a room admin, is ignored and logged.
The homeserver must support GET /_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}?format=event (Matrix spec v1.16), as Synapse, Tuwunel, and Dendrite do; otherwise reading tasks fails.
Scheduled Task Restoration
The router runs a schedule when, at the time the schedule is saved, it may post its trigger and save schedule state in the room; otherwise the agent that saved the schedule runs it, as in a DM or an agent's personal room. Every agent restores the schedules it runs in a room when it joins that room, at startup, when it accepts an invitation, or when it joins a room listed under one of its rooms, and the router also restores the room's pending configuration changes. Schedules keep running when their agent restarts, for example after a config edit: a one-time task that came due during the restart runs once the agent is back, and a recurring task runs the occurrence that came due if it is still within the catch-up window. A one-time task missed by less than 24 hours runs once its agent's Matrix sync is ready; an older one is marked failed instead. When an agent is removed from the config while MindRoom runs, each schedule it runs is marked failed and the agent says so in the schedule's thread, or in the room for a schedule without one; its schedules never move to another agent. When it is removed while MindRoom is stopped, a bot that may save schedule state in a room marks the agent's schedules there failed and says so when it rejoins that room, and schedules in the agent's DMs stay pending.
Recurring task recovery
After a restart or a late wake-up, a recurring task runs its latest missed occurrence if it is within the catch-up window, and multiple missed occurrences run once. Occurrences outside the window are skipped and logged, and later runs keep the normal cadence.
Recurring progress is kept in tracking/recurring_schedules/ under the storage directory, which must persist across restarts.
Without it, or after a schedule edit, MindRoom resumes from the next future occurrence without replaying past ones.
Restarts do not post the same trigger twice.
For schedule:fired hooks that run more than once for the same occurrence, see Hooks.
Automations
Automations are checks MindRoom runs on a cron schedule; when one passes, the agent posts the automation's prompt in its room and answers it with a normal, visible run.
MindRoom ships three, prompt_curation, dreaming, and exploration, and plugins can add more.
The check runs in code, so a schedule that finds nothing to do costs no model call and posts nothing.
Enable them per agent in config.yaml, or under defaults for every eligible agent:
defaults:
automations: [] # inherited by agents that omit the field
agents:
mind:
memory_backend: file
rooms: [personal]
automations:
- prompt_curation # the built-in with its defaults
# or: {name: prompt_curation, cron: "0 4 * * *", room: personal, trigger_tokens: 30000, model: opus}
- dreaming
- {name: weekly_digest, cron: "0 9 * * 1", options: {target: digest.md}} # from a plugin
- An entry is a built-in name, or a mapping with
nameplus overrides; unknown fields fail config load. - Any other name is an automation a loaded plugin provides: it needs
cronand takes theoptionsthe plugin documents; an entry no loaded plugin provides is skipped with a warning in the log and failsmindroom config validate. cronis a five-field expression in the agent's timezone.roomnames a room as an entry ofroomsdoes, and it must be a room the agent is in, because the agent posts the prompt itself; it defaults to the agent's first configured room.- Each run starts in a new thread, even for an agent with
thread_mode: room, and a re-check follows up in that thread. agents.<name>.automations: []turns inherited defaults off for one agent.- A private agent runs its automations once for each requester who has used it, as that requester and on that requester's own files, and posts in their personal room with the agent.
Only the agent named by
personal_rooms.agentcan run automations as a private agent, its entries cannot setroom, and it inherits only default entries withoutroom. A requester without a personal room, or whom the agent may no longer answer, is skipped. Everyone who can read that personal room, such as an agent the requester invited or an adopted room's other participants, sees the prompts and replies, like any other reply there. prompt_curationanddreamingneedmemory_backend: file, andexplorationneedsknowledge_graph: true; an agent that lacks what a default entry needs skips it and keeps inheriting the others.- Edits apply on config reload without restarting the agent.
- The agent posts the prompt in its own name and mentions itself, so it answers even in a room with other agents.
- When the response to a prompt is final, or an hour after the prompt was posted without one, the automation's next step runs: it posts a notice in the prompt's thread or asks the agent again.
- An agent, or each requester's instance of a private agent, runs one automation at a time; one that comes due meanwhile starts when the other ends.
- A check that cannot read what it checks posts a warning in the room.
- A restart skips an occurrence it missed, and prompts posted before the restart get no follow-up.
For conditions that need your own code, write a plugin automation, or gate an ordinary recurring schedule with a schedule:fired hook, which can suppress a fire or rewrite its message.
prompt_curation
Agents append to MEMORY.md and their context_files far more often than they condense them, and every model call re-sends those files.
prompt_curation checks their total size daily and, once it passes the trigger, asks the agent for a gradual cut.
- The check measures
MEMORY.mdplus the agent'scontext_filesby the token estimate of the agent's configured model, not of a room or thread model override, which may count high (how tokens are counted); for a private agent these areMEMORY.mdandprivate.context_filesin the requester's private root, because agent-levelcontext_filesload from the workspace every requester shares. - Above
trigger_tokens, or when the preload has to withhold part ofMEMORY.mdbecause it passesmemory.file.max_entrypoint_lines(default200) ormemory.file.max_entrypoint_tokens, it posts a prompt with exact numbers, for example "bring them to at most 19800 tokens in total, but not below 18700", a cut betweenmin_reductionandmax_reduction(10 to 15%). - The prompt asks the agent to commit the files to git first, take lines out of a
MEMORY.mdover either preload cap first (the prompt shows its line and token counts against both caps), fold each later correction into the entry it corrects, keep each fact once in the file that owns it, move detail and history verbatim intomemory/topic files with one-line pointers, and otherwise never invent facts or change their meaning. - Once the run ends, verify measures the files again; when any of these holds, it lists them in the thread and mentions the agent once to re-check its change against that commit:
- a file can no longer be read safely;
- a file shrank by more than 25%;
- the files total less than the floor, or did not shrink;
MEMORY.mdwas over the line cap and still has as many lines;- a file is no longer valid UTF-8;
- total memory content (the files plus
memory/**) dropped by more thanmax_content_lossof the files' size, which means detail was deleted instead of moved.
When the files changed and none of these holds, verify reports the new size and marks the thread resolved.
When the prompt files are unchanged, verify only checks that no memory/ detail was deleted, and otherwise reports that nothing changed.
Verify never changes the files; the agent's answer to a re-check is not verified again, and the next pass comes on the next scheduled check.
| Field | Default | Description |
|---|---|---|
cron |
0 4 * * * |
When to check |
room |
first configured room | Where to post the prompt |
trigger_tokens |
20000 (min 1) |
Post the prompt once the files exceed this many estimated tokens; a MEMORY.md the preload cannot show whole also posts it |
min_reduction |
0.10 (at most 0.25) |
Smallest cut the prompt asks for; no file may shrink more than 25%, so no pass can be asked for more |
max_reduction |
0.15 |
Largest cut before verify asks for a re-check |
max_content_loss |
0.05 |
Largest net drop in total memory content, as a fraction of the files' size, before verify asks for a re-check |
model |
the agent's model | A key of models to run the prompt and its re-check with, for example one with a larger context window than the agent's everyday model |
prompt_curation needs memory_backend: file, because moved detail must stay searchable, and the prompt templates are overridable as PROMPT_CURATION_PROMPT_TEMPLATE and PROMPT_CURATION_RECHECK_TEMPLATE.
dreaming
dreaming keeps the agent's memory/ files current: each night it reconciles them with new conversations and daily notes, through a proposal that a second run reviews before MindRoom applies it.
- It runs only when a thread export or a daily note from before today is new or changed since its last run, so a night without new threaded messages in the agent's rooms and without new daily notes costs nothing.
- The agent proposes changes in a copy of
memory/: it updates facts that later evidence corrects, marks superseded lines instead of deleting them, files new durable facts such as decisions, preferences, and stable settings in topic files with their source and date, records conflicting sources with both versions, and removes duplicates. It leaves transient tasks in the daily notes and never removes or doubts a fact only because newer notes do not mention it. - A second run, in a thread of its own, reviews the proposal against its sources and approves or rejects it.
- MindRoom applies an approved proposal and marks both threads resolved.
MindRoom never changes MEMORY.md, context files, or today's daily note; the agent suggests changes to them in its report.
When the review rejects a proposal, a run stops unfinished or changes a file it may not, or memory changed during the run, nothing is applied; the next run, once a new thread export or daily note arrives, retries the same inputs and starts from any proposal that reached review and its review.
A run handles at most 40 inputs; the rest wait for later runs.
Turning the automation or thread exports on starts from conversations and notes of the last seven days instead of reviewing the older archive.
Each run keeps its agenda and report, and a run that reached review also its patch and verdict, in .mindroom/dreaming/runs/<run>/ in the workspace, the newest 30 runs at least; undo an applied run with git apply -R .mindroom/dreaming/runs/<run>/proposal.patch from the workspace root.
| Field | Default | Description |
|---|---|---|
cron |
15 3 * * * |
When to check |
room |
first configured room | Where both prompts are posted |
model |
the agent's model | A key of models to run both prompts with |
dreaming needs memory_backend: file and something to work from: auto-flush writes the daily notes it reviews and thread exports add threaded conversations, so with neither on, and no daily notes the agent writes itself, it never runs.
It also needs a tool that writes workspace files, such as filesystem or shell, because the agent edits its copy and writes its report and verdict as files; without one, every run stops unfinished.
Its prompt templates are overridable as DREAMING_PROMPT_TEMPLATE and DREAMING_VERIFY_TEMPLATE.
exploration
exploration asks an agent with a knowledge graph to explore its data sources on a schedule, so the graph learns about projects, people, and documents nobody has asked about yet.
agents:
mind:
knowledge_graph: true
tools: [mcp_github, duckduckgo]
rooms: [exploration]
automations:
- name: exploration
cron: "0 */6 * * *"
room: exploration
max_tool_calls: 30
- The check lists the tool calls the agent's conversations made since its last run, such as the repositories and searches people asked about.
- When there are such calls, or
revisit_dayshave passed since the last run and people talked to the agent since, the agent posts a prompt in a new thread to check what the graph knows, re-read those sources for changes, and follow references to what the graph lacks; an agent withknowledge_graph_editsis also asked to fix the mistakes it found in the graph. - The agent answers the prompt like any message, with its own tools and approval rules; a shared agent's call that needs approval is denied, because no person asked for the run, while a private agent's call waits in the thread until its requester answers or the request expires.
- When the run ends, MindRoom marks the thread resolved and adds its tool results to the graph; the agent's own summary is not added, and an interrupted run adds nothing.
The prompt tells the agent to only read, apart from fixing its graph when it may edit it, and to stay within max_tool_calls, but nothing enforces either: the agent's max_tool_calls_per_turn is the hard limit, and approval rules are what stop writes.
The prompt lists recent tool calls with their arguments, credential-like values removed and mentions disabled so it wakes nobody, so a shared agent's exploration needs a room whose members may see what the agent's conversations looked up; a private agent posts in each requester's personal room.
A turn whose message was redacted can still be listed until the agent next replies in that conversation.
| Field | Default | Description |
|---|---|---|
cron |
30 2 * * * |
When to check |
room |
required for a shared agent | Where the prompt is posted |
max_tool_calls |
40 (1 to 1000) |
Tool calls the prompt asks one run to stay within |
max_leads |
20 (0 to 200) |
Most recent tool calls listed in the prompt |
revisit_days |
7 (min 1) |
Run without new tool calls once this many days have passed since the last run, if people talked to the agent since |
model |
the agent's model | A key of models to run the exploration with |
Its prompt template is overridable as EXPLORATION_PROMPT_TEMPLATE; for an agent with knowledge_graph_edits, its {fix_step} and {fix_exception} placeholders insert EXPLORATION_FIX_STEP and EXPLORATION_FIX_EXCEPTION, which are overridable too and start with their own separator, a line break and a comma.
Its model usage counts as ordinary replies, and extracting what it read counts as knowledge_graph usage.