🐒 Ming's Note

← Back to Concepts

Hermes Agent Profiles & Multi-User Architecture

Overview

Hermes Agent supports two mechanisms for running multiple personas/contexts:

  1. Profiles — fully isolated HERMES_HOME directories (complete separation)
  2. Personality overlay — system prompt layer on top of SOUL.md (tone/style only)

Profile System (True Isolation)

Each profile is a separate Hermes home directory with its own: - config.yaml — independent settings, model, provider - SOUL.md — independent identity/persona - MEMORY.md — independent memory - USER.md — independent user profile - users/ — independent per-user directories - skills/ — independent skills - sessions/ — independent conversation history

Profile Commands

hermes profile create NAME --clone      # Copy config + SOUL + skills
hermes profile create NAME --clone-all  # Copy everything (memory + sessions)
hermes profile create NAME --clone-from SOURCE  # Clone from specific profile
hermes profile use NAME                 # Set as default
hermes --profile NAME chat              # One-off command with specific profile
hermes profile alias NAME               # Create wrapper command (e.g., hermes-samantha)
hermes profile list                     # Show all profiles
hermes profile show NAME                # Show profile details
hermes profile delete NAME              # Remove profile
hermes profile export NAME              # Backup to tar.gz
hermes profile import FILE              # Restore from archive

Profile Directory Structure

~/.hermes/profiles/NAME/
├── config.yaml     # Independent config
├── SOUL.md         # Independent identity
├── .env            # API keys (can be shared or separate)
├── memories/       # Independent memory
│   ├── MEMORY.md
│   ├── USER.md
│   └── users/
├── skills/         # Independent skills
└── sessions/       # Independent conversation history

Multi-Gateway Setup

Each profile can run its own gateway instance: - Different bot tokens (e.g., WhatsApp for personal, Telegram for work) - Different ports - Simultaneous operation - No interference between profiles

Personality Overlay (Tone/Style Only)

Defined in config.yaml under agent.personalities:

agent:
  personalities:
    professional:
      system_prompt: "You are a professional work assistant..."
      tone: "direct"
      style: "structured"
    casual:
      system_prompt: "You are a playful assistant..."
      tone: "casual"
      style: "humorous"

Activated via display.personality: NAME in config.

Limitations of Personality System

Per-User Memory (Within Single Profile)

Hermes supports per-user memory separation:

memories/
├── MEMORY.md              # Global memory (all contexts)
├── USER.md                # Global user profile
└── users/
    ├── henry/
    │   ├── USER.md        # Henry's personal info
    │   └── MEMORY.md     # Henry's personal notes
    ├── henna/
    │   ├── USER.md        # Henna's info
    │   └── MEMORY.md     # Henna's notes
    └── group/
        ├── USER.md        # Group chat info
        └── MEMORY.md     # Group chat rules

Each user directory is loaded based on who's talking (platform user ID).

Per-User Profile Routing (Feature Request)

GitHub issue #33548 proposes {PLATFORM}_USER_PROFILE_MAP environment variable: - Maps platform user IDs to Hermes profiles - Single bot serves different users with fully isolated profiles - Each user gets their own config, skills, memory, model, cronjobs - Not yet implemented (as of 2026-06-17)

Practical Patterns

Pattern 1: Two Profiles, Two Gateways (Recommended for True Separation)

Default profile (Ming):
  - WhatsApp gateway (personal)
  - Personal memory, users, skills
  - Casual tone

Work profile (Samantha):
  - Telegram gateway (work)
  - Work memory, users, skills
  - Professional tone

Pros: True isolation, no cross-contamination Cons: Double maintenance, two sets of config/memory/skills

Pattern 2: Single Profile, Work Mode (Simpler)

Default profile (Ming):
  - One gateway (all channels)
  - Shared memory and users
  - Work mode activated via keyword ("work mode")
  - Different focus/tone based on context

Pros: Simple, single maintenance Cons: No memory separation, work sees personal context

Pattern 3: Single Profile, Personality Overlay (Limited)

Default profile:
  - One gateway
  - `display.personality` switched manually
  - Tone/style changes, but memory/users stay same

Pros: Minimal setup Cons: Global switch, no per-channel automation, no real separation

Decision Matrix

Need Profile Personality Work Mode
Different identity ✅ ✅ ❌
Memory separation ✅ ❌ ❌
User separation ✅ ❌ ❌
Different tools ✅ ❌ ❌
Per-channel auto-switch ❌ ❌ ❌
Single maintenance ❌ ✅ ✅
Different gateway ✅ ❌ ❌

Key Insight

The choice depends on whether you need memory separation or just behavioral separation:

Related