Hermes Production Patterns¶

A production engineering system for building reliable Hermes Agents.
Reliable. Observable. Recoverable. Evolvable.
Built on Harness Engineering methodology + Loop Engineering + 12-Factor Agents

📖 Introduction¶

Hermes Production Patterns is a production engineering system that turns Hermes Agent from a chat toy into a 7×24 autonomous production system.

🚀 v2.0.0 (2026-08-31) Productization Phase: upgraded from Pattern Library to Production Engineering System — 6 Starter Kits (starter-kits/), 5 official Production Stacks (stacks/), 10-Minute Quick Start (quickstart.md), 7 Production Recipes (recipes/), Production Audit + Readiness Score (audit/), Compatibility Matrix (compatibility/), and the hpp CLI (cli/: init/add/validate/audit/doctor). The goal is no longer More Patterns — it is MAKE PATTERNS USABLE.

🆕 2026-09 — synced with the latest Hermes capabilities: browser automation (browser_navigate/snapshot/click/vision/console), messaging gateway (QQ official Bot via platforms.qqbot), multimodal output (image_generate for diagrams + text_to_speech), enhanced retrieval (zg/hybrid_retrieve, three-layer + RRF). Every capability has a verified run in a real environment (examples/capability-verification-2026-09.md), and the capability map is bumped to v1.4.0. See CHANGELOG v2.2.0.

You've installed Hermes. Now what? If you're struggling with:

Writing reliable Skills that don't drift over time
Cron jobs that silently produce garbage instead of failing loudly
Agent output quality that requires constant human babysitting
Task state that evaporates the moment the session ends
Error traces that flood the context window and derail the agent

This project is for you.

These aren't armchair best practices — every pattern here has been battle-tested in real 7×24 production runs, broken, fixed, and hardened into reusable conventions.

🧪 v1.04.00 (2026-08-27): Added the regression re-test suite test-prompts.json — 30 trap-style prompts covering all 19 behavioral-contract patterns (capability-map is a reference table, exempt), each with assertions (must hit) / forbidden (must not touch); skill-evolution bumped to v1.3.0 documenting when/how to run. Acceptance bar for any skill upgrade = old failures never return + old successes still hold. See CHANGELOG.

🇨🇳 中文版 also available.

See a Pattern in 30 Seconds¶

Take Error Compact (conventions/error-compact-pattern.md) as an example — no setup needed, just before vs after:

❌ Before (raw error floods the context window):

Error: ModuleNotFoundError: No module named "requests"
Traceback (most recent call last):
  File "/usr/lib/python3.11/runpy.py", line 196, in _run_module_as_main
    ...(30 lines of stack trace)
ModuleNotFoundError: No module named "requests"

✅ After (compressed into a one-line structured summary):

[STEP_FAILED] fetch_data@2026-08-28T10:00:00
  Error: ModuleNotFoundError - "requests" package not installed
  Hint: pip install requests
  Recoverable: YES

One pattern, one problem solved. All 15 conventions are in the conventions/ directory.

Why This Project¶

The Hermes community is full of "how to install" guides, but there's almost nothing about "how to run it reliably in production." This project fills that gap by providing:

Problem	Solution
Skills drift and degrade over time	`conventions/skill-evolution.md` — systematic ADD/DELETE/REPLACE cycle
No separation between generation and verification	`conventions/maker-checker.md` — two independent agents
Task state lost between sessions	`conventions/state-file-pattern.md` — STATE.md with atomic writes
LLM calls used for everything (expensive)	`conventions/control-flow-separation.md` — code for known paths, LLM for decisions
Raw errors flood agent context	`conventions/error-compact-pattern.md` — compacted, categorized, actionable
No maturity progression for new automations	`patterns/maturity-staging-l1-l2-l3.md` — L1 report → L2 assisted → L3 autonomous

Project Structure¶

