# the-coca-cola-company/hermes-agent architecture

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

- Interactive diagram: https://gitdiagram.com/the-coca-cola-company/hermes-agent
- Repository: https://github.com/the-coca-cola-company/hermes-agent

## Overview

Hermes Agent is a self-improving, multi-provider AI agent exposed through a CLI/TUI and messaging gateway, with a desktop client also present in the repository. A user submits a turn through a client or messaging platform; the agent prepares context, calls a model, and may execute tools before returning a response. Major branches include persistent learning, scheduled automations, parallel subagents, and multiple terminal environments. Source excerpts are limited, so README-documented capabilities are shown without claiming unsampled implementation details.

Main entry points: [`agent/conversation_loop.py`](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/conversation_loop.py) (Conversation Loop), [`agent/tool_executor.py`](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/tool_executor.py) (Tool Execution), [`gateway/platforms/signal.py`](https://github.com/the-coca-cola-company/hermes-agent/blob/main/gateway/platforms/signal.py) (Messaging Gateway), [`ui-tui/src/app/turnController.ts`](https://github.com/the-coca-cola-company/hermes-agent/blob/main/ui-tui/src/app/turnController.ts) (CLI and TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_clients["CLI and TUI<br/>[turnController.ts]"]
  node_desktop["Desktop Client<br/>[index.tsx]"]
  node_gateway["Messaging Gateway<br/>[signal.py]"]
end

subgraph group_agent["Agent Runtime"]
  node_turn["Conversation Loop"]
  node_context["Context Management"]
  node_model["Model Routing"]
  node_metadata["Model Metadata<br/>[model_metadata.py]"]
  node_tools["Tool Execution<br/>[tool_executor.py]"]
  node_terminal["Terminal Backends"]
  node_redaction["Data Redaction<br/>[redact.py]"]
end

subgraph group_learning["Learning and Memory"]
  node_memory[("Agent Memory<br/>[memory_manager.py]")]
  node_skills["Learning Skills"]
end

subgraph group_integrations["Platforms and Integrations"]
  node_platforms["Messaging Platforms"]
  node_websearch["Web Search"]
  node_media["Media Providers"]
end

subgraph group_operations["Automation and Research"]
  node_scheduler["Scheduled Automations"]
  node_subagents["Parallel Subagents"]
  node_trajectories["Trajectory Generation<br/>[trajectory.py]"]
end

node_user(("User"))

node_user -->|"starts turn"| node_clients
node_user -->|"messages"| node_gateway
node_user -->|"uses"| node_desktop
node_clients -.->|"submits turn"| node_turn
node_desktop -.->|"submits turn"| node_turn
node_gateway -.->|"routes messages"| node_turn
node_gateway -->|"connects platforms"| node_platforms
node_turn -->|"prepares context"| node_context
node_turn -.->|"requests completion"| node_model
node_model -->|"resolves model"| node_metadata
node_turn -->|"dispatches tools"| node_tools
node_tools -->|"runs commands"| node_terminal
node_turn -->|"uses memory"| node_memory
node_memory -->|"supports learning"| node_skills
node_turn -.->|"redacts data"| node_redaction
node_tools -.->|"offers search"| node_websearch
node_tools -.->|"offers media tools"| node_media
node_scheduler -->|"delivers automations"| node_platforms
node_turn -->|"spawns workers"| node_subagents
node_turn -->|"records trajectories"| node_trajectories

click node_clients "https://github.com/the-coca-cola-company/hermes-agent/blob/main/ui-tui/src/app/turnController.ts"
click node_desktop "https://github.com/the-coca-cola-company/hermes-agent/blob/main/apps/desktop/src/app/chat/index.tsx"
click node_gateway "https://github.com/the-coca-cola-company/hermes-agent/blob/main/gateway/platforms/signal.py"
click node_turn "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/conversation_loop.py"
click node_context "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/context_compressor.py"
click node_model "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/auxiliary_client.py"
click node_metadata "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/model_metadata.py"
click node_tools "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/tool_executor.py"
click node_terminal "https://github.com/the-coca-cola-company/hermes-agent/tree/main/tools/environments"
click node_memory "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/memory_manager.py"
click node_redaction "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/redact.py"
click node_platforms "https://github.com/the-coca-cola-company/hermes-agent/tree/main/gateway/platforms"
click node_websearch "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/web_search_provider.py"
click node_media "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/image_gen_provider.py"
click node_scheduler "https://github.com/the-coca-cola-company/hermes-agent/tree/main/plugins/cron_providers"
click node_subagents "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/subagent_lifecycle.py"
click node_trajectories "https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/trajectory.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_clients,node_desktop,node_gateway,node_user toneBlue
class node_turn,node_context,node_model,node_metadata,node_tools,node_terminal,node_redaction toneAmber
class node_memory,node_skills toneMint
class node_platforms,node_websearch,node_media toneRose
class node_scheduler,node_subagents,node_trajectories toneIndigo
```

## Components

### User Interfaces

- [CLI and TUI](https://github.com/the-coca-cola-company/hermes-agent/blob/main/ui-tui/src/app/turnController.ts): `ui-tui/src/app/turnController.ts`
- [Desktop Client](https://github.com/the-coca-cola-company/hermes-agent/blob/main/apps/desktop/src/app/chat/index.tsx): `apps/desktop/src/app/chat/index.tsx`
- [Messaging Gateway](https://github.com/the-coca-cola-company/hermes-agent/blob/main/gateway/platforms/signal.py): `gateway/platforms/signal.py`

### Agent Runtime

- [Conversation Loop](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Context Management](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/context_compressor.py): `agent/context_compressor.py`
- [Model Routing](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/auxiliary_client.py): `agent/auxiliary_client.py`
- [Model Metadata](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/model_metadata.py): `agent/model_metadata.py`
- [Tool Execution](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/tool_executor.py): `agent/tool_executor.py`
- [Terminal Backends](https://github.com/the-coca-cola-company/hermes-agent/tree/main/tools/environments): `tools/environments`
- [Data Redaction](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/redact.py): `agent/redact.py`

### Learning and Memory

- [Agent Memory](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- **Learning Skills**

### Platforms and Integrations

- [Messaging Platforms](https://github.com/the-coca-cola-company/hermes-agent/tree/main/gateway/platforms): `gateway/platforms`
- [Web Search](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/web_search_provider.py): `agent/web_search_provider.py`
- [Media Providers](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/image_gen_provider.py): `agent/image_gen_provider.py`

### Automation and Research

- [Scheduled Automations](https://github.com/the-coca-cola-company/hermes-agent/tree/main/plugins/cron_providers): `plugins/cron_providers`
- [Parallel Subagents](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/subagent_lifecycle.py): `agent/subagent_lifecycle.py`
- [Trajectory Generation](https://github.com/the-coca-cola-company/hermes-agent/blob/main/agent/trajectory.py): `agent/trajectory.py`

### Other components

- **User**

## Connections

- User → CLI and TUI: starts turn (evidence: `README.md`)
- User → Messaging Gateway: messages (evidence: `README.md`)
- User → Desktop Client: uses (evidence: `README.md`)
- CLI and TUI → Conversation Loop: submits turn
- Desktop Client → Conversation Loop: submits turn
- Messaging Gateway → Conversation Loop: routes messages
- Messaging Gateway → Messaging Platforms: connects platforms (evidence: `README.md`)
- Conversation Loop → Context Management: prepares context (evidence: `agent/context_compressor.py`)
- Conversation Loop → Model Routing: requests completion
- Model Routing → Model Metadata: resolves model (evidence: `agent/auxiliary_client.py`)
- Conversation Loop → Tool Execution: dispatches tools (evidence: `README.md`)
- Tool Execution → Terminal Backends: runs commands (evidence: `README.md`)
- Conversation Loop → Agent Memory: uses memory (evidence: `README.md`)
- Agent Memory → Learning Skills: supports learning (evidence: `README.md`)
- Conversation Loop → Data Redaction: redacts data
- Tool Execution → Web Search: offers search
- Tool Execution → Media Providers: offers media tools
- Scheduled Automations → Messaging Platforms: delivers automations (evidence: `README.md`)
- Conversation Loop → Parallel Subagents: spawns workers (evidence: `README.md`)
- Conversation Loop → Trajectory Generation: records trajectories (evidence: `README.md`)
