Initial commit: Matrix Bridge Daemon

Persistent Python daemon connecting Matrix DM room to AiAgent API.

- Config-driven (JSON config file)
- Extensible command system (/new_session, /help)
- Typing indicators while agent processes
- Session auto-naming for identification
- Persistent state across restarts
- Token refresh, retry logic, error handling
- Python stdlib only — no external dependencies

README.md

@@ -0,0 +1,57 @@
+# 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.