Nous Research

Hermes Agent

The self-improving AI agent that creates skills from experience, improves them during use, and runs anywhere. Open source. MIT licensed.

What makes Hermes different? Most AI agents are stateless—every conversation starts from zero. Hermes has a built-in learning loop: it creates reusable skills from successful interactions, persists memory across sessions, and gets better the more you use it.

v0.8.0

MIT License

Python 3.11+

200+ Models

MCP Native

Multi-Platform

Explore the Guide

Installation

One-line install for Linux, macOS, WSL2, and Termux. First-run setup wizard.

quickstartsetup

→

CLI Reference

Commands, slash commands, sessions, cron scheduler, and terminal UI features.

commandsTUI

→

Skills & Learning Loop

How Hermes creates, improves, and persists skills autonomously across sessions.

self-improvingskills-hub

→

MCP & Tools

Model Context Protocol servers, 17 built-in toolsets, and extensibility.

MCPtoolsets

→

Model Providers

OpenRouter, Nous Portal, Anthropic, OpenAI, and custom endpoints.

LLMproviders

→

Platforms & Gateway

Deploy to Telegram, Discord, Slack, WhatsApp, Signal, and more.

gatewaymessaging

→

Architecture Deep Dive

Memory system, terminal backends, security model, and data flow.

internalsdesign

→

Quick Links

GitHub Repository

NousResearch/hermes-agent

Official Docs

hermes-agent.nousresearch.com

Nous Research

nousresearch.com

Community Discord

Support & discussion

Getting Started

Installation

Hermes Agent installs in one command on Linux, macOS, WSL2, and Android (Termux). Windows users need WSL2.

One-Line Install

# Install Hermes Agent curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

What the installer does: Creates a Python 3.11+ virtual environment, installs the hermes-agent package and dependencies, sets up ~/.hermes/ configuration directory, and adds the hermes command to your PATH.

Manual Install (pip)

# Requires Python 3.11+ pip install hermes-agent # With optional extras pip install "hermes-agent[telegram,discord,voice,mcp]"

Platform Requirements

Platform	Requirement	Notes
Linux	Python 3.11+	Native support, all features
macOS	Python 3.11+	Native support, all features
Windows	WSL2	Must run inside WSL2, not native Windows
Android	Termux	Install via `hermes-agent[termux]` extra

First-Run Setup

1. Launch hermesRun hermes to start the setup wizard

2. Select providerhermes model — choose your LLM provider

3. Set API keyEnter credentials for your chosen provider

4. Configure toolshermes setup — enable toolsets and platforms

5. Start chattinghermes drops into interactive TUI

Optional Extras

Messaging

telegram, discord, slack, matrix — gateway platform adapters

Voice

voice — faster-whisper STT + sounddevice for speech-to-text and TTS

Deployment

modal, daytona — cloud terminal backends

MCP

mcp — Model Context Protocol server support

Smart Home

homeassistant — Home Assistant integration

Research

rl — reinforcement learning training via Tinker-Atropos

Verify Installation

hermes doctor ✓ Python 3.12.4 ✓ Virtual environment active ✓ Config directory: ~/.hermes/ ✓ Required packages installed ✓ API key configured # Use --fix to auto-repair issues hermes doctor --fix

Migrating from OpenClaw

Hermes Agent includes automated migration from OpenClaw. The migration preserves:

Persona files (SOUL.md)
Memories and session history
Skills and command allowlists
API keys and provider configuration

Command Line

CLI Reference

Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.

Top-Level Commands

Command	Description
hermes	Launch interactive chat (default mode)
hermes model	Select LLM provider and model
hermes setup	Run full configuration wizard
hermes gateway	Manage messaging platform services
hermes doctor	Diagnose and auto-fix installation issues
hermes mcp	Manage MCP server connections
hermes skills	Browse, install, and manage skills
hermes cron	Schedule automated tasks

Slash Commands (In-Chat)

Session Management

/new

Start a fresh conversation session

/clear

Clear current session context

/history

Browse past sessions with search

/save

Save current session to disk

/retry

Re-run the last agent response

/undo

Revert the last message pair

/branch

Fork conversation into a new branch

/compress

Compress session to save context

/background

Send current task to background

/resume

Resume a background task

Configuration

/model

Switch model mid-session: /model gpt-4o

/voice

Toggle voice input/output

/skin

Change terminal UI theme

/verbose