hermes-production-patterns/
├── conventions/                 ← Engineering conventions (core)
│   ├── maker-checker.md         — Generate / verify dual-role separation
│   ├── state-file-pattern.md    — STATE.md cross-run state management
│   ├── control-flow-separation.md — Deterministic vs LLM control flow
│   ├── error-compact-pattern.md — Error compression, classification & self-heal
│   ├── skill-evolution.md       — Skill versioning & lifecycle management
│   ├── cron-job-pattern.md      — Cron idempotency & silent-failure prevention
│   ├── checkpoint-pattern.md    — Long-running task checkpoint recovery
│   ├── secret-management.md     — Secret storage & rotation
│   ├── anti-patterns.md         — 💡 Anti-patterns & corrections
│   ├── pattern-composition.md   — 🧩 Scenario→pattern decision tree
│   ├── state-schema.json        — 📐 STATE.md JSON Schema (programmatic validation)
│   ├── data-driven-optimization.md — 📊 Data-driven skill iteration from real analytics
│   ├── hermes-capability-map.md — 🗺️ Hermes capability × pattern mapping (2026-09, v1.4.0)
│   ├── self-update-pattern.md — 🔄 Safe self-update: autostash recovery, test-failure baseline, rollback
│   ├── memory-os-pattern.md — 🧠 Cognitive memory: 5-layer memory + vector/graph/RRF retrieval
│   └── evolution-gate.md — 📈 Evolution gate: G1-G5 + weighted 5-dim scoring + regression Deploy/Rollback
│
├── templates/                   ← Reusable file templates
│   ├── SKILL.md.template
│   ├── STATE.md.template
│   └── AGENTS.md.template
│
├── patterns/                    ← Design patterns & methodology
│   ├── loop-engineering-14-steps.md       — From prompter to loop designer
│   ├── 12-factor-agents-for-hermes.md     — 12 principles mapped to Hermes
│   ├── maturity-staging-l1-l2-l3.md       — L1→L2→L3 rollout protocol
│   └── maturity-checklist.md              — Readiness checklist
│
├── examples/                    ← Runnable examples
│   ├── daily-news-digest/       — SKILL.md + STATE.md + test_example.py
│   ├── cron-safety/             — Cron + safety integration walkthrough
│   ├── maker-checker-pipeline/  — Article production pipeline demo
│   ├── wechat-article-pipeline.md   — WeChat writing + AI-detect + diagram pipeline
│   └── wechat-article-pipeline/ — Scripts (ai_detect.py) + templates
│
├── scripts/                     ← Validation & automation
│   ├── validate_state.py        — STATE.md schema compliance checker
│   ├── atomic_state_write.py    — Atomic writes with file locking
│   └── check_maturity.py        — L1→L2→L3 checklist runner (JSON output)
│
└── ARCHITECTURE.md              — System architecture, data flow, observability

Three Design Principles¶

1. Harness Engineering — The Repository is the Source of Truth¶

The repo itself is a Harness Engineering case study. AGENTS.md is the entry point for any AI reading your project. Each conventions/ file is an executable skill. Templates are instantiable prototypes.

2. Loop Engineering — From Prompts to Systems¶

Don't hand-write every prompt. Design an autonomous loop that discovers work → dispatches it to the agent → verifies the result → records state → decides next move.

3. 12-Factor Agents — Reliability by Design¶

Each engineering principle maps to a concrete decision:

Factor	Convention
2 — Own your prompts	Write SKILL.md, not ad-hoc prompts
5 — Unify state	STATE.md with atomic writes + file locking
7 — Human-in-loop	Maker/Checker dual-role separation
8 — Own control flow	Deterministic code paths + LLM paths, separate
9 — Compact errors	Categorized, compressed, recoverable

Quick Start¶

git clone https://github.com/Komagon/hermes-production-patterns.git
cd hermes-production-patterns

Copy conventions to your Hermes skills directory:

