# artemfire1980/hermes-titan architecture

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

- Interactive diagram: https://gitdiagram.com/artemfire1980/hermes-titan
- Repository: https://github.com/artemfire1980/hermes-titan

## Overview

Hermes-Titan is an autonomous engineering and research platform built around an external Hermes Agent, with Telegram as its documented user interface. Its principal workflow is Telegram → Hermes → Aider → Git; a distinct research workflow runs topic research through search, page extraction, evidence analysis, and cited summaries. The graph also preserves the documented task board, memory, skills, and MCP integrations. Research-module connections are based on shown calls or the source index; unsampled integrations are shown only where the README documents them.

Main entry points: [`scripts/research/runner.py`](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/runner.py) (Research orchestrator), [`scripts/aider_runner.py`](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/aider_runner.py) (Aider runner), [`scripts/research_runner.py`](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research_runner.py) (Research CLI), [`scripts/research/search.py`](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/search.py) (Web search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_telegram(("Telegram"))
  node_hermes["Hermes Agent"]
end

subgraph group_engineering["Engineering workflow"]
  node_aider["Aider runner<br/>[aider_runner.py]"]
  node_git[("Git repository")]
  node_taskledger[("Task ledger<br/>[task_ledger.py]")]
end

subgraph group_research["Research engine"]
  node_researchcli["Research CLI<br/>[research_runner.py]"]
  node_researchrunner["Research orchestrator<br/>[runner.py]"]
  node_search["Web search<br/>[search.py]"]
  node_fetch["Page extraction<br/>[fetch.py]"]
  node_llm["LLM gateway<br/>[llm.py]"]
  node_evidence["Evidence analysis<br/>[evidence.py]"]
  node_scoring["Source scoring<br/>[scoring.py]"]
  node_checkpoint["Research checkpoints<br/>[checkpoint.py]"]
  node_summary["Cited summaries"]
end

subgraph group_operations["Platform capabilities"]
  node_skills["Agent skills"]
  node_memory["Holographic memory"]
  node_kanban["Kanban board"]
end

subgraph group_integrations["External integrations"]
  node_searxng["SearXNG"]
  node_freellm["FreeLLM API"]
  node_mcp{{"MCP services"}}
  node_telegramnotify["Telegram notifications"]
end

node_user(("User"))

node_user -->|"sends request"| node_telegram
node_telegram -->|"routes request"| node_hermes
node_hermes -->|"delegates code"| node_aider
node_aider -.->|"records tasks"| node_taskledger
node_aider -->|"changes code"| node_git
node_hermes -.->|"starts research"| node_researchcli
node_researchcli -->|"runs research"| node_researchrunner
node_researchrunner -->|"queries sources"| node_search
node_search -->|"searches web"| node_searxng
node_researchrunner -->|"fetches pages"| node_fetch
node_researchrunner -->|"extracts evidence"| node_llm
node_llm -->|"calls API"| node_freellm
node_researchrunner -->|"validates claims"| node_evidence
node_researchrunner -->|"scores sources"| node_scoring
node_researchrunner -->|"saves progress"| node_checkpoint
node_researchrunner -->|"generates summary"| node_summary
node_hermes -->|"uses skills"| node_skills
node_hermes -->|"uses memory"| node_memory
node_hermes -->|"manages tasks"| node_kanban
node_hermes -->|"connects services"| node_mcp
node_telegramnotify -.->|"sends updates"| node_telegram

click node_aider "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/aider_runner.py"
click node_taskledger "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/task_ledger.py"
click node_researchcli "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research_runner.py"
click node_researchrunner "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/runner.py"
click node_search "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/search.py"
click node_fetch "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/fetch.py"
click node_llm "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/llm.py"
click node_evidence "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/evidence.py"
click node_scoring "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/scoring.py"
click node_checkpoint "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/checkpoint.py"
click node_summary "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/summary_generator.py"
click node_skills "https://github.com/artemfire1980/hermes-titan/tree/main/skills"
click node_memory "https://github.com/artemfire1980/hermes-titan/blob/main/configs/holographic-entities.patch"
click node_searxng "https://github.com/artemfire1980/hermes-titan/tree/main/configs/searxng"
click node_telegramnotify "https://github.com/artemfire1980/hermes-titan/blob/main/scripts/send_to_telegram.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_telegram,node_hermes,node_user toneBlue
class node_aider,node_git,node_taskledger toneAmber
class node_researchcli,node_researchrunner,node_search,node_fetch,node_llm,node_evidence,node_scoring,node_checkpoint,node_summary toneMint
class node_skills,node_memory,node_kanban toneRose
class node_searxng,node_freellm,node_mcp,node_telegramnotify toneIndigo
```

## Components

### User interaction

- **Telegram**
- **Hermes Agent**

### Engineering workflow

- [Aider runner](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/aider_runner.py): `scripts/aider_runner.py`
- **Git repository**
- [Task ledger](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/task_ledger.py): `scripts/task_ledger.py`

### Research engine

- [Research CLI](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research_runner.py): `scripts/research_runner.py`
- [Research orchestrator](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/runner.py): `scripts/research/runner.py`
- [Web search](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/search.py): `scripts/research/search.py`
- [Page extraction](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/fetch.py): `scripts/research/fetch.py`
- [LLM gateway](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/llm.py): `scripts/research/llm.py`
- [Evidence analysis](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/evidence.py): `scripts/research/evidence.py`
- [Source scoring](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/scoring.py): `scripts/research/scoring.py`
- [Research checkpoints](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/research/checkpoint.py): `scripts/research/checkpoint.py`
- [Cited summaries](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/summary_generator.py): `scripts/summary_generator.py`

### Platform capabilities

- [Agent skills](https://github.com/artemfire1980/hermes-titan/tree/main/skills): `skills`
- [Holographic memory](https://github.com/artemfire1980/hermes-titan/blob/main/configs/holographic-entities.patch): `configs/holographic-entities.patch`
- **Kanban board**

### External integrations

- [SearXNG](https://github.com/artemfire1980/hermes-titan/tree/main/configs/searxng): `configs/searxng`
- **FreeLLM API**
- **MCP services**
- [Telegram notifications](https://github.com/artemfire1980/hermes-titan/blob/main/scripts/send_to_telegram.py): `scripts/send_to_telegram.py`

### Other components

- **User**

## Connections

- User → Telegram: sends request (evidence: `README.md`)
- Telegram → Hermes Agent: routes request (evidence: `README.md`)
- Hermes Agent → Aider runner: delegates code (evidence: `README.md`)
- Aider runner → Task ledger: records tasks (evidence: `scripts/aider_runner.py`)
- Aider runner → Git repository: changes code (evidence: `README.md`)
- Hermes Agent → Research CLI: starts research
- Research CLI → Research orchestrator: runs research (evidence: `scripts/research_runner.py`)
- Research orchestrator → Web search: queries sources (evidence: `scripts/research/runner.py`)
- Web search → SearXNG: searches web (evidence: `README.md`)
- Research orchestrator → Page extraction: fetches pages (evidence: `scripts/research/runner.py`)
- Research orchestrator → LLM gateway: extracts evidence (evidence: `scripts/research/runner.py`)
- LLM gateway → FreeLLM API: calls API (evidence: `README.md`)
- Research orchestrator → Evidence analysis: validates claims (evidence: `scripts/research/runner.py`)
- Research orchestrator → Source scoring: scores sources (evidence: `scripts/research/runner.py`)
- Research orchestrator → Research checkpoints: saves progress (evidence: `scripts/research/runner.py`)
- Research orchestrator → Cited summaries: generates summary (evidence: `scripts/research/runner.py`)
- Hermes Agent → Agent skills: uses skills (evidence: `README.md`)
- Hermes Agent → Holographic memory: uses memory (evidence: `README.md`)
- Hermes Agent → Kanban board: manages tasks (evidence: `README.md`)
- Hermes Agent → MCP services: connects services (evidence: `README.md`)
- Telegram notifications → Telegram: sends updates (evidence: `README.md`)
