# 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:**
```bash
# 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:

```bash
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`):**
```bash
# 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`):**
```bash
# 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:**
```bash
# 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:**
```bash
# 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`:
```ini
[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:
```bash
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:
```bash
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`:
```bash
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`:**
```yaml
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