Toggle verbose tool output

/yolo

Toggle auto-approve mode for tools

/fast

Toggle fast inference mode

Tools & Skills

/tools

List all available tools and their status

/toolsets

Enable or disable toolset groups

/skills

Manage installed skills

/cron

View and manage scheduled jobs

/plugins

Manage installed plugins

/reload-mcp

Reconnect to MCP servers

Cron Scheduler

Hermes includes a built-in cron system for automating recurring tasks. Jobs are defined with cron expressions and executed by the gateway service.

# Create a scheduled job hermes cron add "Check my email and summarize" --schedule "0 9 * * *" # List all jobs hermes cron list # Check scheduler status hermes cron status # Pause / resume hermes cron pause job-id hermes cron resume job-id

Gateway required: The gateway service must be running for cron jobs to fire automatically. Install it as a systemd user service with hermes gateway install, or run hermes gateway start in the foreground.

Session Management

Sessions are stored in a local SQLite database (~/.hermes/state.db) with FTS5 full-text search. The curses-powered session browser supports live search filtering, title/preview matching, and relative timestamps.

Search: FTS5 with LLM summarization for cross-session recall
Branch: Fork conversations to explore alternatives
Compress: Reduce context length while preserving meaning
Resume: Pick up any previous session exactly where you left off

Doctor Diagnostics

The hermes doctor command runs comprehensive checks across your installation:

Python environmentVersion, venv, required packages

Configuration files.env, config.yaml, version migrations

Directory structuresessions, logs, skills, memories, SOUL.md

External toolsgit, ripgrep, Docker, SSH, Node.js

API connectivityProvider endpoints, auth validation

MCP serversConnection status, tool discovery

Learning Loop

Skills & Self-Improvement

Hermes creates reusable skills from successful interactions, stores them locally, and improves them over time. This is the core differentiator.

The learning loop: When Hermes solves a problem well, it can extract the approach into a named skill with metadata. Next time a similar task appears, it finds and applies the skill—and refines it based on the outcome. Skills compound: the agent gets meaningfully better with use.

Skill Lifecycle

1. CreateAgent extracts approach into SKILL.md with YAML frontmatter

2. StoreSaved to ~/.hermes/skills/{category}/{name}/

3. DiscoverFuzzy matched by name, tags, and description when relevant

4. ApplyInjected into context when the agent recognizes a matching task

5. ImproveUpdated based on outcomes—better approaches replace old ones

Skills Hub

The Skills Hub is a multi-source registry for discovering and installing community-built skills. It supports four trust levels:

Official

Published by Nous Research. Highest trust, auto-approved installation.

Trusted

Verified partner skills. Installed with a trust badge indicator.

Community

User-contributed skills. Security scanned before installation.

Custom Taps

Your own GitHub repos as skill sources via hermes skills tap add.

Skill Commands

# Browse available skills hermes skills browse # Install a skill by short name hermes skills install pptx # List installed skills hermes skills list # Check for updates hermes skills update # Export/import skill configuration hermes skills export > my-skills.json hermes skills import my-skills.json

Security Model

Every skill goes through a security pipeline before installation:

QuarantineIsolated in temporary directory

ScanStatic analysis via skills_guard

Policy CheckVerdict: pass, warn, or block

ConfirmUser approval for warn-level findings

DeployInstalled to skills directory, cache invalidated

Blocked skills: If a skill receives a “dangerous” verdict from the scanner, installation is blocked entirely. Warnings require a --force flag. All actions are audit-logged.

Memory System

Alongside skills, Hermes maintains persistent memory across sessions:

Agent-curated memory with periodic nudges for relevance
FTS5 session search with LLM summarization for cross-session recall
Honcho integration for dialectic user modeling—builds a profile of your preferences and working style
SQLite-backed storage in ~/.hermes/state.db

Extensibility

MCP & Tools

17 built-in toolsets plus unlimited extension via Model Context Protocol servers. The same MCP servers that work with Claude Code work with Hermes.

Built-in Toolsets

Web Search

Search and scrape the web via Firecrawl, Exa, Tavily, or Nous Subscription

Browser

Full browser automation via local Chromium, Browserbase, or Firecrawl

Terminal

Execute commands in local, Docker, SSH, Daytona, Singularity, or Modal

File Operations

Read, write, search, and manage files in the working directory

Code Execution

Run Python, JavaScript, and shell scripts with output capture

