How Hermes Agent’s Multi‑Layer Memory Beats OpenClaw’s Simple Markdown Store

Hermes Agent has become popular again, and the author compares it with OpenClaw, highlighting that the core difference lies in architecture philosophy: OpenClaw follows a breadth‑first task executor with static Markdown files, while Hermes follows a deep‑first self‑learning loop (execute → evaluate → extract → refine) that automatically generates skills and uses a multi‑layer memory system.

1. Knowledge Architecture

Hermes splits knowledge into four stores that map to a well‑known cognitive classification: MEMORY.md (declarative facts, ~2200 chars) and USER.md (user profile, ~1375 chars) hold pure text; SKILL.md holds procedural knowledge with no size limit and is written by the agent; a SQLite + FTS5 database records situational transcripts; and SOUL.md defines the agent’s persona. The routing between these stores is deterministic, implemented in _build_system_prompt(), which decides based on the type of new information whether it goes to USER, MEMORY, SKILL, or SESSION DB.

2. Local Memory Constraints

The declarative store is limited to 3575 characters, a design choice that forces the agent to prioritize entries (user corrections > preferences > environment facts > process notes). Operations are add (with duplicate rejection), replace (substring match + budget check), and remove; there is no explicit read because the memory is always visible in the system prompt.

3. Frozen Snapshot and Nudge

When a session starts, a frozen snapshot of the memory files is loaded into the system prompt. Writes during the session go to disk but do not update the prompt until the next session, preserving cache stability. A nudge_interval (default 10) inserts periodic reminders, and flush_min_turns (default 6) prevents premature flushing, creating a rhythm of work → nudge → evaluate → persist → continue.

4. Security Scanning

Before any write, _scan_memory_content() checks for prompt‑injection patterns, data‑exfiltration commands, SSH backdoors, and invisible Unicode characters. Atomic writes use os.replace() + fsync() so concurrent readers never see a partially written file.

5. A Real Session Walk‑through

In a 25‑round session, the first two rounds capture a user request for a navigation bar and a preference for a dark theme; after eight more layout tweaks, the nudge triggers and the preference is written to USER.md while the frozen snapshot remains unchanged. Later, token usage exceeds a 50 % threshold, triggering a three‑phase compression: sentinel‑driven flush, Gemini Flash summarization (T = 0.3), and SQLite session split with a new parent foreign key. Subsequent sessions start with the dark‑theme preference already present.

6. Dual‑Peer Model (Honcho)

Honcho adds a user peer and an AI peer, both with observe_me=True. It observes utterances, builds evolving representations, and supplies them to the persona layer. Context prefetching runs in a background daemon after each round, so only the first round incurs HTTP latency.

7. Skill System

A skill is a SKILL.md file with YAML front‑matter stored under ~/.hermes/skills/. Reading is done by tools/skills_tool.py (≈900 lines) and writing by tools/skill_manager_tool.py (≈659 lines) with patch‑based find‑and‑replace for self‑improvement. tools/skills_guard.py (≈350 lines) enforces over 60 modes and trust‑level policies; blocked actions trigger atomic rollbacks. After a complex task (≥5 tool calls), the agent proposes saving the workflow as a skill; if a skill fails, it is immediately patched. Token cost is controlled by progressive disclosure: Tier 1 index in the prompt (~2 tokens per skill), Tier 2 on‑demand loading of SKILL.md, Tier 3 loading of supporting files.

8. Persona

SOUL.md

defines the core identity: “You are Hermes, an AI assistant made by Nous Research.” It also specifies tone (“you are a peer, you know a lot but do not flaunt it”) and anti‑patterns (no emojis, no hype). The persona file is editable by the user and is part of a 12‑layer system prompt assembled in _build_system_prompt(), with the first 10 layers cached per session and the last 2 rebuilt each API call.

9. Context Compression

Because LLMs have limited context windows, Hermes uses a three‑phase compression pipeline implemented in _compress_context() (run_agent.py:3994‑4058) and agent/context_compressor.py (382 lines). Phase 1 flushes memories via a sentinel call; Phase 2 protects the first 3 and last 4 messages while Gemini Flash (T = 0.3) summarizes the middle; Phase 3 splits the session, marks the old one with end_reason: "compression", creates a new parent FK, and rebuilds the prompt cache. Compression is presented as consolidation rather than loss.

10. System Integration

Hard boundaries enforced in the system prompt keep facts in memory and procedures in skills. Skills ↔ session search enable experience‑based learning: a task triggers a search of past sessions, crystallizes a skill, and reuses it later. Persona ↔ Honcho evolves the AI peer’s representation. Compression ↔ memory links flush‑then‑compress cycles, turning compression into a knowledge‑consolidation event. The limited 3575‑character store is a deliberate signal‑density design, not a compromise. All persistence boundaries undergo security checks, providing deep defense against prompt injection.

11. Deployment Model

All components are plain text, markdown, or SQLite files under ~/.hermes/. The system is model‑agnostic—changing the underlying LLM does not lose memory, skills, or persona—and it is not a cloud service but user‑controlled infrastructure.