Hermes Agent (Nous Research) — research for the agent-memory demo kingdom

Purpose. Source input for the Kingdom.md demo kingdom "agent memory" — a fictional markdown corpus that authentically mimics a real advanced agent's on-disk memory + skills store. Goal: borrow the structural conventions (the agentskills.io standard is open) and author original in-world content — we are not copying Hermes' files.

Method. A basic web pass, then two parallel sub-agents: (A) usage/best-practices in the wild, and (B) a source-fidelity deep-dive over a local clone (C:\Projects\_research-clones\hermes-agent, full checkout). Claims below are [confirmed] (read from the repo/official docs verbatim) or [inferred] (synthesis). Adoption stats and the "OpenClaw" rivalry are promotional/lower-confidence.

What Hermes Agent is

A self-hosted, model-agnostic, self-improving personal AI agent from Nous Research (released Feb 25 2026; repo github.com/NousResearch/hermes-agent; MIT). One-line install, runs as a persistent daemon + messaging gateway across 16–20+ chat platforms, provider-agnostic (any OpenAI-compatible API). Its defining trait for us: the agent's entire "brain" — memory, user-model, skills, identity — is human-readable markdown on disk under ~/.hermes/. It reads and writes those files itself. [confirmed]

⭐ Why this is the perfect demo target

The transparency angle is the whole design, not an afterthought: a real, popular agent stores its mind as plain markdown a human can read. Pointing Kingdom.md at a ~/.hermes/-shaped corpus literally renders an AI's memory as a beautifully-typeset document tree — a built-in marketing story ("read your agent's mind"). And the structure is near-convergent with Yggdrasil itself (MEMORY.md index, typed memory, SKILL.mds, a curator/hygiene pass that ages → archive, a usage ledger, even a dogfood skill) — which opens a cheeky meta-seam: a demo of an AI's memory, rendered in a viewer, structured like the very agent that would maintain it.

The ~/.hermes/ on-disk layout (the skeleton to emulate)

Profile root = HERMES_HOME (~/.hermes on POSIX, %LOCALAPPDATA%\hermes on native Windows; named profiles at ~/.hermes/profiles/<name>). [confirmed: hermes_constants.py, hermes_cli/profiles.py]

~/.hermes/                              # profile root
├── SOUL.md                             # agent identity/voice — system-prompt slot #1; seeded if absent
├── config.yaml                         # non-secret config: memory / curator / skills / auxiliary blocks
├── .env                                # secrets (provider keys)
├── state.db                            # SQLite: all sessions, FTS5 full-text search (the "recall" tier)
│
├── memories/                           # the always-on markdown memory core
│   ├── MEMORY.md                       #   agent's notes — 2,200-char cap (~800 tok)
│   └── USER.md                         #   user profile  — 1,375-char cap (~500 tok)
│
├── skills/                             # single source of truth for skills (procedural memory)
│   ├── <category>/<skill>/SKILL.md     #   + sibling references/ templates/ scripts/ assets/
│   ├── <category>/DESCRIPTION.md       #   one-line category descriptor (frontmatter-only)
│   ├── .usage.json                     #   curator telemetry sidecar (per-skill counters + state)
│   ├── .bundled_manifest               #   bundled skill → origin content hash
│   ├── .archive/<skill>/               #   curator-archived skills (flat; recoverable, never deleted)
│   ├── .curator_backups/<utc-iso>/     #   pre-run tar.gz snapshots
│   └── .hub/{lock.json, taps.json, quarantine/, audit.log}   # Skills Hub state
│
├── skill-bundles/<slug>.yaml           # group skills under one slash command
├── plans/                              # plan dir (also: /plan writes workspace-relative .hermes/plans/)
├── logs/curator/<YYYYMMDD-HHMMSS>/     # per-run: run.json + REPORT.md
├── sessions/  cron/  skins/  workspace/  home/
├── pending/skills/<id>.json            # staged writes when write_approval:true
└── profiles/<name>/                    # named profiles — each a full HERMES_HOME

Plus project-local context files (not under ~/.hermes/): AGENTS.md is primary; alternates .hermes.md/HERMES.md, CLAUDE.md, .cursorrules (first-match-wins, 20k-char cap). [confirmed: context-files.md]

File formats (with verbatim shapes)

MEMORY.md / USER.md — the memory core

Plain markdown, no frontmatter. A flat list of entries joined by the delimiter "\n§\n" (a line containing exactly §). [confirmed: memory_tool.py — ENTRY_DELIMITER = "\n§\n"] Loaded once at session start into a frozen snapshot injected into the system prompt (mid-session writes persist to disk but don't re-enter the prompt until next session — prefix-cache discipline). Managed only via the memory tool: add / replace / remove, no read (it's already in context); replace/remove use unique-substring matching. No auto-compact — an overflowing write returns a structured error and the agent must consolidate in-turn. [confirmed: memory.md]

Rendered system-prompt block (verbatim from docs — the banner is generated at injection, not on disk):

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations

