05-2 Hermes-Agent Anatomy: Nous Research's Minimalist Agent

​

Learning objectives

• Explain Hermes-Agent’s origins and positioning: it is an agent framework, not an inference model, maintained by Nous Research under the MIT license
• Describe its core architecture: the AIAgent main loop, three-layer system prompt assembly, multi-backend tool dispatch, and SQLite state storage
• State the role of SOUL.md, MEMORY.md, USER.md, and AGENTS.md in prompt assembly — their layers and responsibilities
• Identify the trade-offs of the minimalist Markdown file design: easy to understand and externalize, but lacking structured version control under high concurrency or multi-agent scenarios
• Summarize the essence of this system in one everyday analogy
• Compare it directly against 05-1 OpenClaw’s multi-file design

​

1. Origins and positioning

• It is not the Hermes model family. Hermes-3-405B, Hermes-3-70B, and similar models are open-source LLMs trained by Nous Research. They are separate products from the Hermes-Agent framework. Hermes-Agent is not bound to any inference backend; it supports OpenRouter, Anthropic, OpenAI, Google, vLLM, llama.cpp, and any other OpenAI-compatible API. The Hermes models are simply Nous Portal’s default preferred endpoint.
• It is not a lightweight SDK. Despite the clean Markdown file interface, it is positioned as a full-featured agentic harness that “can run on a $5 VPS or a GPU cluster and interact across Telegram, Discord, and other platforms.” It ships with sub-agent delegation, SQLite state storage, and cross-session memory.
• The license is MIT (as of 2026-05, per the repository LICENSE file): commercial use, modification, and closed-source redistribution are all permitted.

​

2. Core technology

1. Prompt assembly is three layers, not scattered ad hoc. agent/prompt_builder.py assembles the stable / context / volatile layers into a system prompt, with explicit slot numbers and injection strategies for each layer.
2. Inference backend is fully pluggable. Any service that accepts an OpenAI-compatible API can be connected — a deliberate choice for “no single-vendor lock-in.”
3. State is SQLite, not plain files. OpenClaw’s memory relies mainly on MEMORY.md + memory/YYYY-MM-DD.md; Hermes-Agent adds a SQLite + FTS5 layer supporting cross-session full-text search and LLM-summary recall.

​

2.5 Why it can “grow with you”: the agent curates its own memory and re-injects it next session

1. Two capped memory files: MEMORY.md (2,200 character limit, roughly 800 tokens) records “environmental facts, conventions, and things learned”; USER.md (1,375 character limit, roughly 500 tokens) records “your preferences, communication style, and expectations.” Both live in ~/.hermes/memories/.
2. Written by the agent itself via the memory tool: there is no background process auto-distilling content. The agent judges during interaction that “this is worth remembering” and actively adds, replaces, or removes entries in the two files above. The character limit is a key design choice: it forces the agent to select and consolidate rather than accumulate indefinitely, so “growth” is curated compression, not a running log.
3. Re-injected at the next session: at session start, both files are frozen into a snapshot and injected into the volatile layer (see the three-layer assembly above). The agent then opens with “what I remembered about you and this work last time,” producing more contextually appropriate behavior.

​

3. System structure

​

User-side configuration directory: ~/.hermes/

model:
  provider: openrouter          # openrouter | anthropic | openai | gemini | nous | auto
  default: anthropic/claude-opus-4.6
  base_url: https://openrouter.ai/api/v1   # any OpenAI-compatible endpoint; local vLLM / llama.cpp goes here
  # api_key goes in ~/.hermes/.env, not here

memory:
  memory_char_limit: 2200       # MEMORY.md limit, corresponds to ~800 tokens in Section 2.5
  user_char_limit: 1375         # USER.md limit, corresponds to ~500 tokens

agent:
  max_concurrent_children: 3    # concurrent sub-agents
  max_spawn_depth: 1

terminal:
  backend: docker               # local | docker | ssh | modal | daytona | singularity

security:
  redact_secrets: true
  approvals:
    mode: manual                # manual | smart | off

