# sullipaupau/hermes-agent architecture

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

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

## Overview

Hermes Agent is a multi-interface AI agent: people chat through its terminal UI/CLI or messaging platforms, the agent uses a configurable model and tools to act, and responses return through the initiating interface. The README also describes persistent learning and recall, scheduled jobs, delegated subagents, and multiple execution backends as product capabilities. The graph groups these major branches with the core interaction flow; edges cite README statements or source-index references. Some subsystem wiring is unsampled, so those relationships are left out rather than inferred.

Main entry points: [`agent/conversation_loop.py`](https://github.com/sullipaupau/hermes-agent/blob/main/agent/conversation_loop.py) (Conversation runtime), [`model_tools.py`](https://github.com/sullipaupau/hermes-agent/blob/main/model_tools.py) (Tool dispatch), [`gateway/run.py`](https://github.com/sullipaupau/hermes-agent/blob/main/gateway/run.py) (Messaging gateway), [`agent/auxiliary_client.py`](https://github.com/sullipaupau/hermes-agent/blob/main/agent/auxiliary_client.py) (Model routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_terminal["Terminal UI<br/>[server.py]"]
  node_tui["TUI client<br/>[turnController.ts]"]
  node_gateway["Messaging gateway<br/>[run.py]"]
  node_platforms["Platform adapters<br/>[base.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Conversation runtime"]
  node_models["Model routing"]
  node_providers["Model providers<br/>[base.py]"]
  node_tools["Tool dispatch<br/>[model_tools.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_execution["Execution backends<br/>[base.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_memory["Memory and recall<br/>[memory_manager.py]"]
  node_skills["Learning skills<br/>[skill_utils.py]"]
  node_search["Session search"]
  node_delegation["Subagents<br/>[delegate_tool.py]"]
  node_cron["Scheduled jobs<br/>[scheduler.py]"]
end

subgraph group_operations["Configuration and operations"]
  node_config["Configuration<br/>[config.py]"]
  node_state[("Agent state<br/>[hermes_state.py]")]
end

node_person(("User"))
node_external_models{{"Model APIs"}}

node_person -->|"starts chat"| node_cli
node_cli -->|"starts conversation"| node_agent
node_person -->|"chats in"| node_terminal
node_terminal -->|"serves UI"| node_tui
node_person -->|"sends message"| node_platforms
node_platforms -->|"routes messages"| node_gateway
node_gateway -->|"runs conversation"| node_agent
node_agent -.->|"requests completion"| node_models
node_models -->|"resolves backend"| node_providers
node_providers -.->|"calls model API"| node_external_models
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"queries definitions"| node_registry
node_tools -->|"runs commands"| node_execution
node_agent -->|"curates memory"| node_memory
node_agent -->|"learns skills"| node_skills
node_agent -->|"recalls sessions"| node_search
node_agent -->|"spawns subagents"| node_delegation
node_cron -->|"delivers reports"| node_gateway
node_config -->|"configures providers"| node_models
node_memory -.->|"persists state"| node_state

click node_cli "https://github.com/sullipaupau/hermes-agent/blob/main/cli.py"
click node_terminal "https://github.com/sullipaupau/hermes-agent/blob/main/tui_gateway/server.py"
click node_tui "https://github.com/sullipaupau/hermes-agent/blob/main/ui-tui/src/app/turnController.ts"
click node_gateway "https://github.com/sullipaupau/hermes-agent/blob/main/gateway/run.py"
click node_platforms "https://github.com/sullipaupau/hermes-agent/blob/main/gateway/platforms/base.py"
click node_agent "https://github.com/sullipaupau/hermes-agent/blob/main/agent/conversation_loop.py"
click node_models "https://github.com/sullipaupau/hermes-agent/blob/main/agent/auxiliary_client.py"
click node_providers "https://github.com/sullipaupau/hermes-agent/blob/main/providers/base.py"
click node_tools "https://github.com/sullipaupau/hermes-agent/blob/main/model_tools.py"
click node_registry "https://github.com/sullipaupau/hermes-agent/blob/main/tools/registry.py"
click node_execution "https://github.com/sullipaupau/hermes-agent/blob/main/tools/environments/base.py"
click node_memory "https://github.com/sullipaupau/hermes-agent/blob/main/agent/memory_manager.py"
click node_skills "https://github.com/sullipaupau/hermes-agent/blob/main/agent/skill_utils.py"
click node_search "https://github.com/sullipaupau/hermes-agent/blob/main/tools/session_search_tool.py"
click node_delegation "https://github.com/sullipaupau/hermes-agent/blob/main/tools/delegate_tool.py"
click node_cron "https://github.com/sullipaupau/hermes-agent/blob/main/cron/scheduler.py"
click node_config "https://github.com/sullipaupau/hermes-agent/blob/main/hermes_cli/config.py"
click node_state "https://github.com/sullipaupau/hermes-agent/blob/main/hermes_state.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_terminal,node_tui,node_gateway,node_platforms,node_person toneBlue
class node_agent,node_models,node_providers,node_tools,node_registry,node_execution toneAmber
class node_memory,node_skills,node_search,node_delegation,node_cron,node_external_models toneMint
class node_config,node_state toneRose
```

## Components

### User interfaces

- [CLI](https://github.com/sullipaupau/hermes-agent/blob/main/cli.py): `cli.py`
- [Terminal UI](https://github.com/sullipaupau/hermes-agent/blob/main/tui_gateway/server.py): `tui_gateway/server.py`
- [TUI client](https://github.com/sullipaupau/hermes-agent/blob/main/ui-tui/src/app/turnController.ts): `ui-tui/src/app/turnController.ts`
- [Messaging gateway](https://github.com/sullipaupau/hermes-agent/blob/main/gateway/run.py): `gateway/run.py`
- [Platform adapters](https://github.com/sullipaupau/hermes-agent/blob/main/gateway/platforms/base.py): `gateway/platforms/base.py`

### Agent runtime

- [Conversation runtime](https://github.com/sullipaupau/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Model routing](https://github.com/sullipaupau/hermes-agent/blob/main/agent/auxiliary_client.py): `agent/auxiliary_client.py`
- [Model providers](https://github.com/sullipaupau/hermes-agent/blob/main/providers/base.py): `providers/base.py`
- [Tool dispatch](https://github.com/sullipaupau/hermes-agent/blob/main/model_tools.py): `model_tools.py`
- [Tool registry](https://github.com/sullipaupau/hermes-agent/blob/main/tools/registry.py): `tools/registry.py`
- [Execution backends](https://github.com/sullipaupau/hermes-agent/blob/main/tools/environments/base.py): `tools/environments/base.py`

### Agent capabilities

- [Memory and recall](https://github.com/sullipaupau/hermes-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Learning skills](https://github.com/sullipaupau/hermes-agent/blob/main/agent/skill_utils.py): `agent/skill_utils.py`
- [Session search](https://github.com/sullipaupau/hermes-agent/blob/main/tools/session_search_tool.py): `tools/session_search_tool.py`
- [Subagents](https://github.com/sullipaupau/hermes-agent/blob/main/tools/delegate_tool.py): `tools/delegate_tool.py`
- [Scheduled jobs](https://github.com/sullipaupau/hermes-agent/blob/main/cron/scheduler.py): `cron/scheduler.py`

### Configuration and operations

- [Configuration](https://github.com/sullipaupau/hermes-agent/blob/main/hermes_cli/config.py): `hermes_cli/config.py`
- [Agent state](https://github.com/sullipaupau/hermes-agent/blob/main/hermes_state.py): `hermes_state.py`

### Other components

- **User**
- **Model APIs**

## Connections

- User → CLI: starts chat (evidence: `README.md`)
- CLI → Conversation runtime: starts conversation (evidence: `README.md`)
- User → Terminal UI: chats in (evidence: `README.md`)
- Terminal UI → TUI client: serves UI (evidence: `tui_gateway/server.py`)
- User → Platform adapters: sends message (evidence: `README.md`)
- Platform adapters → Messaging gateway: routes messages (evidence: `README.md`)
- Messaging gateway → Conversation runtime: runs conversation (evidence: `README.md`)
- Conversation runtime → Model routing: requests completion
- Model routing → Model providers: resolves backend (evidence: `agent/auxiliary_client.py`)
- Model providers → Model APIs: calls model API
- Conversation runtime → Tool dispatch: dispatches tools (evidence: `README.md`)
- Tool dispatch → Tool registry: queries definitions (evidence: `model_tools.py`)
- Tool dispatch → Execution backends: runs commands (evidence: `README.md`)
- Conversation runtime → Memory and recall: curates memory (evidence: `README.md`)
- Conversation runtime → Learning skills: learns skills (evidence: `README.md`)
- Conversation runtime → Session search: recalls sessions (evidence: `README.md`)
- Conversation runtime → Subagents: spawns subagents (evidence: `README.md`)
- Scheduled jobs → Messaging gateway: delivers reports (evidence: `README.md`)
- Configuration → Model routing: configures providers (evidence: `agent/auxiliary_client.py`)
- Memory and recall → Agent state: persists state