File size: 5,055 Bytes
9aa5185 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | ---
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.
|