# 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