Vision

Analyze images, screenshots, and visual content

Image Generation

Create images via Nous Subscription or FAL.ai

Text-to-Speech

Five TTS providers: Edge (free), OpenAI, ElevenLabs, Mistral, Nous

Skills Management

Create, discover, install, and improve reusable skills

Task Planning

Break complex tasks into steps with dependency tracking

Memory

Persistent cross-session knowledge and user modeling

Session Search

FTS5 full-text search across all conversation history

Clarifying Questions

Agent asks for clarification when intent is ambiguous

Task Delegation

Spawn isolated subagents for parallel execution

Cron Jobs

Schedule and manage automated recurring tasks

RL Training

Reinforcement learning via Tinker-Atropos (research)

Home Assistant

Control smart home devices via HA integration

MCP Server Management

# Add an HTTP MCP server hermes mcp add my-server --url https://mcp.example.com/sse # Add a stdio MCP server hermes mcp add my-local --command npx --args @example/mcp-server # Add from preset hermes mcp add github --preset github # List configured servers hermes mcp list # Test connection and discover tools hermes mcp test my-server # Configure which tools are enabled hermes mcp configure my-server # Remove a server hermes mcp remove my-server

MCP Configuration

Server configurations persist in ~/.hermes/config.yaml under the mcp_servers key:

mcp_servers: my-server: transport: http url: "https://mcp.example.com/sse" headers: Authorization: "Bearer ${MCP_MY_SERVER_API_KEY}" tools: include: ["tool_a", "tool_b"] enabled: true

Environment variable interpolation: Values containing ${VARIABLE} are resolved at connection time. API keys are stored as env vars (e.g., MCP_SERVERNAME_API_KEY) and referenced in headers. OAuth 2.1 PKCE is also supported.

Tool Provider Configuration

Category	Providers
Text-to-Speech	Nous (managed), Edge (free), OpenAI, ElevenLabs, Mistral
Web Search	Nous, Firecrawl, Exa, Parallel, Tavily, Self-hosted
Browser	Nous, Local Chromium, Browserbase, Browser Use, Firecrawl, Camofox
Image Gen	Nous (managed), FAL.ai

LLM Providers

Model Configuration

Hermes works with any model—200+ options via OpenRouter, plus direct API access to major providers. Switch models mid-session without code changes.

Supported Providers

OpenRouter

200+ models via pay-per-use aggregator. Recommended for flexibility—one API key, every model.

Nous Portal

Subscription-based access to Nous-hosted models. Managed infrastructure, predictable pricing.

Anthropic

Direct Claude API access. Supports OAuth, API keys, and Claude Code credential sharing.

OpenAI

GPT-4o, o1, o3, and Codex models. Direct API or via Codex integration.

GitHub Copilot

OAuth and ACP modes for Copilot-authenticated access to multiple backends.

Custom Endpoint

Any OpenAI-compatible API. Self-hosted models, vLLM, TGI, Ollama, etc.

Regional Providers

Qwen (Alibaba)

Kimi / Moonshot

MiniMax

z.ai / GLM

DingTalk

Feishu

Mistral AI

Switching Models

# Interactive model selector hermes model # Switch mid-session (in chat) /model claude-sonnet-4-6 # Set globally /model gpt-4o --global # Use any OpenRouter model /model anthropic/claude-opus-4-6

No code changes needed: The model_normalize.py layer handles API differences between providers transparently. Switch from Claude to GPT to Qwen mid-conversation—tool calling, streaming, and function schemas are automatically adapted.

Authentication Methods

Provider	Auth Method	Config Key
OpenRouter	API key	OPENROUTER_API_KEY
Nous Portal	Subscription OAuth	Managed via `hermes model`
Anthropic	API key / OAuth	ANTHROPIC_API_KEY
OpenAI	API key	OPENAI_API_KEY
Copilot	OAuth / ACP	Managed via `hermes model`
Custom	API key + base URL	CUSTOM_API_KEY + CUSTOM_BASE_URL

Deployment

Platforms & Gateway

Run Hermes as a CLI tool, or deploy it as a persistent agent on Telegram, Discord, Slack, WhatsApp, Signal, and more via the gateway service.

Supported Platforms

CLI (Default)

Full TUI with curses interface, multiline editing, autocomplete, and streaming output.

Bot API integration. Rich messages, inline keyboards, voice messages.

Discord

Bot integration with slash commands, threads, and skill registration.

Slack

App integration with subcommand routing and channel awareness.

Via WhatsApp Business API or bridge services.

Signal

Secure messaging via Signal CLI bridge.

Matrix

Decentralized chat protocol support.

SMS

Text message interface via SMS gateway providers.

Gateway Service

# Start gateway in foreground hermes gateway start # Install as systemd user service hermes gateway install # Check gateway status hermes gateway status # Stop the service hermes gateway stop

The gateway is the backbone: It handles incoming messages from all platforms, routes them to the agent, manages sessions per-user, and executes cron jobs. Without the gateway running, messaging platforms and scheduled tasks won't work.

Terminal Backends

When Hermes needs to execute commands, it can use multiple terminal backends depending on your security and isolation requirements:

LocalDirect execution on host machine (default)

DockerSandboxed execution in ephemeral containers

SSHRemote execution on any SSH-accessible host

DaytonaCloud development environments

SingularityHPC-compatible containerized execution

ModalServerless cloud compute with GPU support

Platform Configuration

# Interactive platform setup hermes setup # Configure specific platform hermes gateway configure telegram # Enable platform toolsets hermes setup tools

Internals

Architecture

How Hermes Agent is built: the data flow, module structure, memory system, and security model.

System Overview

USER INTERFACES CLI/TUI Telegram Discord Slack ... │ │ │ │ │ └─────────────┴──────────────┴────────────┴──────────┘ │ ┌─────────▼──────────┐ │ Gateway Router │ └─────────┬──────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Agent Core │ │ Skills Hub │ │ MCP Bridge │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ ┌──────▼───────┐ ┌──────▼───────┐ ┌──────▼───────┐ │ LLM Provider │ │ Skill DB │ │ MCP Servers │ └──────────────┘ └──────────────┘ └──────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ state.db │ │ memories │ │ sessions │ └──────────┘ └──────────┘ └──────────┘

Key Modules

Module	Purpose
main.py	CLI entry point, command routing, first-run guards
commands.py	Slash command registry, aliases, autocomplete, platform filtering
claw.py	Core agent loop—LLM interaction, tool execution, streaming
gateway.py	Multi-platform message router and service manager
skills_hub.py	Skill discovery, installation, security scanning, trust levels
skills_config.py	Skill metadata, SKILL.md parsing, YAML frontmatter
mcp_config.py	MCP server lifecycle—add, test, configure, remove
tools_config.py	Toolset management, provider selection, API key handling
model_normalize.py	Cross-provider API normalization layer
model_switch.py	Runtime model switching without session restart
memory_setup.py	Memory provider configuration (Honcho, Mem0)
doctor.py	Diagnostic checks, auto-fix, health monitoring
cron.py	Job scheduler—create, pause, resume, tick
config.py	YAML config persistence, env var loading, profile support
callbacks.py	Event hooks for tool execution, streaming, and UI updates

Data Flow

When a user sends a message, here's what happens:

1. InputUser message received via CLI prompt or gateway platform

2. ContextSession history, relevant memories, and active skills loaded

3. LLM CallMessage sent to configured provider with tool definitions

4. Tool ExecutionAgent may call tools (terminal, web, MCP, skills) in parallel

5. ResponseStreamed back to user with rich formatting

6. LearningSkills updated, memories persisted, session saved

Directory Structure

~/.hermes/ ├── .env # API keys and secrets ├── config.yaml # All configuration ├── SOUL.md # Agent persona definition ├── state.db # SQLite: sessions, search index ├── skills/ # Installed skills by category │ ├── coding/ │ ├── research/ │ └── custom/ ├── memories/ # Persistent agent memories ├── sessions/ # Session export files ├── logs/ # Runtime logs └── cron/ # Scheduled job definitions

Security Model

Skill Scanning

All community skills are statically analyzed before installation. Dangerous patterns are blocked.

Tool Approval

By default, tool calls require user approval. /yolo mode auto-approves (use with caution).

Sandboxed Execution

Docker and Singularity backends isolate terminal commands from the host system.

Credential Isolation

API keys stored in .env, referenced via ${VAR} interpolation—never exposed in config files.

Entry Points

# Three registered entry points (pyproject.toml) hermes → hermes_cli.main # Interactive CLI hermes-agent → run_agent # Headless agent mode hermes-acp → acp_adapter.entry # Agent Communication Protocol