# absentdaemon-ctrl/kos-mos architecture

> Architecture diagram of the GitHub repository absentdaemon-ctrl/kos-mos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/absentdaemon-ctrl/kos-mos
- Repository: https://github.com/absentdaemon-ctrl/kos-mos

## Overview

Hermes Agent is a self-improving, tool-using AI agent that users can access through a CLI/TUI or messaging platforms. A user request enters an interface and is handled by the conversation loop, which prepares context and prompts, calls a selectable model provider, and can dispatch tools or delegate parallel work. The product also includes memory and skill learning, scheduled automation, and multiple execution environments. Relationships here are grounded in README capability statements; several subsystems are represented by their directories because their implementation files were not sampled.

Main entry points: [`agent/conversation_loop.py`](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/conversation_loop.py) (Conversation loop), [`gateway`](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/gateway) (Messaging gateway), [`hermes_cli`](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/hermes_cli) (CLI), [`ui-tui/src/app.tsx`](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/ui-tui/src/app.tsx) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI"]
  node_tui["Terminal UI<br/>[app.tsx]"]
  node_messaging["Messaging gateway"]
end

subgraph group_runtime["Agent runtime"]
  node_loop["Conversation loop"]
  node_prompt["Prompt building<br/>[prompt_builder.py]"]
  node_context["Context compression"]
  node_compression["Conversation compression"]
  node_helpers["Runtime helpers"]
end

subgraph group_capabilities["Agent capabilities"]
  node_learning["Learning and memory"]
  node_session_search[("Session search<br/>[hermes_state.py]")]
  node_trajectory["Trajectory generation<br/>[trajectory.py]"]
end

subgraph group_integrations["Models and tools"]
  node_models["Model selection<br/>[models.py]"]
  node_providers["Provider adapters"]
  node_tools["Tool execution<br/>[tool_executor.py]"]
end

subgraph group_operations["Automation and environments"]
  node_backends["Terminal backends"]
  node_delegation["Subagents"]
  node_scheduler["Scheduled jobs"]
end

node_user(("User"))

node_user -->|"starts chat"| node_cli
node_user -->|"starts chat"| node_tui
node_user -->|"sends message"| node_messaging
node_cli -->|"runs turn"| node_loop
node_tui -->|"runs turn"| node_loop
node_messaging -->|"runs turn"| node_loop
node_loop -->|"builds prompt"| node_prompt
node_loop -->|"selects model"| node_models
node_models -->|"routes request"| node_providers
node_loop -->|"compresses context"| node_context
node_loop -->|"compresses history"| node_compression
node_loop -->|"dispatches tools"| node_tools
node_tools -->|"runs commands"| node_backends
node_loop -->|"spawns agents"| node_delegation
node_loop -->|"learns from use"| node_learning
node_learning -->|"searches history"| node_session_search
node_scheduler -->|"delivers reports"| node_messaging
node_loop -->|"records trajectories"| node_trajectory
node_loop -.->|"uses runtime support"| node_helpers

click node_cli "https://github.com/absentdaemon-ctrl/kos-mos/tree/main/hermes_cli"
click node_tui "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/ui-tui/src/app.tsx"
click node_messaging "https://github.com/absentdaemon-ctrl/kos-mos/tree/main/gateway"
click node_loop "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/conversation_loop.py"
click node_prompt "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/prompt_builder.py"
click node_context "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/context_compressor.py"
click node_compression "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/conversation_compression.py"
click node_helpers "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/agent_runtime_helpers.py"
click node_models "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/hermes_cli/models.py"
click node_providers "https://github.com/absentdaemon-ctrl/kos-mos/tree/main/agent"
click node_tools "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/tool_executor.py"
click node_backends "https://github.com/absentdaemon-ctrl/kos-mos/tree/main/tools/environments"
click node_delegation "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/subagent_lifecycle.py"
click node_learning "https://github.com/absentdaemon-ctrl/kos-mos/tree/main/agent"
click node_session_search "https://github.com/absentdaemon-ctrl/kos-mos/blob/main/hermes_state.py"
click node_scheduler "https://github.com/absentdaemon-ctrl/kos-mos/tree/main/cron"
click node_trajectory "https://github.com/absentdaemon-ctrl/kos-mos/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_messaging,node_user toneBlue
class node_loop,node_prompt,node_context,node_compression,node_helpers toneAmber
class node_learning,node_session_search,node_trajectory toneMint
class node_models,node_providers,node_tools toneRose
class node_backends,node_delegation,node_scheduler toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/hermes_cli): `hermes_cli`
- [Terminal UI](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/ui-tui/src/app.tsx): `ui-tui/src/app.tsx`
- [Messaging gateway](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/gateway): `gateway`

### Agent runtime

- [Conversation loop](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/conversation_loop.py): `agent/conversation_loop.py`
- [Prompt building](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/prompt_builder.py): `agent/prompt_builder.py`
- [Context compression](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/context_compressor.py): `agent/context_compressor.py`
- [Conversation compression](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/conversation_compression.py): `agent/conversation_compression.py`
- [Runtime helpers](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/agent_runtime_helpers.py): `agent/agent_runtime_helpers.py`

### Agent capabilities

- [Learning and memory](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/agent): `agent`
- [Session search](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/hermes_state.py): `hermes_state.py`
- [Trajectory generation](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/trajectory.py): `agent/trajectory.py`

### Models and tools

- [Model selection](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/hermes_cli/models.py): `hermes_cli/models.py`
- [Provider adapters](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/agent): `agent`
- [Tool execution](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/tool_executor.py): `agent/tool_executor.py`

### Automation and environments

- [Terminal backends](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/tools/environments): `tools/environments`
- [Subagents](https://github.com/absentdaemon-ctrl/kos-mos/blob/main/agent/subagent_lifecycle.py): `agent/subagent_lifecycle.py`
- [Scheduled jobs](https://github.com/absentdaemon-ctrl/kos-mos/tree/main/cron): `cron`

### Other components

- **User**

## Connections

- User → CLI: starts chat
- User → Terminal UI: starts chat
- User → Messaging gateway: sends message
- CLI → Conversation loop: runs turn (evidence: `agent/conversation_loop.py`)
- Terminal UI → Conversation loop: runs turn
- Messaging gateway → Conversation loop: runs turn
- Conversation loop → Prompt building: builds prompt (evidence: `agent/conversation_loop.py`)
- Conversation loop → Model selection: selects model
- Model selection → Provider adapters: routes request (evidence: `hermes_cli/models.py`)
- Conversation loop → Context compression: compresses context (evidence: `agent/conversation_loop.py`)
- Conversation loop → Conversation compression: compresses history
- Conversation loop → Tool execution: dispatches tools
- Tool execution → Terminal backends: runs commands
- Conversation loop → Subagents: spawns agents
- Conversation loop → Learning and memory: learns from use (evidence: `agent/conversation_loop.py`)
- Learning and memory → Session search: searches history
- Scheduled jobs → Messaging gateway: delivers reports
- Conversation loop → Trajectory generation: records trajectories
- Conversation loop → Runtime helpers: uses runtime support (evidence: `agent/conversation_loop.py`)
