feat(gateway): per-channel profile routing via channel_routes config

[andyg5000-agent]

Problem

A single Hermes gateway instance serves all connected chats/groups/channels with one model, one set of credentials, and one identity. There is no way to route different Signal groups, Telegram chats, or Discord channels to different profiles with their own models, SOUL.md, memories, and API keys.

Users working around this run multiple gateway instances (one per profile), which is fragile and wastes resources.

Solution

Add channel_routes config that maps chat IDs to Hermes profiles. When a message arrives from a routed chat, the gateway resolves the target profile and overrides:

• Model - from the profile's config.yaml (model.default or model.model)
• Provider / base_url - from the profile's config
• API key - from the profile's .env (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
• SOUL.md - replaces the global identity/persona
• Memories - USER.md + MEMORY.md from the profile replace global memories
• Context files - skipped (AGENTS.md, CLAUDE.md not loaded) to avoid leaking global context

Config Example

channel_routes:
  "group:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=":
    profile: profile_a
  "group:BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=":
    profile: profile_b
  "group:CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=":
    profile: profile_c
  "+10000000000":
    profile: profile_a

Architecture

New module gateway/channel_routing.py:

• resolve_channel_route() - matches chat_id to config, loads profile into ProfileContext dataclass
• build_routed_runtime_kwargs() - extracts api_key/base_url/provider for AIAgent construction
• build_routed_ephemeral_prompt() - combines SOUL.md + memories + platform context

Gateway integration (gateway/run.py):

1. Resolve route after session creation in inbound handler (non-fatal fallback)
2. Thread route_context through _run_agent() call chain (main path + goal continuation path)
3. Override model/runtime/ephemeral prompt when route matches
4. Set skip_context_files/skip_memory to prevent double-loading global context

Testing

14 tests covering:

• Empty/missing/no-match routes return None
• String and dict route formats
• SOUL.md and memory loading
• Custom provider with no-key fallback
• Runtime kwargs and ephemeral prompt construction
• Module import smoke tests

Documentation

New website/docs/user-guide/features/channel-routing.md with setup guide, chat ID formats per platform, troubleshooting, and config examples.

What This Does NOT Change

• Profiles without a route match continue using the default gateway profile (zero breaking change)
• Route resolution errors are logged at DEBUG level and silently fall back to default
• Skills still come from the gateway's installed skills (not the routed profile) - this keeps tool schemas consistent across channels

[andyg5000]

If you're looking for something to manage this without patching hermes, check out https://github.com/agents-blueoi/signal-mux. It allows you to have a single signal-cli running with multiple ports for hermes profiles to subscribe to for routing groups (signal) -> profiles (hermes)

[teknium1]

Thanks for the concrete routing proposal and tests. The use case remains distinct from current main: channel_overrides only covers model/provider/prompt (gateway/config.py:403-434), while multiplexing requires a separate adapter credential per profile (website/docs/user-guide/multi-profile-gateways.md:158-165).

Problems

• The PR creates the gateway session before route resolution at gateway/run.py:6331-6344 and never stamps source.profile. That leaves routed messages in the gateway profile’s session namespace, rather than the profile-scoped keying current main uses in gateway/session.py:1257-1322.
• gateway/channel_routing.py:183-193 manually recognizes only OpenRouter, Anthropic, and OpenAI keys. The routed runtime then bypasses current main’s profile secret scope (gateway/run.py:1413-1444), which is the fail-closed path for profile credentials.
• The gateway integration has substantially moved: the PR no longer applies cleanly to current gateway/run.py (git apply --check fails on its inbound-handler hunk).

Suggested changes

• Build chat-route resolution into the current multiplexing boundary before session creation, set SessionSource.profile, and use _profile_runtime_scope() for the whole routed turn.
• Add end-to-end coverage for session namespace, provider-secret isolation, memory/skills scope, and reply delivery for two channels sharing one adapter.

Automated hermes-sweeper review.

[teknium1]

Route resolution must occur before this session is created, and the resolved profile needs to be stamped on source. Otherwise the SessionStore derives the default gateway namespace and the routed turn cannot own profile-isolated session state.

[teknium1]

This hand-picked API-key list bypasses Hermes’s provider and credential-scope resolution, so routed profiles using OAuth, credential pools, or another supported provider will not receive their configured credentials. Route through the profile-scoped runtime/secret resolver instead.

[teknium1]

The capability this PR implements has now landed on main via PR #64835 (a salvage of #20096 by @Burgunthy, the earliest submission of this feature): gateway.profile_routes routes guilds/channels/threads to profiles at build_source() time, with full per-profile HERMES_HOME isolation (config, skills, memory, secrets, agent:<profile> session namespace) through the multiplex runtime scope.

Your channel_routes approach (per-chat model/credential/SOUL overlay via prompt injection) is covered as a strict subset — the merged feature supplies the profile's model, credentials, SOUL, memories, skills, and sessions through real HERMES_HOME scoping rather than system-prompt overlays, and the matcher additionally supports guild and thread specificity.

Docs: https://hermes-agent.nousresearch.com/docs/user-guide/multi-profile-gateways

Thank you for the work and for pushing on this use case — the demand from PRs like this one is what got the feature prioritized. Closing as superseded by the merged implementation.

[andyg5000]

Thanks @teknium1 !