Skip to content

4.HermesAgent

📅 Mon. 2026-04-20 🕐 23:25 from Gemini 3 Flash; consolidated 2026-05-17

👉 #AI #Agents #Hermes #Automation #MachineLearning

📎 Nous Research Hermes Agent GitHub 📎 Hermes Agent Configuration Guide 📎 Model Context Protocol (MCP) Integration

Consolidated reference combining the original HermesAgent.md, HermesAgent_Video.md (Théo's video walkthrough), and HelpHermes.md (CLI cheatsheet).

1. Overview

1.1. Design Intent

Hermes Agent, released by Nous Research in early 2026, was engineered to solve the "Ephemeral Intelligence" problem — the tendency of AI assistants to lose context and procedural knowledge once a session terminates. Unlike standard chatbot wrappers, Hermes is a persistent, stateful agent designed to live on the user's infrastructure. It bridges the gap between raw LLM capabilities and functional, long-running digital assistants.

1.2. Pain Points Solved
  • Contextual Amnesia: Standard agents forget user preferences and past project details. Hermes utilizes a Three-Layer Memory architecture to maintain a persistent model of the user and their workflows.
  • Rigid Tooling: Traditional agents require manual coding for every new capability. Hermes features an "Auto-Skill" system that distills successful multi-step executions into reusable, version-controlled skill documents.
  • Infrastructure Lock-in: Most agent frameworks are tied to specific cloud providers. Hermes is provider-agnostic, supporting local inference (Ollama), massive model aggregators (OpenRouter), and native cloud APIs (Anthropic, OpenAI, Google).
1.3. Key Features
  • Closed Learning Loop: Automatically observes successful tasks and crystallizes them into skills.
  • Multi-Platform Gateway: Native support for 15+ messaging platforms including Telegram, Discord, Slack, and Signal.
  • Model Context Protocol (MCP): Seamless integration with the MCP ecosystem for standardized tool access.
  • Sandboxed Execution: Modular backends allowing code execution in Docker, SSH, or Modal cloud sandboxes.
  • Unified Streaming: Real-time token delivery across CLI and gateway platforms.
1.4. Use Cases
  • Autonomous Research: Web searching, summarizing multiple sources, and delivering daily briefings to a messaging app.
  • DevOps & Infrastructure: Monitoring logs via SSH and autonomously patching known issues using stored skills.
  • Personal Knowledge Management: Integrating with Obsidian or local knowledge bases to provide "Second Brain" querying.
  • Scheduled Workflows: Running complex cron jobs that require reasoning, such as weekly data analysis or social media management.
1.5. Competitors
  • OpenClaw: A primary rival focusing on broad tool coverage and ease of deployment. Hermes competes by offering deeper "self-improvement" logic that OpenClaw lacks.
  • Microsoft AutoGen: Focuses on multi-agent conversation patterns. Hermes is more specialized as a "singular persistent companion."
  • LangChain / LlamaIndex: These are libraries for building agents. Hermes is a pre-built, production-ready agent server.
  • Claude Code: Similar terminal capabilities, but Hermes offers a wider gateway ecosystem (messaging apps) and multi-model flexibility.

2. Concept, Component, & Architecture

2.1. Key Concepts
  • The "Soul": The identity of the agent is defined in a SOUL.md file. This acts as the primary behavioral guardrail and personality template, loaded into the system prompt's first slot.
  • The Learning Loop: Hermes operates on an "Observe → Execute → Reflect → Crystallize" cycle.
  • Procedural Memory (Skills): When the agent completes a task involving five or more tool calls, it enters a reflection phase to generate a .skill file — a structured YAML/Markdown document detailing the procedure.
  • Episodic Memory: A SQLite-backed FTS5 (Full-Text Search) system that indexes every interaction. The agent can "search" its own past conversations to retrieve facts.
  • Memory Tiers:
  • Session: Wiped daily at 04:00 (default) to keep the "brain" fast.
  • Persistent: Facts about you (e.g., "I prefer Python") stay forever.
2.2. Core Components
  • The Gateway: A long-running process that manages platform adapters. It handles message routing, media attachments, and voice-to-text transcription.
  • The Core Orchestration Engine (AIAgent): The brain that handles the reasoning loop. It manages the system prompt assembly, tool selection, and model calls.
  • Execution Backends: Pluggable modules that define where shell and python tools actually run.
  • The Skill Manager: A dedicated toolset that allows the agent to search, read, write, and patch its own skills.
2.3. Architecture & Design
graph TD
  A[User Interface: CLI/Telegram/Slack] --> B[Gateway Process]
  B --> C[Orchestration Engine]
  C --> D[Memory Layer: SQLite/FTS5]
  C --> E[Skill Library: .skills]
  C --> F[LLM Provider: OpenRouter/Anthropic]
  C --> G[Execution Backend: Docker/SSH/Local]
2.4. Eco-system
  • External Integrations: Filesystem, browser automation (Playwright/Firecrawl), and standard database drivers.
  • Plugin Architecture: Drop Python scripts into ~/.hermes/plugins/ to add custom CLI commands or tool hooks without modifying the core framework.
  • MCP Support: Full compatibility with Model Context Protocol servers allows Hermes to use any tool published to the MCP community hub.

3. Install, Configure, Secure, & Cheatsheet

3.1. Infrastructure Choices (from Théo's video walkthrough)

Before installation, decide where Hermes will live:

  • VPS (Virtual Private Server): A 24/7 cloud computer where the agent lives. Recommended: Hetzner (Ubuntu 22.04 or 24.04) for a cloud-native deployment.
  • Local Machine: macOS or Linux desktop for personal use; loses persistence when the machine is off unless run as a service.
  • SSH is the "tunnel" you use from iTerm/Terminal to control the VPS: ssh root@<Your_VPS_IP>.
  • Terminal Backend Choice:
  • Local: Commands execute directly (simpler for beginners).
  • Docker: Commands execute in an isolated container (safer / sandboxed; recommended for production).
  • LLM Provider (the brain): Hermes is the "body" (memory, tools); needs an API key from OpenRouter (recommended for multi-model), OpenAI, or Anthropic.
3.2. Server Preparation (VPS)
# Update Ubuntu system
apt update && apt upgrade -y

# Generate SSH key on local machine (press Enter through prompts)
ssh-keygen -t rsa -b 4096
cat ~/.ssh/id_rsa.pub      # Paste the output into VPS provider's "SSH Keys" settings
3.3. Installation

The preferred method is the one-line automated installer.

# Pre-stage dependencies (install.sh handles them, but this avoids interactive prompts)
brew install git uv node       # Git: worktree isolation; uv: Python; Node.js: MCP stdio servers, agent-browser, WhatsApp bridge
brew install ripgrep ffmpeg    # ripgrep: fast file search (Agent tool); ffmpeg: audio format conversion (TTS/Voice)
uv python install              # Hermes runtime

# One-click official installer: dependency detection, repo cloning, venv creation,
# global `hermes` command registration, LLM Provider config wizard
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Verify installation
hermes doctor
ll ~/.local/bin/hermes         # Global hermes command symlink
mkdir -p ~/.hermes/            # Config and data directory
source ~/.zshrc                # Refresh PATH (or ~/.bashrc on Linux)

hermes config edit             # Initialize config.yaml
touch ~/.hermes/.env           # Create env file
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env
hermes setup                   # Optional wizard for API key, model selection
hermes chat -q "Hello! What tools do you have?"

Dependencies summary: Python 3.11+, Node.js 20+, ripgrep, ffmpeg, Docker (optional but recommended).

Installation choices during wizard: - Provider: Paste your OpenRouter API key (terminal won't echo characters; just paste and hit Enter). - Model: e.g., Claude 3.5 Sonnet or Llama 3. - Action Limit: Default 60 — max steps per task. - Context Compression: Default 0.85 — starts summarizing when 85% of memory is full.

3.4. Optional Extras (uv pip install -e ".[group]")
uv pip install -e ".[all]"            # All components
uv pip install -e ".[messaging]"      # Telegram, Discord, Slack gateway
uv pip install -e ".[cron]"           # Cron expression parsing
uv pip install -e ".[cli]"            # Terminal menu UI
uv pip install -e ".[modal]"          # Modal cloud execution backend
uv pip install -e ".[voice]"          # CLI mic input + audio playback
uv pip install -e ".[mcp]"            # Model Context Protocol support
uv pip install -e ".[honcho]"         # Honcho user modeling integration
uv pip install -e ".[homeassistant]"  # Home Assistant integration
uv pip install -e ".[acp]"            # ACP editor integration
uv pip install -e ".[slack]"          # Slack messaging
uv pip install -e ".[tts-premium]"    # ElevenLabs premium voice
uv pip install -e ".[dev]"            # pytest + testing tools
3.5. Configuration

Configuration is split between config.yaml (behavioral settings) and .env (secrets).

Core configuration (~/.hermes/config.yaml)

model: "anthropic/claude-3-5-sonnet"
terminal:
  backend: "docker"
  docker_image: "python:3.11-slim"
  docker_volumes:
    - "/Users/user/projects:/workspace"
compression:
  summary_model: "openai/gpt-4o-mini"
  threshold: 40000
memory:
  provider: "native"
  auto_persist: true

Environment secrets (~/.hermes/.env)

OPENROUTER_API_KEY=sk-or-v1-...
TELEGRAM_BOT_TOKEN=123456...
TELEGRAM_ALLOWED_USERS=987654321
FIRECRAWL_API_KEY=fc-...
3.6. Telegram Gateway Setup

Talk to your agent from your phone without opening a terminal.

  1. BotFather: Search for @BotFather on Telegram, run /newbot, save the API token.
  2. User ID: Use @userinfobot to get your numerical ID. This ensures only you can talk to your agent.
  3. Hermes installer prompts: When asked, paste the bot token and your user ID.
3.7. Persistent Background Service
hermes gateway service install
hermes gateway service start
hermes gateway status

# If `hermes` command isn't recognized after install:
source ~/.bashrc       # or ~/.zshrc on macOS
3.8. Security Best Practices
  • Use Docker backend: Never run the agent in local backend with untrusted inputs or complex code execution. Docker provides a hardened container with dropped capabilities.
  • Whitelist gateway users: Always set ALLOWED_USERS in .env to prevent unauthorized access to your terminal via Telegram/Discord.
  • Redact secrets: The built-in logger automatically redacts common API key patterns. Ensure custom tools follow the hermes.log redact standard.
3.9. CLI Cheatsheet
# Basic operations
hermes                                       # Start interactive chat
hermes chat -q "One-line question"           # Single question, non-interactive
hermes chat --model anthropic/claude-opus-4  # Specify model
hermes chat --toolsets web,terminal          # Specify toolsets
hermes chat --skills my-skill                # Preload skills
hermes chat --yolo                           # Skip approval
hermes chat --worktree                       # Git Worktree isolation
hermes --resume <session-id>                 # Resume specified session
hermes --continue                            # Resume most recent session

# Config & Models
hermes config show                           # View configuration
hermes config edit                           # Edit config.yaml
hermes config set KEY VALUE                  # Set value
hermes config check                          # Check for missing options
hermes config migrate                        # Interactively add new options
hermes model                                 # Interactively select Provider + Model
hermes auth                                  # Manage credential pool
hermes auth add openrouter --api-key sk-or-xxx

# Gateway (messaging platforms)
hermes gateway setup                         # Configure messaging platforms
hermes gateway run                           # Run in foreground
hermes gateway start                         # Start in background
hermes gateway stop                          # Stop
hermes gateway status                        # Status check
hermes gateway install                       # Install as system service

# Skills (official optional skills from Nous Research)
hermes skills browse                         # Browse Hub
hermes skills search <query>                 # Search
hermes skills install <id>                   # Install
hermes skills list                           # List installed
hermes skills check                          # Check for updates
hermes skills update                         # Update all

# MCP (Model Context Protocol)
hermes mcp add <name> --command <cmd> --args "<args>"
hermes mcp list                              # List configured servers
hermes mcp test <name>                       # Test connection
hermes mcp serve                             # Run as MCP Server

# Diagnose & Debug
hermes doctor                                # Diagnose issues
hermes doctor --fix                          # Auto-fix
hermes dump                                  # Export debug info
hermes debug share                           # Upload debug report
hermes status --all                          # Full status
hermes logs -f                               # Real-time logs
hermes logs --level WARNING --since 1h

# Sessions & Insights
hermes sessions list                         # List sessions
hermes sessions browse                       # Interactively browse
hermes sessions export out.jsonl
hermes insights --days 30                    # Token / cost analysis

# Backup & Migration
hermes backup                                # Full backup
hermes backup --quick                        # Quick status snapshot
hermes import backup.zip                     # Restore
hermes claw migrate --dry-run                # Preview OpenClaw migration
hermes claw migrate --preset full
3.10. Python SDK Usage
from run_agent import AIAgent

# Initialize the agent
agent = AIAgent(
    model="anthropic/claude-3.5-sonnet",
    quiet_mode=True,
    enabled_toolsets=["web_search", "filesystem"]
)

# Run a task
result = agent.chat("Analyze the files in /workspace and summarize them.")
print(result)

4. Bootcamp & Workshops

4.1. Official Training Resources
4.2. Troubleshooting (RCA)
  • Error: Context Length Exceeded
  • Root cause: The summary model context is smaller than the main agent model.
  • Solution: Set compression.summary_model to a high-capacity model (e.g., GPT-4o) or increase the compression.threshold.
  • Error: Gateway Reconnection Loop
  • Root cause: Invalid bot token or network firewall blocking the messaging API.
  • Solution: Run hermes doctor to check connectivity to messaging endpoints.
  • Error: Agent fails to respond
  • Check logs via SSH: hermes logs -f
  • Verify OpenRouter / API credits.
4.3. Q & A
  • Can Hermes run fully offline?
  • Yes. Set the model provider to custom and point it to a local Ollama or vLLM instance (e.g., http://localhost:11434/v1).
  • How does it handle large files?
  • "Context Compression" keeps the system prompt and recent turns in high resolution while summarizing older parts of the conversation.
  • Is my data shared with Nous Research?
  • No. All memories, skills, and logs are stored locally in ~/.hermes/. No telemetry is sent unless explicitly opted in.
  • What workflow or "Skill" should I build first?
  • Common starters: a daily briefing skill (web search + summary → Telegram), a code-review skill (read PR diff → comment), or a research skill (multi-source synthesis to Obsidian).