Hermes Architecture Reference

Hermes Architecture Reference

Overview

Hermes Agent has several entry points that feed one agent loop, and each subsystem keeps its state in a known place: config and secrets in the Hermes home, sessions in a SQLite store, and profiles as isolated copies of that layout. This reference maps those pieces so you can find the right file or subsystem before you change anything. It is an offline orientation, not a substitute for the official docs or the upstream repository. Where they differ, the live docs and the upstream repository win.

Authoritative sources:

• Official docs: https://hermes-agent.nousresearch.com/docs/
• Source repository: https://github.com/NousResearch/hermes-agent

When to Use

• A Hermes issue spans more than one subsystem (gateway, provider, tools, sessions, cron, MCP, memory) and you need the right starting point.
• You are about to add a tool, a plugin, a memory provider, an MCP server or a gateway hook.
• You are changing provider routing, context compression, prompt caching or session storage.
• You are about to claim which config is active, or where a value comes from.

Features

• A symptom-to-subsystem lookup table for the agent loop and its internal subsystems.
• Layout of the Hermes home: config, secrets file, persona, memory files, session store, and per-profile copies.
• Subsystem pitfalls for tools, memory, sessions, cron, gateway keys and profile isolation.
• Config-change rules: use the CLI, validate model slugs, and confirm each change by reading it back.
• A procedure for keeping a local copy of this reference in line with upstream.

Benefits

• You start in the right module instead of grepping the whole tree.
• Common traps (frozen memory snapshots, cron prompts without history, hand-built session keys) are avoided.
• Config changes land in the file the active profile actually reads.
• Claims about behavior are checked against the official docs or the code before they are repeated.

Procedure

1. Establish the active install and config before you reason about anything:

   hermes --version
   hermes config path
   hermes config check
   git -C <hermes-clone> rev-parse HEAD

   The clone path differs between machines. Locate it first. Do not assume a default path.

2. Pick the subsystem from the symptom, then read only that area:

   Symptom area	Start here
   Gateway, messaging platforms, session keys	Gateway internals, then the platform adapter
   Provider, API mode, model routing	Provider runtime resolution
   Tool not offered, tool error, tool dispatch	Tool registry, toolsets, dispatch
   Session data, search, corruption	Session storage (SQLite with full-text index)
   Context too large, slow first turn	Context compression and prompt caching
   MCP server missing or failing	MCP integration: naming, filtering, OAuth, reloads
   Cron job not running or wrong output	Cron scheduler and job lifecycle
   Memory not recalled	Memory system and provider plugin lifecycle

3. Use the layout of the Hermes home. Resolve paths through the CLI, not by hand:

   Item	Purpose
   config.yaml	Non-secret configuration
   .env	Secrets such as API keys and tokens
   SOUL.md	Agent persona
   MEMORY.md, USER.md	Agent-maintained memory and user notes
   state.db	Session store and search index
   profiles/<profile>/	A profile's own copy of config, memory, skills

4. For a design or code change, check the dependency order and the extension contract before editing:

   • a custom tool follows the tool contract (returns a JSON string, declares an availability check);
   • a memory provider implements the provider interface and is the only external provider active at a time;
   • a plugin ships a manifest and registers through the plugin API;
   • an MCP server is configured in the profile's config and its tool names follow the documented pattern.

5. Make configuration changes through the official CLI. Read each change back before reporting it:

   hermes config set <key> <value>
   hermes config check

6. Verify any claim you are about to repeat against the docs or the repository. Note the commit or version you checked.

Keeping a local copy current

Use this when you maintain a local architecture note against upstream.

1. Record three revisions and keep them separate: the revision of the local install, the upstream main revision after a fetch, and the upstream revision that this note last reviewed. The changes to review are the commits between the last-reviewed revision and upstream main. The local install's revision does not set that range.
2. Group those commits by architecture area, not by commit. Spot-check each high-impact commit with git show --stat --format= <sha> before you quote it. Guard the call so that one missing commit does not stop the run: git show --stat --format= <sha> 2>/dev/null || echo "missing: <sha>".
3. Choose one action by the size of the change. A small set of changes gets an inline note in the main document. A medium set gets a dated changelog entry, and the main note stays as it is. A very large set, or a note that has not been reviewed for a long time, gets a full rewrite of the note.
4. Never make a partial edit to the main note. It looks current while it is not.
5. Check the note's frontmatter by parsing it as YAML, not with a regular expression. A multi-line header defeats most regular expressions.
6. Re-count the commits on each run. Do not copy a count from an earlier note.

Pitfalls

• Never hardcode the Hermes home path. Use the config-path command and the profile-aware helpers. A profile may use a different home than the default.
• Confirm which profile is active before you claim a value. Cross-profile writes break isolation.
• **Keep secrets in the .env file only.** Do not put a key in config.yaml, a skill, a prompt or a log.
• Tool handlers return a JSON string and do not raise. An exception breaks the turn instead of reporting the error to the model.
• A tool availability check that returns false removes the tool silently. Test availability before you assume a tool exists.
• Memory snapshots are frozen at session start. A mid-session write does not change the prompt the model already has. Start a new session to see it.
• Cron jobs have no conversation history. A cron prompt must be self-contained, with every fact it needs.
• A wildcard toolset does not enable every toolset. Name the toolset you need explicitly.
• Build gateway session keys with the provided builder. Never construct one by hand.
• Memory sync must not block the turn. Run it on a background thread.
• **Set model.default to a real model slug.** The literal word default makes a picker fall back to a stale label.
• Do not route routine chat through a multi-model council provider. It multiplies cost on every turn.
• Validate every provider model slug against the provider's live catalog before writing it into config or a routing table.
• A routing table row is not a runnable profile. Only a profile directory with its own config file is real.
• When cloning a profile for a worker, rewrite the inherited persona file. Otherwise the worker keeps the orchestrator's identity.
• If a file tool refuses to write a config file, do not route around the refusal with a script. Ask the operator to make the edit or approve it.
• Never report a config change as done without a read-back. Check the file or the CLI output after the change.

Verification

• hermes config check passes, and hermes config path names the file you edited.
• A claim you repeat cites the commit, version or doc page you checked.
• For a fix, the subsystem behaves as expected in a short test run, and the config read-back matches what you set.