Good-entry style (dense, multi-fact, actionable): Project ~/code/api uses Go 1.22, sqlc, chi router. Run tests with 'make test'. CI via GitHub Actions. Save: preferences, environment facts, corrections, conventions, completed work. Skip: trivia, re-discoverable facts, raw dumps, ephemera.

SKILL.md — the skill unit

YAML frontmatter + markdown body. Verbatim real example [confirmed: skills/creative/excalidraw/SKILL.md]:

---
name: excalidraw
description: "Hand-drawn Excalidraw JSON diagrams (arch, flow, seq)."
version: 1.0.0
author: Hermes Agent
license: MIT
dependencies: []
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [Excalidraw, Diagrams, Flowcharts, Architecture, Visualization, JSON]
    related_skills: []
---

Optional frontmatter: homepage, required_environment_variables, and under metadata.hermes: category, fallback_for_toolsets/requires_toolsets (conditional activation), config[]. Body section vocabulary (de-facto): # Title, ## When to Use/## Overview, ## Workflow/## Procedure (numbered), ## Pitfalls, ## Verification, ## Tips, a ## Tools Reference table, with relative links to sibling references/<x>.md and templates/<x>. Package = a directory; SKILL.md is the only required file; optional siblings references/ templates/ scripts/ assets/ tests/. Every installed skill auto-becomes a /slash-command. [confirmed: skills.md, live skill trees]

DESCRIPTION.md — category descriptor (frontmatter-only, no body)

---
description: Knowledge and Tools for Machine Learning Operations - tools and frameworks for training, fine-tuning, deploying, and optimizing ML/AI models
---

Sits at a category dir; nests (skills/mlops/DESCRIPTION.md, skills/mlops/evaluation/DESCRIPTION.md). [confirmed: skills/mlops/DESCRIPTION.md]

SOUL.md — agent identity (plain markdown, no frontmatter)

Durable voice/tone/posture, not project facts. System-prompt slot #1; empty → built-in fallback ("You are Hermes Agent… created by Nous Research…"). Body shape: # Personality / ## Style / ## What to avoid / ## Technical posture. [confirmed: personality.md, context-files.md]

AGENTS.md — project context (plain markdown)

Body shape: # Project Context / ## Architecture / ## Conventions / ## Important Notes. [confirmed: context-files.md]

Plans & curator reports

  • Plan files: .hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md — Goal / Context / Approach / Steps / Files / Tests / Risks. [confirmed: plan SKILL.md]
  • Curator: ~/.hermes/logs/curator/<timestamp>/{run.json, REPORT.md}. [confirmed: curator.md]

The Curator & skill lifecycle (what sells "self-improving")

Telemetry sidecar skills/.usage.json, one entry per skill — verbatim shape [confirmed: curator.md]:

{
  "my-skill": {
    "use_count": 12, "view_count": 34,
    "last_used_at": "2026-04-24T18:12:03Z", "last_viewed_at": "2026-04-23T09:44:17Z",
    "patch_count": 3, "last_patched_at": "2026-04-20T22:01:55Z",
    "created_at": "2026-03-01T14:20:00Z",
    "state": "active", "pinned": false, "archived_at": null
  }
}

State machine active → stale → archived, deterministic clocks (no LLM): unused 30 days → stale, unused 90 days → archived (package moved to skills/.archive/<skill>/). Never auto-deletes; recoverable via hermes curator restore. Runs on inactivity (default every 7 days, only after 2h idle), takes a pre-run .curator_backups/<utc-iso>/skills.tar.gz snapshot, then a single aux-model review may keep/patch/consolidate. Jurisdiction: only agent-created skills (created_by:"agent", set by the background self-improvement fork) are fully curated; user-authored, hub, and protected built-ins (e.g. plan) are left alone; pinned:true exempts a skill. [confirmed: curator.md, skill_usage.py]

The layered memory model

Two additive layers, never mutually exclusive [confirmed: memory.md, memory-providers.md]:

  1. Markdown core (always on) — MEMORY.md + USER.md (bounded, §-delimited, frozen snapshot), plus session search over state.db (SQLite + FTS5) as the unbounded on-demand recall tier.
  2. Pluggable external provider (≤1 active, runs alongside the core) — 8 plugins in plugins/memory/ (honcho, mem0, hindsight, holographic, openviking, retaindb, byterover, supermemory), each a folder with plugin.yaml + __init__.py + README.md. Selected via memory.provider: in config.yaml. Local-first (holographic = SQLite+FTS5+HRR) through cloud knowledge-graph (honcho, mem0, supermemory).

Mental model: core = small/fast/always-present curated facts; session search = unbounded raw recall; provider = optional semantic/graph long-term layer. None replaces the markdown files.

