# lokesh-dadhich/hermes-agent architecture

> Architecture diagram of the GitHub repository lokesh-dadhich/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/lokesh-dadhich/hermes-agent
- Repository: https://github.com/lokesh-dadhich/hermes-agent

## Overview

Hermes Agent is a multi-surface, self-improving AI assistant. A user can start through the CLI/TUI, messaging gateway, or ACP editor integration; requests enter the agent’s conversation loop, which prepares context, calls a model, and can dispatch tools before returning a response. The README also documents distinct learning, automation, delegation, and research capabilities. The sampled sources confirm ACP session/server behavior and context-engine responsibilities; other subsystem links below reflect README-level product descriptions, not inspection of their unsampled implementations.

Main entry points: [`agent/conversation_loop.py`](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/conversation_loop.py) (Conversation loop), [`tui_gateway/server.py`](https://github.com/lokesh-dadhich/hermes-agent/blob/main/tui_gateway/server.py) (Messaging gateway), [`hermes_cli/console_engine.py`](https://github.com/lokesh-dadhich/hermes-agent/blob/main/hermes_cli/console_engine.py) (CLI / TUI), [`acp_adapter/server.py`](https://github.com/lokesh-dadhich/hermes-agent/blob/main/acp_adapter/server.py) (ACP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_cli["CLI / TUI<br/>[console_engine.py]"]
  node_gateway["Messaging gateway<br/>[server.py]"]
  node_acp["ACP server<br/>[server.py]"]
  node_acp_sessions[("ACP sessions<br/>[session.py]")]
end

subgraph group_runtime["Agent runtime"]
  node_loop["Conversation loop"]
  node_context["Context engine<br/>[context_engine.py]"]
  node_compressor["Context compressor"]
  node_providers["Model providers"]
  node_tools["Tool execution<br/>[tool_executor.py]"]
  node_terminal["Terminal backends<br/>[local.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_learning["Learning and skills<br/>[learning_graph.py]"]
end

subgraph group_state["Memory and state"]
  node_memory[("Agent memory<br/>[memory_manager.py]")]
  node_session_store[("Session history")]
end

subgraph group_operations["Automation and research"]
  node_scheduler["Scheduled jobs<br/>[jobs.py]"]
  node_subagents["Subagents"]
  node_trajectory["Research trajectories<br/>[trajectory.py]"]
end

node_user(("User"))
node_model_service{{"Model service"}}

node_user -->|"starts chat"| node_cli
node_user -->|"messages"| node_gateway
node_user -->|"uses editor"| node_acp
node_cli -->|"starts turns"| node_loop
node_gateway -->|"routes requests"| node_loop
node_acp -->|"manages sessions"| node_acp_sessions
node_acp_sessions -->|"runs agent"| node_loop
node_loop -->|"manages context"| node_context
node_context -->|"uses default"| node_compressor
node_loop -->|"selects provider"| node_providers
node_providers -->|"sends requests"| node_model_service
node_loop -->|"dispatches tools"| node_tools
node_tools -->|"executes commands"| node_terminal
node_loop -->|"records history"| node_session_store
node_loop -->|"uses learned memory"| node_memory
node_loop -->|"creates skills"| node_learning
node_scheduler -->|"delivers jobs"| node_gateway
node_loop -->|"delegates work"| node_subagents
node_loop -->|"generates traces"| node_trajectory

click node_cli "https://github.com/lokesh-dadhich/hermes-agent/blob/main/hermes_cli/console_engine.py"
click node_gateway "https://github.com/lokesh-dadhich/hermes-agent/blob/main/tui_gateway/server.py"
click node_acp "https://github.com/lokesh-dadhich/hermes-agent/blob/main/acp_adapter/server.py"
click node_acp_sessions "https://github.com/lokesh-dadhich/hermes-agent/blob/main/acp_adapter/session.py"
click node_loop "https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/conversation_loop.py"
click node_context "https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/context_engine.py"
click node_compressor "https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/context_compressor.py"
click node_providers "https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/provider_registry.py"
click node_tools "https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/tool_executor.py"
click node_terminal "https://github.com/lokesh-dadhich/hermes-agent/blob/main/tools/environments/local.py"
click node_learning "https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/learning_graph.py"
click node_memory "https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/memory_manager.py"
click node_session_store "https://github.com/lokesh-dadhich/hermes-agent/blob/main/hermes_state_sessions.py"
click node_scheduler "https://github.com/lokesh-dadhich/hermes-agent/blob/main/cron/jobs.py"
click node_subagents "https://github.com/lokesh-dadhich/hermes-agent/blob/main/tools/async_delegation.py"
click node_trajectory "https://github.com/lokesh-dadhich/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_gateway,node_acp,node_acp_sessions,node_user toneBlue
class node_loop,node_context,node_compressor,node_providers,node_tools,node_terminal toneAmber
class node_learning toneMint
class node_memory,node_session_store toneRose
class node_scheduler,node_subagents,node_trajectory,node_model_service toneIndigo
```

## Components

### User surfaces

- [CLI / TUI](https://github.com/lokesh-dadhich/hermes-agent/blob/main/hermes_cli/console_engine.py): `hermes_cli/console_engine.py`
- [Messaging gateway](https://github.com/lokesh-dadhich/hermes-agent/blob/main/tui_gateway/server.py): `tui_gateway/server.py`
- [ACP server](https://github.com/lokesh-dadhich/hermes-agent/blob/main/acp_adapter/server.py): `acp_adapter/server.py`
- [ACP sessions](https://github.com/lokesh-dadhich/hermes-agent/blob/main/acp_adapter/session.py): `acp_adapter/session.py`

### Agent runtime

- [Conversation loop](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Context engine](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/context_engine.py): `agent/context_engine.py`
- [Context compressor](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/context_compressor.py): `agent/context_compressor.py`
- [Model providers](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/provider_registry.py): `agent/provider_registry.py`
- [Tool execution](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/tool_executor.py): `agent/tool_executor.py`
- [Terminal backends](https://github.com/lokesh-dadhich/hermes-agent/blob/main/tools/environments/local.py): `tools/environments/local.py`

### Agent capabilities

- [Learning and skills](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/learning_graph.py): `agent/learning_graph.py`

### Memory and state

- [Agent memory](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Session history](https://github.com/lokesh-dadhich/hermes-agent/blob/main/hermes_state_sessions.py): `hermes_state_sessions.py`

### Automation and research

- [Scheduled jobs](https://github.com/lokesh-dadhich/hermes-agent/blob/main/cron/jobs.py): `cron/jobs.py`
- [Subagents](https://github.com/lokesh-dadhich/hermes-agent/blob/main/tools/async_delegation.py): `tools/async_delegation.py`
- [Research trajectories](https://github.com/lokesh-dadhich/hermes-agent/blob/main/agent/trajectory.py): `agent/trajectory.py`

### Other components

- **User**
- **Model service**

## Connections

- User → CLI / TUI: starts chat
- User → Messaging gateway: messages
- User → ACP server: uses editor
- CLI / TUI → Conversation loop: starts turns
- Messaging gateway → Conversation loop: routes requests (evidence: `agent/conversation_loop.py`)
- ACP server → ACP sessions: manages sessions (evidence: `acp_adapter/server.py`)
- ACP sessions → Conversation loop: runs agent (evidence: `acp_adapter/session.py`)
- Conversation loop → Context engine: manages context (evidence: `agent/conversation_loop.py`)
- Context engine → Context compressor: uses default (evidence: `agent/context_engine.py`)
- Conversation loop → Model providers: selects provider
- Model providers → Model service: sends requests
- Conversation loop → Tool execution: dispatches tools
- Tool execution → Terminal backends: executes commands
- Conversation loop → Session history: records history
- Conversation loop → Agent memory: uses learned memory
- Conversation loop → Learning and skills: creates skills
- Scheduled jobs → Messaging gateway: delivers jobs
- Conversation loop → Subagents: delegates work
- Conversation loop → Research trajectories: generates traces
