ideas/matrix-multi-profile-integration.md

Matrix Integration with Multiple Hermes Profiles

Date: 2026-06-15 Author: Hermes Agent (via user request)

Overview

Hermes Agent supports multiple profiles — isolated environments with their own skills, memories, cron jobs, and configuration. Currently, the system has these profiles:

Profile	Purpose
default	Main agent (current Telegram/Matrix bot)
coder	TDD-focused development agent
academic_researcher	Research-oriented agent
locallama	Local LLM inference agent
on-docker	Docker-hosted agent
profile-architect	Architecture/planning agent

The goal is to give each profile its own Matrix bot account so you can talk to different "personalities" in different Matrix rooms or DMs.

---

Architecture Options

Option A: Multiple Matrix Bot Accounts (Recommended)

Each profile gets its own Matrix bot user (e.g., @hermes-coder:chiabur.xyz, @hermes-researcher:chiabur.xyz). Each runs as a separate gateway process with its own .env variables.

Pros:

• Complete isolation — each profile has its own skills, memory, and cron
• Clear separation in Matrix — different rooms for different bots
• No risk of cross-profile context contamination

Cons:

• Requires multiple Matrix bot accounts
• More resource usage (multiple gateway processes)

Option B: Single Bot with Profile Switching via Commands

One Matrix bot account handles all profiles. Use @session:[profile] commands to switch context.

Pros:

• Single Matrix account, simpler setup
• Lower resource usage

Cons:

• All profiles share the same active skills/memory
• @session only pulls past context — new memories still go to the active profile
• Confusing in shared rooms

Option C: Proxy Mode with Multiple Thin Gateways

Run one "main" gateway with the agent, and separate thin gateway instances (proxy mode) for each profile's Matrix bot. Each thin gateway forwards to the main agent with a different profile.

Pros:

• Single agent instance, multiple Matrix entry points
• Each profile gets its own Matrix bot
• Efficient resource usage

Cons:

• More complex setup
• Requires the API server to be enabled

---

Step-by-Step: Option A (Recommended)

Prerequisites

• Hermes Agent installed and running
• Access to a Matrix homeserver (currently: matrix.chiabur.xyz)
• Admin access to create new Matrix users

Step 1: Create Matrix Bot Accounts

For each profile you want to expose on Matrix, create a dedicated bot user on your homeserver.

Via Synapse admin API:

# Register a new user for the coder profile
curl -X POST https://matrix.chiabur.xyz/_synapse/admin/v2/users/@hermes-coder:chiabur.xyz \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "<strong_password>",
    "displayname": "Hermes Coder",
    "admin": false
  }'

Via Element:

1. Go to app.element.io
2. Create a new account for each bot (e.g., hermes-coder, hermes-researcher)
3. Log in and get the access token from Settings → Help & About → Advanced

Step 2: Get Access Tokens

For each bot account, get an access token:

curl -X POST https://matrix.chiabur.xyz/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@hermes-coder:chiabur.xyz",
    "password": "***"
  }'

Save the access_token from each response.

Step 3: Create Per-Profile Environment Files

Each profile needs its own Matrix configuration. Create a .env file for each profile.

For the coder profile (~/.hermes/profiles/coder/.env):

# Matrix Gateway — Coder Profile
MATRIX_HOMESERVER=https://matrix.chiabur.xyz
MATRIX_ACCESS_TOKEN=syt_...  # token for @hermes-coder:chiabur.xyz
MATRIX_ALLOWED_USERS=@doru:chiabur.xyz
MATRIX_REQUIRE_MENTION=false
MATRIX_E2EE_MODE=required
MATRIX_HOME_ROOM=!CinRAVDERPuYUJSjBz:chiabur.xyz

For the academic_researcher profile (~/.hermes/profiles/academic_researcher/.env):

# Matrix Gateway — Academic Researcher Profile
MATRIX_HOMESERVER=https://matrix.chiabur.xyz
MATRIX_ACCESS_TOKEN=syt_...  # token for @hermes-researcher:chiabur.xyz
MATRIX_ALLOWED_USERS=@doru:chiabur.xyz
MATRIX_REQUIRE_MENTION=false
MATRIX_E2EE_MODE=required
MATRIX_HOME_ROOM=!CinRAVDERPuYUJSjBz:chiabur.xyz