​

4. Custom Markdown files: the role of SOUL.md and others

• SOUL.md is only loaded from HERMES_HOME, independent of CWD. This ensures the persona stays stable across projects: the persona you wrote for project A cannot be overwritten by project B’s AGENTS.md.
• The default SOUL.md is auto-planted: on first launch, hermes_cli/default_soul.py writes a short identity declaration. Read that default before editing it — then you know “if I delete this entire block, what happens.”
• Volatile layer frozen snapshot: at session start, the contents of MEMORY.md and USER.md are frozen into a snapshot and injected into the system prompt. Memory operations during the session only write to disk; they take effect in the next session. This design preserves LLM prefix cache stability (the prompt prefix does not change within a session), at the cost of “in-session self-improvement is not visible until the next round.”
• Sub-agent delegation exception: when delegate_task launches a sub-agent (skip_context_files), SOUL.md is not loaded; the hardcoded DEFAULT_AGENT_IDENTITY is used instead. Sub-agents do not inherit the main persona — this is the design choice that enables “different personas for different tasks.”

​

5. One everyday analogy

​

6. Trade-offs of minimalist design

​

6.1 What you gain

• Human-readable, version-controllable, portable across platforms. Everything about “who the agent is, what it should remember, how it should behave” is expressed in Markdown or diffable SQLite. No closed-source binary configuration.
• Prefix-cache friendly. The volatile frozen snapshot keeps the prompt prefix stable within a session, lowering model costs.
• No vendor lock-in. Any OpenAI-compatible API works — a real strategic option in 2026’s fast-shifting provider landscape.
• Progressive skill disclosure. Level 0 only loads the skills index (roughly 3k tokens); Level 1 loads full skill content. This is cost control for “many skills installed but not all used in every session.”

​

6.2 What you pay

• Plain-text format lacks structured schema validation. Markdown files have no type checking; personality drift is hard to quantify. How do you know three rounds of edits to SOUL.md haven’t pushed the tone away from the original design?
• Volatile freezing makes in-session memory changes take effect with a delay. This creates friction relative to the intuition of real-time awareness.
• Persona differentiation in multi-agent scenarios: sub-agents use hardcoded DEFAULT_AGENT_IDENTITY, but how do you inject different personas into different sub-agents? Official documentation does not describe a SOUL.md override mechanism for sub-agents.
• SQLite is single-machine storage. If you want to sync session history across multiple machines, you need to add a sync layer yourself (filesystem watcher, Syncthing, or a self-hosted S3-compatible layer).

​

Hands-on exercises

​

Common pitfalls

• Assuming Hermes-Agent only works with Hermes-series models: any OpenAI-compatible API works (OpenRouter, Anthropic, OpenAI, Google, vLLM, llama.cpp, etc.)
• Assuming editing SOUL.md takes effect immediately in the current session: a restart is required because the volatile layer is frozen into a snapshot at session start
• Treating AGENTS.md and SOUL.md as equivalent: they belong to different prompt layers (context vs. stable) and have different scopes (CWD walk-up vs. unique HERMES_HOME)
• Treating SQLite state as a disposable cache: SQLite contains the basis for session search and LLM-summary recall; deleting it makes “why did it do that last time” unrecoverable. Backup strategy should include the SQLite file.
• Expecting sub-agents to have the main persona: sub-agents launched by delegate_task do not inherit SOUL.md and use DEFAULT_AGENT_IDENTITY directly. If a specific persona is needed for a sub-agent, pass the context explicitly at call time or set up a sub-agent-specific SOUL.md in advance; official documentation does not explicitly state whether native override support exists.

​

Self-check

​

Sources and further reading

• Related: 05-1 OpenClaw (TypeScript, more Markdown files, more complete heartbeat scheduling); 05-3 NemoClaw (NVIDIA open-sourced 2026-03, wraps Hermes inside an OpenShell sandbox, enterprise-ready); 05-4 Three-approaches comparison; 01-6 Harness Engineering for the harness design criteria this unit’s architecture embodies.