Understand the 24 core mechanisms of Hermes Agent v0.19.0, one chapter at a time
This is an independent teaching companion for Hermes Agent, aligned with v0.19.0 (2026-07-20) and its current multi-platform, self-improving, profile-isolated, multi-agent, durable-delivery architecture.
Instead of reading the source directly:
- Each core mechanism is isolated into one chapter
- Layer 1 (h01–h06) provides runnable minimal teaching implementations (Python + OpenAI SDK)
- Layer 2–4 (h07–h19) explains curated source mechanisms
- Layer 5 (h20–h24) covers the current v0.19 production architecture
Warning
This repository contains educational implementations, not production-ready agent code. Some runnable chapters intentionally let the model invoke local shell commands so the agent loop remains easy to inspect. Do not run them with untrusted prompts or in a privileged environment.
- Use a disposable workspace, least-privilege account, and constrained API key.
- Never reuse production secrets in the examples.
- Review tool calls before execution and add sandboxing/allowlists for any real deployment.
- For production use, prefer the official Hermes Agent runtime and its approval, permission, and isolation controls.
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your HERMES_BASE_URL / HERMES_API_KEY / HERMES_MODEL
python agents/h01_agent_loop.py| # | Chapter | Core Addition |
|---|---|---|
| h01 | Agent Loop | while loop + tool_result feedback |
| h02 | Tool System | ToolRegistry — schema/handler separation |
| h03 | Planning & Todos | Agent-level tool interception + PlanState |
| h04 | Prompt Assembly | PromptBuilder — 5-layer dynamic assembly |
| h05 | Context Compression | Preflight compression + lineage_id |
| h06 | Session Storage | SQLite + FTS5 full-text search |
| h07 | Memory System | MEMORY.md flush + deduplication |
| h08 | Skills System | Skill injection as user message |
| h09 | Approval & Permission | DangerPattern interception pipeline |
| h10 | Error Recovery | fallback_providers chain |
| h11 | CLI Architecture | COMMAND_REGISTRY → multi-platform dispatch |
| h12 | Gateway System | GatewayRunner + platform adapters |
| h13 | Cron Scheduler | jobs.json + skill attachment |
| h14 | Hook System | pre/post_tool_call lifecycle |
| h15 | Subagent Delegation | Shared IterationBudget across agents |
| h16 | Provider Runtime | (provider, model) → api_mode mapping |
| h17 | MCP Integration | Dynamic tool discovery + shared registry |
| h18 | Plugin System | PluginContext API |
| h19 | RL & Trajectories | ShareGPT trajectory generation + filtering |
| h20 | Profile Isolation | HERMES_HOME identity and state boundary |
| h21 | Multi-Agent Kanban | Task graph, worker lanes, worktrees, recovery |
| h22 | ACP & Surfaces | CLI / Desktop / Gateway / IDE share AIAgent |
| h23 | Smart Security | Smart approvals, user deny, SecretSource |
| h24 | Durable Delivery | Obligation ledger, acknowledgement, recovery |
| Variable | Description | Example |
|---|---|---|
HERMES_BASE_URL |
OpenAI-compatible API base URL | https://api.openai.com/v1 |
HERMES_API_KEY |
API key | sk-... |
HERMES_MODEL |
Model name | gpt-4o |