Matrix Integration
This page records the Matrix contracts that MindRoom's code does not make obvious: one identity invariant, the custom key namespace, the room-level reply relation, the conversation-notice marker, and the room accounts list and model-selection wire protocol that external clients implement. User-facing Matrix behavior is on Matrix Integration, event-journal decisions and homeserver behaviour are on Matrix Event-Journal Contracts, and invites and delivery epochs are on Bot Runtime.
Identity Invariant
Code must resolve an entity's Matrix ID through the persisted identity registry, keyed by configured alias, and never derive it from the requested localpart, because the actual account can differ (see Agent Users).
Custom Key Namespace
New custom Matrix event types, state event types, and content keys use the io.mindroom.* namespace.
Existing names under other prefixes, such as the com.mindroom.* keys, org.mindroom.personal_room, and chat.mindroom.call_failure, keep their names and are never migrated, because events already in room history, MindRoom Chat, and documented procedures use those names.
Room-Level Reply Relation
A reply outside a thread, such as every reply in thread_mode: room, names its source as m.relates_to: {"io.mindroom.in_reply_to": {"event_id": "<source>"}} instead of m.in_reply_to, because clients render m.in_reply_to as a quote of the source above the answer.
The link stays inside m.relates_to rather than in a top-level content key because every path that handles an event's relation already carries or drops that object whole: nio copies it into the cleartext of an encrypted event, and long-message previews and segments, attachment-backed content, queued edits, and the room-level relation strip in dispatch treat it as one unit.
A top-level key would need its own handling in each of those paths, and the reply would stop counting as a relation, so it would become eligible as a thread root.
Clients, bridges, and homeservers treat a relation with neither rel_type nor m.in_reply_to as no relation, so the reply shows as a plain message.
Conversation Notices
A notice that asks its reader to reply in its thread, such as a contact request asking its owner to accept or decline, carries "io.mindroom.conversation": true in its content, and in the m.new_content of any edit to it.
MindRoom Chat lists an agent's notice as a conversation, and lets it make its room unread, only when the notice carries this key or its thread has replies, so an unmarked notice that asks for a reply would leave its room looking read.
Informational notices stay unmarked.
Room Accounts List
The router publishes which joined members of a room are MindRoom accounts, so clients can recognize agents and teams whose user names do not start with mindroom_, such as personal agents with a custom matrix_username.
The room state event has type io.mindroom.accounts, the router's user ID as its state key, and the sorted user IDs of the joined router, agent, and team accounts of the router's installation:
{"accounts":["@alice.mind:example.org","@mindroom_research:example.org","@mindroom_router:example.org"]}
The router publishes it on startup and after every config reload, and updates it when one of those accounts joins or leaves the room.
Matrix accepts a state key that starts with @ only from that user, but any member allowed to send the type can send it under another state key.
So a client reads only the event keyed by a router's user ID, and trusts it only when its sender is a MindRoom router (@mindroom_router:<server>, or @mindroom_router_<namespace>:<server> for a namespaced installation) on the viewer's own homeserver.
Each MindRoom installation in a room has its own router, which lists only its own accounts.
The router can send the event only where the room's power levels allow it, which the rooms MindRoom creates do; managed rooms regain that power level at every startup, personal rooms regain it at startup while their owner is still in an onboarding room, other rooms keep the power levels they were created with, and a client that creates rooms should give the type power level 0 too.
Model Selection Protocol
Discovery uses Olm-encrypted to-device events, including for unencrypted rooms, so it needs no room-state advertisement, state permissions, or external endpoint. Only the router answers discovery. It authenticates the actual requesting device and requires the requester and router to be currently joined, plus at least one configured, joined agent the requester may address. An included thread must be a readable, unredacted root in that room, whether or not it is encrypted. Replies go only to the authenticated device, and sending a catalog never verifies a previously untrusted device. Blocked devices, malformed requests, and unauthorized room or thread scopes receive no response.
Send type io.mindroom.models.request with exact content:
Omit thread_id for room capability discovery; null is invalid.
Request IDs allow up to 128 characters; room/thread IDs allow up to 1024.
Do not add claimed sender or device fields.
The private reply type is io.mindroom.models.response:
{
"version": 1,
"request_id": "random-uuid",
"room_id": "!room:example.org",
"thread_id": "$root",
"capabilities": ["model_selection"],
"agent_user_ids": ["@mindroom_helper:example.org"],
"catalog_revision": "sha256-of-published-entries",
"models": [{"key":"fast","display_name":"Quick helper","provider":"openai","id":"gpt-6-astra","icon_url":"mxc://example.org/image","reasoning_levels":["low","high"],"reasoning_default":"low"}],
"selection": {"override":"fast","reasoning":"high","inherited":[{"entity":"helper","user_id":"@mindroom_helper:example.org","model":"fast","source":"agent"}]}
}
The response omits thread_id when the request did.
selection.override is always present and is null for absent or deleted model overrides.
It names a thread override only when every requester-visible responding entity uses that override, and is null when those entities have different thread overrides or some have none.
inherited lists requester-visible responding entities with their room-level model, ignoring thread overrides.
Each inherited[].user_id is that agent's or team's own Matrix account, and each inherited[].source names what chose that model: room for a saved !room_model override, room_config for the room's authored room_models entry, or agent for the entity's own configured model.
reasoning_levels and reasoning_default appear only on models with reasoning levels.
selection.override and each inherited[].model are catalog keys; when the chosen reference is key@level, a reasoning field beside them carries the level, and it is absent otherwise.
This explains what resetting the thread will use, including different defaults across agents and teams.
Each request reads current config.
Models are sorted by stable key; the SHA-256 revision covers only published entries, including labels and resolved Matrix icons.
Display names may repeat and fall back to the key.
Icons use Matrix mxc:// URIs only; other local icon rules are on the model configuration page.
The router stops processing a request after 12 seconds, but a response already handed to nio is not retracted. Admission caps queued/in-flight requests at eight, and at two per Matrix user across all of that user's devices, and accepts at most eight fresh requests per user in 12 seconds; concurrent duplicate requests share the active request. Authorization is last checked when the response is handed to nio, so a requester who loses room access while nio prepares or retries the send can still receive that already-authorized catalog. Clients must independently enforce current joined-agent eligibility and discard expired responses.
Clients register their response listener before sending, correlate request, room, thread, and actual authenticated runtime device, and independently check returned agent membership. Candidate runtime accounts are hints; clients require an owner-signed runtime device. Multiple runtime devices remain separate choices. Refresh on picker opening; expire requests after 12 seconds and discard late results.
Thread Changes and Acknowledgements
Mutations use the ordinary m.room.message / m.text path with readable body !model fast or !model reset, carrying this additional content:
{"io.mindroom.model_selection":{"version":1,"runtime_user_id":"@mindroom_router:example.org","runtime_device_id":"ROUTER_DEVICE","operation":"set","model":"fast"}}
operation is set or reset; reset omits model.
model is a catalog key or key@level for one of the key's reasoning_levels, and the result's override echoes it as sent.
Explicit set permits keys such as default, reset, or list.
The required runtime device ID comes from authenticated discovery, routes the command, and grants no authority.
Actual room and canonical thread come from Matrix event routing.
Malformed structured metadata is rejected without falling back to text parsing; unrelated runtime users/devices ignore targeted commands.
Existing authorization, command policy, and durable deduplication still apply.
The normal command reply carries the persisted result alongside readable text:
{"io.mindroom.model_selection_result":{"version":1,"command_event_id":"$command","room_id":"!room:example.org","thread_id":"$root","runtime_user_id":"@mindroom_router:example.org","runtime_device_id":"ROUTER_DEVICE","operation":"set","model":"fast","status":"applied","override":"fast"}}
Applied reset omits model and has override:null.
Rejection has status:"rejected", no override, and may include a readable error.
The reply to a typed !model <key> or !model reset that was applied carries the same result, with the answering router's own account and device as runtime_user_id and runtime_device_id, so a client can pair any applied change with its command event and show both as one line.
A typed listing or refusal, and a typed reset that found no override to remove, carry no result and stay ordinary text.
The picker's own reset is acknowledged as applied either way, since its result answers the operation.
The result is room-visible, so it names only what the command itself named: the selected key and level.
It must never carry a previous model, an inherited default, a display name, or which agents changed, because those come from the requester-scoped discovery reply and other room members may not be allowed to see them.
Clients therefore show a change's new model only, and cannot show the model it replaced.
Uncertain crash recovery may omit result metadata; clients refresh after timeout rather than infer success from sending.
Accept an acknowledgement only for the client's current pending command event, exact room/thread, runtime user/device, operation, and model.
Encrypted events additionally authenticate the sender device.
In plaintext rooms, Matrix authenticates the sender account; device metadata only correlates the result.
Serialize pending changes per runtime/thread and prevent earlier discovery results from replacing later confirmed changes.
Other clients and text commands become visible on refresh; there is no global selection revision.