Chapter 1 Architecture Overview

Understanding the internal architecture of Hermes Agent is the foundation for customization and extension. This chapter gives you a bird's-eye view of the entire system.

System Architecture Diagram

┌───────────────────────────────────────────────────┐
│                   Entry Layer                      │
│                                                    │
│   CLI (cli.py)  ──  Gateway (gateway/)  ──  ACP   │
│   Batch runner      API Server         Python lib  │
└──────┬──────────────┬──────────────────┬──────────┘
       │              │                  │
       ▼              ▼                  ▼
┌───────────────────────────────────────────────────┐
│              AIAgent (run_agent.py)                │
│              Core Conversation Loop                │
│                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Prompt   │  │ Provider │  │  Tool    │        │
│  │ Builder  │  │ Resolver │  │ Dispatch │        │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘        │
│       │              │              │              │
│  ┌────┴─────┐  ┌────┴─────┐  ┌────┴─────┐        │
│  │Compress  │  │3 API modes│  │Tool Registry│     │
│  │& Cache   │  │chat/codex │  │ 47+ tools   │     │
│  │          │  │/anthropic │  │ 20 toolsets │     │
│  └──────────┘  └──────────┘  └──────────┘        │
└───────────────────────────────────────────────────┘
       │                              │
       ▼                              ▼
┌──────────────┐              ┌──────────────┐
│Session Store │              │ Tool Backends│
│ SQLite+FTS5  │              │ Terminal(6)  │
│              │              │ Browser      │
│              │              │ File         │
│              │              │ Web          │
│              │              │ Cron         │
└──────────────┘              └──────────────┘

---

Core Subsystems

1. Agent Loop (Core Loop)

The Agent Loop is the heart of Hermes, located in run_agent.py (~9,200 lines). It is a synchronous orchestration engine that handles:

• Provider selection and fallback
• Prompt construction and maintenance
• Tool execution and result processing
• Retry and error handling
• Context compression
• Session persistence

Workflow:

User Message → Prompt Construction → LLM Call → Parse Response
                                                    ↓
                                              Has tool call?
                                              ├─ Yes → Execute tool → Add result to context → Call LLM again
                                              └─ No → Return text response → Done

2. Provider Resolution (Model Routing)

A shared runtime resolver used by CLI, Gateway, Cron, and ACP alike.

• Supports 18+ providers
• Three API modes: chat_completion, codex_response, anthropic
• OAuth flow handling
• Credential Pool (multi-key rotation)
• Alias resolution (e.g., zai = glm)

3. Tool System

The central tool registry is located at tools/registry.py:

• 47 registered tools across 20 toolsets
• Each tool file self-registers on import
• Supports 6 terminal backends (local, Docker, SSH, Daytona, Modal, Singularity)
• Schema collection, dispatch, availability checks

4. Session Storage

Based on SQLite + FTS5 full-text search:

• Sessions have lineage tracking (parent-child relationship across compressions)
• Platform-isolated
• Atomic writes and concurrency handling

5. Messaging Gateway

A long-running process that includes:

• 14 platform adapters
• Unified session routing
• User authorization (Allowlist + DM pairing)
• Slash command dispatch
• Hook system
• Cron scheduling checks
• Background maintenance tasks

6. Plugin System

Three discovery sources:

• ~/.hermes/plugins/ (user-level)
• .hermes/plugins/ (project-level)
• pip entry points

Two specialized plugin types:

• Memory Provider: External memory services (Honcho, Mem0, etc.)
• Context Engine: Context processing engine

---

Directory Structure

hermes-agent/
├── run_agent.py              # AIAgent core loop (~9,200 lines)
├── cli.py                    # CLI interactive interface (~8,500 lines)
├── model_tools.py            # Tool discovery, schema collection, dispatch
├── toolsets.py               # Toolset grouping & platform presets
├── hermes_state.py           # SQLite session/state database
├── hermes_constants.py       # HERMES_HOME, Profile paths
│
├── agent/                    # Agent internal modules
│   ├── prompt_builder.py     # System prompt assembly
│   ├── context_compressor.py # Context compression
│   ├── auxiliary_client.py   # Auxiliary LLM calls
│   ├── memory_manager.py     # Memory management
│   └── ...
│
├── hermes_cli/               # CLI subcommands
│   ├── main.py               # All hermes subcommands
│   ├── config.py             # Default configuration
│   ├── commands.py           # Slash command registration
│   ├── auth.py               # Provider authentication
│   └── ...
│
├── tools/                    # Tool implementations
│   ├── registry.py           # Tool registry
│   ├── terminal.py           # Terminal tools
│   ├── browser.py            # Browser tools
│   └── ...
│
├── gateway/                  # Messaging gateway
│   ├── run.py                # Gateway entry point
│   ├── adapters/             # Platform adapters
│   └── ...
│
└── plugins/                  # Plugin system
    ├── memory/               # Memory provider plugins
    └── context_engine/       # Context engine plugins

---

Design Principles

Hermes Agent follows several core design principles:

1. Self-Registration Pattern

Tools automatically register on import. Adding a new tool only requires:

1. Creating the tool file
2. Adding the import in model_tools.py's _discover_tools()

2. Configuration-Driven

Behavior is determined by configuration, not code. Most customization can be done through config.yaml and .env.

3. Fail-Safe

All critical operations follow the fail-closed principle:

• Approval timeout → Deny
• API failure → Fallback to fallback model
• Session write → Atomic operation

4. Progressive Complexity

• Beginner: Run with default configuration
• Intermediate: Modify config.yaml
• Advanced: Develop custom Skills
• Expert: Write plugins, modify source code

---

Data Flow

CLI Interaction Flow

User Input → cli.py → AIAgent → Prompt Builder
                                    ↓
                            LLM API Call
                                    ↓
                          Parse Tool Calls
                                    ↓
                        Tool Registry Lookup
                                    ↓
                          Execute Tool → Return Result
                                    ↓
                        Add to Context → Call LLM Again
                                    ↓
                        Final Response → Display to User
                                    ↓
                        Session Storage Persistence

Gateway Message Flow

Platform Message → Adapter → Gateway Router → User Authorization Check
                                                    ↓
                                              Session Lookup/Creation
                                                    ↓
                                                AIAgent Processing
                                                    ↓
                                          Response → Adapter → Platform

---

Recommended Reading Order

If you want to dive into the source code, we suggest this order:

1. Architecture (this chapter) — Build a big-picture view
2. Agent Loop Internals — Understand the core loop
3. Prompt Assembly — Understand context construction
4. Tool System — Understand tool registration and execution
5. Gateway Internals — Understand message routing
6. Session Storage — Understand data persistence

Further Reading

• Official Architecture Docs
• Agent Loop Internals

---