How Matrix rooms, DMs, and threads map onto Apus sessions, and how much room history each turn carries.

Threads

Matrix supports native threads for both automatic replies and message-tool sends. Two independent knobs control behavior:

Session routing (sessionScope)

dm.sessionScope decides how Matrix DM rooms map to Apus sessions:

• "per-user" (default): all DM rooms with the same routed peer share one session.
• "per-room": each Matrix DM room gets its own session key, even for the same peer.

Explicit conversation bindings always win over sessionScope; bound rooms and threads keep their chosen target session.

Reply threading (threadReplies)

threadReplies decides where the bot posts its reply:

• "off": replies are top-level. Inbound threaded messages stay on the parent session.
• "inbound": reply inside a thread only when the inbound message was already in that thread.
• "always": reply inside a thread rooted at the triggering message; that conversation routes through a matching thread-scoped session from the first trigger onward.

dm.threadReplies overrides this for DMs only - for example, keep room threads isolated while keeping DMs flat.

Selecting a reply target inside a thread preserves both the thread and the selected message. Ordinary threaded messages can carry reply metadata for older clients; Apus does not treat that compatibility fallback as a quoted message in the agent's context.

Mentions in bot-created threads

Set channels.matrix.requireMentionInBotThreads: false to accept unmentioned follow-ups in native Matrix threads rooted in an event sent by the receiving bot. Set it to true to require mentions in those threads even when the room uses requireMention: false or autoReply: true. Omitting it preserves the room's existing mention behavior.

The setting is also available under accounts.<id> and each groups or rooms entry. Room entries override the account value. As with other Matrix room settings, an exact room entry replaces the wildcard entry; omitted fields in an exact entry fall back to the account, not the wildcard.

Only a native m.thread relationship qualifies. An ordinary reply to a bot message does not. Apus resolves the thread root using the receiving account and caches its verified author. Matrix content redaction does not change that author, so a redacted bot-authored root still qualifies. If the root's identity cannot be read or verified, the existing mention behavior applies. Room access, sender restrictions, and allowBots: "mentions" still apply.

Thread inheritance and slash commands

• Inbound threaded messages include the thread root message as extra agent context.
• Message-tool sends auto-inherit the current Matrix thread when targeting the same room (or the same DM user target), unless an explicit threadId is provided.
• DM user-target reuse only kicks in when current session metadata proves the same DM peer on the same Matrix account; otherwise Apus falls back to normal user-scoped routing.
• /session unbind, /agents, /session idle, /session max-age, and thread-bound /acp spawn all work in Matrix rooms and DMs.
• /acp spawn --thread auto creates a new Matrix thread when threadBindings.spawnSessions is enabled.
• Running /acp spawn --thread here inside an existing Matrix thread binds that thread in place.

When Apus detects a Matrix DM room colliding with another DM room on the same shared session, it posts a one-time m.notice suggesting dm.sessionScope: "per-room" to isolate the rooms. The notice only appears when thread bindings are enabled.

ACP conversation bindings

Matrix rooms, DMs, and existing Matrix threads can become durable ACP workspaces without changing the chat surface.

Fast operator flow:

• Run /acp spawn codex --bind here inside the Matrix DM, room, or existing thread to keep using.
• In a top-level DM or room, the current DM/room stays the chat surface and future messages route to the spawned ACP session.
• Inside an existing thread, --bind here binds that current thread in place.
• /new and /reset reset the same bound ACP session in place.
• /acp close closes the ACP session and removes the binding.

--bind here does not create a child Matrix thread. threadBindings.spawnSessions gates /acp spawn --thread auto|here, where Apus needs to create or bind a child thread.

Thread binding config

Matrix inherits global defaults from session.threadBindings and supports per-channel overrides:

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions: gates both subagent and ACP thread spawns.
• Deprecated threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions keys are migrated to spawnSessions by apus doctor --fix.
• threadBindings.defaultSpawnContext

Matrix thread-bound session spawns default on. Set threadBindings.spawnSessions: false to block native subagent and ACP thread spawns from creating/binding Matrix threads. Set threadBindings.defaultSpawnContext: "isolated" when native subagent thread spawns should not fork the parent transcript.

History context

• channels.matrix.historyLimit controls how many recent room messages are included as InboundHistory when a room message triggers the agent. Falls back to messages.groupChat.historyLimit; effective default 0 if both are unset (disabled).
• Matrix room history is room-only; DMs keep using normal session history.
• Room history is pending-only: Apus buffers room messages that did not trigger a reply yet, then snapshots that window when a mention or other trigger arrives.
• The current trigger message is not included in InboundHistory; it stays in the main inbound body for that turn.
• Retries of the same Matrix event reuse the original history snapshot instead of drifting forward to newer room messages.