Hermes Agent
Architecture Deep Analysis

Architecture Overview

Hermes Agent is a self-improving AI agent operating system. It runs a re-entrant agentic loop that assembles context from multiple sources, invokes an LLM, executes tool calls, observes results, and recursively abstracts successful workflows into reusable skills. The v2026.4.30 release represents the most significant architectural expansion since the initial launch — introducing background curation, task orchestration, and tool safety guardrails.

flowchart TB
    subgraph PA["Prompt Assembly"]
        SOUL["SOUL.md (Identity Core)"]
        SKILL["Skill Index (FTS5 + LRU)"]
        PROJ["Project Context (.hermes.md)"]
        KANBAN["Kanban Protocol"]
        GUARD["Guardrails"]
    end

    subgraph AL["Agentic Loop"]
        LOOP["AIAgent.run()"]
        LLM["LLM Inference"]
        TOOLS["Tool Execution (40+)"]
        OBSERVE["Observation"]
    end

    subgraph NEW["v2026.4.30 Subsystems"]
        CURATOR["Curator (Background)"]
        KANBAN_DB["Kanban Board (SQLite)"]
        GOALS["Persistent Goals"]
    end

    SOUL --> LOOP
    SKILL --> LOOP
    PROJ --> LOOP
    KANBAN --> LOOP
    GUARD --> TOOLS
    LOOP --> LLM
    LLM --> TOOLS
    TOOLS --> OBSERVE
    OBSERVE --> LOOP
    LOOP -.-> CURATOR
    LOOP -.-> KANBAN_DB
    LOOP -.-> GOALS

    style CURATOR fill:#0a2a1a,stroke:#00FF88,stroke-width:2px
    style KANBAN_DB fill:#0a2a1a,stroke:#00FF88,stroke-width:2px
    style GOALS fill:#0a2a1a,stroke:#00FF88,stroke-width:2px
    style GUARD fill:#1a0a2a,stroke:#FF00FF,stroke-width:2px
    style LOOP fill:#0a1a2a,stroke:#00FFFF,stroke-width:2px
  

Curator NEW

Background Skill Maintenance Orchestrator

The Curator is an auxiliary-model background process that periodically reviews agent-created skills and maintains the collection. It's the first true "meta-agent" — a second AIAgent fork that runs independently to curate the primary agent's skill corpus.

stateDiagram-v2
    [*] --> Active: Agent creates
    Active --> Stale: 30 days unused
    Stale --> Archived: 90 days unused
    Active --> Pinned: User pins
    Pinned --> Active: User unpins
    Archived --> Active: User recovers
    state Stale {
        [*] --> ReviewNeeded
        ReviewNeeded --> Consolidate
        ReviewNeeded --> Patch
    }
      

The Curator never auto-deletes — only archives. Archive is recoverable. It uses a separate auxiliary LLM client so it never touches the main session's prompt cache or token budget. This is a safety-first design.

Kanban Board NEW

Multi-Agent Task Orchestration System

The Kanban system is a full task management and multi-agent orchestration layer built on SQLite. It enables persistent, cross-session task delegation where the AI agent acts as both worker and dispatcher — spawning specialist sub-agents for decomposed work items.

sequenceDiagram
    participant U as User
    participant GW as Gateway
    participant AG as Main Agent
    participant KB as Kanban DB
    participant W1 as Worker A
    participant W2 as Worker B

    U->>GW: Create task
    GW->>AG: Dispatch
    AG->>KB: kanban_create()
    AG->>KB: Create child tasks

    Note over AG: Orchestration complete

    KB->>W1: Spawn worker (task=t1)
    W1->>KB: kanban_show() (Orient)
    W1->>KB: kanban_heartbeat()
    W1->>KB: kanban_complete(summary)

    KB->>W2: Spawn worker (depends on t1)
    W2->>KB: kanban_show() (Reads handoff)
    W2->>KB: kanban_complete(summary)

    AG->>U: Results summary
  

Tool Guardrails NEW

Side-Effect-Free Safety Controller

A pure observation layer that classifies every tool call as idempotent (read-only) or mutating, tracks per-turn tool call patterns, and returns decisions that the runtime can use for warning guidance, synthetic tool results, or controlled turn halts.

Persistent Goals NEW

Cross-Turn Goal Persistence (Ralph Loop)

The /goal command introduces persistent cross-turn goals — objectives that survive across sessions and automatically re-inject into the agent's context on each new turn.

