Architecture Overview

Relevant source files

• .env.example
• AGENTS.md
• README.md
• agent/agent_init.py
• agent/agent_runtime_helpers.py
• agent/auxiliary_client.py
• agent/chat_completion_helpers.py
• agent/context_compressor.py
• agent/conversation_compression.py
• agent/conversation_loop.py
• agent/tool_executor.py
• agent/turn_context.py
• cli-config.yaml.example
• cli.py
• contributors/emails/lanyusea@gmail.com
• contributors/emails/miniadmin@skshim-mini.local
• gateway/run.py
• hermes_cli/auth.py
• hermes_cli/commands.py
• hermes_cli/config.py
• hermes_cli/main.py
• hermes_cli/models.py
• hermes_cli/runtime_provider.py
• hermes_cli/setup.py
• run_agent.py
• tests/agent/test_auxiliary_client.py
• tests/agent/test_cjk_token_estimation.py
• tests/agent/test_codex_gpt55_autoraise_notice.py
• tests/agent/test_compression_anti_thrash_persistence.py
• tests/agent/test_compression_concurrent_fork.py
• tests/agent/test_compressor_tool_call_budget.py
• tests/agent/test_context_compressor.py
• tests/agent/test_context_compressor_summary_continuity.py
• tests/agent/test_context_compressor_temporal_anchoring.py
• tests/agent/test_credential_pool_routing.py
• tests/agent/test_idle_compaction_lock_and_guards.py
• tests/agent/test_resume_stale_active_task.py
• tests/agent/test_summary_prefix_semantics.py
• tests/agent/test_summary_prefix_tool_use.py
• tests/agent/test_turn_context.py
• tests/cli/test_cli_interrupt_ack_race.py
• tests/cli/test_cli_shutdown_memory_messages.py
• tests/hermes_cli/test_commands.py
• tests/hermes_cli/test_model_validation.py
• tests/hermes_cli/test_runtime_provider_resolution.py
• tests/run_agent/test_413_compression.py
• tests/run_agent/test_compression_feasibility.py
• tests/run_agent/test_compression_persistence.py
• tests/run_agent/test_credential_pool_interrupt.py
• tests/run_agent/test_identity_flush.py
• tests/run_agent/test_run_agent.py
• tests/test_hermes_state_compression_locks.py
• tests/tools/test_daemon_pool.py
• tools/daemon_pool.py
• website/docs/developer-guide/agent-loop.md
• website/docs/developer-guide/architecture.md
• website/docs/developer-guide/context-compression-and-caching.md
• website/docs/developer-guide/cron-internals.md
• website/docs/developer-guide/gateway-internals.md
• website/docs/reference/tools-reference.md
• website/docs/reference/toolsets-reference.md
• website/docs/user-guide/features/tools.md

Purpose and Scope

This document describes the high-level architecture of the Hermes Agent system, focusing on the three-tier architecture, major subsystems, and their technical interactions. Hermes Agent is an AI agent framework designed with self-improvement capabilities, orchestrating interactions between LLMs, a diverse tool registry, and multiple execution environments. run_agent.py1-21

The architecture is organized into three primary tiers:

1. User Interface Layer: Interactive frontends including the CLI (terminal interface), the Messaging Gateway (platform adapters for Telegram, Discord, etc.), and the Web UI Dashboard. cli.py1-13 gateway/run.py1-14 hermes_cli/main.py1-44
2. Core Agent Layer: The central AIAgent class orchestrates the conversation loop, manages context/memory, and handles tool invocation. run_agent.py17-21 agent/conversation_loop.py1-20
3. Tool & Execution Layer: A modular system of toolsets (terminal, browser, file operations) and an environment abstraction layer that supports local, Docker, SSH, and serverless backends. run_agent.py136-144 tools/terminal_tool.py142-143

---

Core Architecture Components

System Overview Diagram

Sources: run_agent.py17-21 cli.py5-13 gateway/run.py1-14 hermes_cli/config.py1-13 hermes_cli/auth.py1-20 hermes_cli/main.py1-44 agent/conversation_loop.py1-15 agent/context_compressor.py1-17

---

AIAgent: The Central Orchestrator

The AIAgent class in run_agent.py is the primary engine of the system. It encapsulates the logic for the "Think-Act-Observe" loop, managing the state of a single conversation session. run_agent.py5-21

Conversation Orchestration

• Loop Management: The agent executes a tool-calling loop until a final response is generated or the IterationBudget is exhausted. run_agent.py10-14 run_agent.py116-117
• Conversation Loop Logic: The core logic is extracted into agent/conversation_loop.py, which handles model calls, tool dispatching, retries, and post-turn hooks. agent/conversation_loop.py1-15
• Context Scrubbing: It uses sanitize_context to manage message history and handles reasoning/thought blocks (e.g., <think> tags) to prevent leaking internal chain-of-thought into tool inputs. run_agent.py148 agent/conversation_loop.py124-140
• Token Estimation: It utilizes estimate_request_tokens_rough to monitor context window usage and ensure model limits are respected. run_agent.py151-153

