Add Matrix multi-profile integration guide
This commit is contained in:
root
parent
613fbda73b
commit
5b11af884d
295
matrix-multi-profile-integration.md
Normal file
295
matrix-multi-profile-integration.md
Normal file
@ -0,0 +1,295 @@
|
||||
# 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
|
||||
Loading…
Reference in New Issue
Block a user