inside hermes: a step-by-step breakdown of the agent architecture.
nous research describes hermes as “the self-improving ai agent” — one you can run on a $5 vps and talk to from telegram while it works on a cloud vm. underneath the pitch is an unusually disciplined architecture: one agent loop, one gateway, many surfaces. this piece walks through what actually happens when a message arrives, then makes the case for why the design is a paradigm shift — and is honest about what isn’t new.
not a chatbot. an operating layer.
most agent frameworks are libraries: you import them, wire a graph of prompts and tools, and ship a product around them. hermes inverts that. it is a long-running process that owns its own state — sessions in sqlite, skills on disk, cron jobs in a scheduler — and every interface you use to reach it (cli, desktop app, telegram, discord, slack, whatsapp, signal, email, home assistant, and more than a dozen others) is just an adapter feeding the same single loop.
that inversion sounds small. it isn’t. it changes what the thing is: not a feature inside an app, but a persistent computational tenant that happens to be reachable from wherever you already are.
telegram discord slack whatsapp
signal email cli desktop
\ | | /
+------ gateway -------+
|
one agent loop
(run_agent.py)
|
+----------+-----------+
| | |
toolsets skills memory
(~70 core) (170+) (sqlite + fts5)
|
terminal · browser · files · web
cron · delegation · mcp · visionthe life of one message.
a message arrives at the gateway
whether it comes from telegram, discord, slack, whatsapp, signal, email, a github webhook, or home assistant, a platform adapter normalises the message and hands it to the gateway runner. the gateway resolves who you are, which session this belongs to (one per user + platform + thread), guards against mid-run interruptions by queueing, and intercepts control commands like /stop, /approve, and /new before the model ever sees them.
crucially, every platform lands in the same session database. start a task in the cli, check on it from telegram — it’s one continuous conversation, not twenty siloed bots.
the system prompt is assembled — once
the prompt builder composes the agent’s identity, a manifest of available skills, any project context files (agents.md / claude.md), and a summary of what it remembers about you. then comes the discipline: that prompt stays byte-stable for the life of the conversation.
hermes’s contributor docs call per-conversation prompt caching “sacred”. because providers cache the prompt prefix, every design decision is filtered through “does this invalidate the cache?” — no synthetic message injections mid-loop, no re-shuffling tool schemas per turn. long conversations reuse the cached prefix every single turn, cutting cost and latency dramatically.
a provider is resolved at runtime
hermes doesn’t hard-wire a model. a declarative provider profile — auth, endpoints, quirks, model catalogues — is resolved at runtime from 30+ bundled providers (anthropic, openai, gemini, deepseek, openrouter, bedrock, ollama, and more), and a custom: prefix accepts any openai-compatible endpoint. you can switch models mid-session with one command, no restart. (this site’s lab instance runs hermes against gemini through a local litellm proxy — the custom: mechanism makes that a config line, not a fork.)
the tool loop runs until the work is done
the model answers with tool calls, hermes executes them, and the loop continues until there’s a final response. the core surface is deliberately small — roughly 70 tools organised into 28 named toolsets: terminal (with six backends: local, docker, ssh, modal, daytona, singularity), a full browser-automation suite, files, web search, vision, image generation, delegation, scheduling.
dangerous operations pass through an approval gate — a terminal command that looks destructive blocks until you send /approve from whatever platform you’re on. and each platform gets a curated toolset: a public webhook gets the “safe” set with no terminal at all.
context is compressed, never discarded
when a conversation approaches the context window, hermes doesn’t truncate. a context engine protects the head and tail of the conversation and summarises the middle into a structured digest — resolved questions, pending asks, task snapshot — explicitly marked as reference material so the model doesn’t re-litigate old decisions. the original session is preserved and chained to its continuation in sqlite, so nothing is truly lost.
everything is persisted and searchable
every session lands in a sqlite database with full-text search built in, and the agent has a tool to query its own past conversations. alongside that sits a curated memory — the agent nudges itself to persist durable facts, and optional pluggable backends (honcho, mem0, supermemory, and others) deepen the model it builds of who you are across sessions.
experience becomes skills
this is the distinctive move. after working through a complex task, hermes can write itself a skill— a markdown playbook with scripts and references — save it to disk, and load it next time the situation recurs. it ships with 170+ curated skills, a curator process archives agent-created skills that go unused, and usage is tracked so the library stays honest. the agent doesn’t just complete tasks; it compiles them into reusable procedures.
and it keeps running when you leave
a cron scheduler runs jobs on durations, cron expressions, or one-shot timestamps — each with its own skills, model override, and delivery target (results can go straight to telegram or slack). background terminal processes notify the agent when they finish, triggering a new turn. a kanban-backed work queue coordinates multiple worker agents with claim-reclaiming and failure auto-blocking. autonomy is infrastructure here, not a demo.
why this is a paradigm shift.
1. from request/response to resident process
the dominant paradigm — from chatgpt to most agent sdks — is session-shaped: a request comes in, tokens come out, state evaporates. hermes is daemon-shaped: it owns durable state, schedules its own work, watches its background processes, and treats your messages as interrupts rather than the only source of events. that’s the difference between a program you run and a system that runs.
2. the narrow waist
like ip in networking, hermes keeps its core deliberately thin — every core tool is sent on every api call, so the bar for adding one is brutal. capability explodes at the edges instead: skills, plugins, mcp servers, platform adapters. contributor docs codify this as a “footprint ladder” and reject speculative infrastructure outright. frameworks accrete; operating layers curate.
3. economics as a design constraint
treating prompt-cache stability as sacred looks like an implementation detail. it’s actually the thing that makes a persistent agent affordable— cached prefixes make hundred-turn conversations cost pennies instead of dollars, which is what makes “always-on” viable on a $5 vps. most frameworks rebuild context freely and pay full price every turn. hermes designed the economics in from the start.
4. a learning loop you can inspect
“self-improving” usually means gradient updates you can’t see. hermes’s loop is legible: skills are markdown files on disk, memory is a database you can query, session history is searchable text. the agent gets better at your workflows in a way you can read, edit, and delete. that’s improvement without fine-tuning — and without trusting a black box.
what’s not novel — and why that’s the point
honesty matters in a piece like this. the tool-calling loop itself is standard openai-style function calling. multi-llm support has been table stakes since langchain. there’s no exotic planner, no multi-agent debate, no learned router. individually, almost every component of hermes exists elsewhere.
the shift isn’t any single mechanism — it’s the composition and the discipline. one loop instead of many bots. a curated core instead of an accreting framework. cache-stable prompts instead of free-form context rebuilding. state that outlives the process instead of evaporating with it. paradigm shifts in software rarely look like new inventions; they look like a set of old ideas finally arranged with conviction. unix wasn’t the first operating system, either.
agents as tenants, not tools.
the lab’s bet — and the reason we run hermes here — is that the next generation of agentic products won’t be chat windows bolted onto saas. they’ll be resident processes with memory, schedules, and accumulated skills, reachable from wherever the user already lives. hermes is the clearest open-source articulation of that shape so far: not because any one part is unprecedented, but because the whole thing is built like it means it.
the code is open — nous research publishes the full agent, gateway, skills library, and contributor philosophy. read the architecture docs alongside this piece; the discipline is visible in the source.