Memory and Context

• Memory Management: The agent builds memory context blocks via MemoryManager and manages persistent identity via load_soul_md. run_agent.py159-166 agent/memory_manager.py148-149
• Context Compression: When the context limit is approached, ContextCompressor summarizes past turns to free up space while protecting the most recent messages (the "tail"). run_agent.py157 agent/context_compressor.py1-17
• Auxiliary Client: Side tasks like vision analysis, web extraction, or compression are offloaded to an AuxiliaryClient. This router resolves the best available secondary backend (OpenRouter, Nous Portal, or local endpoints) to avoid interrupting the main conversation flow. agent/auxiliary_client.py1-41

Sources: run_agent.py5-21 run_agent.py148-166 agent/auxiliary_client.py1-41 agent/conversation_loop.py1-15 agent/context_compressor.py1-17

---

Tool System and Execution

Hermes employs a modular tool dispatch system that bridges natural language requests to code execution across isolated environments.

Tool Execution Flow

• Registry: model_tools.py provides the central registry where tools are defined via get_tool_definitions and executed via handle_function_call. run_agent.py136-141
• Guardrails: The system inspects calls for destructive patterns or dangerous commands before execution, often using FailoverReason and classify_api_error to handle execution failures gracefully. agent/conversation_loop.py42-43 agent/error_classifier.py71-75
• Environments: Terminal commands and file operations are managed with specific cleanup routines like cleanup_vm and cleanup_browser to ensure environment stability and resource management. run_agent.py142-144

Sources: run_agent.py136-144 model_tools.py136-141 agent/conversation_loop.py42-43 agent/error_classifier.py71-75

---

Configuration and Authentication

The system uses a hierarchical configuration and a multi-provider authentication store.

Configuration Hierarchy

1. CLI Flags: Highest priority passed during invocation (e.g., --tui, --gateway, --model). cli.py8-13 hermes_cli/main.py5-44
2. config.yaml: User-defined settings in ~/.hermes/config.yaml. hermes_cli/config.py5-6
3. .env: Secrets and API keys in ~/.hermes/.env. hermes_cli/config.py6
4. Defaults: System defaults defined in DEFAULT_CONFIG. hermes_cli/config.py139-140

Authentication Store

The authentication system in hermes_cli/auth.py manages credentials for various providers. It supports:

• OAuth Flows: Device code and external browser-based flows for Nous Portal, OpenAI Codex, xAI, Qwen, and Spotify. hermes_cli/auth.py69-130
• API Keys: Traditional key management for OpenRouter, custom endpoints, and specific providers like Gemini, Z.ai (GLM), or Moonshot (Kimi). hermes_cli/auth.py157-183
• Runtime Resolution: The system handles token refresh automatically for OAuth providers (e.g., XAI_ACCESS_TOKEN_REFRESH_SKEW_SECONDS = 3600). hermes_cli/auth.py110-120
• Persistence: Auth state is persisted in ~/.hermes/auth.json with cross-process file locking. hermes_cli/auth.py4-6

Sources: hermes_cli/config.py1-13 hermes_cli/auth.py1-20 hermes_cli/auth.py69-183 hermes_cli/main.py5-44

---

Messaging Gateway and Interface Layer

The system supports multiple concurrent interfaces managed by specialized runners.

Messaging Gateway

The GatewayRunner in gateway/run.py enables multi-platform support (Telegram, Discord, Slack, etc.).

• Session Caching: It maintains an LRU cache of AIAgent instances (_AGENT_CACHE_MAX_SIZE = 128) to prevent unbounded growth in long-lived gateways. gateway/run.py61-68
• Platform Adapters: Provides entry points for messaging platform integrations through a base BasePlatformAdapter interface. gateway/run.py2-6 gateway/platforms/base.py1-6
• Command Registry: A central command registry defines slash commands (e.g., /new, /model, /usage) shared across the CLI and Gateway. gateway/run.py56-57

CLI and TUI

• REPL: cli.py provides a rich interactive terminal interface using prompt_toolkit. cli.py5-13
• TUI: A React Ink-based interface can be launched via the --tui flag, providing a more graphical terminal experience. hermes_cli/main.py5-44
• Web Dashboard: A FastAPI-based web server provides a dashboard for managing sessions, configuration, and analytics. hermes_cli/main.py5-44

Sources: gateway/run.py1-14 gateway/run.py61-68 gateway/platforms/base.py1-6 hermes_cli/main.py5-44