Unofficial owners guideSource commit b5f15a6, November 2026
Owners
Workshop
Manual

Hermes Agent owners workshop manual

The open-source, self-improving AI agent from Nous Research. Identification, operation, specifications, strip-down, reassembly and fault-finding.

Handwritten: Property of notes in blue are mine. @jamesonedge

Line drawing of the agent: a central engine block connected by hoses to a terminal, a chat bubble, a clock, an editor window and a plug

Models covered

  • CLIInteractive terminal interface, started with hermes
  • Messaging gatewayLong-running process serving Telegram, Discord, Slack and other platforms
  • Cron schedulerScheduled agent tasks with delivery to any platform
  • Editor integration (ACP)Stdio server for VS Code, Zed and JetBrains
  • MCP clientConnects external Model Context Protocol tool servers
API modes
3
Compression trigger
0.50 of context
Terminal command timeout
180 s
Memory limit
2,200 chars
User profile limit
1,375 chars
Written and annotated by (@jamesonedge on X)Hermes Agent is made by Nous Research. This guide is unofficial.

Chapter 1: General information and identificationWhat the unit is, where it keeps its parts, and how settings are resolved

1.1What it is

Hermes Agent is an AI agent built by Nous Research and released under the MIT licence. It works with many model providers, keeps a persistent memory, creates and refines its own skills, searches its past sessions, and runs scheduled tasks.

One agent core, the AIAgent class, serves every entry point: the terminal interface, the messaging gateway, the editor adapter, batch runs and the API server. Platform differences live in the entry point, not in the agent.

Shell commands can run on any of the built-in terminal backends: local, docker, ssh, modal, daytona and vercel_sandbox. Plugins add more, such as Singularity/Apptainer.

1.2Identification

Identification plate

Make
Nous Research
Model
Hermes Agent
Licence
MIT
Command
hermes
Version
hermes --version
Home
~/.hermes/
Windows home
%LOCALAPPDATA%\hermes
Profiles
hermes -p <name>

Each profile gets its own HERMES_HOME, config, memory, sessions and gateway process, and several profiles can run at once.

Margin note: Nous Research also train the Hermes models. nousresearch.com

1.3What lives in the home directory