Step 4: Start Gateway Instances

Each profile's gateway must be started as a separate process, pointing to that profile's config.

Using the hermes CLI with profile flag:

# Start the coder profile's Matrix gateway
hermes gateway run --profile coder

# Start the academic_researcher profile's Matrix gateway
hermes gateway run --profile academic_researcher

Using environment variables:

# Start with explicit profile
HERMES_PROFILE=coder hermes gateway run

Using systemd (recommended for persistence):

Create a systemd service file for each profile.

/etc/systemd/system/hermes-gateway-coder.service:

[Unit]
Description=Hermes Agent Gateway — Coder Profile
After=network.target

[Service]
Type=simple
User=root
Environment=HERMES_PROFILE=coder
ExecStart=/root/.local/bin/hermes gateway run
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Then enable and start:

systemctl daemon-reload
systemctl enable hermes-gateway-coder
systemctl start hermes-gateway-coder

Repeat for each profile.

Step 5: Invite Bots to Rooms

1. In your Matrix client (Element), create rooms for each profile (e.g., #coder-bot, #research-bot)
2. Invite the corresponding bot user to each room
3. The bot auto-joins on invite
4. Set the home room for each bot using /sethome in the room

Step 6: Verify

Send a test message to each bot:

• DM @hermes-coder:chiabur.xyz → should respond with coder profile personality
• DM @hermes-researcher:chiabur.xyz → should respond with researcher profile personality

Check the logs:

tail -f ~/.hermes/profiles/coder/logs/agent.log
tail -f ~/.hermes/profiles/academic_researcher/logs/agent.log

---

Step-by-Step: Option C (Proxy Mode)

If you want a single agent instance with multiple Matrix entry points:

On the Main Host (Agent)

Enable the API server in ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0

For Each Profile (Thin Gateway Container)

Create a Docker container per profile that only runs the Matrix adapter and forwards to the main agent.

docker-compose-coder.yml:

services:
  hermes-matrix-coder:
    image: hermes-agent:latest
    environment:
      MATRIX_HOMESERVER: "https://matrix.chiabur.xyz"
      MATRIX_ACCESS_TOKEN: "syt_..."
      MATRIX_ALLOWED_USERS: "@doru:chiabur.xyz"
      MATRIX_ENCRYPTION: "true"
      MATRIX_DEVICE_ID: "HERMES_CODER"
      GATEWAY_PROXY_URL: "http://10.0.4.100:8642"
      GATEWAY_PROXY_KEY: "your-secret-key-here"
      HERMES_PROFILE: "coder"
    volumes:
      - ./matrix-store-coder:/root/.hermes/platforms/matrix/store

---

Current Setup Reference

Current Matrix configuration (default profile):

• Homeserver: matrix.chiabur.xyz
• Bot user: @hermes:chiabur.xyz
• Home room: !CinRAVDERPuYUJSjBz:chiabur.xyz
• E2EE: Required
• Allowed users: @doru:chiabur.xyz

Existing profiles:

~/.hermes/profiles/
├── academic_researcher/
├── coder/
├── locallama/
├── on-docker/
└── profile-architect/

---

Troubleshooting

Bot doesn't respond

• Check MATRIX_ALLOWED_USERS includes your Matrix user ID
• Verify the bot has joined the room
• Check gateway logs for errors

"Failed to authenticate"

• Verify the access token is valid
• Check the homeserver URL is correct

E2EE issues

• Ensure libolm is installed
• Set MATRIX_RECOVERY_KEY for cross-signing
• In Element, use /discardsession to force a new encryption session

Multiple gateways conflict

• Each gateway needs its own Matrix device ID (set via MATRIX_DEVICE_ID)
• Each gateway needs its own crypto store (automatic per profile)

---

Next Steps

1. Decide which profiles need Matrix bots
2. Create Matrix accounts for each
3. Set up .env files per profile
4. Start gateway instances (systemd recommended)
5. Invite bots to rooms and test