Usage & best practices in the wild

  • Deployment: one-line curl|bash (or PowerShell installer on Windows — native Windows is supported per the official FAQ, contradicting one stale third-party review). Runs local / Docker / SSH / Modal / Termux. Signature shape = long-lived gateway daemon bridging chat platforms; multi-user via allowlists + DM pairing. [confirmed: faq.md, quickstart.md]
  • Canonical workflows: scheduled daily-briefing bot (cron → 8am Telegram digest), GitHub PR-review agent, team chat assistant, batch trajectory generation, named "digital twin" assistants. [confirmed: guides]
  • Memory discipline: keep entries dense and near the char caps for realism; consolidate above ~80%; duplicate entries auto-rejected; a security scan blocks prompt-injection / credential / invisible-Unicode content; memory.write_approval:true stages background-review writes for /memory pending. [confirmed: memory.md]
  • Skills in practice: the agent authors its own via skill_manage (create/patch[preferred]/ edit/delete) after complex tasks, error recovery, or user corrections. Mature libraries are category-organized (mlops, creative, github, productivity, research, software-development, devops, finance, security, autonomous-ai-agents…). Sharing via "taps" (GitHub repos of SKILL.md dirs), skills.sh, .well-known/skills/index.json; default taps include openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills. [confirmed: skills.md, curator.md]

Flavor & quirks (cheek fuel)

  • Self-aware dogfood culture: a bundled dogfood skill (the agent QA-testing web apps) + an dogfood-adversarial-ux-test — it literally ships skills for testing itself. [confirmed]
  • Personality as a swappable layer: SOUL.md = durable identity; /personality = temporary overlay. Real presets include helpful, concise, technical, teacher and joke ones: kawaii ★, catgirl (nya~), pirate (Captain Hermes), uwu, noir, surfer, hype. [confirmed: personality.md]
  • "Ralph loop" /goal: a standing goal where an aux judge model decides done/continue each turn (20-turn budget). UI: ⊙ Goal set, ↻ Continuing toward goal (3/20): …, ✓ Goal achieved. Openly credits Codex CLI's /goal. [confirmed: goals.md]
  • Curator quirk: when no agent-created skills exist, reports show Model: (not resolved) … Duration: 0s — a cheeky empty-run line. [confirmed: curator.md]
  • Community rivalry with "OpenClaw" (framed: "your agent under your rules" vs. Hermes "shaped by accumulated workflows"); there's an openclaw-migration skill. [inferred/promotional]

What we'll emulate for the kingdom (distilled blueprint)

A believable fictional ~/.hermes/ corpus (all original in-world content) wants:

  1. Root identity + config — SOUL.md (voice), config.yaml (memory:/curator:/skills:/ auxiliary: blocks), AGENTS.md (project context). A .env stub is optional flavor.
  2. memories/MEMORY.md + USER.md — plain markdown, entries split by § lines, packed dense near the 2,200 / 1,375-char feel. No frontmatter.
  3. skills/<category>/<skill>/SKILL.md across diverse domains, full frontmatter (metadata.hermes nest), ## When to use/## Workflow/## Pitfalls/## Verification body, a ## Tools Reference table, and real sibling references//templates//scripts/. Per-category DESCRIPTION.md (frontmatter-only).
  4. Curator artifacts — skills/.usage.json (exact schema, a couple marked created_by:"agent"), .bundled_manifest, a .archive/<old-skill>/, a .curator_backups/<utc-iso>/ stub, and logs/curator/<ts>/REPORT.md narrating an active→stale→archived transition + an LLM consolidation.
  5. Plans & bundles — a few plans/YYYY-MM-DD_HHMMSS-<slug>.md, a skill-bundles/<slug>.yaml.
  6. Layered-memory hint — config.yaml memory.provider: holographic + a plugins/memory/holographic/ plugin.yaml stub.

Believability levers: the § delimiter, the metadata.hermes frontmatter nest, the frontmatter-only DESCRIPTION.md, and especially the dot-prefixed curator sidecars (.usage.json, .bundled_manifest, .archive/, .curator_backups/) — the hidden-file mechanics are what make it read as a self-improving store rather than a static skills folder.

Viewer note / open design point: Kingdom.md's tree ignores all dotfiles, so the curator sidecars (.usage.json, .archive/, .hub/…) and .env would be hidden in the rendered kingdom — which both (a) accurately demos the dotfile-ignore filter and (b) means the "self-improving machinery" is invisible unless we surface a visible curator artifact (e.g. the logs/curator/<ts>/REPORT.md, which is not dotted). Decide at author time how much of the curator story to tell through visible files.

Sources

Primary (verbatim from repo main / official docs): github.com/NousResearch/hermes-agent; website/docs/user-guide/features/{memory,skills,curator,context-files,goals,personality,kanban}.md; website/docs/reference/faq.md; hermes-agent.nousresearch.com/docs/; and the local clone at C:\Projects\_research-clones\hermes-agent (read directly for code paths and skill examples).

Third-party (flavor / adoption / criticism — lower confidence): turingpost.com/p/hermes; aibuilderclub.com Hermes review; github.com/SamurAIGPT/awesome-hermes-agent.