MatrixBridge/README.md

Matrix Bridge — Lucy's Messaging Bridge

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.