Pattern 6: Hermes

Hermes Agent is the open-source agent framework from Nous Research. It exposes two pluggable extension points — MemoryProvider and ContextEngine — that together control what an agent remembers and what survives a context-window compression. The sonzai-hermes package ships both implementations as a paired drop-in: install once, and every Hermes turn flows through the Relationship Layer.

When to use this

• You're already running Hermes Agent (or your team has standardised on it).
• You want Hermes' existing chat loop, tool plugins, and orchestration to keep working — Sonzai only owns memory + context compression.
• You want Hermes' own loader to discover the plugins through its standard ABCs (no monkey-patching, no forks).

When to switch

• Not on Hermes — switch to Pattern 1: Managed Runtime (we run the chat), Pattern 3: OpenClaw (different framework), or Pattern 4: Standalone Realtime (you run the chat with one of our SDKs).
• No real-time chat at all — switch to Pattern 5: Standalone Batch.

One-shot install

pip install sonzai-hermes
sonzai-hermes install            # stages both plugins into Hermes' discovery paths
sonzai-hermes setup              # provisions a 14-day trial if no key, writes $HERMES_HOME/.env

sonzai-hermes install stages the Memory Provider into $HERMES_HOME/plugins/sonzai/ (Hermes' supported user path) and the Context Engine into the Hermes install tree's plugins/context_engine/sonzai/ (Hermes' loader only scans the bundled tree for engines today). It's idempotent and safe to re-run after pip install --upgrade hermes-agent.

Then in your Hermes profile (~/.hermes/config.yaml):

memory:
  provider: sonzai
context:
  engine: sonzai

Restart Hermes and the agent has persistent memory and Sonzai-driven context compression. Already have a Sonzai key? Set SONZAI_API_KEY before setup and the trial flow is skipped.

Architecture

Hermes Agent Runtime          sonzai-hermes plugins         Sonzai Relationship Layer
    |                                |                            |
    |-- start_session(user, agent) ->|  MemoryProvider            |
    |                                |-- resolve session -------->|
    |                                |<-- ranked memory ----------|
    |                                |                            |
    |-- on_turn(user_message) ----->|                            |
    |                                |-- recall + persist ------->|
    |                                |<-- structured memory ------|
    |                                |                            |
    |  [LLM call w/ memory context]  |                            |
    |                                |                            |
    |-- compact(ctx_window) -------->|  ContextEngine             |
    |                                |-- consolidation ---------->|
    |                                |<-- compressed window ------|
    |                                |   (not a naive summary)    |
    |                                |                            |
    |-- end_session(session_id) ---->|                            |
    |                                |-- extract facts, update    |
    |                                |   mood + personality ----->|

BYOK — bring your own LLM provider keys

If OPENAI_API_KEY, GEMINI_API_KEY (or GOOGLE_API_KEY), XAI_API_KEY, or OPENROUTER_API_KEY are set in your environment, both plugins automatically register them with the Sonzai platform on first startup.

Sonzai then routes LLM calls through your provider account, charging only the 25% service fee instead of the ~125% platform-key markup. The registration is idempotent; subsequent startups are no-ops if nothing changed.

Override per provider with SONZAI_BYOK_<PROVIDER>_KEY (takes precedence over the standard env var name). Set SONZAI_PROJECT_ID if your tenant has multiple projects and none is named Default.

CLI reference

Flags --hermes-home and --hermes-src override the auto-detected locations when Hermes lives somewhere non-standard.

Where to next