matrix-group-chats

Documentation Index

Fetch the complete documentation index at: https://docs.ixo.world/llms.txt

Use this file to discover all available pages before exploring further.

​

Summary

1. Per-turn gating middleware. In Matrix group rooms (!isDirect && memberCount > 2), the oracle only replies when mentioned, replied to, or already in an active thread. Otherwise the turn short-circuits and nothing is posted. DMs and non-Matrix transports pass through untouched.
2. Per-room compacted memory. Every message in the room is captured into an FTS5-searchable SQLite store, compacted into ~200–400 token summary chunks, and synced back to the same Matrix room as encrypted media. The agent can recall, search, and pin durable facts via four tools.

​

Activation

await createOracleApp({
  config,
  features: { 'matrix-group-chats': false },
});

• rtCtx.session.client === 'matrix'
• rtCtx.session.roomId is set
• The room is not a DM and has more than 2 members

​

Environment variables

​

What it contributes

• Tools (all per-tool visibility: 'always', so they bypass the capability gate when returned for group rooms):
  • recall_channel_memory — recent compacted summary chunks + pinned facts + member roster.
  • search_channel_memory — FTS5 keyword search over compacted chunks.
  • pin_room_fact — persist a durable fact to this room (decisions, deadlines, roles).
  • unpin_room_fact — remove a pinned fact by id.
• Sub-agents: none.
• Middleware: one — the per-turn group-chat gate (see below).
• HTTP routes: none.
• Nest modules: ChannelMemoryModule (the per-room SQLite store + Matrix sync).
• Shared state: channelMemory — other plugins read the ChannelMemoryService singleton via rtCtx.shared.channelMemory.

​

What the middleware does per turn

1. Captures the latest HumanMessage into channel memory — even when the bot stays silent.
2. Runs shouldAgentRespond. Precedence: DM (auto-respond) → mention → reply-to-bot → active-thread cache → Matrix-history fallback → ignore.
3. If the bot shouldn’t respond → short-circuits the turn (jumpTo: 'end'); the Matrix transport detects “no AI message produced” and posts nothing.
4. If it should → checks m.room.power_levels; short-circuits silently when the bot lacks permission to send m.room.message.
5. Refreshes the room’s member roster (fire-and-forget) so the next turn has fresh names.
6. Runs just-in-time compaction with a 3-second cap so the agent gets up-to-date summary context.

​

Speaker identity in group rooms

• Group rooms (memberCount > 2) — content is prefixed [DisplayName]: so the agent reads who’s speaking inline.
• DMs — same additional_kwargs metadata (senderDid, senderMatrixUserId, senderDisplayName, threadId, eventId, raw m.mentions / m.relates_to), no content prefix.

​

When to use it

• A user asks what was said or decided earlier in this Matrix group room.
• A user asks who is in the room or what their role is.
• A durable fact should survive across threads (deadline, decision, project context) — pin it.
• You need to recall the gist of prior conversation before answering a multi-step group request.

​

When NOT to use it

• Single-user DMs — the plugin only acts in rooms with more than 2 members.
• Long-term personal memory about a specific user — use memory.
• Verbatim text of a specific Matrix event — query Matrix history directly.

​

Opt out / Opt in

const app = await createOracleApp({
  config,
  features: { 'matrix-group-chats': false }, // never load
  // features: { 'matrix-group-chats': true }, // force load (default)
});

​

Where to read next