Module 02 / Hermes Architecture

Hermes Architecture

How Hermes is structured, what makes it self-improving, and why it is the safer but less flexible choice compared to OpenClaw.

Learning Objectives
  • Describe the self-improvement loop and how skills are created automatically.
  • Name the three memory files and explain what each stores.
  • Explain Hermes's security model and why command approval matters.
  • Articulate the key trade-offs between Hermes and OpenClaw.
Context

Hermes and OpenClaw: More Alike Than Different

Both let you run your own AI agent instead of renting one from a big company. You install it yourself, it's free, and it talks to you through apps you already use, like Telegram or Discord.

Already using OpenClaw? hermes claw migrate brings your existing setup across automatically, showing you what will change before it touches anything.

Core Mechanism

The Self-Improvement Loop

This is what separates Hermes from most agents. Every interaction is an opportunity to learn, not just to respond.

You Give a Task Hermes executes it Background Review Runs Fires if ANY one is true: • 5+ tool calls succeeded • it worked through an error • you corrected it • it was a non-trivial workflow None true → no change made skill_manage Writes or revises SKILL.md, or /learn triggers it directly USER.md Updates too
A skill is born, via skill_manage

Hermes writes a SKILL.md file to ~/.hermes/skills/ on its own, or you trigger it directly with /learn, pointing it at a codebase, a doc, or a workflow you just walked it through.

The skill improves

The same review can revise an existing skill instead of creating a new one. Not fine-tuning, just a markdown file being edited. skills.write_approval stages every write for your review first, if you want tighter control.

★ Rule of thumb: if you'd put it on a sticky note, it's memory. If you'd put it in a reference document, it's a skill.
Memory System

Memory Architecture

Hermes maintains persistent memory across three plain-text files plus a searchable conversation history. These are not logs, they are active inputs to every conversation.

File / Store Holds Written by
SOUL.md Durable identity and tone, like a system prompt you edit directly, global to the instance You, directly
MEMORY.md Small durable facts, things you've told it, conclusions from past tasks Hermes and you
USER.md Your preferences, communication patterns, what you care about Hermes, automatically
Conversation history Past conversations, indexed separately, searchable via session_search Hermes, automatically

The conversation-history split matters in practice: hermes memory reset only clears MEMORY.md and USER.md, not history. Use --target conversations or --target everything for a genuinely clean slate.

Security Model

Security

Hermes asks for your approval before any shell command or file operation, by default, not as an option. You see exactly what it's about to do before it happens.

✓ Even a malicious MCP tool trying to run a destructive command hits this prompt first. Command approval makes certain attacks structurally harder.

The trade-off is friction. For scheduled tasks, mark specific commands as trusted to skip the prompt, anything new or risky still stops and asks. More in Module 08.

Case: OpenClaw's 2026 security incident
OpenClaw went viral in early 2026, and security researchers found real problems fast. Authentication was disabled by default, exposing tens of thousands of instances, and one vulnerability let a malicious website silently take over a running agent from a single clicked link. The team has since patched filesystem boundaries, network egress controls, and plugin trust verification.
Comparison

Hermes vs OpenClaw: The Trade-offs

No tool is universally better.

What you'd ask Hermes OpenClaw
Does it get smarter the more I use it? Yes, it writes itself new cheat sheets as it goes, automatically Remembers things about you, but doesn't rewrite its own procedures the same way
Can I just install ready-made add-ons? Smaller library, mostly ones it builds for your own use A big public library (ClawHub) other people have already built and shared
Will it ask before doing something risky? Yes, always, before any file change, message, or command Had a serious security scare in 2026, since fixed. See Security above.
Best for A personal assistant that actually improves the more you use it Wide messaging-app coverage and a big ready-made add-on library

As of today, Hermes is the more polished of the two, and the one we'd point you to if you're only running one. Nothing wrong with running both side by side either, migrating back and forth is a solved problem either way.