Contents of ~/.hermes/
ItemWhat it holdsWritten by
config.yamlAll non-secret settings: model, terminal, compression, memory limits, toolsets, MCP serversYou, or hermes config set
.envAPI keys, bot tokens and other secretsYou, or hermes config set for UPPER_SNAKE names
auth.jsonOAuth provider credentialsLogin flows
SOUL.mdThe agent's identity and tone; slot 1 of the system promptYou (a starter file is seeded if none exists)
memories/MEMORY.md (agent's notes) and USER.md (user profile)The agent, through the memory tool
skills/Bundled, hub-installed and agent-created skills, each with a SKILL.mdInstaller, Skills Hub, the agent
cron/Scheduled jobs (jobs.json) and run output (output/)hermes cron, the agent
state.dbSQLite session database with FTS5 full-text search and message historyThe agent core
sessions/Gateway sessionsThe gateway
logs/agent.log, errors.log, gateway.log, mcp-stderr.log and others; secrets are redactedAll processes
plugins/User plugins (tools, hooks, CLI commands)hermes plugins

1.4How a setting is resolved

  1. Command-line arguments, for example hermes chat --model <model>
  2. ~/.hermes/config.yaml
  3. ~/.hermes/.env (required for secrets)
  4. Built-in defaults
Warning

Keep API keys, bot tokens and passwords in .env, never in config.yaml. hermes config set routes any UPPER_SNAKE name to .env automatically.

Note

Memory and context files are read once, at session start. Edits to SOUL.md, AGENTS.md or memory made during a session take effect in the next session.

Chapter 2: Exploded viewFourteen principal components and where each lives in the source tree

Hover over or focus a number to highlight its part. Click or press Enter to pin it. The key works the same way. The drawing is schematic: it groups documented modules into parts and does not show real code structure or dependencies.

Exploded view of Hermes AgentLine drawing of fourteen numbered components: four entry points at the top, the agent core with three sub-assemblies, the approval plate, tool backends and the storage parts at the bottom. Use the numbered callouts or the key to identify each part.5610789111234121413
Fig. 2.1 Hermes Agent, exploded. Entry points (1 to 4) feed the agent core (5) and its sub-assemblies (6 to 8); tool calls pass the approval guard (9) to the backends (10, 11); state is kept in parts 12 to 14.

Margin note: No. 9 is the safety valve. Learn more: trust: untrusted for any MCP server I don't control.

Chapter 3: Principles of operationThe turn cycle, how a tool call runs, and the three API modes

3.1Entry points

Every entry point ends in a call to AIAgent.run_conversation(). What differs is what comes before and after it:

3.2The turn cycle

Turn-cycle flow diagram A user message is appended to history, the system prompt is built or reused, compression runs if the conversation is over half the context window, API messages are built for the active API mode, ephemeral layers and cache markers are added, and an interruptible API call is made. If the response contains tool calls, the tools run, their results are appended, and the cycle returns to building API messages. If not, the session is saved, memory is flushed and the reply is returned. User message arrives Append to conversation history Build or reuse system prompt Over 50% of context window?Preflight compression runs first Build API messages for the mode Add ephemeral prompt layersCache markers on Anthropic Interruptible API call Tool calls? Run tools, append results Save session, flush memory,return the reply Yes Loop back No
Fig. 3.1 One turn of the agent loop. The loop repeats from "Build API messages" for as long as the model returns tool calls.

Messages are held in OpenAI-style format (role, content, tool_calls) whichever API mode is in use. The loop enforces strict alternation: never two assistant or two user messages in a row; only tool results may follow one another.

The API call runs in a background thread while the main thread waits for the response, an interrupt or a timeout. If you send a new message, use /stop or signal the process, the response is discarded and nothing partial enters the history.

Compression

Preflight compression runs when the conversation exceeds 50% of the model's context window. The gateway also compresses between turns at 85%. Memory is flushed to disk first, the middle turns are summarised, the most recent messages are kept intact (compression.protect_last_n, default 20), and tool call and result pairs are never split.

Failure and fallback

On a 429, a 5xx or a 401/403, the agent works through the fallback_providers list in order, refreshing credentials first on 401/403. Retries per provider before fallback are set by agent.api_max_retries (default 3).

Margin note: Why two thresholds? Learn more: compression & caching doc

3.3How a tool call runs

A single tool call runs in the main thread. Several run concurrently in a thread pool, except interactive tools such as clarify, which force sequential execution. Results are put back in the original order. For each call:

  1. 1

    Resolve the handler

    Look up the tool in tools/registry.py.

  2. 2

    Pre-call hook

    Fire the pre_tool_call plugin hook.

  3. 3

    Danger check

    tools/approval.py checks for a dangerous command. If found, the approval callback asks the user and waits.

  4. 4

    Execute

    Run the handler with its arguments and the task ID.

  5. 5

    Post-call hook

    Fire the post_tool_call plugin hook.

  6. 6

    Append the result

    Add a tool message with the result to the history.

Note

Four agent-level tools are intercepted before dispatch because they change agent state directly: todo, memory, session_search and delegate_task.

3.4API modes

API modeUsed forClient
chat_completionsOpenAI-compatible endpoints: OpenRouter, custom endpoints and most providersopenai.OpenAI
codex_responsesOpenAI Codex and the Responses APIopenai.OpenAI in Responses format
anthropic_messagesThe native Anthropic Messages APIanthropic.Anthropic via an adapter

The mode is chosen in this order: an explicit api_mode argument; provider-specific detection (the anthropic provider selects anthropic_messages); base URL heuristics (api.anthropic.com selects anthropic_messages); otherwise chat_completions.

Chapter 4: SpecificationsSettings and defaults in config.yaml, with the tools needed to read and change them

Defaults are as documented. Where the configuration guide and the example file cli-config.yaml.example both give a value, they agree. Keys whose documented defaults conflict are listed in 4.3 and left out of the table.

4.1Settings and defaults

KeyDefaultUnitNotesSource
Model and provider
model.provider"auto"n/aAuto-detects from available credentialsExample config
agent.api_max_retries3retriesPer provider, before fallback engages; 0 fails over at onceConfig guide
agent.auto_recovery_cycles5cyclesWait-and-retry after retries and fallback are spent on an outage; 0 disablesConfig guide
Terminal
terminal.backendlocaln/alocal, docker, ssh, modal, daytona, vercel_sandbox or a plugin backendConfig guide, example config
terminal.cwd"."pathUsed by gateway and cron; the CLI always uses its launch directoryConfig guide, example config
terminal.timeout180sPer commandConfig guide, example config
Context compression
compression.enabledtruen/aAutomatic compression on or offConfig guide, example config
compression.threshold0.50ratioFraction of the context limit; the example file notes a 0.75 floor for windows under 512KConfig guide, example config
compression.target_ratio0.20ratioFraction of the threshold kept as recent tailConfig guide, example config
compression.protect_last_n20messagesMinimum recent messages kept uncompressedConfig guide, example config, agent loop
Memory and skills
memory.memory_enabledtruen/aAgent's notes, MEMORY.mdConfig guide, example config
memory.user_profile_enabledtruen/aUser profile, USER.mdConfig guide, example config
memory.memory_char_limit2,200charsAbout 800 tokens tiny! keep entries tightConfig guide, example config
memory.user_char_limit1,375charsAbout 500 tokensConfig guide, example config
memory.write_approvalfalsen/atrue requires approval before any memory writeConfig guide, memory guide
memory.nudge_interval10user turnsReminder to consider saving memories; 0 disablesExample config
skills.write_approvalfalsen/atrue stages every agent skill write for reviewConfig guide
skills.guard_agent_createdfalsen/aContent scanner for agent skill writesConfig guide
Reads, output and runtime
file_read_max_chars100,000charsLargest single read_file resultConfig guide
tool_output.max_bytes50,000charsTerminal output cap; keeps first 40% and last 60%Config guide
tool_output.max_lines2,000linesCap on one read_file call's limitConfig guide
context_file_read_timeout5.0sSlow context files are skipped with a warningConfig guide
runtime.nofile_soft_limit4,096filesOpen-file soft limit for long-running serversConfig guide, example config
sessions.retention_days90daysUsed when sessions.auto_prune is on (off by default)Sessions guide, config guide
MCP servers and cron
mcp_servers.<name>.enabledtruen/afalse skips the server but keeps its configMCP config reference
mcp_servers.<name>.connect_timeout60sAlso bounds the initialize handshakeMCP config reference
mcp_servers.<name>.ssl_verifytruen/aOr a path to a CA bundle; false is insecureMCP config reference
cron.catch_up_missedtruen/afalse skips past-grace recurring misses after downtimeExample config

4.2Tools required

CLI commands used in this manual

  • hermes setup: full setup wizard
  • hermes model: choose provider and model
  • hermes tools: enable or disable tools per platform; --summary prints them
  • hermes config: view; get, set, unset, edit, check, migrate
  • hermes status: one-screen summary; --full for every section
  • hermes doctor: diagnostics; --fix attempts repairs
  • hermes logs: view or follow logs; -f, --since, --level
  • hermes gateway: setup, install, start, stop, status, run
  • hermes mcp: list, add, install, test, configure, login, remove
  • hermes cron: list, status, pause, resume, run, doctor
  • hermes backup and hermes import: archive and restore the home directory
  • hermes update: update; --check looks without applying
  • hermes sessions: list, export, prune
  • hermes acp: start the editor integration server
  • /reload-mcp: in-session MCP reload

4.3Values withheld

The public sources disagree on these, so no value is given:

  • (flagged to review) agent.max_turns: the agent loop page and the example config say 500; the configuration guide says unlimited by default (and mentions 500 elsewhere on the same page).
  • (flagged to review) delegation.max_iterations: the agent loop page says 50; the example config and the delegation guide say 250.
  • mcp_servers.<name>.timeout: the MCP config reference shows 120 in its example and 300 in its key table.
  • Number of built-in tools: 40+ (README), 60+ (docs home), 70+ (architecture page).
  • Number of messaging platforms: 20+ (docs home), 25+ adapters (architecture page).
  • Number of terminal backends: the architecture diagram says 7; its own text and the other pages say 6 built-in plus plugins. This manual names the backends without counting them.

Chapter 5: Strip-downTaking an installation out of service in a safe order

Use this sequence before moving an installation, replacing components or rebuilding a profile. The order (backup, record, gateway, tools, MCP servers) is this manual's advice; each command is documented.

Warning

Do not start until step S1 has finished with exit status 0. A partial archive exits 1 and reports Backup incomplete; another backup already running exits 2.

  1. S1

    Back up first

    hermes backup
    # or a fast state-only snapshot:
    hermes backup --quick --label "pre-strip"

    A full backup zips configuration, skills, sessions and data to ~/hermes-backup-<timestamp>.zip. It is safe to run while Hermes is running.

    Margin note: always. no exceptions.

  2. S2

    Record the current state

    hermes status --full
    hermes tools --summary
    hermes mcp list
    hermes cron list

    Keep the output. Key values are redacted. You will compare against it during reassembly.

  3. S3

    Pause scheduled jobs

    hermes cron pause <job>

    Optional. Pausing keeps the job without deleting it. A recurring slot that falls due while paused gets one catch-up run or a logged skip after resume.

  4. S4

    Stop the gateway

    hermes gateway stop
    hermes gateway status

    If chat turns, cron jobs or delegations are running, the command lists them and asks before interrupting. Add --all to stop every profile's gateway.

  5. S5

    Remove the service

    hermes gateway uninstall

    Only when decommissioning. Removes the systemd or launchd service that hermes gateway install created.

  6. S6

    Disconnect tools

    hermes tools
    # or, everywhere at once, in config.yaml:
    agent:
      disabled_toolsets:
        - web

    hermes tools opens the per-platform tool UI. agent.disabled_toolsets removes a toolset on every platform, after per-platform settings.

  7. S7

    Disconnect MCP servers

    mcp_servers:
      <name>:
        enabled: false
    # or remove it entirely:
    hermes mcp remove <name>

    enabled: false stops connection, discovery and tool registration but keeps the entry for later. In a running session, apply with /reload-mcp.

Caution

Backups exclude browser profiles, SQLite -wal/-shm sidecars, regenerable caches and the hermes-agent code itself. Keep your own copy of anything you placed in those locations.

Chapter 6: ReassemblyRefitting components, then diagnostics and a road test

Reverse the strip-down. Compare each stage with the record from step S2.

Warning

Stop the gateway before running hermes import, to avoid conflicts with running processes.

  1. R1

    Restore, if required

    hermes import <zipfile>

    Every file in the archive overwrites its counterpart in the home directory. A damaged archive is detected before anything is written and exits 1.

  2. R2

    Check the configuration

    hermes config check
    hermes config migrate

    check finds missing options and stale saved selections; migrate adds missing options interactively.

  3. R3

    Refit the model

    hermes model

    Choose provider and model. Secrets go to .env.

  4. R4

    Refit tools

    hermes tools
    hermes tools --summary

    Re-enable toolsets and remove any temporary agent.disabled_toolsets entries.

  5. R5

    Refit MCP servers

    hermes mcp add <name> --url <URL>
    hermes mcp test <name>
    hermes mcp configure <name>

    Or set enabled: true again. For OAuth servers run hermes mcp login <name> from a fresh terminal.

  6. R6

    Refit the gateway

    hermes gateway setup
    hermes gateway install
    hermes gateway start
    hermes gateway status

    On WSL, Docker or Termux, use hermes gateway run in the foreground instead of the service.

  7. R7

    Resume cron

    hermes cron resume <job>
    hermes cron status
    hermes cron doctor

    status confirms the scheduler is running. doctor is read-only and exits non-zero when it finds problems.

  8. R8

    Diagnostics

    hermes doctor
    hermes logs errors --since 30m

    hermes doctor exits 0 when nothing is unresolved and 1 otherwise. --fix attempts automatic repairs.

  9. R9

    Road test

    hermes -z "List the files in the current directory"
    hermes cron run <job>

    hermes -z prints only the final reply, so a tool-using answer proves model, tools and terminal together. Then send the gateway a message from your platform, and trigger a cron job on the next tick.

    Margin note: best bit. try it from Telegram too.

Chapter 7: Fault-findingSymptom, probable cause and remedy

Rows tagged Documented restate behaviour described in the sources. Rows tagged Advice are this manual's general suggestions and are not documented behaviour.

SymptomProbable causeRemedyBasis
Agent saved a fact but acts as if it does not know itMemory is injected as a frozen snapshot at session startStart a new session. For long gateway chats, hermes sessions refresh-promptsDocumented
Edits to SOUL.md or AGENTS.md have no effectContext files are assembled at session startRestart the sessionDocumented
hermes gateway start fails or the gateway keeps disconnecting on WSLsystemd support on WSL is unreliableUse hermes gateway run, for example inside tmuxDocumented
MCP server's tools do not appearServer has enabled: false, or tools.include / exclude filters themhermes mcp list, hermes mcp configure <name>, then /reload-mcp. Filters use the original tool nameDocumented
(flagged to review) MCP login seems to work, but every tool call times outProvider rejects dynamic client registration (for example Google Drive, Atlassian)Create your own OAuth client in the provider's console, add it to the server config, run hermes mcp login <name>Documented
(flagged to review) OAuth for a new MCP server fails when added from inside a sessionIn-session auto-reload allows only 30 sRun hermes mcp login <name> from a fresh terminal; it waits 5 minutesDocumented
An MCP server stops working in the background with a warning in gateway.logIts refresh token expired; background processes never open a browserRe-authorise once with hermes mcp login <name>Documented
Slow failover when the main provider is flakyRetries on the primary come first (agent.api_max_retries, default 3)Configure fallback_providers; set agent.api_max_retries: 0 to fail over on the first transient errorDocumented
read_file refuses a large fileResult would exceed file_read_max_chars (100,000)Read a range with offset and limit, or raise the limit on large-context modelsDocumented
Terminal output shows [OUTPUT TRUNCATED]Output exceeded tool_output.max_bytes (50,000)Raise the limit, or narrow the command's outputDocumented
Antivirus quarantines uv.exe on WindowsFalse positive on the bundled Python package managerVerify the file as the README describes, then exclude the folder, not the file hashDocumented
hermes doctor exits 1At least one problem is unresolvedRead the report; try hermes doctor --fixDocumented
Bot does not answer on a messaging platformGateway not running, the platform not set up, or the user not authorisedhermes gateway status, hermes status, hermes logs gateway; rerun hermes gateway setupAdvice
Scheduled job did not runScheduler not running, job paused, or a delivery failurehermes cron status, hermes cron list, hermes cron doctor; check ~/.hermes/cron/output/Advice
Replies slow down or get worse in a very long sessionContext pressure; frequent compressionCheck with /usage; start fresh with /new; run /compress deliberatelyAdvice

Margin note: = read these twice before I connect Google Drive or Atlassian over MCP.

Chapter 8: Routine maintenanceA suggested service schedule

Caution

The intervals below are this manual's advice. Nous Research does not publish a service schedule. The commands and their behaviour are documented.

IntervalTaskCommand
DailyScan for new warnings and errorshermes logs errors --since 1d
WeeklyFull backup. By default older full backups beyond the newest 3 are deleted calendar reminder, Fridayshermes backup
WeeklyHealth checks for the install and the cron fleethermes doctor, hermes cron doctor
MonthlyCheck for and apply updates. A quick state snapshot is taken first by default, and running gateways are restartedhermes update --check, then hermes update
MonthlyCheck hub skills for upstream changeshermes skills check
MonthlyReview connected MCP servers and remove unused ones. Catalog MCPs are never auto-updatedhermes mcp list, hermes mcp install <name> to refresh
QuarterlyPreview and prune old sessions (default filter: older than 90 days)hermes sessions prune --dry-run
QuarterlyCheck configuration for missing options; review memory files, which have fixed character limitshermes config check
After every updateConfirm gateways run the new codehermes gateway status
Note

Rotate API keys in .env on your organisation's normal schedule (advice). If a key may have been exposed, revoke it at the provider immediately.

My notes

Hermes Agent, read cover to cover. Things to chase up:

Learn more about

  • ACP: try it in Zed / VS Code
  • how it writes its own SKILL.md files
  • subagents + iteration budgets
  • Honcho user modelling
  • MCP trust tiers + spend limits

Review

  • max_turns: 500 or unlimited?
  • delegation budget: 50 or 250?
  • 6 or 7 terminal backends? 6 built-in + plugins
  • run R9 road test after every update

James Taylor

more teardowns like this on X:

Hermes Agent is by Nous Research, go and look.

SourcesPublic sources only, retrieved 11 November 2026. Repository at commit b5f15a6 on main

Repository: github.com/NousResearch/hermes-agent

  1. README.md: overview, install, getting-started commands, Windows notes
  2. cli-config.yaml.example: example configuration and inline defaults
  3. website/docs/: source of the documentation site below (the repository has no top-level docs/ directory)

Documentation: hermes-agent.nousresearch.com/docs

  1. Docs home
  2. Architecture
  3. Agent loop internals
  4. Cron internals
  5. Configuration
  6. Which file does what
  7. Sessions
  8. Memory
  9. Skills system
  10. Cron scheduling
  11. MCP
  12. Delegation
  13. ACP editor integration
  14. CLI commands reference
  15. MCP config reference

Pages 4 and 5 were read on the live site; the rest were read from their source files in website/docs/ at the commit above. The two live pages matched their source files. The visual style references the general look of classic car workshop manuals; no text, artwork or marks were taken from any publisher.

Unofficial

This is an unofficial guide, independently written and annotated by . It is not affiliated with, produced by or endorsed by Haynes or Nous Research. The handwritten notes are personal opinions and study notes, not documentation. Hermes Agent is developed by Nous Research. Check the official documentation before relying on any value here.