{
  "id": "page:docs-hermes-research-raw-architecture",
  "_kind": "Page",
  "_file": "wiki/docs/hermes-research/raw/architecture.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/hermes-research/raw/architecture.md",
    "sourceKind": "repo-docs",
    "title": "Hermes Agent Architecture",
    "displayName": "Hermes Agent Architecture",
    "slug": "docs/hermes-research/raw/architecture",
    "articlePath": "wiki/docs/hermes-research/raw/architecture.md",
    "article": "\n# Hermes Agent Architecture\n\n> Source: https://hermes-agent.nousresearch.com/docs/developer-guide/architecture\n\n## System Overview\n\nThe architecture consists of three entry points (CLI, Gateway, ACP) that feed into the core `AIAgent`, which orchestrates:\n\n- **Prompt Builder**: System prompt assembly\n- **Provider Resolution**: API mode and credentials selection\n- **Tool Dispatch**: Schema collection and tool execution\n\nThese components interact with session storage (SQLite with FTS5) and tool backends spanning terminal, browser, web, MCP, and file operations.\n\n## Directory Structure\n\nThe codebase organizes around:\n\n- `run_agent.py` -- Core conversation loop\n- `cli.py` -- Interactive terminal UI\n- `model_tools.py` -- Tool discovery and dispatch\n- `agent/` -- Agent internals (prompt building, context compression, caching)\n- `hermes_cli/` -- CLI subcommands and setup\n- `tools/` -- 70+ tool implementations across 28 toolsets\n- `gateway/` -- 20 messaging platform adapters\n- `acp_adapter/` -- IDE integration (VS Code, Zed, JetBrains)\n- `plugins/` -- Memory providers and context engines\n\n## Data Flow\n\n**CLI Session**: User input -> HermesCLI -> AIAgent -> prompt builder -> provider resolution -> API call -> tool dispatch (if needed) -> response display and session save\n\n**Gateway Message**: Platform event -> adapter -> authorization -> session resolution -> AIAgent -> response delivery\n\n**Cron Job**: Scheduler tick -> load jobs -> fresh AIAgent with skill context -> execute -> platform delivery\n\n## Major Subsystems\n\n**Agent Loop**: Synchronous orchestration handling provider selection, prompt construction, tool execution, retries, and persistence.\n\n**Prompt System**: Assembles ordered tiers (identity -> context -> volatile), applies Anthropic cache breakpoints, and summarizes conversation turns when context exceeds thresholds.\n\n**Provider Resolution**: Maps provider-model pairs to API credentials across 18+ providers with OAuth and alias resolution.\n\n**Tool System**: Central registry auto-discovering 70+ tools at import time with terminal backends supporting local, Docker, SSH, Daytona, Modal, and Singularity.\n\n**Session Persistence**: SQLite storage with lineage tracking, platform isolation, and contention handling.\n\n**Messaging Gateway**: Long-running process with 20 platform adapters, unified routing, authorization, slash commands, hooks, and cron integration.\n\n**Plugin System**: Three discovery sources (user, project, pip) registering tools, hooks, and commands. Specialized plugins for memory providers and context engines (single-select only).\n\n**Cron**: First-class agent tasks storing in JSON with multiple schedule formats, skill attachment, and multi-platform delivery.\n\n**ACP Integration**: Editor-native agent over stdio/JSON-RPC for IDE environments.\n\n**Trajectories**: ShareGPT-format generation from agent sessions for training data.\n\n## Design Principles\n\n| Principle | Implementation |\n|-----------|-----------------|\n| Prompt stability | System prompt unchanged mid-conversation; cache-breaking only on explicit actions |\n| Observable execution | Every tool call visible via callbacks with progress updates |\n| Interruptible | API calls and tool execution cancellable by user input or signals |\n| Platform-agnostic core | Single AIAgent class across CLI, gateway, ACP, batch, and API |\n| Loose coupling | Optional subsystems use registry patterns and conditional gating |\n| Profile isolation | Each profile gets dedicated HERMES_HOME, config, memory, and sessions |\n\n## File Dependency Chain\n\nTool registration occurs at import time: `tools/registry.py` (zero dependencies) <- `tools/*.py` (auto-register) <- `model_tools.py` <- entry points. This enables automatic tool discovery without manual imports.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-hermes-research",
      "to": "page:docs-hermes-research-raw-architecture",
      "kind": "contains_page"
    }
  ]
}