# nousresearch/hermes-agent architecture

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

- Interactive diagram: https://gitdiagram.com/nousresearch/hermes-agent
- Repository: https://github.com/nousresearch/hermes-agent
- Video tour (about a minute): https://gitdiagram.com/nousresearch/hermes-agent/video

## Overview

Hermes Agent is a self-improving, model-flexible AI agent accessed through a CLI/TUI or messaging gateway. The main workflow is a user turn handled by the conversation loop, which uses model providers and tools, with context management supporting ongoing conversations. Separate capabilities include memory and skill learning, delegation, scheduled jobs, and LSP-assisted coding. The README documents product-level flows; the sampled source excerpts are too limited to establish most internal call edges, so those are omitted rather than inferred.

Main entry points: [`agent/conversation_loop.py`](https://github.com/nousresearch/hermes-agent/blob/main/agent/conversation_loop.py) (Conversation loop), [`agent/lsp/manager.py`](https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/manager.py) (LSP service), [`plugins/teams_pipeline/pipeline.py`](https://github.com/nousresearch/hermes-agent/blob/main/plugins/teams_pipeline/pipeline.py) (Teams summaries), [`cli.py`](https://github.com/nousresearch/hermes-agent/blob/main/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_tui["Terminal UI"]
  node_gateway["Messaging gateway<br/>[server.py]"]
  node_openai_api["OpenAI routes"]
end

subgraph group_runtime["Agent runtime"]
  node_conversation["Conversation loop"]
  node_providers["Model providers"]
  node_tools["Tool execution<br/>[tool_executor.py]"]
  node_runtime_helpers["Runtime helpers"]
  node_delegation["Subagents"]
  node_lsp_manager["LSP service<br/>[manager.py]"]
  node_lsp_client["LSP client<br/>[client.py]"]
  node_lsp_servers["LSP servers<br/>[servers.py]"]
  node_lsp_workspace["LSP workspace<br/>[workspace.py]"]
  node_lsp_events["LSP event log<br/>[eventlog.py]"]
end

subgraph group_learning["Learning and context"]
  node_context["Context engine<br/>[context_engine.py]"]
  node_memory["Memory<br/>[memory_manager.py]"]
  node_skills["Skills<br/>[skill_commands.py]"]
  node_session_search["Session search"]
end

subgraph group_operations["Automation and integrations"]
  node_cron["Scheduled jobs<br/>[jobs.py]"]
  node_teams_pipeline["Teams summaries<br/>[pipeline.py]"]
  node_spillover[("Tool result storage")]
  node_redaction["Redaction<br/>[redact.py]"]
  node_localization["Localization<br/>[i18n.py]"]
end

node_user(("User"))

node_user -->|"starts chat"| node_cli
node_user -->|"interacts"| node_tui
node_user -->|"messages"| node_gateway
node_cli -->|"starts conversation"| node_conversation
node_conversation -->|"uses models"| node_providers
node_conversation -->|"calls tools"| node_tools
node_conversation -->|"manages context"| node_context
node_user -->|"sends requests"| node_openai_api
node_openai_api -->|"routes turns"| node_conversation
node_lsp_manager -->|"manages clients"| node_lsp_client
node_lsp_manager -->|"loads definitions"| node_lsp_servers
node_lsp_manager -->|"uses workspace"| node_lsp_workspace
node_lsp_manager -->|"logs events"| node_lsp_events
node_teams_pipeline -->|"calls model"| node_providers
node_teams_pipeline -.-> node_spillover

click node_cli "https://github.com/nousresearch/hermes-agent/blob/main/cli.py"
click node_tui "https://github.com/nousresearch/hermes-agent/blob/main/ui-tui/src/app/useInputHandlers.ts"
click node_gateway "https://github.com/nousresearch/hermes-agent/blob/main/tui_gateway/server.py"
click node_openai_api "https://github.com/nousresearch/hermes-agent/blob/main/gateway/platforms/api_server_openai_routes.py"
click node_conversation "https://github.com/nousresearch/hermes-agent/blob/main/agent/conversation_loop.py"
click node_providers "https://github.com/nousresearch/hermes-agent/blob/main/agent/auxiliary_client.py"
click node_tools "https://github.com/nousresearch/hermes-agent/blob/main/agent/tool_executor.py"
click node_runtime_helpers "https://github.com/nousresearch/hermes-agent/blob/main/agent/agent_runtime_helpers.py"
click node_context "https://github.com/nousresearch/hermes-agent/blob/main/agent/context_engine.py"
click node_memory "https://github.com/nousresearch/hermes-agent/blob/main/agent/memory_manager.py"
click node_skills "https://github.com/nousresearch/hermes-agent/blob/main/agent/skill_commands.py"
click node_session_search "https://github.com/nousresearch/hermes-agent/blob/main/agent/session_persistence.py"
click node_delegation "https://github.com/nousresearch/hermes-agent/blob/main/agent/delegation_provider.py"
click node_lsp_manager "https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/manager.py"
click node_lsp_client "https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/client.py"
click node_lsp_servers "https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/servers.py"
click node_lsp_workspace "https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/workspace.py"
click node_lsp_events "https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/eventlog.py"
click node_cron "https://github.com/nousresearch/hermes-agent/blob/main/cron/jobs.py"
click node_teams_pipeline "https://github.com/nousresearch/hermes-agent/blob/main/plugins/teams_pipeline/pipeline.py"
click node_spillover "https://github.com/nousresearch/hermes-agent/blob/main/tools/tool_result_storage.py"
click node_redaction "https://github.com/nousresearch/hermes-agent/blob/main/agent/redact.py"
click node_localization "https://github.com/nousresearch/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_tui,node_gateway,node_openai_api,node_user toneBlue
class node_conversation,node_providers,node_tools,node_runtime_helpers,node_delegation,node_lsp_manager,node_lsp_client,node_lsp_servers,node_lsp_workspace,node_lsp_events toneAmber
class node_context,node_memory,node_skills,node_session_search toneMint
class node_cron,node_teams_pipeline,node_spillover,node_redaction,node_localization toneRose
```

## Components

### User interfaces

- [CLI](https://github.com/nousresearch/hermes-agent/blob/main/cli.py): `cli.py`
- [Terminal UI](https://github.com/nousresearch/hermes-agent/blob/main/ui-tui/src/app/useInputHandlers.ts): `ui-tui/src/app/useInputHandlers.ts`
- [Messaging gateway](https://github.com/nousresearch/hermes-agent/blob/main/tui_gateway/server.py): `tui_gateway/server.py`
- [OpenAI routes](https://github.com/nousresearch/hermes-agent/blob/main/gateway/platforms/api_server_openai_routes.py): `gateway/platforms/api_server_openai_routes.py`

### Agent runtime

- [Conversation loop](https://github.com/nousresearch/hermes-agent/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Model providers](https://github.com/nousresearch/hermes-agent/blob/main/agent/auxiliary_client.py): `agent/auxiliary_client.py`
- [Tool execution](https://github.com/nousresearch/hermes-agent/blob/main/agent/tool_executor.py): `agent/tool_executor.py`
- [Runtime helpers](https://github.com/nousresearch/hermes-agent/blob/main/agent/agent_runtime_helpers.py): `agent/agent_runtime_helpers.py`
- [Subagents](https://github.com/nousresearch/hermes-agent/blob/main/agent/delegation_provider.py): `agent/delegation_provider.py`
- [LSP service](https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/manager.py): `agent/lsp/manager.py`
- [LSP client](https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/client.py): `agent/lsp/client.py`
- [LSP servers](https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/servers.py): `agent/lsp/servers.py`
- [LSP workspace](https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/workspace.py): `agent/lsp/workspace.py`
- [LSP event log](https://github.com/nousresearch/hermes-agent/blob/main/agent/lsp/eventlog.py): `agent/lsp/eventlog.py`

### Learning and context

- [Context engine](https://github.com/nousresearch/hermes-agent/blob/main/agent/context_engine.py): `agent/context_engine.py`
- [Memory](https://github.com/nousresearch/hermes-agent/blob/main/agent/memory_manager.py): `agent/memory_manager.py`
- [Skills](https://github.com/nousresearch/hermes-agent/blob/main/agent/skill_commands.py): `agent/skill_commands.py`
- [Session search](https://github.com/nousresearch/hermes-agent/blob/main/agent/session_persistence.py): `agent/session_persistence.py`

### Automation and integrations

- [Scheduled jobs](https://github.com/nousresearch/hermes-agent/blob/main/cron/jobs.py): `cron/jobs.py`
- [Teams summaries](https://github.com/nousresearch/hermes-agent/blob/main/plugins/teams_pipeline/pipeline.py): `plugins/teams_pipeline/pipeline.py`
- [Tool result storage](https://github.com/nousresearch/hermes-agent/blob/main/tools/tool_result_storage.py): `tools/tool_result_storage.py`
- [Redaction](https://github.com/nousresearch/hermes-agent/blob/main/agent/redact.py): `agent/redact.py`
- [Localization](https://github.com/nousresearch/hermes-agent/blob/main/agent/i18n.py): `agent/i18n.py`

### Other components

- **User**

## Connections

- User → CLI: starts chat (evidence: `README.md`)
- User → Terminal UI: interacts (evidence: `README.md`)
- User → Messaging gateway: messages (evidence: `README.md`)
- CLI → Conversation loop: starts conversation (evidence: `README.md`)
- Conversation loop → Model providers: uses models (evidence: `README.md`)
- Conversation loop → Tool execution: calls tools (evidence: `README.md`)
- Conversation loop → Context engine: manages context (evidence: `agent/context_engine.py`)
- User → OpenAI routes: sends requests (evidence: `gateway/platforms/api_server_openai_routes.py`)
- OpenAI routes → Conversation loop: routes turns (evidence: `gateway/platforms/api_server_openai_routes.py`)
- LSP service → LSP client: manages clients (evidence: `agent/lsp/manager.py`)
- LSP service → LSP servers: loads definitions (evidence: `agent/lsp/manager.py`)
- LSP service → LSP workspace: uses workspace (evidence: `agent/lsp/manager.py`)
- LSP service → LSP event log: logs events (evidence: `agent/lsp/manager.py`)
- Teams summaries → Model providers: calls model (evidence: `plugins/teams_pipeline/pipeline.py`)
- Teams summaries → Tool result storage
