Matrix-Hermes

Matrix bridge for Hermes Agent — provides authentication, client connectivity, bridge utilities, room management, messaging, and real-time sync.

Quick Start

cd ~/projects/matrix-hermes
pip install -e ".[dev]"
cp .env.example .env
# Edit .env with your Matrix credentials
matrix-hermes check
matrix-hermes login

Environment Variables

Variable	Description	Required
`MATRIX_HOMESERVER`	Homeserver URL (e.g. https://matrix.org)	Yes
`MATRIX_ACCESS_TOKEN`	Existing access token (preferred)	Yes*
`MATRIX_USER_ID`	Full Matrix user ID (@user:server)	Yes*
`MATRIX_PASSWORD`	Password for login	Yes*
`MATRIX_DEVICE_ID`	Stable device ID for E2EE	No
`MATRIX_SESSION_DIR`	Session persistence dir	No
`MATRIX_ENCRYPTION`	Enable E2EE (true/false)	No
`MATRIX_ALLOWED_USERS`	Comma-separated user whitelist	No
`MATRIX_HOME_ROOM`	Room ID for notifications	No

*Either MATRIX_ACCESS_TOKEN or MATRIX_USER_ID + MATRIX_PASSWORD is required.

Authentication Flow

Access token — if MATRIX_ACCESS_TOKEN is set, it's validated via /whoami
Session file — if no token, checks ~/.hermes/matrix_sessions/<user>.json
Password login — falls back to MATRIX_USER_ID + MATRIX_PASSWORD; token auto-saved

CLI Commands

# Authentication
matrix-hermes login        # Authenticate with homeserver
matrix-hermes whoami       # Validate current token
matrix-hermes logout       # Invalidate token + remove session
matrix-hermes check        # Check config from env
matrix-hermes show-config   # Show config as env vars

# Rooms
matrix-hermes rooms list                         # List joined rooms
matrix-hermes rooms create --name "My Room"      # Create a new room
matrix-hermes rooms join !room:example.org       # Join a room
matrix-hermes rooms leave !room:example.org      # Leave a room
matrix-hermes rooms info !room:example.org       # Get room details
matrix-hermes rooms members !room:example.org    # List room members
matrix-hermes rooms invite !room:example.org @user:example.org

# Messaging
matrix-hermes send text !room:example.org "Hello Matrix!"
matrix-hermes send image !room:example.org /tmp/photo.jpg --caption "Check this"
matrix-hermes send file !room:example.org /tmp/report.pdf

# Sync
matrix-hermes sync listen                                      # Listen for all messages
matrix-hermes sync listen --room !room:example.org             # Filter by room
matrix-hermes sync listen --filter-type m.room.message         # Filter by type
matrix-hermes sync listen --show-all                           # Show all event types

Python API

import asyncio
from matrix_hermes import MatrixConfig, MatrixClient

async def main():
    config = MatrixConfig.from_env()
    async with MatrixClient(config) as client:
        # Rooms
        rooms = await client.get_joined_rooms()
        ok = await client.join_room("!room:example.org")
        
        # Messages
        result = await client.send_message("!room:example.org", "Hello from Hermes!")
        
        # Sync
        from matrix_hermes import SyncEngine, SyncFilter
        engine = SyncEngine(client._client)
        
        async def on_message(event):
            print(f"[{event.room_id}] {event.sender}: {event.content.get('body')}")
        
        engine.on_event("m.room.message", on_message)
        engine.start_background()
        
        # ... do other work ...
        
        await engine.stop()

asyncio.run(main())

Module Reference

Module	Purpose	Key exports
`auth`	Login, token, sessions	`login`, `login_from_config`, `logout`, `save_session`
`config`	Env-based configuration	`MatrixConfig`
`client`	Async mautrix wrapper	`MatrixClient`, `MatrixMessage`, `SendResult`
`rooms`	Room management	`create_room`, `join_room`, `leave_room`, `get_room_info`, `get_room_members`
`messaging`	Send messages, media	`send_text`, `send_image`, `send_file`, `edit_message`, `send_reaction`
`sync`	Real-time event sync	`SyncEngine`, `SyncFilter`, `sync_once`, `extract_events`, `get_messages`
`cli`	CLI entry point	`main`

Room Management

create_room() — create rooms with presets, visibility, invites
join_room() / leave_room() / forget_room() — membership lifecycle
get_joined_rooms() — list joined rooms
get_room_info() — fetch room metadata (name, topic, member count, encryption)
get_room_members() — list members with display names
invite_user() / kick_user() / ban_user() / unban_user() — moderation
set_room_name() / set_room_topic() — room settings

Messaging

send_text() — plain text with optional HTML, reply, thread
send_notice() — m.notice (less intrusive)
send_emote() — m.emote (/me style)
send_image() / send_file() / send_sticker() — rich media
edit_message() — m.replace edits
redact_message() — message deletion
send_reaction() — emoji reactions
send_typing() / send_read_receipt() / set_fully_read() — presence

Sync Engine

SyncEngine — continuous sync with handler dispatch, exponential backoff
SyncFilter — filter by event type, room, sender
sync_once() — single sync call
extract_events() — parse sync response into event objects
get_messages() — paginated message history

Project Structure

src/matrix_hermes/
├── __init__.py    # Package init, re-exports all public API
├── auth.py        # Login, token, session persistence
├── client.py      # Async MatrixClient (mautrix wrapper)
├── config.py      # Env-based configuration
├── rooms.py       # Room management (create/join/list/moderate)
├── messaging.py   # Messaging (text/media/edit/react/typing)
├── sync.py        # Sync engine (poll, filter, dispatch, history)
└── cli.py         # CLI entry point (all commands)
tests/             # 182 unit tests

Dependencies

Python >= 3.10
mautrix >= 0.20.0
aiohttp >= 3.9
python-dotenv >= 1.0

Repository

https://gitea.ourpad.casa/shawn/matrix-hermes