AGENTS.md — ESRA Integration for Hermes

Goal: Make Hermes improvement work systematic, value-aligned, observable, and evidence-driven through the Evolutionary Self-Recursive Architecture (ESRA) meta-layer.

Official architecture name: ESRA — Evolutionary Self-Recursive Architecture
Specification repository: https://github.com/rrpauls/esra
This repository: Concrete Hermes implementation of ESRA

Core Rule

After a major architecture or skill change, repeated failure, or an explicit full-cycle request, evaluate whether to run one bounded hermes-evolution-orchestrator review. Routine successful work should not trigger a full cycle.

A recommendation from evolution_hook.py does not execute a cycle. The caller must explicitly activate the orchestrator.

Install layout (where things live)

After ./install.sh, Hermes home looks like:

$HERMES_HOME/                         # default: ~/.hermes
├── AGENTS.md                         # this file
├── skills/esra/                      # meta-skills (Hermes skill discovery)
│   ├── esra-runtime/                 # documents tool paths for the agent
│   ├── hermes-evolution-orchestrator/
│   └── …
└── esra/                             # ESRA runtime package (not a skill)
    ├── manifest.json                 # machine-readable paths and protocol version
    ├── conformance.json              # evidence-backed capability declaration
    └── tools/                        # Python CLIs — use these paths

Override roots with $HERMES_HOME and/or $ESRA_HOME if set.

Always run tools by installed absolute path (do not depend on a git clone or cwd):

python ~/.hermes/esra/tools/evolution_hook.py
python ~/.hermes/esra/tools/evolution_hook.py --force-cycle
python ~/.hermes/esra/tools/skill_validator.py --verbose --skills-dir ~/.hermes/skills/esra
python ~/.hermes/esra/tools/evolution_dashboard.py

If unsure, activate the esra-runtime skill or open ~/.hermes/esra/manifest.json.

How to Run the Orchestrator

Recommended Triggers

After this task, run hermes-evolution-orchestrator

orchestrate evolution

run full ESRA cycle

improve the self-development cycle

perform evolutionary audit of this task

Smart Triggering via evolution_hook.py

The helper at ~/.hermes/esra/tools/evolution_hook.py analyzes supplied task context and local evolution history and recommends whether the caller should launch the orchestrator.

Callers that preserve lifecycle state must pass origin, root_task_id, and cycle_depth. origin=esra, any cycle_depth > 0, or a second recommendation for the same root_task_id is rejected before all trigger heuristics, including forced or explicit requests. Post-task results are fail-closed: only explicit success: true is success, and declared artifact paths must exist, be non-empty, and have a valid image envelope when applicable.

Capabilities:

• Considers task complexity, new skill creation, and result confidence
• Includes rate limiting
• Analyzes historical patterns
• Produces a recommendation and prompt; it is not a native Hermes event hook

Usage:

python ~/.hermes/esra/tools/evolution_hook.py
python ~/.hermes/esra/tools/evolution_hook.py --force-cycle

Decision Structuring

For any uncertainty or important decision, run ooda-framework (optionally with related meta-skills such as self-observer, value-clarifier, or loop-auditor).

Periodic Audit

Every 5–10 recorded significant cycles, or after an anomaly, explicitly run the audit. If cycle history is unavailable, report cadence as unknown:

Run loop-auditor to audit the current evolutionary cycle

Installed ESRA Components

Meta-skills

All skills live in: ~/.hermes/skills/esra/

Supporting tools (~/.hermes/esra/tools/)

Installation

From the root of this repository:

chmod +x install.sh
./install.sh

This installs:

1. Meta-skills → ~/.hermes/skills/esra/ (including esra-runtime)
2. Tools package → ~/.hermes/esra/tools/
3. Manifest → ~/.hermes/esra/manifest.json
4. Conformance declaration → ~/.hermes/esra/conformance.json
5. This file → ~/.hermes/AGENTS.md

Respects $HERMES_HOME / $ESRA_HOME when set.

Philosophy

• Hermes provides a powerful engine for self-improvement.
• ESRA provides the steering, brakes, navigation, and audit system.
• hermes-evolution-orchestrator is the mechanism that connects them.
• Skills are discovered by Hermes; tools are a package under Hermes home, advertised by esra-runtime.

The goal is not merely to add skills, but to make the evolution process itself recursive and self-improving.

Relationship to the ESRA Specification

This repository implements ESRA for Hermes.
The pure conceptual and technical description of the architecture (principles, 8 levels, Loop Execution Protocol) lives in the separate repository:

→ https://github.com/rrpauls/esra

Version: 1.3 Date: 28 July 2026
Compatible with: Hermes Agent + ESRA (Evolutionary Self-Recursive Architecture)