Hermes Agent Framework¶

Hermes Agent is an open-source AI agent framework developed by Nous Research. It's designed to be a self-improving, persistent AI assistant that can run across multiple platforms and learn from experience.

What is Hermes Agent?¶

Hermes Agent belongs to a new category of AI tools called autonomous agents. Unlike traditional chatbots that only respond to questions, Hermes can:

Execute tasks — Run shell commands, read/write files, browse the web
Learn from experience — Save reusable procedures as "skills"
Remember context — Maintain persistent memory across sessions
Run everywhere — Terminal, Telegram, Discord, Slack, WhatsApp, and more

Key Differentiators¶

Feature	Traditional Chatbot	Hermes Agent
Tool Access	❌ None	✅ 68+ built-in tools
Memory	❌ Resets each session	✅ Persistent across sessions
Learning	❌ Static	✅ Creates skills from experience
Platforms	❌ Single interface	✅ 15+ platforms
Customization	❌ Limited	✅ Full control

Core Architecture¶

1. Agent Loop¶

The heart of Hermes is the conversation loop:

┌─────────────────────────────────────────────────────────────┐
│                     Agent Loop                              │
├─────────────────────────────────────────────────────────────┤
│  1. Build System Prompt                                     │
│     ├── Load persona (SOUL.md)                              │
│     ├── Inject memory                                        │
│     ├── Load skills                                          │
│     └── Add tool schemas                                     │
│                                                             │
│  2. Call LLM                                                │
│     ├── Send messages + tool schemas                         │
│     └── Receive response (text or tool_calls)                │
│                                                             │
│  3. Process Response                                        │
│     ├── If tool_calls → Execute tools → Append results      │
│     └── If text → Return to user                            │
│                                                             │
│  4. Loop until complete or max_turns reached                │
└─────────────────────────────────────────────────────────────┘

2. Tool System¶

Hermes has 68+ built-in tools organized into toolsets:

Toolset	Tools	Description
`terminal`	Shell commands	Execute bash/zsh commands
`file`	read_file, write_file, patch	File operations
`web`	web_search, web_extract	Web access
`browser`	browser_navigate, browser_click	Browser automation
`vision`	vision_analyze	Image analysis
`memory`	memory save/load	Persistent memory
`skills`	skill_manage, skill_view	Skill management
`delegation`	delegate_task	Subagent spawning
`cronjob`	cronjob create/list	Scheduled tasks

3. Skills System¶

Skills are reusable procedures that Hermes creates from experience:

~/.hermes/skills/
├── devops/
│   ├── docker/
│   │   └── SKILL.md
│   └── kubernetes/
│       └── SKILL.md
├── programming/
│   ├── python-debugging/
│   │   └── SKILL.md
│   └── git-workflow/
│       └── SKILL.md
└── research/
    └── paper-analysis/
        └── SKILL.md

A skill file looks like:

---
name: python-debugging
description: Debug Python applications effectively
tags: [python, debugging, pdb]
---

# Python Debugging Guide

## When to Use
- Application crashes
- Unexpected behavior
- Performance issues

## Steps
1. Read the error traceback
2. Set breakpoints with `pdb`
3. Inspect variables
4. Fix the issue

## Common Pitfalls
- Forgetting to import modules
- Type mismatches
- Off-by-one errors

4. Memory System¶

Hermes maintains persistent memory across sessions:

# User Profile (who you are)
user:
  name: "Alice"
  role: "ML Engineer"
  preferences:
    language: "Python"
    editor: "VS Code"

# Memory (environment facts)
memory:
  - "Project uses PyTorch 2.0"
  - "Deploy on AWS EC2"
  - "Test with pytest"

Memory is injected into every conversation, so Hermes remembers: - Your preferences and habits - Project details and conventions - Lessons learned from past sessions

5. Multi-Platform Gateway¶

The same agent runs on multiple platforms:

┌─────────────────────────────────────────────────────────────┐
│                    Gateway Architecture                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│   │ Telegram │  │ Discord  │  │  Slack   │  │ WhatsApp │  │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  │
│        │             │             │             │         │
│        └─────────────┼─────────────┼─────────────┘         │
│                      │             │                       │
│                      ▼             ▼                       │
│              ┌───────────────────────────┐                 │
│              │      Gateway Server      │                 │
│              │   (Message Routing)      │                 │
│              └───────────┬───────────────┘                 │
│                          │                                 │
│                          ▼                                 │
│              ┌───────────────────────────┐                 │
│              │       Agent Core         │                 │
│              │  (Shared Agent Loop)     │                 │
│              └───────────────────────────┘                 │
│                                                             │
└─────────────────────────────────────────────────────────────┘

How It Works: Step by Step¶

Step 1: User Input¶

When you send a message (via terminal, Telegram, etc.):

User: "Help me debug this Python script"

Step 2: System Prompt Construction¶

Hermes builds a system prompt including:

You are Hermes Agent, an AI assistant...

## Memory
- User is a Python developer
- Project uses FastAPI

## Skills
- python-debugging: Debug Python apps
- git-workflow: Git best practices

