# synthwave-solutions/hermes-agent architecture

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

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

## Overview

Hermes Agent, the engine behind the SynthPulse Agentic Workstation, is a multi-surface AI agent: users converse through CLI/TUI or messaging platforms, the gateway and conversation runtime coordinate model calls and tools, and the agent returns responses while retaining session context. Its broader product includes learning and recall, scheduled automation, delegation, and multiple execution backends. The README establishes these product capabilities; source excerpts provide only partial implementation evidence, so uncertain internal links are omitted rather than inferred.

Main entry points: [`agent/conversation_loop.py`](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/conversation_loop.py) (Conversation loop), [`gateway`](https://github.com/synthwave-solutions/hermes-agent/tree/main/gateway) (Messaging channels), [`hermes_cli/console_engine.py`](https://github.com/synthwave-solutions/hermes-agent/blob/main/hermes_cli/console_engine.py) (CLI and TUI), [`tui_gateway/server.py`](https://github.com/synthwave-solutions/hermes-agent/blob/main/tui_gateway/server.py) (Gateway service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_cli["CLI and TUI<br/>[console_engine.py]"]
  node_messaging["Messaging channels"]
  node_gateway["Gateway service<br/>[server.py]"]
  node_acp["ACP server<br/>[server.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_conversation["Conversation loop"]
  node_compression["Context compression"]
  node_model_metadata["Model metadata<br/>[model_metadata.py]"]
  node_redaction["Data redaction<br/>[redact.py]"]
  node_i18n["Localization<br/>[i18n.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_delegation["Subagents"]
  node_learning["Learning and skills<br/>[learning_graph.py]"]
  node_search["Session search"]
  node_scheduler["Cron automation"]
end

subgraph group_integrations["Models and tools"]
  node_providers["Model providers"]
  node_tools["Tool execution<br/>[tool_executor.py]"]
  node_backends["Execution backends"]
end

subgraph group_state["Session and memory"]
  node_session[("Session state")]
  node_memory[("Agent memory<br/>[memory_manager.py]")]
  node_compression_history[("Conversation archive")]
end

node_user(("User"))

node_user -.->|"starts chat"| node_cli
node_user -->|"sends messages"| node_messaging
node_cli -.->|"starts conversation"| node_conversation
node_messaging -->|"routes messages"| node_gateway
node_gateway -.->|"runs agent"| node_conversation
node_acp -->|"exposes agent"| node_conversation
node_conversation -.->|"calls models"| node_providers
node_conversation -.->|"dispatches tools"| node_tools
node_tools -->|"uses environments"| node_backends
node_conversation -.->|"compresses context"| node_compression
node_conversation -.->|"persists turns"| node_session
node_conversation -->|"uses model data"| node_model_metadata
node_conversation -->|"sanitizes content"| node_redaction
node_conversation -.->|"localizes responses"| node_i18n
node_conversation -->|"spawns subagents"| node_delegation
node_conversation -->|"learns from tasks"| node_learning
node_conversation -->|"searches history"| node_search
node_scheduler -->|"delivers automation"| node_messaging
node_learning -->|"curates knowledge"| node_memory
node_compression -.->|"archives context"| node_compression_history
node_conversation -.->|"returns response"| node_user

click node_cli "https://github.com/synthwave-solutions/hermes-agent/blob/main/hermes_cli/console_engine.py"
click node_messaging "https://github.com/synthwave-solutions/hermes-agent/tree/main/gateway"
click node_gateway "https://github.com/synthwave-solutions/hermes-agent/blob/main/tui_gateway/server.py"
click node_acp "https://github.com/synthwave-solutions/hermes-agent/blob/main/acp_adapter/server.py"
click node_conversation "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/conversation_loop.py"
click node_compression "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/context_compressor.py"
click node_model_metadata "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/model_metadata.py"
click node_providers "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/provider_registry.py"
click node_tools "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/tool_executor.py"
click node_backends "https://github.com/synthwave-solutions/hermes-agent/tree/main/tools/environments"
click node_delegation "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/delegation_provider.py"
click node_learning "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/learning_graph.py"
click node_search "https://github.com/synthwave-solutions/hermes-agent/tree/main/agent"
click node_scheduler "https://github.com/synthwave-solutions/hermes-agent/tree/main/cron"
click node_session "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/session_persistence.py"
click node_memory "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/memory_manager.py"
click node_compression_history "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/conversation_compression.py"
click node_redaction "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/redact.py"
click node_i18n "https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/i18n.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_messaging,node_gateway,node_acp,node_user toneBlue
class node_conversation,node_compression,node_model_metadata,node_redaction,node_i18n toneAmber
class node_delegation,node_learning,node_search,node_scheduler toneMint
class node_providers,node_tools,node_backends toneRose
class node_session,node_memory,node_compression_history toneIndigo
```

## Components

### User surfaces

- [CLI and TUI](https://github.com/synthwave-solutions/hermes-agent/blob/main/hermes_cli/console_engine.py): `hermes_cli/console_engine.py`
- [Messaging channels](https://github.com/synthwave-solutions/hermes-agent/tree/main/gateway): `gateway`
- [Gateway service](https://github.com/synthwave-solutions/hermes-agent/blob/main/tui_gateway/server.py): `tui_gateway/server.py`
- [ACP server](https://github.com/synthwave-solutions/hermes-agent/blob/main/acp_adapter/server.py): `acp_adapter/server.py`

### Agent runtime

- [Conversation loop](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Context compression](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/context_compressor.py): `agent/context_compressor.py`
- [Model metadata](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/model_metadata.py): `agent/model_metadata.py`
- [Data redaction](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/redact.py): `agent/redact.py`
- [Localization](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/i18n.py): `agent/i18n.py`

### Agent capabilities

- [Subagents](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/delegation_provider.py): `agent/delegation_provider.py`
- [Learning and skills](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/learning_graph.py): `agent/learning_graph.py`
- [Session search](https://github.com/synthwave-solutions/hermes-agent/tree/main/agent): `agent`
- [Cron automation](https://github.com/synthwave-solutions/hermes-agent/tree/main/cron): `cron`

### Models and tools

- [Model providers](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/provider_registry.py): `agent/provider_registry.py`
- [Tool execution](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/tool_executor.py): `agent/tool_executor.py`
- [Execution backends](https://github.com/synthwave-solutions/hermes-agent/tree/main/tools/environments): `tools/environments`

### Session and memory

- [Session state](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/session_persistence.py): `agent/session_persistence.py`
- [Agent memory](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Conversation archive](https://github.com/synthwave-solutions/hermes-agent/blob/main/agent/conversation_compression.py): `agent/conversation_compression.py`

### Other components

- **User**

## Connections

- User → CLI and TUI: starts chat (evidence: `README.md`)
- User → Messaging channels: sends messages (evidence: `README.md`)
- CLI and TUI → Conversation loop: starts conversation
- Messaging channels → Gateway service: routes messages (evidence: `README.md`)
- Gateway service → Conversation loop: runs agent (evidence: `tui_gateway/server.py`)
- ACP server → Conversation loop: exposes agent (evidence: `acp_adapter/server.py`)
- Conversation loop → Model providers: calls models
- Conversation loop → Tool execution: dispatches tools
- Tool execution → Execution backends: uses environments (evidence: `README.md`)
- Conversation loop → Context compression: compresses context (evidence: `agent/conversation_loop.py`)
- Conversation loop → Session state: persists turns
- Conversation loop → Model metadata: uses model data (evidence: `agent/conversation_loop.py`)
- Conversation loop → Data redaction: sanitizes content (evidence: `agent/conversation_loop.py`)
- Conversation loop → Localization: localizes responses
- Conversation loop → Subagents: spawns subagents (evidence: `README.md`)
- Conversation loop → Learning and skills: learns from tasks (evidence: `README.md`)
- Conversation loop → Session search: searches history (evidence: `README.md`)
- Cron automation → Messaging channels: delivers automation (evidence: `README.md`)
- Learning and skills → Agent memory: curates knowledge (evidence: `README.md`)
- Context compression → Conversation archive: archives context
- Conversation loop → User: returns response
