Most AI agents today are chatbots with extra steps. You talk to them, they forget everything, and you start over next time. Hermes Agent, built by Nous Research, takes a different approach. It remembers what it learns, creates reusable skills from experience, and runs on your own infrastructure instead of someone else's cloud.
This article covers what Hermes Agent actually is, why it matters for developers, and how to get it running.
What Is Hermes Agent?
Hermes Agent is an open-source AI agent (MIT licensed) with a built-in learning loop. That phrase sounds like marketing, but it describes something specific: after completing a complex task, the agent can save the approach as a reusable "skill" for next time. It maintains persistent memory across sessions. It builds a model of who you are and how you work.
It is not a wrapper around a single API. You can plug in whatever LLM provider you want -- OpenAI, Anthropic, OpenRouter (which gives you access to 200+ models), or your own self-hosted endpoint running Ollama, vLLM, or SGLang. Switching providers is a single command. No code changes.
The project has about 8,700 stars on GitHub, 142 contributors, and 2,293 commits as of late March 2026. It is written primarily in Python.
Why Should a Developer Care?
There are many agent frameworks out there. Here is what makes Hermes Agent worth looking at.
It is not tied to your laptop. You can run the agent on a $5 VPS, inside a Docker container, over SSH to a remote server, or on serverless infrastructure like Modal or Daytona that hibernates when idle. You talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or the terminal. The conversation continues across platforms.
It has real memory, not a hack. The agent maintains two small, curated files: MEMORY.md (for environment facts, conventions, and lessons learned) and USER.md (for your preferences and communication style). These are injected into the system prompt at session start. The agent also has full-text search over all past sessions stored in SQLite, so it can recall conversations from weeks ago.
It learns from its own work. After a complex task (typically 5+ tool calls), the agent can autonomously create a skill -- a structured markdown document with procedures, pitfalls, and verification steps. Next time a similar task comes up, it loads the skill instead of figuring things out from scratch. Skills can also self-improve during use when the agent discovers a better approach.
It supports MCP out of the box. You can connect any Model Context Protocol server by adding a few lines to the config file. This means the agent can interact with GitHub, databases, or any service that exposes an MCP endpoint.
It is research-ready. If you are working on training better tool-calling models, Hermes includes batch trajectory generation, Atropos RL environments, and trajectory compression. This is not just a user-facing product; it is also infrastructure for building the next generation of agent models.
Core Concepts
Before setting it up, it helps to understand the main building blocks.
The Agent Loop
The core of Hermes is AIAgent in run_agent.py. It handles provider selection, prompt construction, tool execution, retries, compression, and persistence. It is a synchronous orchestration engine -- one loop that drives everything.
Skills
Skills are on-demand knowledge documents stored in ~/.hermes/skills/. They follow a progressive disclosure pattern to minimize token usage:
- Level 0: the agent sees a list of skill names and descriptions (about 3,000 tokens)
- Level 1: the agent loads the full content of a specific skill when needed
- Level 2: the agent loads a specific reference file within a skill
Each skill is a directory with a SKILL.md file and optional reference materials, templates, and scripts. The format uses YAML front matter for metadata and markdown for the actual instructions.
The agent creates skills automatically after complex tasks, but you can also write them by hand, install them from the Skills Hub (which aggregates multiple registries including skills.sh and GitHub repos), or share them with a team via external skill directories.
Memory
Memory is bounded and curated. MEMORY.md gets 2,200 characters. USER.md gets 1,375 characters. That is roughly 1,300 tokens total -- small enough that it does not bloat the context window, but large enough to hold 15-20 useful entries.
The agent manages memory itself. It adds entries when it learns something useful, replaces entries when information changes, and consolidates entries when memory gets full. There is also security scanning on memory entries to prevent prompt injection.
For deeper recall, the agent can search all past sessions using SQLite full-text search and LLM summarization. This is not in the system prompt -- it is on-demand, called when the agent needs to find something from a previous conversation.
Terminal Backends
Hermes supports six ways to execute commands: local, Docker, SSH, Daytona, Singularity, and Modal. Docker and SSH give you sandboxed execution. Daytona and Modal give you serverless persistence -- the environment hibernates when idle and wakes on demand.
The Messaging Gateway
The gateway is a long-running process that connects the agent to messaging platforms. You configure it with hermes gateway setup, start it with hermes gateway start, and then talk to the agent from your phone. The same slash commands work across all platforms.
How to Set It Up
Prerequisites
You need git installed. That is it. The installer handles Python, Node.js, and all dependencies.
Windows is not natively supported. Use WSL2 instead.
Step 1: Install
Run the one-line installer:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
After it finishes, reload your shell:
source ~/.bashrc # or source ~/.zshrc
Step 2: Configure a Provider
Run the model selection command:
hermes model
This walks you through choosing an LLM provider. Your options include:
- Nous Portal -- subscription-based, zero-config, uses OAuth
- OpenRouter -- multi-provider routing, supports 200+ models, needs an API key
- OpenAI -- uses Codex models via device code auth
- Anthropic -- Claude models directly, via Claude Code auth or an API key
- Custom Endpoint -- any OpenAI-compatible API (Ollama, vLLM, SGLang, etc.)
There are also providers for Z.AI, Kimi/Moonshot, MiniMax, Alibaba Cloud, Hugging Face, and several others.
You can switch providers at any time by running hermes model again.
Step 3: Start Chatting
hermes
That is the entire startup command. You will see a welcome banner showing your active model, available tools, and installed skills. Type a message and press Enter.
Step 4: Set Up Sandboxed Execution (Recommended)
By default, the agent runs commands on your local machine. For safety, use a sandboxed backend:
hermes config set terminal.backend docker # Docker isolation
hermes config set terminal.backend ssh # Remote server
Step 5: Connect Messaging (Optional)
If you want to talk to Hermes from Telegram, Discord, Slack, or another platform:
hermes gateway setup # Interactive configuration
hermes gateway start # Start the gateway process
Useful Commands to Know
Once Hermes is running, these commands cover most of what you need day-to-day:
hermes # Start a conversation
hermes -c # Resume the last session
hermes model # Switch LLM provider/model
hermes tools # Configure enabled tools
hermes doctor # Diagnose issues
hermes update # Update to latest version
hermes gateway # Manage messaging platforms
hermes skills search <query> # Find skills to install
Inside a conversation, type / to see all available slash commands. A few highlights:
/model # Switch models mid-conversation
/tools # List available tools
/skills # Browse and manage skills
/personality pirate # Try a fun personality
/save # Save the conversation
/compress # Compress context when it gets long
Adding MCP Servers
To connect external tools via MCP, add entries to ~/.hermes/config.yaml:
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
The agent will then have access to whatever tools that MCP server exposes.
Setting Up Scheduled Tasks
Hermes has a built-in cron scheduler that delivers results to any connected platform. You set up tasks in natural language:
> Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.
The agent creates a cron job that runs automatically via the gateway. No crontab editing required.
Contributing
If you want to contribute to the project, here is the development setup:
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
git submodule update --init mini-swe-agent
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[all,dev]"
uv pip install -e "./mini-swe-agent"
python -m pytest tests/ -q
The mini-swe-agent submodule is a required terminal backend. If you want to work on the RL/training side, also initialize the tinker-atropos submodule.
What It Is Not
Hermes Agent is not a managed service. There is no hosted version you sign up for. You run it on your own machine or server, bring your own API keys, and own all the data. If that is what you want -- full control over an agent that gets better the more you use it -- this is worth trying.
It is also not a simple chatbot wrapper. The codebase includes multiple API modes, prompt caching and compression, gateway-specific session management, RL environment infrastructure, and an editor integration layer via ACP. It is a substantial project with real architectural depth.
