# 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

```bash
# 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.