# hermes-agent-org/hermes architecture

> Architecture diagram of the GitHub repository hermes-agent-org/hermes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hermes-agent-org/hermes
- Repository: https://github.com/hermes-agent-org/hermes

## Overview

Hermes Agent is a multi-provider conversational agent reachable through an interactive CLI or a messaging gateway. A user message enters through one of those interfaces, is handled by the agent loop, and may invoke registered tools before returning a response. The README also describes scheduled delivery, isolated terminal backends, persistent memory and session search, self-improving skills, subagents, and RL-oriented environments. The graph preserves those documented branches; connections among unsampled subsystems are omitted where the excerpts do not establish the caller or data flow.

Main entry points: [`run_agent.py`](https://github.com/hermes-agent-org/hermes/blob/main/run_agent.py) (Agent loop), [`cli.py`](https://github.com/hermes-agent-org/hermes/blob/main/cli.py) (Interactive CLI), [`gateway/run.py`](https://github.com/hermes-agent-org/hermes/blob/main/gateway/run.py) (Messaging gateway), [`hermes_cli/runtime_provider.py`](https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/runtime_provider.py) (Provider resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Interactive CLI<br/>[cli.py]"]
  node_cli_ui["CLI TUI<br/>[curses_ui.py]"]
  node_gateway["Messaging gateway<br/>[run.py]"]
  node_platforms["Messaging platforms<br/>[base.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent_loop["Agent loop<br/>[run_agent.py]"]
  node_providers["Provider resolution"]
  node_model_catalog["Model catalog<br/>[models.py]"]
  node_authentication["Provider authentication<br/>[auth.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tool_api["Tool orchestration<br/>[model_tools.py]"]
  node_tool_registry["Tool registry<br/>[registry.py]"]
  node_terminal["Terminal execution<br/>[terminal_tool.py]"]
  node_mcp["MCP integration<br/>[mcp_tool.py]"]
  node_delegation["Subagent delegation<br/>[delegate_tool.py]"]
end

subgraph group_learning["Memory and learning"]
  node_session_store[("Session state<br/>[hermes_state.py]")]
  node_memory["Persistent memory<br/>[memory_manager.py]"]
  node_skill_manager["Skill management"]
  node_session_search["Session search"]
end

subgraph group_operations["Scheduling and research"]
  node_scheduler["Cron scheduler<br/>[scheduler.py]"]
  node_research_env["Research environments"]
  node_rl_env["RL environments<br/>[agent_loop.py]"]
end

node_user(("User"))

node_user -->|"starts chat"| node_cli
node_user -->|"sends message"| node_gateway
node_cli -->|"renders interface"| node_cli_ui
node_cli -->|"runs turns"| node_agent_loop
node_gateway -->|"connects platforms"| node_platforms
node_gateway -.->|"handles messages"| node_agent_loop
node_agent_loop -->|"dispatches tools"| node_tool_api
node_tool_api -->|"dispatches calls"| node_tool_registry
node_tool_registry -->|"registers tool"| node_terminal
node_agent_loop -.->|"resolves model"| node_providers
node_providers -->|"checks models"| node_model_catalog
node_authentication -->|"supplies credentials"| node_providers
node_agent_loop -.->|"persists sessions"| node_session_store
node_agent_loop -.->|"uses memory"| node_memory
node_agent_loop -->|"creates skills"| node_skill_manager
node_agent_loop -->|"searches history"| node_session_search
node_agent_loop -->|"uses MCP"| node_mcp
node_agent_loop -->|"spawns subagents"| node_delegation
node_scheduler -->|"runs scheduled tasks"| node_agent_loop
node_scheduler -->|"delivers results"| node_platforms
node_research_env -->|"runs research"| node_agent_loop
node_rl_env -.->|"generates trajectories"| node_agent_loop

click node_cli "https://github.com/hermes-agent-org/hermes/blob/main/cli.py"
click node_cli_ui "https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/curses_ui.py"
click node_gateway "https://github.com/hermes-agent-org/hermes/blob/main/gateway/run.py"
click node_platforms "https://github.com/hermes-agent-org/hermes/blob/main/gateway/platforms/base.py"
click node_agent_loop "https://github.com/hermes-agent-org/hermes/blob/main/run_agent.py"
click node_providers "https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/runtime_provider.py"
click node_model_catalog "https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/models.py"
click node_authentication "https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/auth.py"
click node_tool_api "https://github.com/hermes-agent-org/hermes/blob/main/model_tools.py"
click node_tool_registry "https://github.com/hermes-agent-org/hermes/blob/main/tools/registry.py"
click node_terminal "https://github.com/hermes-agent-org/hermes/blob/main/tools/terminal_tool.py"
click node_mcp "https://github.com/hermes-agent-org/hermes/blob/main/tools/mcp_tool.py"
click node_delegation "https://github.com/hermes-agent-org/hermes/blob/main/tools/delegate_tool.py"
click node_session_store "https://github.com/hermes-agent-org/hermes/blob/main/hermes_state.py"
click node_memory "https://github.com/hermes-agent-org/hermes/blob/main/agent/memory_manager.py"
click node_skill_manager "https://github.com/hermes-agent-org/hermes/blob/main/tools/skill_manager_tool.py"
click node_session_search "https://github.com/hermes-agent-org/hermes/blob/main/tools/session_search_tool.py"
click node_scheduler "https://github.com/hermes-agent-org/hermes/blob/main/cron/scheduler.py"
click node_research_env "https://github.com/hermes-agent-org/hermes/blob/main/environments/web_research_env.py"
click node_rl_env "https://github.com/hermes-agent-org/hermes/blob/main/environments/agent_loop.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_cli_ui,node_gateway,node_platforms,node_user toneBlue
class node_agent_loop,node_providers,node_model_catalog,node_authentication toneAmber
class node_tool_api,node_tool_registry,node_terminal,node_mcp,node_delegation toneMint
class node_session_store,node_memory,node_skill_manager,node_session_search toneRose
class node_scheduler,node_research_env,node_rl_env toneIndigo
```

## Components

### User interfaces

- [Interactive CLI](https://github.com/hermes-agent-org/hermes/blob/main/cli.py): `cli.py`
- [CLI TUI](https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/curses_ui.py): `hermes_cli/curses_ui.py`
- [Messaging gateway](https://github.com/hermes-agent-org/hermes/blob/main/gateway/run.py): `gateway/run.py`
- [Messaging platforms](https://github.com/hermes-agent-org/hermes/blob/main/gateway/platforms/base.py): `gateway/platforms/base.py`

### Agent runtime

- [Agent loop](https://github.com/hermes-agent-org/hermes/blob/main/run_agent.py): `run_agent.py`
- [Provider resolution](https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/runtime_provider.py): `hermes_cli/runtime_provider.py`
- [Model catalog](https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/models.py): `hermes_cli/models.py`
- [Provider authentication](https://github.com/hermes-agent-org/hermes/blob/main/hermes_cli/auth.py): `hermes_cli/auth.py`

### Agent capabilities

- [Tool orchestration](https://github.com/hermes-agent-org/hermes/blob/main/model_tools.py): `model_tools.py`
- [Tool registry](https://github.com/hermes-agent-org/hermes/blob/main/tools/registry.py): `tools/registry.py`
- [Terminal execution](https://github.com/hermes-agent-org/hermes/blob/main/tools/terminal_tool.py): `tools/terminal_tool.py`
- [MCP integration](https://github.com/hermes-agent-org/hermes/blob/main/tools/mcp_tool.py): `tools/mcp_tool.py`
- [Subagent delegation](https://github.com/hermes-agent-org/hermes/blob/main/tools/delegate_tool.py): `tools/delegate_tool.py`

### Memory and learning

- [Session state](https://github.com/hermes-agent-org/hermes/blob/main/hermes_state.py): `hermes_state.py`
- [Persistent memory](https://github.com/hermes-agent-org/hermes/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Skill management](https://github.com/hermes-agent-org/hermes/blob/main/tools/skill_manager_tool.py): `tools/skill_manager_tool.py`
- [Session search](https://github.com/hermes-agent-org/hermes/blob/main/tools/session_search_tool.py): `tools/session_search_tool.py`

### Scheduling and research

- [Cron scheduler](https://github.com/hermes-agent-org/hermes/blob/main/cron/scheduler.py): `cron/scheduler.py`
- [Research environments](https://github.com/hermes-agent-org/hermes/blob/main/environments/web_research_env.py): `environments/web_research_env.py`
- [RL environments](https://github.com/hermes-agent-org/hermes/blob/main/environments/agent_loop.py): `environments/agent_loop.py`

### Other components

- **User**

## Connections

- User → Interactive CLI: starts chat
- User → Messaging gateway: sends message
- Interactive CLI → CLI TUI: renders interface (evidence: `cli.py`)
- Interactive CLI → Agent loop: runs turns (evidence: `cli.py`)
- Messaging gateway → Messaging platforms: connects platforms
- Messaging gateway → Agent loop: handles messages
- Agent loop → Tool orchestration: dispatches tools (evidence: `model_tools.py`)
- Tool orchestration → Tool registry: dispatches calls (evidence: `model_tools.py`)
- Tool registry → Terminal execution: registers tool (evidence: `tools/terminal_tool.py`)
- Agent loop → Provider resolution: resolves model
- Provider resolution → Model catalog: checks models (evidence: `hermes_cli/runtime_provider.py`)
- Provider authentication → Provider resolution: supplies credentials (evidence: `hermes_cli/runtime_provider.py`)
- Agent loop → Session state: persists sessions
- Agent loop → Persistent memory: uses memory
- Agent loop → Skill management: creates skills
- Agent loop → Session search: searches history
- Agent loop → MCP integration: uses MCP
- Agent loop → Subagent delegation: spawns subagents
- Cron scheduler → Agent loop: runs scheduled tasks (evidence: `cron/scheduler.py`)
- Cron scheduler → Messaging platforms: delivers results (evidence: `cron/scheduler.py`)
- Research environments → Agent loop: runs research (evidence: `environments/web_research_env.py`)
- RL environments → Agent loop: generates trajectories
