diff --git a/matrix-multi-profile-integration.md b/matrix-multi-profile-integration.md
new file mode 100644
index 0000000..c3e704a
--- /dev/null
+++ b/matrix-multi-profile-integration.md
@@ -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
\ No newline at end of file