# andyweidong/hermes-agent architecture

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

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

## Overview

Hermes Agent is a self-improving conversational agent exposed through CLI/TUI, messaging gateway, desktop/web surfaces, and the Agent Client Protocol. The principal workflow accepts a user turn, runs the agent’s conversation loop with model and tool capabilities, and returns a response through the initiating surface. Distinct product branches include memory and skill learning, scheduled automation, delegation, and research trajectory generation. The graph combines README-documented capabilities with relationships named in the SOURCE INDEX; unsampled implementation details are not assumed.

Main entry points: [`agent/conversation_loop.py`](https://github.com/andyweidong/hermes-agent/blob/main/agent/conversation_loop.py) (Conversation loop), [`acp_adapter/server.py`](https://github.com/andyweidong/hermes-agent/blob/main/acp_adapter/server.py) (ACP server), [`gateway/run.py`](https://github.com/andyweidong/hermes-agent/blob/main/gateway/run.py) (Messaging gateway), [`agent/tool_executor.py`](https://github.com/andyweidong/hermes-agent/blob/main/agent/tool_executor.py) (Tool execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI"]
  node_tui["TUI<br/>[app.tsx]"]
end

subgraph group_runtime["Agent runtime"]
  node_loop["Conversation loop"]
  node_compression["Context compression"]
  node_conversation_compression["Conversation compression"]
  node_display["Response display<br/>[display.py]"]
  node_models["Model selection<br/>[model_switch.py]"]
  node_providers["Model providers"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tools["Tool execution<br/>[tool_executor.py]"]
  node_terminal["Terminal backends<br/>[terminal_tool.py]"]
  node_scheduler["Scheduled automation"]
  node_delegation["Subagents"]
end

subgraph group_platform["Gateway and sessions"]
  node_gateway["Messaging gateway<br/>[run.py]"]
  node_api["API routes<br/>[api_server.py]"]
  node_tui_gateway["TUI gateway<br/>[server.py]"]
  node_acp["ACP server<br/>[server.py]"]
  node_session["Session handling<br/>[session.py]"]
end

subgraph group_learning["Learning and research"]
  node_memory["Memory and recall<br/>[memory_manager.py]"]
  node_skills["Skill learning<br/>[skill_commands.py]"]
  node_trajectory["Trajectories<br/>[trajectory.py]"]
end

node_user(("User"))

node_user -->|"sends messages"| node_gateway
node_user -->|"starts conversation"| node_cli
node_user -->|"chats through"| node_tui
node_user -.->|"connects via ACP"| node_acp
node_gateway -.->|"runs turns"| node_loop
node_api -->|"serves agent turns"| node_loop
node_tui_gateway -->|"runs conversation"| node_loop
node_acp -->|"builds model picker"| node_models
node_acp -.->|"runs agent"| node_loop
node_loop -->|"requests model output"| node_providers
node_loop -->|"invokes tools"| node_tools
node_loop -.->|"compresses context"| node_compression
node_conversation_compression -.->|"uses compressor"| node_compression
node_loop -.->|"returns response"| node_display
node_tools -->|"runs terminal tools"| node_terminal
node_loop -->|"recalls knowledge"| node_memory
node_loop -->|"creates and improves"| node_skills
node_scheduler -->|"delivers scheduled output"| node_gateway
node_loop -->|"spawns subagents"| node_delegation
node_loop -->|"generates trajectories"| node_trajectory

click node_cli "https://github.com/andyweidong/hermes-agent/tree/main/hermes_cli"
click node_tui "https://github.com/andyweidong/hermes-agent/blob/main/ui-tui/src/app.tsx"
click node_gateway "https://github.com/andyweidong/hermes-agent/blob/main/gateway/run.py"
click node_api "https://github.com/andyweidong/hermes-agent/blob/main/gateway/platforms/api_server.py"
click node_tui_gateway "https://github.com/andyweidong/hermes-agent/blob/main/tui_gateway/server.py"
click node_acp "https://github.com/andyweidong/hermes-agent/blob/main/acp_adapter/server.py"
click node_session "https://github.com/andyweidong/hermes-agent/blob/main/gateway/session.py"
click node_loop "https://github.com/andyweidong/hermes-agent/blob/main/agent/conversation_loop.py"
click node_compression "https://github.com/andyweidong/hermes-agent/blob/main/agent/context_compressor.py"
click node_conversation_compression "https://github.com/andyweidong/hermes-agent/blob/main/agent/conversation_compression.py"
click node_display "https://github.com/andyweidong/hermes-agent/blob/main/agent/display.py"
click node_models "https://github.com/andyweidong/hermes-agent/blob/main/hermes_cli/model_switch.py"
click node_providers "https://github.com/andyweidong/hermes-agent/blob/main/agent/provider_registry.py"
click node_tools "https://github.com/andyweidong/hermes-agent/blob/main/agent/tool_executor.py"
click node_terminal "https://github.com/andyweidong/hermes-agent/blob/main/tools/terminal_tool.py"
click node_memory "https://github.com/andyweidong/hermes-agent/blob/main/agent/memory_manager.py"
click node_skills "https://github.com/andyweidong/hermes-agent/blob/main/agent/skill_commands.py"
click node_scheduler "https://github.com/andyweidong/hermes-agent/blob/main/cron/scheduler_worker_env.py"
click node_delegation "https://github.com/andyweidong/hermes-agent/blob/main/tools/async_delegation.py"
click node_trajectory "https://github.com/andyweidong/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_cli,node_tui,node_user toneBlue
class node_loop,node_compression,node_conversation_compression,node_display,node_models,node_providers toneAmber
class node_tools,node_terminal,node_scheduler,node_delegation toneMint
class node_gateway,node_api,node_tui_gateway,node_acp,node_session toneRose
class node_memory,node_skills,node_trajectory toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/andyweidong/hermes-agent/tree/main/hermes_cli): `hermes_cli`
- [TUI](https://github.com/andyweidong/hermes-agent/blob/main/ui-tui/src/app.tsx): `ui-tui/src/app.tsx`

### Agent runtime

- [Conversation loop](https://github.com/andyweidong/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Context compression](https://github.com/andyweidong/hermes-agent/blob/main/agent/context_compressor.py): `agent/context_compressor.py`
- [Conversation compression](https://github.com/andyweidong/hermes-agent/blob/main/agent/conversation_compression.py): `agent/conversation_compression.py`
- [Response display](https://github.com/andyweidong/hermes-agent/blob/main/agent/display.py): `agent/display.py`
- [Model selection](https://github.com/andyweidong/hermes-agent/blob/main/hermes_cli/model_switch.py): `hermes_cli/model_switch.py`
- [Model providers](https://github.com/andyweidong/hermes-agent/blob/main/agent/provider_registry.py): `agent/provider_registry.py`

### Agent capabilities

- [Tool execution](https://github.com/andyweidong/hermes-agent/blob/main/agent/tool_executor.py): `agent/tool_executor.py`
- [Terminal backends](https://github.com/andyweidong/hermes-agent/blob/main/tools/terminal_tool.py): `tools/terminal_tool.py`
- [Scheduled automation](https://github.com/andyweidong/hermes-agent/blob/main/cron/scheduler_worker_env.py): `cron/scheduler_worker_env.py`
- [Subagents](https://github.com/andyweidong/hermes-agent/blob/main/tools/async_delegation.py): `tools/async_delegation.py`

### Gateway and sessions

- [Messaging gateway](https://github.com/andyweidong/hermes-agent/blob/main/gateway/run.py): `gateway/run.py`
- [API routes](https://github.com/andyweidong/hermes-agent/blob/main/gateway/platforms/api_server.py): `gateway/platforms/api_server.py`
- [TUI gateway](https://github.com/andyweidong/hermes-agent/blob/main/tui_gateway/server.py): `tui_gateway/server.py`
- [ACP server](https://github.com/andyweidong/hermes-agent/blob/main/acp_adapter/server.py): `acp_adapter/server.py`
- [Session handling](https://github.com/andyweidong/hermes-agent/blob/main/gateway/session.py): `gateway/session.py`

### Learning and research

- [Memory and recall](https://github.com/andyweidong/hermes-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Skill learning](https://github.com/andyweidong/hermes-agent/blob/main/agent/skill_commands.py): `agent/skill_commands.py`
- [Trajectories](https://github.com/andyweidong/hermes-agent/blob/main/agent/trajectory.py): `agent/trajectory.py`

### Other components

- **User**

## Connections

- User → Messaging gateway: sends messages (evidence: `README.md`)
- User → CLI: starts conversation (evidence: `README.md`)
- User → TUI: chats through (evidence: `README.md`)
- User → ACP server: connects via ACP
- Messaging gateway → Conversation loop: runs turns
- API routes → Conversation loop: serves agent turns
- TUI gateway → Conversation loop: runs conversation (evidence: `tui_gateway/server.py`)
- ACP server → Model selection: builds model picker (evidence: `acp_adapter/server.py`)
- ACP server → Conversation loop: runs agent (evidence: `acp_adapter/server.py`)
- Conversation loop → Model providers: requests model output (evidence: `README.md`)
- Conversation loop → Tool execution: invokes tools (evidence: `README.md`)
- Conversation loop → Context compression: compresses context
- Conversation compression → Context compression: uses compressor
- Conversation loop → Response display: returns response
- Tool execution → Terminal backends: runs terminal tools (evidence: `README.md`)
- Conversation loop → Memory and recall: recalls knowledge (evidence: `README.md`)
- Conversation loop → Skill learning: creates and improves (evidence: `README.md`)
- Scheduled automation → Messaging gateway: delivers scheduled output (evidence: `README.md`)
- Conversation loop → Subagents: spawns subagents (evidence: `README.md`)
- Conversation loop → Trajectories: generates trajectories (evidence: `README.md`)