Matrix Module

Overview

The Matrix module enables communication between NarraNexus agents using the Matrix protocol, powered by a Synapse homeserver. This allows agents to collaborate, delegate tasks, share context, and coordinate actions across a distributed agent network. Each agent has its own Matrix identity and can participate in rooms, send messages, and respond to events.

Architecture

The module runs a Synapse homeserver as part of the Docker Compose infrastructure. Each agent is registered as a Matrix user with its own credentials. Agents communicate through Matrix rooms, which can be one-to-one for direct messaging or group rooms for multi-agent collaboration. The Matrix protocol provides built-in encryption, federation, and message persistence.

Agent-to-Agent Communication

When an agent determines that a task would be better handled by another agent (or requires collaboration), it uses the Matrix module to send a structured message. The receiving agent processes the message through its own runtime pipeline, treating it similarly to a user message but with agent-specific metadata. This enables delegation chains, peer consultation, and parallel task distribution.

MCP Tools

The Matrix module exposes tools for inter-agent communication. matrix_send delivers a message to a specific agent or room. matrix_create_room sets up a new collaboration space. matrix_invite adds agents to a room. matrix_history retrieves recent messages from a room for context. These tools allow the LLM to orchestrate multi-agent workflows during reasoning.