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
| Item | What it holds | Written by |
|---|---|---|
config. | All non-secret settings: model, terminal, compression, memory limits, toolsets, MCP servers | You, or hermes config set |
. | API keys, bot tokens and other secrets | You, or hermes config set for UPPER_ names |
auth. | OAuth provider credentials | Login flows |
SOUL. | The agent's identity and tone; slot 1 of the system prompt | You (a starter file is seeded if none exists) |
memories/ | MEMORY. (agent's notes) and USER. (user profile) | The agent, through the memory tool |
skills/ | Bundled, hub-installed and agent-created skills, each with a SKILL. | Installer, Skills Hub, the agent |
cron/ | Scheduled jobs (jobs.) and run output (output/) | hermes cron, the agent |
state. | SQLite session database with FTS5 full-text search and message history | The agent core |
sessions/ | Gateway sessions | The gateway |
logs/ | agent., errors., gateway., mcp-stderr. and others; secrets are redacted | All processes |
plugins/ | User plugins (tools, hooks, CLI commands) | hermes plugins |
1.4How a setting is resolved
- Command-line arguments, for example
hermes chat --model <model> ~/.hermes/config.yaml~/.hermes/.env(required for secrets)- Built-in defaults
Keep API keys, bot tokens and passwords in .env, never in config.yaml. hermes config set routes any UPPER_SNAKE name to .env automatically.
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.
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:
- CLI: user input goes to
HermesCLI.process_input(); the final response is displayed and saved to the session database. - Gateway: a platform event becomes a
MessageEvent; the gateway authorises the user, resolves the session key, creates an agent with that session's history, and delivers the reply back through the adapter. - Cron: on each scheduler tick, due jobs are loaded from
jobs.json; each runs in a fresh agent with no history and any attached skills injected as context; the response goes to the target platform and the job's next run is updated.
3.2The turn cycle
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
Resolve the handler
Look up the tool in
tools/registry.py. - 2
Pre-call hook
Fire the
pre_tool_callplugin hook. - 3
Danger check
tools/approval.pychecks for a dangerous command. If found, the approval callback asks the user and waits. - 4
Execute
Run the handler with its arguments and the task ID.
- 5
Post-call hook
Fire the
post_tool_callplugin hook. - 6
Append the result
Add a
toolmessage with the result to the history.
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 mode | Used for | Client |
|---|---|---|
chat_ | OpenAI-compatible endpoints: OpenRouter, custom endpoints and most providers | openai. |
codex_ | OpenAI Codex and the Responses API | openai. in Responses format |
anthropic_ | The native Anthropic Messages API | 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
| Key | Default | Unit | Notes | Source |
|---|---|---|---|---|
| Model and provider | ||||
model. | "auto" | n/a | Auto-detects from available credentials | Example config |
agent. | 3 | retries | Per provider, before fallback engages; 0 fails over at once | Config guide |
agent. | 5 | cycles | Wait-and-retry after retries and fallback are spent on an outage; 0 disables | Config guide |
| Terminal | ||||
terminal. | local | n/a | local, docker, ssh, modal, daytona, vercel_ or a plugin backend | Config guide, example config |
terminal. | "." | path | Used by gateway and cron; the CLI always uses its launch directory | Config guide, example config |
terminal. | 180 | s | Per command | Config guide, example config |
| Context compression | ||||
compression. | true | n/a | Automatic compression on or off | Config guide, example config |
compression. | 0.50 | ratio | Fraction of the context limit; the example file notes a 0.75 floor for windows under 512K | Config guide, example config |
compression. | 0.20 | ratio | Fraction of the threshold kept as recent tail | Config guide, example config |
compression. | 20 | messages | Minimum recent messages kept uncompressed | Config guide, example config, agent loop |
| Memory and skills | ||||
memory. | true | n/a | Agent's notes, MEMORY. | Config guide, example config |
memory. | true | n/a | User profile, USER. | Config guide, example config |
memory. | 2,200 | chars | About 800 tokens tiny! keep entries tight | Config guide, example config |
memory. | 1,375 | chars | About 500 tokens | Config guide, example config |
memory. | false | n/a | true requires approval before any memory write | Config guide, memory guide |
memory. | 10 | user turns | Reminder to consider saving memories; 0 disables | Example config |
skills. | false | n/a | true stages every agent skill write for review | Config guide |
skills. | false | n/a | Content scanner for agent skill writes | Config guide |
| Reads, output and runtime | ||||
file_ | 100,000 | chars | Largest single read_ result | Config guide |
tool_ | 50,000 | chars | Terminal output cap; keeps first 40% and last 60% | Config guide |
tool_ | 2,000 | lines | Cap on one read_ call's limit | Config guide |
context_ | 5.0 | s | Slow context files are skipped with a warning | Config guide |
runtime. | 4,096 | files | Open-file soft limit for long-running servers | Config guide, example config |
sessions. | 90 | days | Used when sessions. is on (off by default) | Sessions guide, config guide |
| MCP servers and cron | ||||
mcp_ | true | n/a | false skips the server but keeps its config | MCP config reference |
mcp_ | 60 | s | Also bounds the initialize handshake | MCP config reference |
mcp_ | true | n/a | Or a path to a CA bundle; false is insecure | MCP config reference |
cron. | true | n/a | false skips past-grace recurring misses after downtime | Example config |
4.2Tools required
CLI commands used in this manual
hermes setup: full setup wizardhermes model: choose provider and modelhermes tools: enable or disable tools per platform;--summaryprints themhermes config: view;get,set,unset,edit,check,migratehermes status: one-screen summary;--fullfor every sectionhermes doctor: diagnostics;--fixattempts repairshermes logs: view or follow logs;-f,--since,--levelhermes gateway:setup,install,start,stop,status,runhermes mcp:list,add,install,test,configure,login,removehermes cron:list,status,pause,resume,run,doctorhermes backupandhermes import: archive and restore the home directoryhermes update: update;--checklooks without applyinghermes sessions:list,export,prunehermes 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.
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.
- 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.
- 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.
- 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.
- 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
--allto stop every profile's gateway. - S5
Remove the service
hermes gateway uninstall
Only when decommissioning. Removes the systemd or launchd service that
hermes gateway installcreated. - S6
Disconnect tools
hermes tools # or, everywhere at once, in config.yaml: agent: disabled_toolsets: - webhermes toolsopens the per-platform tool UI.agent.disabled_toolsetsremoves a toolset on every platform, after per-platform settings. - S7
Disconnect MCP servers
mcp_servers: <name>: enabled: false # or remove it entirely: hermes mcp remove <name>enabled: falsestops connection, discovery and tool registration but keeps the entry for later. In a running session, apply with/reload-mcp.
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.
Stop the gateway before running hermes import, to avoid conflicts with running processes.
- 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.
- R2
Check the configuration
hermes config check hermes config migrate
checkfinds missing options and stale saved selections;migrateadds missing options interactively. - R3
Refit the model
hermes model
Choose provider and model. Secrets go to
.env. - R4
Refit tools
hermes tools hermes tools --summary
Re-enable toolsets and remove any temporary
agent.disabled_toolsetsentries. - R5
Refit MCP servers
hermes mcp add <name> --url <URL> hermes mcp test <name> hermes mcp configure <name>
Or set
enabled: trueagain. For OAuth servers runhermes mcp login <name>from a fresh terminal. - R6
Refit the gateway
hermes gateway setup hermes gateway install hermes gateway start hermes gateway status
On WSL, Docker or Termux, use
hermes gateway runin the foreground instead of the service. - R7
Resume cron
hermes cron resume <job> hermes cron status hermes cron doctor
statusconfirms the scheduler is running.doctoris read-only and exits non-zero when it finds problems. - R8
Diagnostics
hermes doctor hermes logs errors --since 30m
hermes doctorexits 0 when nothing is unresolved and 1 otherwise.--fixattempts automatic repairs. - R9
Road test
hermes -z "List the files in the current directory" hermes cron run <job>
hermes -zprints 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.
| Symptom | Probable cause | Remedy | Basis |
|---|---|---|---|
| Agent saved a fact but acts as if it does not know it | Memory is injected as a frozen snapshot at session start | Start a new session. For long gateway chats, hermes sessions refresh-prompts | Documented |
Edits to SOUL. or AGENTS. have no effect | Context files are assembled at session start | Restart the session | Documented |
hermes gateway start fails or the gateway keeps disconnecting on WSL | systemd support on WSL is unreliable | Use hermes gateway run, for example inside tmux | Documented |
| MCP server's tools do not appear | Server has enabled: false, or tools. / exclude filters them | hermes mcp list, hermes mcp configure <name>, then /reload-mcp. Filters use the original tool name | Documented |
| (flagged to review) MCP login seems to work, but every tool call times out | Provider 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 session | In-session auto-reload allows only 30 s | Run hermes mcp login <name> from a fresh terminal; it waits 5 minutes | Documented |
An MCP server stops working in the background with a warning in gateway. | Its refresh token expired; background processes never open a browser | Re-authorise once with hermes mcp login <name> | Documented |
| Slow failover when the main provider is flaky | Retries on the primary come first (agent., default 3) | Configure fallback_; set agent. to fail over on the first transient error | Documented |
read_ refuses a large file | Result would exceed file_ (100,000) | Read a range with offset and limit, or raise the limit on large-context models | Documented |
Terminal output shows [OUTPUT TRUNCATED] | Output exceeded tool_ (50,000) | Raise the limit, or narrow the command's output | Documented |
Antivirus quarantines uv. on Windows | False positive on the bundled Python package manager | Verify the file as the README describes, then exclude the folder, not the file hash | Documented |
hermes doctor exits 1 | At least one problem is unresolved | Read the report; try hermes doctor --fix | Documented |
| Bot does not answer on a messaging platform | Gateway not running, the platform not set up, or the user not authorised | hermes gateway status, hermes status, hermes logs gateway; rerun hermes gateway setup | Advice |
| Scheduled job did not run | Scheduler not running, job paused, or a delivery failure | hermes cron status, hermes cron list, hermes cron doctor; check ~/. | Advice |
| Replies slow down or get worse in a very long session | Context pressure; frequent compression | Check with /usage; start fresh with /new; run /compress deliberately | Advice |
Margin note: = read these twice before I connect Google Drive or Atlassian over MCP.
Chapter 8: Routine maintenanceA suggested service schedule
The intervals below are this manual's advice. Nous Research does not publish a service schedule. The commands and their behaviour are documented.
| Interval | Task | Command |
|---|---|---|
| Daily | Scan for new warnings and errors | hermes logs errors --since 1d |
| Weekly | Full backup. By default older full backups beyond the newest 3 are deleted calendar reminder, Fridays | hermes backup |
| Weekly | Health checks for the install and the cron fleet | hermes doctor, hermes cron doctor |
| Monthly | Check for and apply updates. A quick state snapshot is taken first by default, and running gateways are restarted | hermes update --check, then hermes update |
| Monthly | Check hub skills for upstream changes | hermes skills check |
| Monthly | Review connected MCP servers and remove unused ones. Catalog MCPs are never auto-updated | hermes mcp list, hermes mcp install <name> to refresh |
| Quarterly | Preview and prune old sessions (default filter: older than 90 days) | hermes sessions prune --dry-run |
| Quarterly | Check configuration for missing options; review memory files, which have fixed character limits | hermes config check |
| After every update | Confirm gateways run the new code | hermes gateway status |
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: @jamesonedge
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
- README.md: overview, install, getting-started commands, Windows notes
- cli-config.yaml.example: example configuration and inline defaults
- website/docs/: source of the documentation site below (the repository has no top-level
docs/directory)
Documentation: hermes-agent.nousresearch.com/docs
- Docs home
- Architecture
- Agent loop internals
- Cron internals
- Configuration
- Which file does what
- Sessions
- Memory
- Skills system
- Cron scheduling
- MCP
- Delegation
- ACP editor integration
- CLI commands reference
- 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 James Taylor. 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.