Nous Research's self-improving personal agent OS: one agent that lives on a server, talks to you from any messaging app, runs shell commands anywhere, and teaches itself skills after every job.
Hermes is a whole agent in one box: the body (a gateway process that answers Telegram, Discord, WhatsApp, Signal and ~20 more, plus a terminal UI and a desktop app) and the brain (memory files, a skill library, and a searchable record of every conversation) ship together. It runs on your machine or a $5 server, uses any of 33 model providers, and — its signature trick — after each turn it quietly asks itself should I save a memory or write a skill from what just happened?
in a side process that never touches your conversation. The whole design is organized around one rule: never break the prompt cache. Everything expensive stays out of the model's context window unless it has earned its place there.
| shared term | Hermes calls it | where |
|---|---|---|
| brain | memory (MEMORY.md-style files) + one SQLite state.db | tools/memory_tool.py · hermes_state.py |
| skill | skill (agentskills.io standard) | skills/ · tools/skills_tool.py |
| intake fan | the gateway: ~30 platform adapters → one process → one session store | gateway/run.py |
| filing gate | threat-pattern scans that block writes to memory, cron, and skill installs | tools/threat_patterns.py |
| query path | session search — keyword-only FTS5, zero LLM calls | tools/session_search_tool.py |
| night shift | the curator — idle-triggered (weekly + 2h idle), not nightly | agent/curator.py |
| consolidation | overflow-triggered memory merging; opt-in curator skill consolidation | agent/curator.py |
| pruning | archive — almost nothing truly deletes | hermes_state.py |
| meta layer | background review fork + /learn + curator: skills making skills | agent/background_review.py |
Unusually, this repo is both. The body: gateway, TUI, desktop app, ACP for IDEs, an MCP server, seven terminal backends. The brain: memory files, skills, FTS5 recall. What is not in the box: the models (any provider), and optionally Honcho — an external user-modeling service that plugs in as one of eight swappable memory providers.
The price of the cache-first constitution is a repo of god-files (cli.py is 870 KB, run_agent.py 380 KB) — known debt, not a goal. And the default install runs agent commands directly on your machine: SECURITY.md says plainly that the OS, not the agent, is the only real boundary. There is also no local dollar cap — spend is capped in iterations and characters, never USD.
The repo rendered as answers to the canonical register — Core (C#), Memory bank (M#), plus two DRAFT questions it answers unusually well.
Chose: plain files the user owns under ~/.hermes — config.yaml for behavior, .env for secrets only, Markdown memory, skill folders — plus one SQLite state.db for every transcript. Profiles are separate HERMES_HOME dirs.
Why: profiles are independent islands on purpose
— a PR coupling them was closed for exactly that.
Trade-off: no hosted sync; portability is a migration command, not a service.
Chose: radical honesty. The only security boundary against an adversarial LLM is the operating system.
Every in-process screen is officially a heuristic. Real rails: OS/container isolation, default-deny allowlists at every network surface, salted-hash DM pairing.
Why: a denylist over a Turing-complete shell is structurally incomplete
— so don't pretend otherwise.
Trade-off: the default local backend runs on the host; untrusted input there is declared outside the supported posture.
SECURITY.md · gateway/authz_mixin.py · gateway/pairing.py → step 4
Chose: no single spend cap — six layered caps, each for a different runaway shape: iteration budget (500/turn), tool-result character budgets, compression at 50% of window, opt-in loop circuit-breakers, a 429-amplification guard, provider-side credit caps. Cap #0 is the constitution itself: never invalidate the prompt cache.
Why: cache reuse multiplies the user's cost
when broken.
Trade-off: nothing locally caps dollars per day.
agent/iteration_budget.py · tools/budget_config.py · agent/nous_rate_guard.py
Chose: many bodies, one agent. One AIAgent class serves CLI, gateway, ACP, batch, and API server. Platform differences live in the entry point, not the agent.
The dashboard doesn't rebuild chat in React — it embeds the real terminal UI over a PTY.
Why: anything added to the TUI shows up in the dashboard automatically.
Trade-off: the shared core grew into god-files; the PTY trick is POSIX-only.
run_agent.py · mcp_serve.py · acp_adapter/ · hermes_cli/pty_bridge.py
Chose: the Footprint Ladder — extend existing → CLI command + skill → gated tool → plugin → curated MCP catalog → new core tool last. Third-party product plugins and new memory providers are closed out of the tree; they ship as standalone repos.
Why: We are expansive at the edges and conservative at the waist
; in-tree vendor code is our burden to keep working against a fast-moving core.
Trade-off: capability arrives less ergonomically (a skill + shell, not a typed tool), and out-of-tree plugins lose discoverability.
AGENTS.md · toolsets.py · optional-mcps/ → step 9
Chose: a prompt-text rail shipped to every session: the deliverable is a working artifact backed by real tool output — not a description of one… NEVER substitute plausible-looking fabricated output.
Extra scaffolding for GPT/Grok models that declare done without verifying. Contributor side: if you can't point to the exact line where the bug manifests… you haven't verified the premise.
Trade-off: it's all prose — no machine-checked evidence gate. The one structural exception: computer-use returns a driver-verified effect verdict the model may not override.
Chose: framing over filtering. Web/browser/MCP results get wrapped in untrusted-data delimiters (embedded fake delimiters neutralized); hostile chat names are JSON-quoted at the gateway. Hard blocking is reserved for surfaces the user can't intervene on: context files, memory writes, cron prompts, skill installs. Strongest move: capability removal — the webhook toolset is just 4 read-only tools.
Why: it changes how the model interprets the content rather than relying on regex… catching every payload.
Trade-off: prompt injection per se is declared out of bug-bounty scope; only chained outcomes count.
agent/tool_dispatch_helpers.py:544 · tools/threat_patterns.py · toolsets.py:90 → steps 1, 4
Chose: the core brain is two Markdown files (agent notes + user profile) with hard character caps, plus one SQLite file holding every session, indexed by three trigger-maintained FTS5 tables. Eight pluggable external providers (Honcho, mem0, …), max one active.
Why: character caps because char counts are model-independent
; local-first, no service dependency.
Trade-off: ~1,300 tokens of curated memory total — tiny by design.
tools/memory_tool.py · hermes_state_common.py · plugins/memory/
Chose: a free-text entry split by a § delimiter. No IDs, no timestamps, no embeddings — edits address entries by substring.
Why: the file is small enough that the agent is the index.
Trade-off: no dedup machinery; curation is the model's job, forced by the cap (see M8).
Chose: schemaless memory; typed everything else. Skills carry agentskills.io frontmatter (name ≤64, description effectively ≤60 chars); sessions live in a migrated SQLite schema with provenance ordering (derived < llm < user) so a model can never overwrite a title you typed.
Trade-off: memory can't be queried structurally — that's what session search and providers are for.
Chose: agent-curated writes during the turn, plus a post-turn background review fork. The famous periodic nudges
are not injected text — they're counters (10 user turns without a memory write; 10 tool iterations without a skill write) that trigger the fork. A filing gate strict-scans every entry because it enters the system prompt.
Why: a poisoned entry persists for the entire session and across sessions.
Trade-off: human review of writes is opt-in, not default.
agent/turn_finalizer.py · agent/background_review.py → step 6
Chose: deliberately flat. No typed graph, no backlinks — memory entries are prose; skills structure knowledge as folders (SKILL.md + references/). Relationship modeling is outsourced to Honcho's peer cards when you want it.
Trade-off: "who works where"-style hops need an external provider; the built-in brain can't follow arrows.
Chose: keyword-only, zero LLM. FTS5 + BM25 with hand-tuned rank surgery: kanban/subagent sessions hidden, cron sessions demoted (their repetitive vocabulary caused "recall blindness", starving out real conversations), compaction payloads stripped. Model-invoked only — never fires automatically.
Why: No LLM calls anywhere — every shape returns actual messages from the DB.
~20ms, free.
Trade-off: no semantic recall in the core; the README's "LLM summarization" claim is stale (removed in PR #27590).
tools/session_search_tool.py · hermes_state_search.py → step 7
Chose: both sides of the fork, split by kind: compiled understanding goes into skills (how-to) and the memory snapshot (who-you-are); retrieval stays raw — full transcripts searchable forever. The bridge: compacted turns leave the model's window but stay flagged discoverable, so compression never shrinks the brain.
Why: memory captures who the user is
; skills capture how to do this class of task for this user.
Chose: consolidation at the moment of overflow: a full memory file returns an error that instructs the agent to merge and retry in the same turn — no auto-compaction ever. Skills get the curator: inactivity-triggered (weekly, after 2h idle), deterministic stale→archive transitions; its LLM consolidation pass is opt-in and off.
Why: silent dropping is worse than a visible squeeze.
Trade-off: a turn occasionally spends effort housekeeping instead of answering.
tools/memory_tool.py · agent/curator.py → step 7
Chose: almost nothing deletes. The curator's maximum destructive action is archive (restorable, agent-created skills only, pinned exempt). Compaction soft-archives rows (active=0) that stay searchable. Real DELETE exists only behind user-typed commands with dry-runs.
Why: Zero uses is absence of evidence, not proof the skill is disposable.
Trade-off: the store only grows; shrinking is a chore the user owns.
Nine steps, from a ping on your phone to a smarter agent. Gold = touches the context window; verdigris = runs outside it.
Every platform — Telegram, Discord, WhatsApp, Signal, email, ~30 surfaces in all — funnels into one gateway process (the intake fan). A message first hits an authorization ladder that ends in default deny; strangers can earn entry only through DM pairing: an 8-char code, salted-hashed, rate-limited, approved by the operator, never by the sender. Authorized messages get a session key — one canonical string that decides which cached agent, and whose history, this message joins.
build_session_key, the single source of truth.At session start, Hermes assembles the system prompt once: persona, the memory files as a frozen snapshot, a skills index (each description cut at 60 chars), and the narrow-waist core tool schemas. Then it never touches it again — a memory saved on turn 3 lands on disk instantly but stays invisible until next session. That's the constitution: a byte-stable prefix means the provider's prompt cache pays for every later turn.
AGENTS.md is replaced with [BLOCKED])._HERMES_CORE_TOOLS: the narrow waist, edited once for all platforms.One turn = a loop of model call → tool calls → results appended → model call again, up to 500 iterations with a one-shot "grace call" so the model can still say goodbye after the budget dies. Mid-flight you have three verbs, each preserving message alternation differently: interrupt breaks the loop, steer rides your note in on the last tool result without stopping anything, redirect cancels only the in-flight model request and replays with your correction as a real user message.
interrupt / steer / redirect live on AIAgent.Every shell command walks an ordered chain — and the order is the design. The hardline blocklist (wipe disk, power off) and user deny rules fire before yolo mode, so "I trust the agent" never means "let it reformat the box." Below yolo sit ~90 dangerous-pattern regexes with real anti-obfuscation work, then an LLM guard that reads the command inside XML delimiters. Sandboxed backends skip the whole chain: the container is the boundary — which is the honest posture, because everything in-process is officially heuristic.
Silence is not consent.
~/.ssh, .env, …), symlink-resolved.inherit_credentials=True.Big jobs leave the parent's context. Subagents get a fresh conversation and return only a summary — the parent never sees their tool calls. Script tool-calling goes further: the model writes a Python script that calls Hermes tools over RPC; intermediate results never enter any context window, only stdout returns, and those iterations are refunded to the budget. Underneath, seven terminal backends run the actual commands — on serverless ones, files hibernate, processes don't.
This is the headline feature, and it's cheaper than it sounds. Two counters tick silently: 10 user turns without a memory write, or 10 tool iterations without a skill write. When one trips, the turn finishes normally — then a daemon-thread fork replays the conversation snapshot and asks itself what's worth keeping. The fork can only touch memory and skill tools; everything else is denied at runtime. Its prompt is opinionated: patch existing skills before creating new ones, treat user frustration as a first-class signal, and never save "tool X is broken" — these harden into refusals the agent cites against itself for months.
/learn: user-triggered distillation of a source into a skill, toolless by design.~/.hermes/skills/.The context window and the brain shrink on different rules. The window: compression fires at 50% capacity, folds the middle into a summary — and here is the load-bearing trick — the folded turns are soft-archived, not deleted, so session search still finds them. Recall is keyword-only FTS5, zero LLM, ~20ms, with hand-tuned ranking (cron sessions demoted so their repetitive vocabulary can't cause "recall blindness"). The skill library gets the night shift (Hermes's curator — idle-triggered, weekly): stale skills are archived, never deleted, and pinned ones are untouchable.
archive_and_compact: one session id for life, history intact.cannot be reconstructed from the work that followed.
Scheduled life has two modes. Normally the gateway ticks every 60 seconds under a file lock and runs due jobs — each in its own cron session (never spliced into your conversation, memory writes off, a 3-minute hard interrupt so a runaway loop can't monopolize the scheduler). For hosted agents that scale to zero, Chronos inverts the clock: the agent arms one external one-shot per job at its real next fire time, then sleeps entirely; the fire arrives as a short-lived signed token. A blueprint, meanwhile, is just a skill with a schedule in its frontmatter — no new object type.
30m, cron exprs), anchored to your timezone.cron never loses its trigger.
Install is a one-liner (shell, Docker, or Nix — pip is deliberately blocked because a wheel would ship without the bundled skills and assets). hermes update git-pulls with surgical restore and prints rollback instructions with the exact pre-pull SHA when it fails; hermes doctor runs security advisories first. And growth itself is governed: every new capability must climb the Footprint Ladder, where each rung costs more context than the last — the top rung, a new core tool, is paid on every API call
and is the explicit last resort.
--fix repairs.The load-bearing components, grouped by job. Long tails (77 bundled skills, 114 optional skills, 22 platform connectors, 33 model providers) are rolled up as directory rows — the atlas links the door, not every room.
| component | what it does | |
|---|---|---|
| cli.py | in-context | The interactive terminal client — 870 KB of it. |
| ui-tui/ | out-of-band | Ink/Node terminal UI; TypeScript owns the screen, Python owns everything else. |
| tui_gateway/ | out-of-band | Python side of the TUI, JSON-RPC over stdio; resolves per-session toolsets. |
| gateway/run.py | out-of-band | The messaging gateway process; caches ≤128 agents with memory-pressure eviction. |
| apps/desktop/ | out-of-band | Electron desktop app. |
| acp_adapter/ | out-of-band | ACP server for VS Code, Zed, JetBrains. |
| mcp_serve.py | out-of-band | Exposes Hermes conversations as MCP tools to other clients — the inverted direction. |
| hermes_cli/web_server.py | out-of-band | Dashboard; its chat is the real TUI over a PTY WebSocket. |
| component | what it does | |
|---|---|---|
| run_agent.py | in-context | AIAgent: state, streaming, interrupts; the loop body moved out. |
| agent/conversation_loop.py | in-context | The real turn loop: model → tools → repeat, compression, retries. |
| agent/prompt_builder.py | in-context | System-prompt assembly + context-file injection blocking + the honesty rail. |
| agent/turn_context.py | in-context | Per-turn state; hydrates nudge counters on resume. |
| agent/turn_finalizer.py | out-of-band | Teardown; fires micro-compaction and the background review. |
| agent/tool_executor.py | in-context | Concurrent/sequential dispatch; deterministic approval ordering. |
| agent/transports/ | out-of-band | Provider wire adapters (chat-completions, Anthropic, Bedrock, Codex). |
| agent/iteration_budget.py | out-of-band | 500-iteration cap with refunds and one grace call. |
| agent/context_engine.py | in-context | ABC for swappable context managers; default is the built-in compressor. |
| component | what it does | |
|---|---|---|
| gateway/session.py | out-of-band | Session keys, multi-user isolation, hostile-metadata neutralization. |
| gateway/authz_mixin.py | out-of-band | Default-deny authorization; two regression comments against fail-open. |
| gateway/pairing.py | out-of-band | DM pairing: hashed codes, lockout-before-lookup, operator-only approval. |
| gateway/platform_registry.py | out-of-band | Plugin platform registry; passive probe vs active installer split (#79812). |
| gateway/mirror.py | out-of-band | Cross-session delivery mirroring with role rules that keep alternation legal. |
| gateway/relay/ | out-of-band | Hosted-gateway relay: zero public inbound surface, fail-closed tenant routing. |
| gateway/profile_routing.py | out-of-band | Multi-profile message routing; byte-identical no-op when off. |
| plugins/platforms/ | out-of-band | 22 connectors: telegram, discord, slack, whatsapp, email, matrix, teams, irc… |
| gateway/platforms/ | out-of-band | Native adapters: Signal, WhatsApp Cloud, WeChat, QQ, BlueBubbles, webhooks, API server. |
| component | what it does | |
|---|---|---|
| tools/memory_tool.py | in-context | The two-file brain; frozen snapshot, char caps, strict filing gate. |
| agent/memory_manager.py | out-of-band | Provider orchestration: off-thread sync, FIFO, bounded shutdown drain. |
| plugins/memory/ | out-of-band | 8 swappable providers (honcho, hindsight, openviking, holographic, mem0…); tree closed to new ones. |
| agent/background_review.py | out-of-band | The learning-loop fork; memory+skill whitelist, negative-capture blocklist. |
| agent/curator.py | out-of-band | The night shift for skills: archive-only, pinned exempt, cron-referenced protected. |
| tools/skills_tool.py | in-context | Read side: progressive disclosure — index → SKILL.md → linked files. |
| tools/skill_manager_tool.py | out-of-band | Write side with provenance; agent skills quarantined from bundled ones. |
| tools/session_search_tool.py | out-of-band | Cross-session recall: FTS5, zero LLM, rank surgery against recall blindness. |
| hermes_state.py | out-of-band | The SQLite session DB: soft-archive compaction, provenance-ordered titles. |
| skills/ | in-context | 77 bundled skills in 15 categories (github, creative, productivity, research…). |
| optional-skills/ | out-of-band | 114 more in 20 categories, installed on demand from the hub. |
| component | what it does | |
|---|---|---|
| toolsets.py | in-context | 59 toolsets over ~84 tools; webhook toolset is 4 read-only tools by design. |
| model_tools.py | in-context | Tool resolution: disabled always subtracts last; schemas rebuilt against reality. |
| tools/registry.py | out-of-band | check_fn-gated registration with TTL cache and last-good grace. |
| tools/approval.py | in-context | The guard chain: hard rails before yolo, ~90 heuristic patterns, LLM guard. |
| tools/threat_patterns.py | out-of-band | One pattern library, three scopes; anchors on attack vocabulary, not bossy English. |
| agent/tool_dispatch_helpers.py | in-context | Untrusted-result delimiters — the architectural injection defense. |
| agent/redact.py | out-of-band | Secret masking on terminal output before the model sees it. |
| agent/secret_sources/ | out-of-band | Bitwarden / 1Password backends over one shared 0600+TTL cache substrate. |
| tools/delegate_tool.py | out-of-band | Subagents: fresh context, blocked-tool list with reasons, summary-only return. |
| tools/code_execution_tool.py | out-of-band | Script tool-calling over RPC; stdout-only return, iterations refunded. |
| tools/environments/ | out-of-band | 7 backends: local, docker, ssh, singularity, modal, daytona, vercel sandbox. |
| tools/budget_config.py | in-context | Per-result and per-turn character budgets, scaled to the model's window. |
| component | what it does | |
|---|---|---|
| cron/scheduler.py | out-of-band | 60s tick under a file lock; isolated cron sessions, one-line failure summaries. |
| cron/jobs.py | out-of-band | Job store; natural-language schedules in the user's timezone. |
| plugins/cron_providers/ | out-of-band | Chronos: NAS-mediated one-shot fires for scale-to-zero deployments. |
| tools/blueprints.py | out-of-band | Blueprint = skill + schedule; no new object type, rides the skills pipeline. |
| hermes_cli/update_cmd.py | out-of-band | hermes update: backup, surgical restore, rollback SHA on failure. |
| hermes_cli/doctor.py | out-of-band | Diagnostics; security advisories run first, --fix repairs. |
| plugins/model-providers/ | out-of-band | 33 declarative provider profiles; user plugins override bundled by name. |
| optional-mcps/ | out-of-band | 6 curated MCPs (blender, figma, linear, n8n…), SHA-pinned, never auto-updated. |
| batch_runner.py | out-of-band | Research mode: batch trajectory generation for training tool-calling models. |
| AGENTS.md | out-of-band | The 77 KB constitution: cache rules, footprint ladder, testing bans, closure policies. |
| SECURITY.md | out-of-band | The threat model that names its own heuristics as heuristics. |