Hermes Agent, Taken Apart
Nous Research's open-source Hermes Agent, dismantled into eight layers: a gateway to six chat platforms, curated memory and session search, skills it writes for itself, subagents, a scheduler and six execution backends.
1. Case file
- In one sentence.
- An always-on, open-source agent you can message from anywhere, built around learning from its own work: it curates memory, searches past sessions and writes its own skills.
2. The whole system in one picture
๐๏ธ The whole system, layer by layer, with one task traced
Same eight-layer reference stack in every article of the series. Components and calls are drawn from the project's documentation and code; where internals are not public the drawing is inferred from documented behaviour. The monospace box shows what actually moves between layers at each step (simplified).
3. Layer by layer
L1๐ฅ๏ธ Interfaces ยท Where people (or other agents) talk to it
- What it does
- Where you reach it.
- How it is built here
- CLI/TUI plus Telegram, Discord, Slack, WhatsApp, Signal and email; installs on Linux, macOS, WSL2, native Windows and Android/Termux.
- Design choice
- Meet people where they already talk, not only in an editor.
- Without it
- The agent is only useful at a desk.
L2๐งญ Sessions & orchestration ยท Who owns a task: sessions, background tasks, subagents
- What it does
- Routing, helpers, schedules.
- How it is built here
- A single gateway process for all platforms; isolated subagents; a built-in cron scheduler.
- Design choice
- An always-on service rather than a session you open.
- Without it
- No way to receive messages or run jobs on a schedule.
L3๐ Agent loop ยท How it decides the next step
- What it does
- The decision loop.
- How it is built here
- Core agent loop โ ๏ธ (documented on a site we could not reach).
- Design choice
- Unknown in detail; the distinctive work happens in layers 4 and 5.
- Without it
- โ
๐ How this loop compares with the other four, dial by dial, and its RSI level: Inside the Agent Loop
L4๐ง Context engine ยท What the model sees on each turn
- What it does
- What it remembers.
- How it is built here
- Agent-curated memory with periodic nudges, FTS5 full-text session search, and Honcho user modelling.
- Design choice
- Memory curated by the agent itself, plus search over everything it has done.
- Without it
- Every conversation starts from zero.
L5๐ ๏ธ Tools ยท What it can do
- What it does
- What it can do, and learn to do.
- How it is built here
- Tools, skills it creates after complex tasks (agentskills.io-compatible), and Python scripts that call its tools over RPC.
- Design choice
- The agent writes its own procedures: skills become reusable know-how.
- Without it
- It solves the same problem from scratch every time.
L6๐ก๏ธ Policy & safety ยท What it may do
- What it does
- What it may do.
- How it is built here
- Depends on the chosen backend and configuration โ ๏ธ; not detailed in the README.
- Design choice
- Safety comes largely from where it runs (layer 7).
- Without it
- A self-improving agent with broad local access is risky.
L7๐ฆ Execution ยท Where actions actually run
- What it does
- Where commands run.
- How it is built here
- Six terminal backends: local, Docker, SSH, Modal, Daytona, Vercel Sandbox.
- Design choice
- Execution is swappable: laptop, container, remote or cloud sandbox.
- Without it
- One environment for every job, safe or not.
L8๐งฌ Model & telemetry ยท Which model, and what gets logged
- What it does
- The model.
- How it is built here
- A model you configure โ ๏ธ.
- Design choice
- Model choice left to the user โ ๏ธ.
- Without it
- โ
4. Connecting the dots
- Layers 4 and 5 make it self-improving.
- Memory, session search and self-written skills together mean later tasks start where earlier ones ended.
- Where it sits on the RSI ladder.
- It improves while in use, inside a fixed improvement process: a Level 4 pattern on the site's RSI map (our classification). It does not rewrite how it learns.
- A service, not a session.
- The gateway and scheduler (layer 2) make it something that runs all the time.
๐งฌ Design DNA: the three decisions that define it
๐ธ Where the tokens go in the traced task (our estimate)
An illustrative split for a ~300k-token task: about $1.20 at an assumed blended $4 per million tokens. Real numbers vary widely with the repo, the model and caching; the shape (context re-sent every turn dominates) is the point.
5. How it evolved
- We could not reach the documentation site, so a dated history is not given rather than guessed.
6. Where it breaks, and what it does about it
| Failure | Layer | What happens | What this system does about it |
|---|---|---|---|
| Bad lessons stick | L4 | Wrong facts saved to memory or skills are reused. | Review skills it writes; prune memory โ ๏ธ. |
| Skill drift | L5 | Self-written skills accumulate or contradict each other. | Treat skills like code: version and review them. |
| Chat-borne injection | L1 | Anyone who can message it can try to instruct it. | Restrict who can reach the gateway; prefer sandboxed backends. |
| Broad local access | L7 | Local backend with full user permissions. | Use Docker or a cloud sandbox backend. |
| Unattended jobs | L2 | Cron jobs fail silently or act repeatedly. | Log and alert on scheduled runs. |
7. Security and threat model
๐งฑ Trust boundaries
- The special risk of self-improvement.
- A poisoned memory or skill keeps influencing future runs. Review what it learns, the same way the Maestro series' gate reviews every skill.
8. Standards it shares, and benchmarks
- Interoperability.
- Agent Skills: compatible with the agentskills.io open standard, the same SKILL.md format other harnesses use.
- Six execution backends, including third-party cloud sandboxes.
- Benchmarks.
- No benchmark claims on the pages we read.
9. What people use it for
10. How to build one from scratch
- Start small: remember and reuse.
- This separate toy shows the Hermes ideas: a gateway handles chat messages, past sessions are searched with SQLite FTS5, and a skill written after the first task is reused on the second. The model is a scripted stub.
"""mini_hermes.py โ a toy harness in the style of Hermes Agent (illustrative).
A gateway receives chat messages; the agent searches past sessions (SQLite FTS5,
falling back to a simple scan if FTS5 is missing), reuses a skill it wrote last
time, and writes or updates skills after a task. The "model" is a scripted stub;
standard library only.
"""
import sqlite3
db = sqlite3.connect(":memory:")
try:
db.execute("CREATE VIRTUAL TABLE sessions USING fts5(text)"); FTS = True
except sqlite3.OperationalError:
db.execute("CREATE TABLE sessions(text)"); FTS = False
SKILLS = {}
def search(q):
if FTS: return [r[0] for r in db.execute("SELECT text FROM sessions WHERE sessions MATCH ?", (q,))]
return [r[0] for r in db.execute("SELECT text FROM sessions") if q in r[0]]
def handle(platform, msg):
hits = search("date")
skill = SKILLS.get("fix-date-tests")
steps = skill["steps"] if skill else ["run tests", "inspect parse()", "try formats", "fix", "re-run"]
db.execute("INSERT INTO sessions VALUES (?)", (f"{platform}: {msg} -> fixed date parsing",))
if skill: skill["uses"] += 1
else: SKILLS["fix-date-tests"] = {"steps": ["run tests with TZ=UTC", "check split format", "fix", "re-run"], "uses": 1}
return f"[{platform}] recalled {len(hits)} past session(s), {'reused skill' if skill else 'no skill yet'}, {len(steps)} steps"
def main():
print(handle("slack", "date test failing, please fix"))
print(handle("telegram", "the date test broke again"))
print(f"skills: {[(k, v['uses']) for k, v in SKILLS.items()]} session search: {'fts5' if FTS else 'scan'}")
if __name__ == "__main__":
main()| Phase | What you build | Time* | Team* | Cost* |
|---|---|---|---|---|
| 0 ยท Prototype | Loop with tools and one chat platform | 1โ2 weeks | 1 | $15โ40k |
| 1 ยท Memory | Session store, full-text search, curated memory | 1โ2 months | 2 | $100โ250k |
| 2 ยท Learning | Skill writing and reuse, user model, review tools | 2โ4 months | 3โ5 | $300โ800k |
| 3 ยท Reach | Gateway for many platforms, scheduler, backends | 2โ4 months | 3โ6 | $300โ900k |
| 4 ยท Community product | Installers for every OS, docs, security hardening | 6+ months | 5โ15 incl. contributors | $1โ3M a year |
*Our estimates, not vendor figures: fully loaded engineer cost assumed at $250k a year (US-style salaries; lower elsewhere), plus model API and infrastructure. Treat as orders of magnitude.
- The hard part.
- Deciding what is worth remembering and keeping self-written skills correct: the learning loop needs a quality gate.
๐งฎ What would running your own cost a month?
Our model: model cost = tasks ร tokens ร price ร 30 days; people = engineers ร $250k รท 12; infrastructure (sandboxes, storage, logs) assumed at 15% of model cost. A blended price mixes cached input, fresh input and output; check your provider's current prices.
11. When to choose it
โ Choose it when
- A personal or team agent you message from anywhere.
- You want it to get better at recurring tasks.
- Open source and your choice of execution backend.
โ ๏ธ Think twice when
- You need strict change control: self-written skills need review.
- You need enterprise support.
12. How it compares, layer by layer
| Harness | L1Interfaces | L2Sessions & orchestration | L3Agent loop | L4Context engine | L5Tools | L6Policy & safety | L7Execution | L8Model & telemetry |
|---|---|---|---|---|---|---|---|---|
| Claude Code | Terminal, IDE, desktop, web, Slack; Agent SDK | Sessions with resume; subagents; cloud sessions on the web | One general think โ act โ observe loop | CLAUDE.md, auto memory, compaction | Built-in file/shell/search tools, MCP, skills | Permission rules and modes, hooks | Your machine (optional sandboxing โ ๏ธ); cloud for web sessions | Claude models; transcripts, cost and usage telemetry |
| Codex | Terminal, IDE, web (chatgpt.com/codex) | Parallel cloud tasks; local sessions | Agent loop per task | AGENTS.md, repo context | Shell, file edits, MCP | Approval modes โ ๏ธ | OS sandbox locally โ ๏ธ; container per cloud task | OpenAI models; task logs and diffs |
| Gemini CLI / Jules | Terminal (CLI); browser + GitHub (Jules) | Interactive session vs asynchronous task | Agent loop (CLI); plan-then-execute (Jules โ ๏ธ) | GEMINI.md context files | Built-in tools, MCP | Confirmations in the CLI; plan approval in Jules โ ๏ธ | Your machine (CLI); cloud VM (Jules โ ๏ธ) | Gemini models (CLI "not optimized for Gemini 4+") |
| Deep Agents | Your own app (library) | LangGraph threads; sub-agents | Planning loop on LangGraph | Filesystem as memory; offloading | Your tools, MCP, skills | Human-in-the-loop interrupts | Pluggable backends: local, sandboxed, remote | Any chat model; LangGraph state and tracing |
| Hermes Agent | Terminal + Telegram, Discord, Slack, WhatsApp, Signal, email | Gateway, subagents, cron scheduler | Agent loop (details on its docs site โ ๏ธ) | Curated memory, FTS5 session search, user model | Tools, self-written skills (agentskills.io), Python RPC scripts | Depends on backend and configuration โ ๏ธ | Six backends: local, Docker, SSH, Modal, Daytona, Vercel Sandbox | Model you configure โ ๏ธ |
One line per layer; our reading of each project's documentation and code as of 7 Nov 2026.
| Harness | Runs where | Open source | Subagents | Persistent memory | Skills | MCP | Sandbox | Human approval | Async / cloud tasks |
|---|---|---|---|---|---|---|---|---|---|
| Claude Code | Terminal, IDE, desktop, web | โ | โ | โ | โ | โ | โ | โ | โ |
| Codex | Terminal, IDE, cloud | โ (CLI) | โ | โ | โ | โ | โ | โ | โ |
| Gemini CLI / Jules | Terminal (CLI), cloud VM (Jules) | โ (CLI) | โ | โ | โ | โ | โ | โ | โ |
| Deep Agents | Your Python / JS app | โ | โ | โ | โ | โ | โ | โ | โ |
| Hermes Agent | Terminal + chat apps | โ | โ | โ | โ | โ | โ | โ | โ |
โ built in ยท โ partial or via add-ons ยท โ not a feature. Our reading of each project's documentation as of 7 Nov 2026; check before relying on it.
13. The series
Agentic AI System Designs: four kinds of agent system, one teardown each
All of them on one page: Agentic Systems at a Glance.
๐ Glossary: 15 terms used across the series
- Agent loop
- The repeat cycle: the model picks an action, the harness runs it, the result goes back to the model.
- Harness
- Everything around the model that turns it into a working agent: loop, tools, context, policy, execution.
- Context window
- The text the model can see at once. Everything the agent knows on a turn has to fit in it.
- Context compaction
- Summarising older conversation so a long task keeps fitting in the context window.
- Tool schema
- A machine-readable description of a tool (name, inputs) that tells the model how to call it.
- MCP
- Model Context Protocol: an open standard for connecting agents to outside tools and data.
- Subagent
- A second agent with its own context, used for a side task; only its summary comes back.
- Skill
- A packaged set of instructions (and sometimes scripts) the agent loads when relevant.
- Hook
- Your own command that runs automatically before or after an agent action.
- Sandbox
- A restricted place to run commands so mistakes or attacks cannot reach the rest of the system.
- Approval mode
- The rule for what the agent may do without asking you first.
- Prompt injection
- Instructions hidden in data the agent reads (a file, a web page) that try to hijack it.
- Trace
- The full record of a run: every model call, tool call and result.
- AGENTS.md / CLAUDE.md / GEMINI.md
- Plain markdown files of project instructions that harnesses read at the start of a session.
- Asynchronous agent
- An agent you hand a task to and leave; it returns a result (often a pull request) later.