The Design Philosophy: Local, Owned, Multi-Surface

+15 Mana ✨
Hermes Architecture Overview(DOCUMENTATION)

Introduction

Behind every developer tool is a set of opinions. Hermes Agent makes three explicit ones: code and state should stay local, the user should own their stack, and a single agent should reach the user wherever they are. These three pillars explain almost every design decision in the product, from the bundled Python runtime to the SQLite session store to the 20+ messaging gateways.

Key Concepts

  • Local-first: All persistent state, sessions, memory, skills, configuration, lives in your home directory and survives the loss of any vendor.
  • Owned: You bring the model credentials, you choose the provider, you control the data. There is no Nous-hosted backend that mediates your conversations.
  • Multi-surface: The same agent runs in your terminal, in messaging platforms, in your IDE, and as an HTTP server. Surface choice is a workflow decision, not a product decision.

Real World Context

Consider what it costs when a vendor pivots. A team that relied on a closed AI tool that gets discontinued, repriced, or bought loses everything: the conversations, the memory, the muscle memory. A team running Hermes loses nothing, the binary still works, the sessions are still in state.db, the credentials are still local, and a different model provider is one config change away. This is the value of the local-first contract.

Deep Dive

Local-first

When you install Hermes, the runtime drops into ~/.hermes/hermes-agent/ and the persistent data lands in ~/.hermes/. Every session message, every memory entry, every skill definition is on your disk in a format you can inspect, copy, or migrate. There is no cloud account to register, no telemetry endpoint to opt out of, and no mandatory sync.

text
~/.hermes/
├── hermes-agent/      # the installed code
├── state.db           # SQLite session + memory store
├── config/            # provider settings, fallback chains
└── skills/            # custom skill definitions

Owned

Hermes never holds your credentials in its own infrastructure. When you run hermes auth add openrouter, the key is encrypted on your disk. When Hermes calls a model, it calls the provider you chose with the key you configured. Switching providers means editing a config file, there is no tier of access that Nous can revoke.

Multi-surface

The clearest demonstration of the multi-surface principle is how the same code path drives radically different experiences:

text
hermes                   → Interactive TUI session in your terminal
hermes -z "summarize..." → One-shot scripted call (stdout only)
hermes gateway start     → Bot listening on configured chat platforms
hermes acp               → ACP server for IDE integration

Each surface is a thin adapter on the same agent loop. The session store, the memory, and the skills follow you across them.

Common Pitfalls

  1. Reading local-first as offline-only, Hermes runs locally but normally calls cloud model APIs over the internet. Local-first means your state is local, not that the whole stack runs without a network.
  2. Assuming owned means free, You still pay for whichever model provider you use. Ownership is about control and portability, not pricing.

Best Practices

  1. Pick your provider strategy before your surface, Decide cloud vs local model first, then pick how you will talk to the agent.
  2. Treat surface choice as a workflow decision, TUI for deep work, gateways for ambient access, the API server when other code needs to call the agent.

Summary

  • Three design pillars explain Hermes: local-first state, owned stack, multi-surface reach.
  • Local-first means your sessions, memory, and config survive any vendor change.
  • Owned means you bring the model and credentials; Nous never sits between you and the provider.
  • Multi-surface means one install drives terminal, chat, IDE, and API workflows.

Code Examples

bash
# Everything important about your Hermes lives here
ls ~/.hermes/
# hermes-agent/   ← installed code (replaceable)
# state.db        ← sessions and memory (yours)
# config/         ← provider + fallback config
# credentials/    ← encrypted API keys
# skills/         ← custom skill definitions
✓ Completed