## Tools Available
- terminal: Run shell commands
- file: Read/write files
- vision: Analyze images

Step 3: LLM Call¶

Hermes calls the LLM with: - System prompt - Conversation history - Tool schemas

{
  "model": "claude-sonnet-4",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "Help me debug this Python script"}
  ],
  "tools": [...]
}

Step 4: Tool Execution¶

If the LLM requests a tool:

{
  "tool_calls": [{
    "name": "terminal",
    "arguments": {
      "command": "python script.py 2>&1"
    }
  }]
}

Hermes executes it and returns the result:

{
  "role": "tool",
  "content": "Traceback (most recent call last):\n  File \"script.py\", line 5\n    ..."
}

Step 5: Response Generation¶

The LLM generates a response based on the tool output:

Agent: "I found the issue! Line 5 has a syntax error..."

Key Concepts¶

1. Self-Improvement¶

Hermes learns by creating skills:

User: "How did you fix that bug?"
Agent: "Let me save this as a skill..."
→ Creates ~/.hermes/skills/debugging/syntax-error.md
→ Next time, it loads this skill automatically

2. Context Compression¶

When conversations get long, Hermes compresses context:

Original: 100 messages
Compressed: 20 messages + summary

This keeps conversations manageable without losing important information.

3. Delegation¶

Hermes can spawn subagents for parallel work:

delegate_task(
    goal="Research GRPO papers",
    context="Find latest papers on GRPO...",
    toolsets=["web", "file"]
)

4. Credential Pools¶

Multiple API keys rotate automatically:

# ~/.hermes/.env
OPENROUTER_API_KEY_1=sk-...
OPENROUTER_API_KEY_2=sk-...
OPENROUTER_API_KEY_3=sk-...

Hermes rotates between them to avoid rate limits.

Architecture Diagram¶

┌─────────────────────────────────────────────────────────────┐
│                    Hermes Agent Architecture                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   User Interfaces                   │   │
│  │  Terminal │ Telegram │ Discord │ Slack │ WhatsApp    │   │
│  └─────────────────────┬───────────────────────────────┘   │
│                        │                                   │
│                        ▼                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  Gateway Layer                       │   │
│  │         (Message Routing & Platform Adapters)        │   │
│  └─────────────────────┬───────────────────────────────┘   │
│                        │                                   │
│                        ▼                                   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  Agent Core                          │   │
│  │  ┌─────────────────────────────────────────────┐    │   │
│  │  │           Conversation Loop                  │    │   │
│  │  │  Build Prompt → Call LLM → Process Response │    │   │
│  │  └─────────────────────────────────────────────┘    │   │
│  │                        │                            │   │
│  │  ┌─────────────────────┼─────────────────────┐     │   │
│  │  │                     ▼                     │     │   │
│  │  │  ┌─────────────────────────────────────┐  │     │   │
│  │  │  │           Tool Dispatch              │  │     │   │
│  │  │  │  terminal │ file │ web │ browser │ …  │  │     │   │
│  │  │  └─────────────────────────────────────┘  │     │   │
│  │  └───────────────────────────────────────────┘     │   │
│  └─────────────────────────────────────────────────────┘   │
│                        │                                   │
│  ┌─────────────────────┼─────────────────────┐             │
│  │                     ▼                     │             │
│  │  ┌─────────────────────────────────────┐  │             │
│  │  │          Persistent Storage          │  │             │
│  │  │  Memory │ Skills │ Sessions │ Config │  │             │
│  │  └─────────────────────────────────────┘  │             │
│  └───────────────────────────────────────────┘             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Use Cases¶

1. Software Development¶

User: "Build a REST API for user management"
Agent: 
1. Creates project structure
2. Writes FastAPI code
3. Adds database models
4. Writes tests
5. Sets up CI/CD

2. Research¶

User: "Analyze recent papers on RL for robotics"
Agent:
1. Searches arXiv
2. Downloads papers
3. Extracts key findings
4. Creates summary report

3. System Administration¶

User: "Set up monitoring for my servers"
Agent:
1. Installs Prometheus
2. Configures Grafana dashboards
3. Sets up alerts
4. Documents the setup

Comparison with Other Frameworks¶

Feature	Hermes Agent	Claude Code	AutoGPT
Self-improving skills	✅	❌	❌
Persistent memory	✅	❌	❌
Multi-platform	✅ 15+	❌ Terminal only	❌ Web only
Provider-agnostic	✅ 20+	❌ Anthropic only	✅ OpenAI
Open source	✅ MIT	❌ Proprietary	✅ MIT
Local models	✅	❌	✅

Getting Started¶

Installation¶

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

First Run¶

# Interactive chat
hermes

# Single query
hermes chat -q "What is the capital of France?"

# Setup wizard
hermes setup

Configuration¶

# View config
hermes config

# Edit config
hermes config edit

# Change model
hermes model

Next Steps¶

CLI Reference — All commands and flags
Configuration Guide — Detailed config options
Tool System — How tools work
Skills System — Creating and using skills
Memory System — Persistent memory
Gateway Setup — Multi-platform deployment
Contributing — Extend Hermes