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

# 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

2.4 KiB Raw Permalink Blame History