# ── Linux / macOS ──
mkdir -p ~/.hermes/skills/conventions
cp conventions/* ~/.hermes/skills/conventions/

# ── Windows (PowerShell) ──
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\AppData\Local\hermes\skills\conventions"
Copy-Item -Path conventions\* -Destination "$env:USERPROFILE\AppData\Local\hermes\skills\conventions\"

Create your first Skill from a template:

# Unix
cp templates/SKILL.md.template ~/.hermes/skills/my-skill/SKILL.md

Add STATE.md to a cron job:

cp templates/STATE.md.template reports/my-cron-job/STATE.md

Configure Hermes:

cp config.yaml.example ~/.hermes/config.yaml
# Replace YOUR_xxx_HERE with your actual API keys

Environment Variables¶

Variable	Purpose	Required
`HERMES_API_KEY`	Hermes API authentication	Yes
`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`	LLM provider	Depends on provider
`FAL_KEY`	Image generation (FAL.ai)	Optional
`MINERU_API_KEY`	PDF parsing (MinerU)	Optional
`GITHUB_TOKEN`	GitHub API operations	Optional (auto-injected in CI)

# Unix / macOS
export HERMES_API_KEY="your-key-here"

# Windows (PowerShell)
$env:HERMES_API_KEY = "your-key-here"

Quick Reference¶

Concept	File	One-liner
Maker/Checker	`conventions/maker-checker.md`	The agent that writes and the agent that verifies are never the same
STATE.md	`conventions/state-file-pattern.md`	Read state before run, write state after every step
Control Flow	`conventions/control-flow-separation.md`	Use code for anything expressible as a rule
Error Compaction	`conventions/error-compact-pattern.md`	Compress errors to one line, never flood the context
Skill Evolution	`conventions/skill-evolution.md`	ADD / DELETE / REPLACE your skills systematically
Loop Engineering	`patterns/loop-engineering-14-steps.md`	Check if it's worth building, then design it right
Maturity Staging	`patterns/maturity-staging-l1-l2-l3.md`	L1 reports only → L2 assisted → L3 autonomous
12-Factor Map	`patterns/12-factor-agents-for-hermes.md`	12 principles mapped to Hermes conventions
🗺️ Capability Map	`conventions/hermes-capability-map.md`	Map new Hermes capabilities onto existing patterns (2026-09, v1.4.0)
🔄 Safe Self-Update	`conventions/self-update-pattern.md`	Snapshot → verify stash → test-failure baseline → rollback
🧠 Memory OS	`conventions/memory-os-pattern.md`	5-layer memory + 3-way retrieval (vector/graph/RRF) + write discipline
📈 Evolution Gate	`conventions/evolution-gate.md`	G1-G5 gates + weighted 5-dim scoring + regression Deploy/Rollback

References & Credits¶

Core Frameworks¶

Project	Description
Hermes Agent — Nous Research	The self-evolving agent framework this project builds upon
12-Factor Agents — HumanLayer	12 engineering principles for reliable agents
Loop Engineering — @0xCodez (Lev Deviatkin, Anthropic)	14-step roadmap from prompter to loop designer
Harness Engineering — garrytan	Methodology for reliable agent execution

Extended Reading¶

Resource	Description
Addy Osmani — Loop Engineering	Systematic article on loop engineering
AlphaSignal — 4-Condition Test	"Most developers don't need agent loops yet"
Anthropic — Recursive Self-Improvement	Boundaries of agent self-improvement
Geoffrey Huntley — Agentic Loop Failures	Production loop failure case studies
CB Insights — AI Agent Bible	69-page AI Agent landscape report
Google Cloud — AI Agent Trends 2026	Enterprise agent deployment trends
Microsoft SkillOpt	Automated skill document optimization

Document Mapping¶

File	Based On
`conventions/maker-checker.md`	12-Factor Agents Factor 7 + Loop Engineering Step 9
`conventions/state-file-pattern.md`	12-Factor Agents Factor 5 + Loop Engineering Step 10
`conventions/control-flow-separation.md`	12-Factor Agents Factor 8
`conventions/error-compact-pattern.md`	12-Factor Agents Factor 9
`conventions/skill-evolution.md`	Microsoft SkillOpt training loop
`patterns/loop-engineering-14-steps.md`	@0xCodez Loop Engineering
`patterns/12-factor-agents-for-hermes.md`	HumanLayer 12-Factor Agents
`patterns/maturity-staging-l1-l2-l3.md`	cron-scheduler + task-safety production experience

Prerequisites¶

Hermes Agent v0.6+
Obsidian (optional, for knowledge management)
Git (for versioning skill files)

License¶

MIT — free to use, modify, and distribute.

Contributing¶

PRs and Issues welcome. Core principle: every pattern must have been validated in a production environment — purely theoretical designs are not accepted.

See CONTRIBUTING.md for guidelines.