94 lines
2.4 KiB
Markdown
94 lines
2.4 KiB
Markdown
# Matrix Hermes — Agent Guide
|
|
|
|
Matrix authentication, client, and bridge integration for Hermes Agent. Provides login/token management, async client wrapper, room management, messaging, sync engine, and Kanban board monitoring over Matrix.
|
|
|
|
## Stack
|
|
|
|
- **Python** ≥3.10, **mautrix** (Matrix client SDK), **aiohttp**
|
|
- **python-dotenv** — config loading
|
|
- Optional: `mautrix[encryption]` for E2EE
|
|
- **pytest**, **pytest-asyncio**, **ruff** — dev tooling
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/matrix_hermes/
|
|
__init__.py
|
|
auth.py # Login/logout, access token management, device ID
|
|
client.py # Async MatrixClient wrapper (mautrix-based)
|
|
config.py # MatrixConfig dataclass, .env-based loading
|
|
cli.py # CLI entry point — `matrix-hermes` command
|
|
rooms.py # Room CRUD operations
|
|
messaging.py # Send/edit/reaction/typing indicators
|
|
sync.py # Incremental sync engine
|
|
kanban.py # Kanban DB monitoring over Matrix
|
|
|
|
tests/
|
|
__init__.py
|
|
conftest.py
|
|
test_auth.py
|
|
test_cli.py
|
|
test_config.py
|
|
test_kanban.py
|
|
test_messaging.py
|
|
test_rooms.py
|
|
test_sync.py
|
|
|
|
pyproject.toml # Build config, dependencies
|
|
.env.example # Config template
|
|
README.md
|
|
```
|
|
|
|
## How to Run
|
|
|
|
```bash
|
|
# Install
|
|
pip install -e ".[dev]"
|
|
|
|
# Login
|
|
matrix-hermes login
|
|
|
|
# Check status
|
|
matrix-hermes whoami
|
|
|
|
# Show config
|
|
matrix-hermes show-config
|
|
|
|
# Logout
|
|
matrix-hermes logout
|
|
|
|
# Check connection
|
|
matrix-hermes check
|
|
|
|
# Monitor Kanban
|
|
matrix-hermes kanban
|
|
```
|
|
|
|
## Key Architecture
|
|
|
|
- **Package-based** — installable via `pip install -e .`
|
|
- CLI entry: `matrix-hermes` (click-based)
|
|
- Sessions persist to `~/.hermes/matrix_sessions/`
|
|
- Config via `.env` file (template in `.env.example`)
|
|
- Async core built on `mautrix` — all network calls are async
|
|
|
|
## Production
|
|
|
|
- **CLI tool / library** — no server, no systemd
|
|
- Used as a library by Hermes Agent gateway for Matrix platform support
|
|
|
|
## Environment Variables
|
|
|
|
| Var | Description |
|
|
|-----|-------------|
|
|
| MATRIX_HOMESERVER | Matrix server URL (e.g. `https://matrix.ourpad.casa`) |
|
|
| MATRIX_ACCESS_TOKEN | Persistent access token (after login) |
|
|
| MATRIX_USER_ID | User MXID (after login) |
|
|
| MATRIX_DEVICE_ID | Device identifier (after login) |
|
|
|
|
## Pitfalls
|
|
|
|
- **E2EE is optional** — requires `mautrix[encryption]` install extra
|
|
- Session tokens stored at `~/.hermes/matrix_sessions/` — keep secure
|
|
- All matrix network operations are async — synchronous wrappers may need event loop management
|