website/docs/developer-guide/architecture.md

metadata

sidebar_position: 1
title: Architecture
description: >-
  Hermes Agent internals — major subsystems, execution paths, and where to read
  next

Architecture

This page is the top-level map of Hermes Agent internals. The project has grown beyond a single monolithic loop, so the best way to understand it is by subsystem.

High-level structure

hermes-agent/
├── run_agent.py              # AIAgent core loop
├── cli.py                    # interactive terminal UI
├── model_tools.py            # tool discovery/orchestration
├── toolsets.py               # tool groupings and presets
├── hermes_state.py           # SQLite session/state database
├── batch_runner.py           # batch trajectory generation
│
├── agent/                    # prompt building, compression, caching, metadata, trajectories
├── hermes_cli/               # command entrypoints, auth, setup, models, config, doctor
├── tools/                    # tool implementations and terminal environments
├── gateway/                  # messaging gateway, session routing, delivery, pairing, hooks
├── cron/                     # scheduled job storage and scheduler
├── honcho_integration/       # Honcho memory integration
├── acp_adapter/              # ACP editor integration server
├── acp_registry/             # ACP registry manifest + icon
├── environments/             # Hermes RL / benchmark environment framework
├── skills/                   # bundled skills
├── optional-skills/          # official optional skills
└── tests/                    # test suite

Recommended reading order

If you are new to the codebase, read in this order:

1. this page
2. Agent Loop Internals
3. Prompt Assembly
4. Provider Runtime Resolution
5. Adding Providers
6. Tools Runtime
7. Session Storage
8. Gateway Internals
9. Context Compression & Prompt Caching
10. ACP Internals
11. Environments, Benchmarks & Data Generation

Major subsystems

Agent loop

The core synchronous orchestration engine is AIAgent in run_agent.py.

It is responsible for:

• provider/API-mode selection
• prompt construction
• tool execution
• retries and fallback
• callbacks
• compression and persistence

See Agent Loop Internals.

Prompt system

Prompt-building logic is split between:

• run_agent.py
• agent/prompt_builder.py
• agent/prompt_caching.py
• agent/context_compressor.py

See:

• Prompt Assembly
• Context Compression & Prompt Caching

Provider/runtime resolution

Hermes has a shared runtime provider resolver used by CLI, gateway, cron, ACP, and auxiliary calls.

See Provider Runtime Resolution.

Tooling runtime

The tool registry, toolsets, terminal backends, process manager, and dispatch rules form a subsystem of their own.

See Tools Runtime.

Session persistence

Historical session state is stored primarily in SQLite, with lineage preserved across compression splits.

See Session Storage.

Messaging gateway

The gateway is a long-running orchestration layer for platform adapters, session routing, pairing, delivery, and cron ticking.

See Gateway Internals.

ACP integration

ACP exposes Hermes as an editor-native agent over stdio/JSON-RPC.

See:

• ACP Editor Integration
• ACP Internals

Cron

Cron jobs are implemented as first-class agent tasks, not just shell tasks.

See Cron Internals.

RL / environments / trajectories

Hermes ships a full environment framework for evaluation, RL integration, and SFT data generation.

See:

• Environments, Benchmarks & Data Generation
• Trajectories & Training Format

Design themes

Several cross-cutting design themes appear throughout the codebase:

• prompt stability matters
• tool execution must be observable and interruptible
• session persistence must survive long-running use
• platform frontends should share one agent core
• optional subsystems should remain loosely coupled where possible

Implementation notes

The older mental model of Hermes as “one OpenAI-compatible chat loop plus some tools” is no longer sufficient. Current Hermes includes:

• multiple API modes
• auxiliary model routing
• ACP editor integration
• gateway-specific session and delivery semantics
• RL environment infrastructure
• prompt-caching and compression logic with lineage-aware persistence

Use this page as the map, then dive into subsystem-specific docs for the real implementation details.