flowchart LR
    A["Goal: Deploy SaaS MVP"] --> B["Goal Store (~/.hermes/goals/)"]
    B --> C["Session 1: Research"]
    C --> D["Session 2: Build (auto-injected)"]
    D --> E["Session 3: Ship (auto-injected)"]
    E --> F["Goal: Complete (MVP deployed)"]

    style B fill:#0a1a2a,stroke:#00FFFF
    style F fill:#0a2a1a,stroke:#00FF88
  

Prompt Construction Engine

Updated v2026.4.30 Prompt Assembly Pipeline

flowchart TD
    A["Static Identity (SOUL.md)"] --> E["Assembled Prompt"]
    B["Skill Index (FTS5 + LRU Cache)"] --> E
    C["Project Context (.hermes.md)"] --> E
    D["Platform Hints (Telegram/Discord)"] --> E
    F["Session Context (Current Chat)"] --> E
    G["Memory Injection (Profile + Notes)"] --> E
    H["NEW: Kanban Guidance (Task Protocol)"] --> E
    I["NEW: Goal Injection (Cross-Turn)"] --> E
    E --> J["LLM"]

    style H fill:#0a2a1a,stroke:#00FF88,stroke-width:2px
    style I fill:#0a2a1a,stroke:#00FF88,stroke-width:2px
    style E fill:#0a1a2a,stroke:#00FFFF,stroke-width:2px
  

# Kanban task execution protocol
1. Orient -> kanban_show()
2. Work -> $HERMES_KANBAN_WORKSPACE
3. Heartbeat -> kanban_heartbeat()
4. Block -> kanban_block() if stuck
5. Complete -> kanban_complete(summary, metadata)
6. Spawn follow-up; don't scope-creep

Gateway & Multi-Platform Layer

v2026.4.30 Release Delta

What changed since the previous analysis

Code Impact

Agentic Loop Deep Dive

The Self-Improving Flywheel

flowchart TD
    A["User Message or Cron Trigger"] --> B["Prompt Assembly (SOUL + Skills + Context)"]
    B --> C["LLM Call (Multi-Provider Routing)"]
    C --> D{"Response Type"}
    D -->|"Tool Call"| E["Guardrails Check (Idempotent vs Mutating)"]
    E --> F["Execute Tool (40+ Tools)"]
    F --> G["Observe Result"]
    G --> B
    D -->|"Text Response"| H["Deliver to User"]
    G -.-> I{"5+ Tool Calls?"}
    I -.->|"Yes"| J["Skill Abstraction (skill_manage create)"]
    J -.-> K["Curator Review (Background, Idle)"]
    K -.-> L["Skill Index (FTS5 Database)"]

    style E fill:#1a0a2a,stroke:#FF00FF,stroke-width:2px
    style J fill:#0a2a1a,stroke:#00FF88,stroke-width:2px
    style K fill:#0a2a1a,stroke:#00FF88,stroke-width:3px
  

Deployment Architecture

flowchart TB
    TUI["TUI (hermes chat)"] --> LOOP
    GW["Gateway (REST API)"] --> LOOP
    CRON["Cron (Scheduled)"] --> LOOP
    KANBAN_CLI["Kanban CLI"] --> SQLITE
    GOAL_CLI["Goals CLI"] --> SQLITE
    LOOP["Agentic Loop (AIAgent.run())"] --> CURATOR_DAEMON
    LOOP --> LLM_M
    CURATOR_DAEMON["Curator (Idle-Triggered)"] --> AUX
    LOOP --> LOCAL
    LOOP --> DOCKER
    LOOP --> SSH
    LOOP --> MODAL
    LOOP --> SQLITE
    SQLITE["SQLite (kanban.db, fts5_skills.db, goals/)"]
    LLM_M["LLM (OpenAI/Anthropic/Gemini/OpenRouter)"]
    AUX["Auxiliary LLM (Curator/Summarizer)"]
    LOCAL["Local Shell"]
    DOCKER["Docker (Hardened)"]
    SSH["SSH Remote"]
    MODAL["Modal (Serverless GPU)"]

    style CURATOR_DAEMON fill:#0a2a1a,stroke:#00FF88,stroke-width:2px
    style SQLITE fill:#2a2a0a,stroke:#FFD700
    style LOOP fill:#0a1a2a,stroke:#00FFFF,stroke-width:2px
  

Four-Tier Memory Architecture

The agent maintains four distinct memory tiers, each with a different lifetime and retrieval mechanism:

Architectural Warning Signs