Back to repos

NousResearch/hermes-agent

View on GitHubAnalyzed April 12, 2026

Overview

Hermes Agent is a self-improving, multi-platform AI agent developed by Nous Research. Its core mission is to provide an extensible, highly configurable, and persistent AI assistant that can interact through both terminal (CLI/TUI) and messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, Email, and more). Hermes stands out for its closed learning loop: it autonomously creates, improves, and persists skills from experience, maintains deep user profiles, and enables robust session and memory management across platforms and devices. The agent is designed to run anywhere—from a $5 VPS to serverless cloud infrastructure—without being tied to a specific machine.

Hermes supports a vast array of language models and providers, including OpenRouter (200+ models), Nous Portal, OpenAI, Anthropic, Gemini, Kimi/Moonshot, MiniMax, z.ai/GLM, and custom endpoints. Users can switch models and providers on the fly without code changes. The agent is also deeply extensible: it features a modular tool system (for web search, browser automation, file operations, terminal access, etc.), a skills ecosystem (bundled, optional, and community skills), and a data-driven skin/theme engine for CLI customization.

Architecture

Hermes Agent's architecture is modular and layered:

  • Core Agent Loop: The AIAgent class (in run_agent.py) orchestrates the conversation, tool invocation, and session persistence. It builds prompts, manages tool calls, and handles context compression.
  • Tool System: Tools are self-registering Python modules (in tools/), grouped into toolsets (via toolsets.py). The central registry (tools/registry.py) manages schemas, handlers, and dispatch. Tool discovery is triggered by model_tools.py.
  • Skills System: Skills are procedural memory/instruction bundles (in skills/ and optional-skills/), discoverable and installable via the Skills Hub. Skills can be enabled/disabled per platform and conditionally activated based on tool availability.
  • CLI & Skin Engine: The interactive CLI (cli.py and hermes_cli/) uses prompt_toolkit for input, rich for rendering, and a data-driven skin system (hermes_cli/skin_engine.py) for theming. All slash commands are centrally registered and auto-dispatched.
  • Messaging Gateway: The gateway/ package provides adapters for Telegram, Discord, Slack, WhatsApp, Signal, Email, and Home Assistant, with unified session and tool management.
  • Session & Memory: Persistent session data is managed via SQLite (hermes_state.py) with FTS5 search, and all conversations are logged for recall and training. User profiles and memories are stored per profile in ~/.hermes/.
  • Extensibility: The project supports plugins, RL training environments (Atropos), and integration with the Agent Communication Protocol (ACP) for editor support.

Key Features

  • Self-Improving Agent Loop: Hermes creates and improves skills from experience, nudges itself to persist knowledge, and autonomously manages its memory.
  • Multi-Platform Messaging: Unified gateway for Telegram, Discord, Slack, WhatsApp, Signal, Email, and more, with cross-platform session continuity and media support.
  • Flexible Tool System: 40+ built-in tools (web, browser, terminal, file, vision, etc.), toolset grouping, and per-platform enable/disable.
  • Skills Ecosystem: Bundled, optional, and community skills, with a Skills Hub for discovery and installation. Skills can be conditionally activated based on tool availability or platform.
  • Persistent Memory & Session Search: Full-text search across sessions, context compression, and user modeling (Honcho integration).
  • Cron Scheduling: Built-in scheduler for natural language automations, with delivery to any platform.
  • Parallelization & Delegation: Subagent spawning for parallel workstreams, and Python scripting with RPC tool access.
  • Skin/Theme Engine: Data-driven CLI theming with built-in and user-defined skins.
  • Research-Ready: Batch trajectory generation, RL environments, and trajectory compression for tool-calling model training.
  • Security & Reliability: Dangerous command detection, sandboxed execution, atomic writes, and cross-platform compatibility.

Development & Extensibility

Hermes Agent is designed for both end-users and developers. The project structure is well-documented (see AGENTS.md and CONTRIBUTING.md), with clear guidelines for adding new tools, skills, and skins. The agent supports multiple isolated profiles, robust test coverage (3,000+ tests), and a strong focus on security and reliability. Developers can easily extend the system by adding new tools (Python modules), skills (instruction bundles), or messaging adapters, and can leverage the RL and ACP integrations for advanced use cases.

Example: Agent Loop (from run_agent.py)

while api_call_count < self.max_iterations and self.iteration_budget.remaining > 0:
    response = client.chat.completions.create(model=model, messages=messages, tools=tool_schemas)
    if response.tool_calls:
        for tool_call in response.tool_calls:
            result = handle_function_call(tool_call.name, tool_call.args, task_id)
            messages.append(tool_result_message(result))
        api_call_count += 1
    else:
        return response.content

Documentation & Community

Comprehensive documentation is available at hermes-agent.nousresearch.com/docs, covering installation, configuration, CLI and gateway usage, tool and skill development, security, and architecture. The project is open-source (MIT license) and welcomes contributions via GitHub and Discord.