Agent Configuration
This page covers the agents: section of config.yaml, where each agent is one AI actor with its own model, tools, rooms, and instructions.
It also covers requester-private agents, files preloaded into an agent's prompt, naming rules, and the defaults: section that every agent inherits from.
Basic Agent
agents:
assistant:
display_name: Assistant
role: A helpful AI assistant
model: sonnet
rooms: [lobby]
The key (assistant) is the agent's name, model names an entry under models:, and rooms lists the rooms the agent joins.
A coding agent that runs its code tools in a worker, preloads workspace notes, and replies as plain room messages in a bridged room:
agents:
developer:
display_name: Developer
role: Generate code, manage files, execute shell commands
model: sonnet
tools:
- filesystem
- github
- shell:
extra_env_passthrough: "DAWARICH_*"
worker_tools: [shell, filesystem]
instructions:
- Always read files before modifying them
context_files: [AGENTS.md, USER.md]
rooms: [lobby, dev, bridge_telegram]
room_thread_modes:
bridge_telegram: room
access:
members_of_rooms: [dev]
delegate_to: [research]
To keep defaults.tools away from one agent:
agents:
researcher:
display_name: Researcher
role: Focus on deep research
include_default_tools: false
tools: [duckduckgo]
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
display_name |
string | required | Name shown in Matrix |
matrix_username |
string or null | null |
Exact localpart of the Matrix account MindRoom creates for the agent, such as jarvis for @jarvis:example.com, using lowercase letters, digits, ., _, =, -, or /. When unset, the account is mindroom_<agent key>; unlike that default name, matrix_username gets no _<MINDROOM_NAMESPACE> suffix. MindRoom uses it when it creates the account, so set it before the agent's first start; changing it to another name later stops startup with agents.<agent key>.matrix_username cannot be changed after the agent's Matrix account has been created., and removing it keeps the existing account. Installs paired with a provisioning service, such as hosted mindroom.chat, can register only mindroom_ names the service allows, so a name such as jarvis is refused there. To use an account that already exists, see Use an Existing Matrix Account |
role |
string | "" |
System prompt describing the agent's purpose and expertise |
model |
string | "default" |
Key of an entry under models: |
cheap_model |
string or null | null |
Cheaper model key this agent may switch to; used by cold_cache. Inherits defaults.cheap_model. See Cold-Cache Model |
tools |
list | [] |
Tool names or single-key dicts with per-agent overrides; see Tools and Per-Agent Tool Configuration. The agent gets these plus defaults.tools, without duplicates |
include_default_tools |
bool | true |
Set false to leave out defaults.tools and its overrides for this agent |
skills |
list | [] |
Skill names the agent can use; see Skills |
skill_learning |
object | disabled | Automatic skill learning, separate from learning |
instructions |
list | [] |
Extra lines appended to the system prompt after the role |
minimal_instructions |
list | [] |
Guidance included on every minimal-mode request; see Prompt and minimal_instructions |
rooms |
list | [] |
Room keys or Matrix room IDs to join; missing managed rooms are created (see Rooms) |
accept_invites |
bool or list | true |
true accepts every room invitation, false or [] accepts none, and a list accepts only inviters matching an exact or wildcard Matrix user ID. Rooms joined this way are kept across restarts. Joining a room never grants its members access; see Authorization |
access |
object | null |
Who may converse with the agent: current_room_members, members_of_rooms, and users. When omitted, members of the agent's own managed rooms have access. See Responder access |
credential_managers |
list | [] |
Concrete Matrix user IDs (no wildcards) allowed to manage this agent's credentials and shared OAuth connections; grants no conversation access. See OAuth |
mcp_gateway_shared_credentials |
bool | false |
Let users who may use this agent call its tools through the MCP gateway even though its worker scope is shared or unset. Every caller then runs them with the agent's shared credentials and worker, without its instructions. Agents with private or worker_scope: user or user_agent are available without it |
participation |
object | null |
Opt into adaptive replies in existing multi-human threads; see Adaptive Participation |
mid_turn |
object | null |
Judge whether messages queued during a response can wait until it finishes; see Mid-Turn Coalescing |
cold_cache |
object | null |
Move an idle thread to cheap_model for good when a judge accepts it; see Cold-Cache Model |
room_activity |
object | defaults.room_activity |
Note in thread replies listing the room's other threads with new messages; omitted fields inherit defaults.room_activity. See Activity in Other Threads |
listen |
object | null |
Hear chosen rooms and act silently after a quiet period; see Listening |
contacts |
object | null |
Let a personal agent talk to other people's personal agents and people after both owners approve; see Agent Contacts |
thread_mode |
string | "thread" |
thread replies in Matrix threads; room sends plain room messages with one continuous conversation per room, which suits bridges (Telegram, Signal, WhatsApp) and mobile clients |
room_thread_modes |
map | {} |
Per-room thread or room overrides keyed by room key or Matrix room ID; see Thread Mode Resolution |
markdown |
bool | null |
Tell the agent in its system prompt that its replies are shown as Markdown; chat replies are rendered as Markdown either way. Team leaders follow defaults.markdown, and voice calls leave the line out |
knowledge_graph |
bool | null |
Build a knowledge graph from this agent's conversations and give it the knowledge_graph tool |
knowledge_graph_edits |
bool | null |
Let the agent correct its knowledge graph: delete wrong facts and entities, merge duplicate entities, and rewrite summaries; needs knowledge_graph. See Letting the Agent Fix Its Graph |
timezone |
string | null |
IANA timezone for this agent's dates, times, and schedules, such as Europe/Amsterdam; inherits the top-level timezone. See Timezone |
memory_backend |
string | null |
mem0, file, or none, overriding memory.backend; none disables memory. See Memory |
memory_search |
object | null |
File-memory search override (mode, include, exclude, include_entrypoint, rerank) when the backend is file; omitted fields inherit memory.search. See Searching file memory |
automations |
list | null |
Automations such as prompt_curation, dreaming, or one a plugin provides; null inherits the defaults.automations entries the agent can run and [] turns them off. See Automations |
knowledge_bases |
list | [] |
Keys under top-level knowledge_bases, each at most once; see Knowledge Bases |
context_files |
list | [] |
Workspace files preloaded into the prompt; see File-Based Context Loading |
private |
object | null |
Give each requester a separate copy of the agent's state; see Private Instances |
num_history_runs, num_history_messages, max_tool_calls_from_history |
See History Settings | ||
compaction |
object | defaults.compaction |
Per-agent compaction overrides; enabled: false turns automatic compaction off. See Agent Compaction Settings |
max_tool_calls_per_turn |
int, >= 1 | null |
Tool calls one turn may execute. Further calls return a tool error, and after this many plus two model requests the turn ends with the text produced so far, which also stops loops of unknown or malformed tool calls. Separately, a tool whose calls failed in 8 model requests of one turn, with no success in between, is refused for the rest of the turn with its last error, redacted; several failed calls in one request count once, and calls that never ran (unknown tools, undecodable arguments, the call limit) do not count. Only failed calls count: a tool that returns an error as its ordinary output, such as a shell command that exits with an error, is never refused. If the model calls the refused tool again, the turn ends with the text so far and a line naming the tool and its last error |
created_agents_per_owner |
int, >= 0 | 0 |
How many agents each person may create through this agent with create_agent; 0 turns the tool off. It applies to this agent only and is not inherited from defaults. See Created Agents and Self-Updates |
show_tool_calls |
bool | null |
Show tool-call markers and trace metadata in Matrix messages; see Tool Calls During Streaming |
show_reasoning |
bool | null |
Show the model's reasoning on streamed replies to everyone in the room; see Reasoning |
worker_tools |
list | null |
Tools to run in an isolated worker instead of the primary process; [] runs everything in the primary process. When unset here and in defaults, the deployment's execution mode decides. See Worker Routing |
worker_scope |
string | null |
How worker runtimes are shared: shared (one per agent), user (one per user, across agents), or user_agent (one per user and agent). Not allowed together with private. See Worker scopes |
file_access |
string | null |
workspace limits path-taking tools such as filesystem, attachments, and matrix_message to the agent workspace and its attachments, and lets filesystem also use the agent's shared directories; unrestricted allows any path the tool's process can reach. shell, python, and other code-execution tools are never confined; isolate them with worker_tools. See File access |
terminals |
string | none |
What people in the agent's rooms may do with its terminals: none shows them nothing, watch lets them watch, and type also lets people who may post open, close, and type in them where the agent's shell runs in a worker that mounts its workspace, and lets them only watch in a worker that does not. It applies to this agent only and is not inherited from defaults; the agent's own use of the terminal toolkit does not depend on it |
allow_self_config |
bool | null |
Give the agent a tool to read and change its own entry under agents:; see self_config |
delegate_to |
list | [] |
Agents this agent may run as subagents, including itself only when listed; see Agent Delegation |
dedicated_subagent_workers |
bool | false |
Let this agent run a subagent in a worker of its own on the Docker or Kubernetes worker backend; see Dedicated workers |
thread_exports |
bool or object | null |
Keep YAML exports of the agent's threads under <workspace>/thread_exports/; true uses the defaults. See Thread Exports |
Unset fields that appear in the inheritance table under Defaults take the defaults value; a per-agent value overrides it.
memory_backend and memory_search inherit from the top-level memory: section instead.
Private Instances
Use private when one shared agent definition should give each requester their own workspace, file memory, and knowledge index.
The YAML stays shared, while each requester's files live in their own private root.
knowledge_bases:
company_docs:
path: ./company_docs
watch: false
agents:
mind:
display_name: Mind
role: A persistent personal AI companion
model: sonnet
tools: [filesystem, shell]
worker_tools: [filesystem, shell]
memory_backend: file
private:
per: user
root: mind_data
template_dir: ./mind_template
context_files: [SOUL.md, USER.md, MEMORY.md]
knowledge:
path: memory
watch: false
knowledge_bases: [company_docs]
Here every user gets their own mind_data/ root, seeded from ./mind_template/ (for example SOUL.md, USER.md, MEMORY.md, and a memory/ folder), while company_docs stays shared by everyone.
Private roots live at <storage>/private_instances/<requester scope>/<agent>/<private.root>/, not next to config.yaml, and dedicated workers mount only that root.
A private agent is still one Matrix account, so use personal agents when each person needs an agent of their own that others can mention or add to a team.
How a private agent behaves:
- The template directory is copied into each new private root, and template files added later are copied in without overwriting requester edits.
- The private root is created even without a template.
private.context_filesload from the private root; agent-levelcontext_filesstill load from the shared agent workspace.- With
memory_backend: file, the private root is the requester's file-memory root; with any other backend, private files exist but are not file memory, andnoneturns memory off. - Nothing is enabled implicitly: set
memory_backend,private.context_files, andprivate.knowledgeexplicitly for whatever the template provides; the file names are up to you. - Because
private.persets the agent's worker scope, configuring bothprivateandworker_scopefails withPrivate agents derive their execution scope from private.per; configure private or worker_scope, not both. - Private agents cannot be configured as team members, and a shared team member cannot reach one through
delegate_to. Tagging a private agent together with other agents in a message still forms an ad hoc team for that requester. - A private agent runs only for a known requester; otherwise it fails with
Private agent '<name>' requires an active execution identity to resolve requester-local state. - It never runs for MindRoom's own router, agent, and team accounts or the internal
mindroom_useraccount, for example when a shared agent's automation mentions it or assigns it a todo; such a run fails withPrivate agent '<name>' requires a human or bot-account requester to resolve requester-local state. A delegation to it from such a turn is refused withCannot delegate to '<name>': a private agent runs only for a person or bot account.
Private Fields
| Field | Type | Default | Description |
|---|---|---|---|
private.per |
user or user_agent |
required | Requester boundary that gets its own private instance; it also sets the agent's worker scope |
private.root |
string | <agent_name>_data |
Relative directory name of the private root; cannot be absolute, contain .., or start with sessions, learning, chroma, mem0, knowledge_db, memory_files, calls, agent_modes.json, agent_modes.lock, browser, browser-profiles, or .sessions-recovery.lock |
private.template_dir |
string | null |
Directory copied into each private root; relative paths resolve from config.yaml, absolute paths are allowed, and a missing directory is a config error (Agent '<name>' has invalid private.template_dir) |
private.context_files |
list | null |
Private-root-relative files preloaded into the prompt; cannot escape the private root |
private.knowledge |
object | null |
Per-requester knowledge index built from the private root; see Private Agent Knowledge. Omit it or set enabled: false for no index |
private.knowledge.enabled |
bool | true |
Whether to index private knowledge |
private.knowledge.description |
string | "" |
What the private knowledge contains, shown to the agent in the search_knowledge_base tool description |
private.knowledge.path |
string | required when enabled | Knowledge directory relative to the private root (. allowed) |
private.knowledge.watch |
bool | true |
Refresh the index in the background on access; when false, external edits need an explicit refresh |
private.knowledge.chunk_size |
int | 5000 |
Maximum characters per indexed chunk (min: 128) |
private.knowledge.chunk_overlap |
int | 0 |
Overlapping characters between adjacent chunks; must be smaller than chunk_size |
private.knowledge.git |
object | null |
Git sync, with the same schema as knowledge_bases.<id>.git; needs a dedicated path subtree, see Private Agent Knowledge |
File-Based Context Loading
context_files inlines files into the agent's prompt under a Personality Context section, without a knowledge base.
- Paths are relative to the agent's workspace,
agents/<name>/workspace/in the storage directory; absolute paths and..are rejected. Withmemory_backend: file, the same workspace holds the agent's file memory. - Files load in list order, each headed by its resolved path so the agent knows where to edit it.
- Missing files are skipped with a warning in the logs.
- Edits take effect on the next reply without a restart.
defaults.max_preload_chars (default 50000) caps the section.
When it is exceeded, MindRoom drops whole files from the start of the list first and then trims the last remaining file from its end.
Each affected file keeps its path and a marker with the omitted character count, so the agent can open the file for the rest.
A cap too small to hold the headings and markers fails with max_preload_chars=<n> cannot fit required context headings and omission markers.
Listening
A listening agent hears every message in chosen rooms from the people it may answer, whether or not the message is addressed to it. After a room has been quiet for a while, the agent runs one silent turn over what it heard and calls only the tools you list, for example to remember something or react to a message. It stays a normal agent in those rooms: it still answers when addressed, under the room's usual rules, and listening only adds the silent turns, so a message addressed to it is answered and also heard by the next silent turn.
The agent must already be in each listened room, for example because the room is in its rooms; listening does not join rooms, and MindRoom logs once when a listened room is not joined yet.
Every entry in listen.tools must also be one of the agent's own tools, or the config fails to load.
The default listen.tools is [memory, react], so an agent with listen: and the default tools needs memory and react in its tools:.
A silent turn narrows the agent's own tools to this list and never grants one the agent lacks, so worker_scope checks, tool limits, and reload restarts apply to it as to every other tool.
agents:
scribe:
display_name: Scribe
rooms: [lobby]
tools: [memory, react]
listen:
rooms: [lobby]
quiet_seconds: 120
tools: [memory, react]
model: cheap
| Option | Type | Default | Description |
|---|---|---|---|
rooms |
list | required | Room keys, Matrix room IDs, or aliases to listen in, at least one. Each must resolve the way room_thread_modes keys do |
quiet_seconds |
int, >= 10 | 60 |
Seconds without a message the agent hears before the silent turn runs |
max_messages |
int, 1 to 500 | 200 |
Most messages one silent turn reads; the rest wait for the next turn |
max_runs_per_hour |
int, 1 to 60 | 6 |
Most silent turns per hour for the agent, shared by its listened rooms in turn; further due runs are skipped, logged, and what was heard is kept |
tools |
list | [memory, react] |
The only tools a silent turn may call, at least one, as toolkit names or toolkit.function. Each toolkit must also be in the agent's tools, and some are refused; see What listed tools can do |
model |
string or null | null |
Key of an entry under models: for silent turns, which pins them to it. Unset, a silent turn uses the room's model, set with !room_model or room_models, and otherwise the agent's model |
What a silent turn does
The agent hears every message in a listed room that it may hear.
That uses the same sender authorization its replies use, judged on the person a relay speaks for rather than the relaying account.
Once nothing the agent hears has been said in the room for quiet_seconds, one silent turn runs over at most max_messages of what it heard.
Messages it does not hear, such as its own or those of a sender it may not hear from, never delay that turn, unless there are more than max_messages of them waiting.
More than max_messages messages waiting, a message awaiting its refetch, or another agent's reply still being written counts as busy, and what came before waits too; a reply still being written is heard once it is finished.
In a room that never goes quiet, or stays busy, a turn runs anyway once the oldest message waiting is ten times quiet_seconds old, and a reply still unfinished by then is heard as it stands.
A turn also hears no more than fits its model's context_window, and the rest waits for the next turn.
The turn's own text is never sent to the room, and approval-gated tools and interactive questions are not offered.
It calls only its listen tools, each with its usual effect; see What listed tools can do.
No more than max_runs_per_hour turns run per hour; the count starts again after a restart.
Each turn runs under the config current when it starts, so a reload that removes a tool or a sender applies to every turn after it.
The first run for a room starts at "now". The agent never reads history from before listening was turned on, and a room it stops listening in forgets its place. After a restart, MindRoom repairs the gaps it can, so the agent hears most of what it had not yet heard. Some messages from a long outage may not be heard.
Only shared agents can listen: listen on a private agent, which has no single identity to listen as, fails config load.
A listening agent skips contact rooms, where only a reply passes the contact's message policy.
What listed tools can do
listen.tools is a configuration choice.
A silent turn calls only the tools it names, but each keeps its usual effects, heard text can drive any of them, and some act with the agent's full authority later or elsewhere:
scheduler, one of the default agent tools, schedules a later turn of the agent, and can edit or cancel any pending task in the room; an edited task becomes the agent's own. A scheduled message can also address other agents and teams in the room, which answer the listening agent's account under that account's access, not the heard sender's.filesystem,shell, andpythoncan write any workspace file, includingMEMORY.mdand the context files and skills the agent loads into every later turn;script,shell, andpythonrun code with the agent's worker and credentials.- A tool with a shared connection acts on that connection's credentials, for example
github,sql,postgres,google_drive,homeassistant, andcomposio. report_publishingpublishes workspace files at a public link.- A tool that starts a turn starts it with all of the agent's tools, as the agent's own account, and a tool that checks who asked sees that account, because no person asked for a silent turn.
- A tool that sends still sends, for example
matrix_api,matrix_voice_message,thread_move, and messengers such asslack,discord,telegram,whatsapp,twilio,email,gmail,outlook_mail, andmicrosoft_teams.
List these only if you trust everyone whose messages the agent hears.
MindRoom holds a silent turn to a few lines of its own:
- Config load refuses
matrix_message, presets, and the tools a contact turn never offers:contacts,delegate,agent_manager,self_config,config_manager,dynamic_workflow,claude_agent,skill_manage,dynamic_tools, andmatrix_user. - The turn's tool context carries
listen.tools, so a tool that builds its own catalog from it, such as the functions ascriptmay call, offers nothing outside the list. - No call may save its result to a file with
mindroom_output_path, so a tool that writes no files of its own, such asreact, cannot overwrite one. - A shell in a silent turn does not offer
mindroom-agent, because no requester owns a grant for it.
Privacy and cost
Everyone in a listened room whom the agent may answer is heard, including people who never addressed it.
Heard text is not extracted into memory automatically, and a silent turn stores no run in session history, so a heard message that is later redacted does not linger in a stored run.
What a silent turn writes with its memory tool, though, is the agent's shared memory: heard text can resurface in the agent's replies in other rooms and to other users.
So is what it writes with knowledge_graph, which an agent with knowledge_graph has on its own and which writes the shared graph when knowledge_graph_edits is on.
A listed tool that writes files can write heard text into MEMORY.md as well (see What listed tools can do).
Leave memory, knowledge_graph, and such tools out of listen.tools, or don't listen, in rooms whose talk must stay there.
A silent turn records its usage under the kind listening (see Usage).
Budgets do not apply, because no requester asked for the turn.
Bound the cost with model, a cheaper alias, and with max_runs_per_hour.
Reactions
The react tool adds an emoji to a message in the current room, and cannot send messages.
It suits a silent turn that should acknowledge what it heard without writing in the room.
Known limits
- A failed or timed-out silent turn is retried, and so is one cut off by a restart after its tools have acted, so a memory write or reaction may happen twice.
- A heard message is skipped with a warning when the turns covering it keep failing, after the batch is halved down to that one message, or when it waits more than 10 minutes for a refetch. A turn that fails on its provider, unreachable, busy, out of credit, or refusing the credentials, counts toward no skip; the agent's rooms wait a minute and try again.
- A backlog longer than
max_messages, or a message awaiting its refetch, holds the room's turn for up to ten timesquiet_seconds. What follows a message awaiting its refetch waits up to 10 minutes, or ten quiet windows if that is longer. - A message whose timestamp is already older than the room's place when it arrives, such as one delayed by federation or backdated by a bridge, is not heard; MindRoom reads a room in timestamp order and logs nothing for it. The place moves onto a message the agent did not hear only once it is 30 seconds old, or one quiet window if that is shorter, so a message that arrives a moment late is still heard.
- A message stamped later than now, such as one from a server whose clock runs ahead, waits to be heard until that time comes.
- Heard text can carry prompt injection that drives the listed tools; read Listening agents before adding a tool to
listen.tools.
Naming Rules
Agent and team keys may contain only letters, digits, and underscores (^[a-zA-Z0-9_]+$).
The same key cannot appear under both agents: and teams:.
router, user, and _shared are reserved.
Defaults
The defaults section sets values every agent inherits unless it sets its own, plus global-only settings that cannot be overridden per agent.
defaults:
tools: [scheduler]
max_tool_calls_per_turn: 200
worker_tools: [shell, filesystem, python]
enable_streaming: true
max_preload_chars: 50000
These defaults apply to each agent that leaves the same field unset:
| Field | Default |
|---|---|
markdown |
true |
cheap_model |
null; ignored for an agent whose model is the same. See Cold-Cache Model |
knowledge_graph |
false |
knowledge_graph_edits |
true |
num_history_runs, num_history_messages, max_tool_calls_from_history |
null (no limit) |
compaction |
enabled; see Agent Compaction Settings |
room_activity |
off, window_minutes: 120, max_threads: 5; see Activity in Other Threads |
max_tool_calls_per_turn |
1000 |
show_tool_calls |
true |
show_reasoning |
true |
worker_tools |
null (the deployment's execution mode decides) |
worker_scope |
null |
file_access |
workspace |
allow_self_config |
false |
automations |
[]; private agents inherit them only as personal_rooms.agent, and agents without file memory skip the built-ins. See Automations |
defaults.tools (default [scheduler]) is added to every agent with include_default_tools: true; set it to [] to add nothing.
It accepts the same per-tool overrides as agents.<name>.tools.
These settings are global-only:
| Field | Default | Description |
|---|---|---|
enable_streaming |
true |
Show replies as progressive message edits; see Streaming |
streaming |
see Streaming | Timing settings for progressive edits |
large_message_strategy |
sidecar |
Oversized replies as a preview with the full text attached (sidecar) or as several complete messages (split); see Large Messages |
coalescing.debounce_ms |
1000 |
Milliseconds (>= 0) to wait after unmarked media for more attachments or a trailing caption before replying; text replies immediately, and marked submissions use their own bound |
show_stop_button |
true |
Add a 🛑 reaction while an agent responds; see Stop Button |
max_consecutive_agent_replies |
50 |
Consecutive agent or team messages (>= 1) before agents stop waking each other; see Agents mentioning other agents |
max_preload_chars |
50000 |
Cap (>= 1) on preloaded context files; see File-Based Context Loading |
tool_output_auto_save_threshold_bytes |
51200 |
Larger tool outputs are saved to the workspace; see Workspace and tool output files |
allow_shell_without_worker |
false |
Let the shell tool run commands in the MindRoom process for agents whose shell does not run in a worker; when false, each such call is refused with a message naming this setting. mindroom config init sets it to true |
worker_grantable_credentials |
null |
Shared credential services available inside isolated workers (null grants none); Google OAuth client and token services, google_vertex_adc, and slack_app cannot be granted. See Credential leases |
thread_summary_model, thread_summary_temperature, thread_summary_first_threshold, thread_summary_subsequent_interval |
null, 0.2, 1, 10 |
Automatic thread summaries; see Automatic Thread Summaries |