A persistent Python daemon that connects a Matrix DM room to the local AI agent framework (AiAgent). Listens for incoming messages, forwards them to the agent, and sends responses back — all using only Python stdlib.

Architecture

Matrix ──sync──> MatrixClient ──events──> Bridge ──message──> AgentClient ──> AiAgent API
   ^                                       │                      │
   └─────────── response ──────────────────┘                      │
                                                                   │
   typing indicator, session management, command dispatch       polling loop

Files

File	Purpose
`main.py`	Entry point, CLI argument parsing
`config.py`	Configuration loader (JSON → dataclass)
`bridge.py`	Main loop, event processing, command dispatch
`matrix_client.py`	Matrix API client (sync, send, typing, auth)
`agent_client.py`	Agent API client (sessions, messages, polling)
`state.py`	Persistent state (session ID, batch token, dedup)
`config.json`	Configuration file

Configuration

Edit config.json to set:

Matrix — server, user ID, room ID, credentials file path
Agent — API base URL
Bridge — poll interval, timeouts, limits

Commands

Command	Description
`/new_session`	Create a fresh agent session (clears conversation)
`/help`	Show available commands

Adding new commands: add an entry to Bridge.COMMANDS and a _cmd_<name> method.

Deployment

# Install
sudo cp -r . /opt/MatrixBridge
sudo cp matrix-bridge.service /etc/systemd/system/

# Start
sudo systemctl enable --now matrix-bridge

Requirements

Python 3.10+ with stdlib only — no external packages needed.