website/docs/developer-guide/architecture.md

---
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

```text
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](./agent-loop.md)
3. [Prompt Assembly](./prompt-assembly.md)
4. [Provider Runtime Resolution](./provider-runtime.md)
5. [Adding Providers](./adding-providers.md)
6. [Tools Runtime](./tools-runtime.md)
7. [Session Storage](./session-storage.md)
8. [Gateway Internals](./gateway-internals.md)
9. [Context Compression & Prompt Caching](./context-compression-and-caching.md)
10. [ACP Internals](./acp-internals.md)
11. [Environments, Benchmarks & Data Generation](./environments.md)

## 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](./agent-loop.md).

### 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](./prompt-assembly.md)
- [Context Compression & Prompt Caching](./context-compression-and-caching.md)

### Provider/runtime resolution

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

See [Provider Runtime Resolution](./provider-runtime.md).

### Tooling runtime

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

See [Tools Runtime](./tools-runtime.md).

### Session persistence

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

See [Session Storage](./session-storage.md).

### Messaging gateway

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

See [Gateway Internals](./gateway-internals.md).

### ACP integration

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

See:

- [ACP Editor Integration](../user-guide/features/acp.md)
- [ACP Internals](./acp-internals.md)

### Cron

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

See [Cron Internals](./cron-internals.md).

### RL / environments / trajectories

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

See:

- [Environments, Benchmarks & Data Generation](./environments.md)
- [Trajectories & Training Format](./trajectory-format.md)

## 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.