2 · Identity and Session Routing

This chapter covers two related but distinct things: which “agent identity” a message belongs to, and which “conversation” it belongs to.

2.1 Profiles: One Process, Many Identities

In Hermes, a “Profile” is a complete agent identity. The first sentence of the docs defines it clearly:

A Profile owns its own:

2.2 Four-Level Routing and the “Specificity” Score

Routing rules live in the config file:

gateway:
  profile_routes:
    - name: server-default          # rule name
      platform: discord
      guild_id: "SERVER_ID"
      profile: server-profile       # which identity to route to

    - name: special-channel
      platform: discord
      guild_id: "SERVER_ID"
      chat_id: "CHANNEL_ID"
      profile: channel-profile

    - name: thread-route
      platform: discord
      chat_id: "CHANNEL_ID"
      thread_id: "THREAD_ID"
      profile: thread-profile

The specificity score

@dataclass(frozen=True)
class ProfileRoute:
    name: str
    platform: str
    profile: str
    guild_id:  Optional[str] = None      # server
    chat_id:   Optional[str] = None      # channel
    thread_id: Optional[str] = None      # thread
    enabled: bool = True

    @property
    def specificity(self) -> int:
        """Higher value = more specific match."""
        s = 0
        if self.guild_id:  s += 2        # server   weight 2
        if self.chat_id:   s += 4        # channel  weight 4
        if self.thread_id: s += 8        # thread   weight 8
        return s

hermes-agent/gateway/profile_routing.py

The score uses binary bit weights (2, 4, 8), so the four priority levels line up exactly with the table in the docs:

(Strictly speaking the score is only a sort key; the actual priority 14 > 6 > 2 falls out naturally from the bit weights. The advantage of 2/4/8 over 1/2/3 is that no combination produces a duplicate score, so the ordering is always deterministic.)

Matching is conjunctive

def matches(self, platform, guild_id=None, chat_id=None,
            thread_id=None, parent_chat_id=None) -> bool:
    if not self.enabled:                                       return False
    if self.platform != platform:                              return False
    if self.thread_id and self.thread_id != thread_id:         return False
    if self.chat_id and self.chat_id != chat_id \
                    and self.chat_id != parent_chat_id:        return False    # ★
    if self.guild_id and self.guild_id != guild_id:            return False
    return True

The docs spell out the semantics:

Parent-chain matching: Discord forums and threads

That parent_chat_id branch handles a hierarchy specific to Discord:

2.3 When an Explicit Route Is Rejected

class ProfileRouteRejected(RuntimeError):
    """An explicit route matched a profile this gateway does not serve."""

In other words: an explicit route matched an identity that “this gateway doesn't serve.”

The scenario: you can run several gateway processes, each serving only a subset of identities (for resource isolation, say). A message may then match an identity that “isn't mine” — that's not a misconfiguration; the message just belongs to a different gateway.

Using a dedicated exception type rather than “silently fall back to the default identity” is the right call — a silent fallback would let the wrong identity handle the message, and the user would have a hard time noticing.

2.4 SOUL.md: The Persona File

Each identity has a SOUL.md. Its relationship to the system prompt looks like this:

This layering is the same kind of thing as CLAUDE.md in Claude Code, with one important difference: Hermes splits “persona,” “memory,” and “understanding of the user” into three separate files.

2.5 Session Routing: Continuity Across Platforms

Identity routing decides “which persona to use”; session routing decides “which conversation to continue.”

This is one of the gateway's most valuable capabilities: you can be halfway through a conversation on Slack at your desk, walk out the door, switch to Telegram on your phone, and pick up right where you left off, with the conversation context fully intact.

How it does that

The related modules:

gateway/channel_directory.py    channel directory
gateway/pairing.py              ★ pairing (links accounts on different platforms to the same user)
gateway/mirror.py               mirroring
gateway/profile_routing.py      identity routing

pairing.py is the foundation of this mechanism: the system needs to know that “@alice on Slack” and “alice_w on Telegram” are the same person. The link is usually established with something like a one-time verification code.

2.6 Caching Agent Instances

The gateway caches AIAgent instances, reusing the same one for the same session. That has two consequences:

The upside: state carries over naturally

Message history, the context engine's bookkeeping, and compaction counters all live in the instance; nothing has to be rebuilt from disk every time.

The cost: the risk of state leaking across turns

The top of the main loop has a block of code dedicated to this, and the comment says it plainly:

There is another block that handles hot config reloads: