Hermes Agent
The self-improving AI agent built by Nous Research with a built-in learning loop, persistent memory, and multi-platform messaging support.
Introduction
Hermes Agent is an open-source, self-improving AI agent framework built by Nous Research. It is the only agent with a built-in learning loop: it creates skills from experience, improves them during use, nudges itself to persist knowledge, and builds a deepening model of who you are across sessions.
Unlike a coding copilot tethered to a single IDE or a chatbot wrapper around one API, Hermes is an autonomous agent that lives wherever you put it: a $5 VPS, a GPU cluster, Docker, SSH hosts, or serverless infrastructure on Daytona or Modal. It works with any LLM provider and switches between them with a single command.
Key Features
- Self-Improving Skills - Creates skills from experience, improves them during use, and curates them autonomously. Skills evolve over time without user intervention.
- Persistent Cross-Session Memory - Remembers user preferences, environment details, project conventions, and lessons learned across conversations. Supports multiple backends: built-in SQLite, Honcho, and Mem0.
- 20+ LLM Providers - Works with OpenRouter, Anthropic, OpenAI, DeepSeek, Google Gemini, Nous Portal, xAI, Hugging Face, GitHub Copilot, local models, and more. Swap providers mid-workflow without restarting.
- Messaging Gateway - Connect to Telegram, Discord, Slack, WhatsApp, Signal, Email, and 10+ platforms simultaneously. Talk to your agent from any messaging app.
- Multi-Platform - Runs on Linux, macOS, native Windows, WSL2, Android (Termux), Docker, SSH hosts, and serverless infrastructure.
- Built-in Cron Scheduler - Schedule recurring tasks with natural language or cron expressions. Jobs run autonomously with no user present.
- Subagent Delegation - Spawn isolated subagents for parallel work. Each gets its own conversation context, terminal, and tools.
- Native MCP Client - Built-in Model Context Protocol support for connecting to databases, file systems, cloud APIs, and version control.
- Profiles - Run multiple independent agent instances with isolated configurations, sessions, skills, memory, plugins, and cron jobs. Perfect for work vs personal separation.
- 40+ Built-in Tools - Organized into toolsets: terminal, file, web search, browser automation, image generation, text-to-speech, vision analysis, code execution, and more. Toolsets can be enabled or disabled per platform.
History and Background
Hermes Agent emerged from the OpenClaw ecosystem, the pioneering open-source agent harness that grew to over 381,000 GitHub stars. While OpenClaw pioneered the concept of a personal AI agent that communicates through messaging platforms, it struggled with stability, breaking changes, and limited documentation.
Nous Research, known for their work on open-source AI models like the Hermes series, built Hermes Agent as a more stable, better-documented, and more capable alternative. The project has since grown to over 210,000 GitHub stars, with 14,500+ commits, 5,000+ issues resolved, and 38,000+ forks. It is under active development with daily commits and a dedicated team led by Teknium.
A key differentiator is the built-in migration path: OpenClaw users can run hermes claw migrate to import their persona, memory, skills, messaging settings, API keys, and workspace configs automatically.
Architecture
Hermes Agent follows a modular architecture with several key components:
- Core Agent Loop - The main conversation loop (run_agent.py) handles turn-by-turn interaction with any LLM provider, tool discovery and dispatch, context compression, and session management.
- Terminal UI (Hermes CLI) - Built with prompt_toolkit, offering multiline editing, syntax highlighting, tab completion, streaming tool output, and conversation history. Accessible via the
hermescommand. - Desktop Application - A native desktop GUI for macOS and Windows, providing a graphical interface alongside the CLI.
- Gateway Daemon - A separate process that connects to messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, etc.) and routes messages to the agent. Can run as a background service.
- Cron Scheduler - Background job scheduler for recurring automated tasks. Jobs run in fresh sessions with no memory of past conversations.
- Skills Engine - Manages SKILL.md documents with YAML frontmatter. Skills are scanned before every turn; relevant ones are injected into the system prompt.
- Memory Store - SQLite-backed persistent memory system that survives across sessions and agent restarts.
Installation Guide
Linux / macOS / WSL2 / Termux:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashWindows (PowerShell):
iex (irm https://hermes-agent.nousresearch.com/install.ps1)Desktop App:
Download the Hermes Desktop installer from hermes-agent.nousresearch.com for a native desktop experience.
The installer sets up Python 3.11 via uv, Node.js, ripgrep, and ffmpeg automatically. After installation, run source ~/.bashrc (or source ~/.zshrc), then start chatting with hermes.
Fastest Path to a Working Agent
hermes setup --portalOne OAuth covers a model plus all Tool Gateway tools: web search (Firecrawl), image generation (FAL), text-to-speech (OpenAI), and browser automation (Browser Use).
CLI Usage and Commands
Hermes Agent's CLI is a full terminal user interface (TUI) built with prompt_toolkit. It features multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output. A modern TUI mode with modal overlays and mouse selection is available via hermes --tui.
CLI Commands Reference
| Command | Description |
|---|---|
hermes | Start interactive CLI session (default mode) |
hermes chat -q "query" | Single query mode (non-interactive) |
hermes --tui | Launch modern TUI with modal overlays and mouse support |
hermes --continue | Resume the most recent CLI session (-c) |
hermes --resume SESSION_ID | Resume a specific session by ID (-r) |
hermes --model "provider/model" | Start with a specific model |
hermes --provider PROVIDER | Force a specific provider (nous, openrouter, etc.) |
hermes --toolsets "web,file,terminal" | Enable specific toolsets |
hermes -s SKILL_NAME | Start with one or more skills preloaded |
hermes --verbose | Enable verbose debug output |
hermes --yolo | Skip all approval prompts (auto-approve mode) |
hermes -w | Run in isolated git worktree (parallel agents) |
hermes model | Browse and switch LLM providers/models |
hermes tools | Configure which tools are enabled per platform |
hermes config set KEY VALUE | Set individual config values |
hermes gateway | Start/stop/restart the messaging gateway |
hermes gateway status | Check gateway health and platform connections |
hermes gateway platforms | List all configured messaging platforms and their status |
hermes setup | Run the full setup wizard |
hermes setup --portal | Fast setup with Nous Portal OAuth |
hermes doctor | Diagnose dependencies and config issues |
hermes update | Update Hermes Agent to the latest version |
hermes cron list | List all scheduled cron jobs |
hermes cron create SCHEDULE | Create a new cron job |
hermes skills list | Show installed skills |
hermes skills search QUERY | Search the skills hub |
hermes skills install ID | Install a skill from the hub |
hermes skills browse | Browse all available skills |
hermes profile list | List all agent profiles |
hermes profile create NAME | Create a new profile |
hermes claw migrate | Import all data from OpenClaw |
hermes memory status | Check memory provider status |
hermes mcp list | List configured MCP servers |
hermes portal info | Check what Nous Portal services are wired up |
In-Session Slash Commands
During an interactive session, these slash commands are available:
| Command | Description |
|---|---|
/model | Switch model/provider mid-conversation |
/compress | Compress session context to save tokens |
/usage | View detailed cost breakdown per category |
/yolo | Toggle auto-approve mode |
/platforms | Show messaging platform connection statuses |
/background | Start a background task |
/status | Show session status and stats |
/help | Show all available slash commands |
Status Bar Elements
A persistent status bar above the input area shows real-time session info:
| Element | Description |
|---|---|
| Model name | Current model (truncated at 26 chars) |
| Token count | Context tokens used / max context window |
| Context bar | Visual fill indicator (green <50%, yellow 50-80%, orange 80-95%, red >=95%) |
| Cost | Estimated session cost |
| N | Context compression count |
| N | Active background tasks |
| Duration | Elapsed session time |
Messaging Gateway
The Messaging Gateway is a separate daemon that connects Hermes Agent to your messaging platforms. Once configured, you can talk to your agent from any connected platform and receive responses on the same channel. The gateway runs as a background service and can handle multiple platforms simultaneously.
Supported Platforms
| Platform | Features | Auth Method |
|---|---|---|
| Telegram | Full support, topic threads, voice messages, commands, inline buttons | Bot Token |
| Discord | Thread support, slash commands, role-based access, approval buttons | Bot Token |
| Slack | Channels, DMs, thread replies, app mentions | Bot Token + Signing Secret |
| Individual chats, voice message transcription | Cloud API / WhatsApp Business | |
| Signal | Private messaging, group chats | Signal CLI |
| iMessage | Apple ecosystem messaging | macOS bridge |
| Email (SMTP/IMAP) | Send and receive via any email provider, threading | SMTP/IMAP credentials |
| Matrix | Decentralized chat, end-to-end encryption | Homeserver + Access Token |
| Twitter/X | DMs, post replies, mentions | API v2 Keys |
| SMS (Twilio) | Text messaging via phone number | Twilio Account SID + Token |
| IRC | Classic IRC protocol, channels, private messages | Server + Nickname |
| Facebook Messenger | Page DMs, conversations | Page Access Token |
Gateway Features
- Command Approval - Dangerous commands (rm -rf, git reset --hard, etc.) require confirmation via the messaging platform before execution. Three modes: manual, smart, and off.
- Home Channels - Set a default delivery channel for automated messages and cron output.
- Topic/Thread Support - Telegram topics and Discord threads create separate session scopes for organized conversations.
- Voice Memo Transcription - Automatic speech-to-text for voice messages on supported platforms (Telegram, WhatsApp).
- DM Pairing - Users must be authorized before sending commands to the agent, preventing unauthorized access.
- Multi-Profile Gateway - Run multiple gateway instances, each connected to different platforms or using different credentials.
Gateway Commands
hermes gateway start # Start gateway as background service
hermes gateway status # Check gateway health and platform connections
hermes gateway platforms # List all connected platforms and their status
hermes gateway restart # Restart the gateway
hermes gateway stop # Stop the gateway
During an interactive session, type /platforms to see the live status of all configured messaging platforms.
Skills System
The skills system is what makes Hermes self-improving. Skills are reusable procedural knowledge documents (SKILL.md files with YAML frontmatter) that the agent creates, loads, and improves autonomously. After solving a complex task, Hermes can save the approach as a skill. Relevant skills are injected into every future turn automatically.
Each skill includes YAML frontmatter (name, description, version, metadata, related skills) and a markdown body with procedures, exact commands, pitfalls, and verification steps. A built-in curator tracks skill usage, marks idle skills as stale, and archives unused ones. Pinned skills are exempt from all transitions.
hermes skills list # Show installed skills
hermes skills search QUERY # Search the skills hub
hermes skills install ID # Install from hub
hermes skills browse # Browse all available skills
hermes skills publish PATH # Publish to registry
Provider System
Hermes is provider-agnostic and supports 20+ LLM providers through a unified API interface. Swap models and providers mid-workflow without changing config files or restarting. Providers include Nous Portal, OpenRouter, Anthropic, OpenAI, Google Gemini, DeepSeek, xAI, Hugging Face, GitHub Copilot, MiniMax, and local models via Ollama or llama.cpp.
Hermes supports credential pooling (multiple API keys for the same provider, auto-rotated on rate limits), automatic failover to fallback providers, and individual rate-limit tracking per credential.
Community Provider Recommendations (July 2026)
| Category | Community Pick | Runner-Up |
|---|---|---|
| Best overall (paid API) | DeepSeek V4 Pro (direct) | DeepSeek V4 Flash |
| Best value subscription | OpenCode Go ($10/mo) | MiniMax $10 token plan |
| Best premium subscription | Nous Portal ($20) | OpenAI Codex ($20 ChatGPT) |
| Best free model (no catch) | owL-alpha (OpenRouter) | Nemotron 3 Super 120B (free) |
| Best coding model | GPT-5.5 (via Codex) | DeepSeek V4 Pro |
| Best orchestrator model | GPT-5.4-mini | DeepSeek V4 Flash |
| Best predictable billing | OpenCode Go + MiniMax stack | Nous Portal |
Comparison with Alternatives
| Feature | Hermes Agent | OpenClaw | Coding Agents |
|---|---|---|---|
| Self-improving skills | Built-in, autonomous | Manual only | No |
| Persistent memory | SQLite + plugins | File-based | Session only |
| Messaging platforms | 12+ (unified gateway) | 20+ (separate setups) | None |
| Cron scheduler | Built-in | Built-in | No |
| MCP support | Native built-in | Plugin | Some |
| Provider failover | Automatic | Manual | Varies |
| Desktop app | Native (macOS/Windows) | No | IDE-integrated |
| OpenClaw migration | Built-in CLI command | N/A | N/A |
Use Cases
- Personal AI Assistant - Manage your calendar, emails, to-do lists, and smart home via messaging apps.
- DevOps Automation - Monitor servers, deploy code, check logs, and run maintenance tasks on a schedule.
- Content Generation - Research topics, draft articles, generate images, and publish to your blog automatically.
- Research Assistant - Search the web, extract information, summarize findings, and maintain a knowledge base.
- Coding Companion - Review code, generate tests, refactor projects, and debug issues with subagent delegation.
- Home Automation Hub - Connect to smart home devices and control them through voice or text commands.