Hermes Agent — Complete Masterclass Guide

Overview

Hermes Agent is an open-source AI agent framework built by Nous Research that reached 160,000 ⭐ on GitHub in just two months — one of the fastest-growing open-source projects. Unlike traditional agents that forget everything when you close a session, Hermes Agent remembers and improves over time thanks to a three-tier persistent memory system and self-evolving skills.

This knowledge base covers the complete architecture, identity system, memory, skills, automation (curator, GAPA), installation, and real-world use cases with three functional agents.

[!NOTE] Commands listed here are examples; refer to the official documentation for the latest updates.

System Architecture

Core Agent Loop

Everything flows through a single AI Agent class in run_agent.py. The system runs on a standard ReAct loop:

Think → Act → Observe

Key characteristics:

Multiple entry points — CLI, Telegram, batch runner, IDE. All use the same agent class.
Multi-provider — works with Claude, GPT, Gemini, Ollama (local models) via an API translation layer.
Hard cap of 90 turns per task — prevents infinite loops that would silently burn through API credits.
Sub-agents share the same 90-turn budget.

Inputs (CLI, Telegram, IDE...)
        │
        ▼
┌───────────────────────┐
│     AI Agent          │  ← 90 turns max
│  (run_agent.py)       │
└───────┬───────────────┘
        │
        ▼
  API Translation Layer
        │
        ▼
Provider (Claude, GPT, Gemini, Ollama...)

[!TIP] The 90-turn hard cap is configurable in config.yaml via agent.max_turns.

Identity System — soul.md

Above memory and skills sits soul.md, the file that defines who the agent is.

System Prompt Hierarchy

Slot	Content	Role
1	soul.md	Identity (fixed) — who the agent is
2	Memory	What the agent knows
3	Skills	How the agent does things
4	Conversation	Session history

Principles

soul.md is written once, tweaked over time, and stays consistent across projects and sessions.
Without soul.md, every agent feels the same — it is the agent's personality.

Location: ~/.hermes/soul.md (main agent) or ~/.hermes/profiles/<name>/soul.md (specific profile).

[!WARNING] soul.md occupies system prompt slot 1. Modifying it mid-session breaks prompt caching — prefer starting a new session after changes.

Three-Tier Memory System

Tier 1 — Always in Context

Two Markdown files loaded every turn at zero search cost:

File	Capacity	Content
`memory.md`	2,200 chars max	Agent's notes: environment, projects, hard-learned lessons
`user.md`	1,375 chars max	User profile: name, preferences, communication style

[!NOTE] Frozen snapshot at session start — mid-session changes are persisted but take effect on the next session.

Tier 2 — SQLite Search

All conversations stored in a SQLite database with Full-Text Search (FTS5).
On-demand retrieval (cost: 1 LLM call to summarize results).
Unlimited capacity.

# In a Hermes session: search past conversations
session_search(query="installation hermes", limit=3)

Tier 3 — External Providers

8 plug-and-play providers for deep persistence:

Knowledge graphs
Temporal knowledge graphs
Honcho, Mem0, and others

Principle: Critical facts → Tier 1. Everything else → Tier 2 (searchable). Deep persistence → Tier 3.

Skills — Procedural System

Skill Structure

Skills are Markdown files with YAML frontmatter:

---
name: skill-name
description: "Concise description of what the skill does"
---

Location: ~/.hermes/skills/<category>/<skill-name>/SKILL.md

Progressive Skill Disclosure

Three-level system to save tokens:

Level	What is loaded	When
0	Frontmatter (name + description) of all skills	At the start of every task
1	Full body of the relevant skill	When the skill matches the task
2	Scripts, templates, and references	When execution requires them

[!TIP] Prevents burning tokens by loading 100 unnecessary skills. Only the relevant skill gets expanded.

Self-Evolving Skills

The key mechanism that sets Hermes apart from other agents.

Self-Improvement Loop

Complex task received
        │
        ▼
Trial / error (≥ 5 tool calls)
        │
        ▼
Automatic trigger: skill_manage()
        │
        ▼
Reusable procedure created
        │
        ▼
New skill saved in ~/.hermes/skills/
        │
        ▼
Next similar task → skill loaded → direct execution

Trigger

When a task requires ≥ 5 tool calls with iterations, the agent calls skill_manage() to create a reusable skill.

[!WARNING] After 6 months of use, hundreds of skills can accumulate, including near-duplicates. The Curator solves this.

The Curator — Automatic Skill Maintenance

Filters and consolidates skills approximately every 4 days.

3-Phase Pipeline

Phase 1: Quick Filter

Mechanical criteria without LLM calls (creation date, usage count).

Phase 2: LLM Analysis

Skill importance assessment
Near-duplicate detection
Decision: keep, update, or archive

Phase 3: Consolidation

Merge similar skills into a single one.

# Curator commands
hermes curator status          # Current state
hermes curator run             # Run manually
hermes curator pin <skill>     # Protect a skill (never touched)
hermes curator unpin <skill>   # Remove protection

Safety

Pre-built skills (bundled + hub-installed) are protected by default.
Command hermes curator pin <skill-name> to protect a custom skill.

[!NOTE] The curator never deletes skills. The maximum destructive action is archiving. Pinned skills are exempt from all automatic transitions and LLM review passes.

GAPA — General Agentic Prompt Adaptation

Prompt optimization technique accepted at ICLR 2026.

Features

Separate project from Nous Research (same team as Hermes).
Prompt optimization without modifying model weights.
Runs on CPU — no GPU required.
Compared to GRPO (RL): often more effective for multi-step agent pipelines.

# GAPA is used as a system prompt optimizer

Installation and Setup

Quick Steps

# 1. Install Hermes
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 2. Run interactive setup
hermes setup

# 3. Configure provider and model
hermes model

# 4. Verify installation
hermes doctor

Telegram Connection

Go to BotFather on Telegram.
Run /newbot → name the bot (e.g., programmer).
Copy the bot token.
Get your user ID via @userinfobot.

In Hermes:

hermes gateway setup
# Follow Telegram instructions → paste token + user ID

Creating Profiles

# Create an isolated profile
hermes profile create designer

# Set up the profile
hermes designer setup

# List all profiles
hermes profile list

Recommended Model (Designer)

KimiK 2.6 via OpenRouter — performance close to Opus at a much lower price.

# Configure model for a profile
hermes designer model
# → Select OpenRouter → API key → KimiK 2.6

Ready-to-Use Agents

Neo — Programmer Agent

Delegates complete projects to Claude Code.

Workflow: 1. User submits a request (e.g., "Build me a landing page"). 2. Neo loads the Claude Code skill, performs web research. 3. Generates the full project (index.html, assets, etc.). 4. Configured via soul.md: one-shot task mode, pre-validation with a plan.

# soul.md for the Neo profile
name: Neo
role: Programmer
tool: Claude Code
workflow:
  - Create a plan and validate with the user
  - Execute via Claude Code in one-shot mode
  - Return the result

Pixel — Designer Agent

Generates designs consistent with a brand style guide.

Skill creation process: 1. Upload 4 example images (existing banners). 2. The agent analyzes: palette, typography, composition, style. 3. Automatically creates a handdrawn-banner skill.

Generated structure:

~/.hermes/profiles/designer/skills/handdrawn-banner/
├── SKILL.md          # Design instructions
├── references/       # Design system
├── assets/           # Example images
└── scripts/          # Generation API calls

Deep Researcher — Automated Monitoring

Scans GitHub, research papers, and AI/ML trending news.

How it works: - Cron job configured to run periodically. - Results automatically delivered to Telegram.

# Example cron job for deep researcher
hermes cron create "0 8 * * *" \
  --name deep-researcher \
  --prompt "Scan the latest AI/ML papers, GitHub repos and news. Summarize top 5 findings." \
  --deliver telegram

Skills Hub and Bundles

Official Hub

89 built-in skills shipped with Hermes.
Categories: Apple ecosystem, creative, DevOps, gaming, data science, and more.

# Browse the hub
hermes skills browse

# Search for a skill
hermes skills search "technical-writer"

# Install a skill
hermes skills install <id>

# List installed skills
hermes skills list

Skill Bundles

Group multiple skills into a workflow:

# Create a bundle
hermes skills bundle create backend-feature \
  --skills "code-review,tdd,github-pr-workflow" \
  --instruction "Execute code-review first, then TDD, finally create PR"

Private Skills (GitHub)

# Add a GitHub repo as a skill source
hermes skills tap add <github-user>/<skills-repo>

# Install from that repo
hermes skills install <skill-name>

The `.hermes` Directory Anatomy

~/.hermes/
├── config.yaml          # Main configuration
├── .env                 # API keys and secrets
├── soul.md              # Main agent identity
├── memory/
│   ├── memory.md        # Persistent notes (2,200 chars max)
│   └── user.md          # User profile (1,375 chars max)
├── skills/              # Installed skills
│   └── <category>/<name>/
├── profiles/            # Isolated profiles
│   └── designer/
│       ├── config.yaml
│       ├── soul.md
│       └── skills/
│           └── handdrawn-banner/
│               ├── SKILL.md
│               ├── references/
│               ├── assets/
│               └── scripts/
├── cron/                # Scheduled jobs
├── plugins/             # Extensions
├── sessions/            # Gateway routing + logs
├── state.db             # SQLite session database
└── logs/                # Observability logs

[!NOTE] You won't manually edit most of these files, but knowing this layout gives you control over identity, memory, skills, automation, and system state.

Resources

Official documentation: hermes-agent.nousresearch.com/docs
GitHub repository: github.com/NousResearch/hermes-agent
Help command: hermes --help in the terminal
Slash commands: /help inside a Hermes CLI session

To-do

Status: incomplete. Still to write:

Write the GAPA section: its only code block is an empty bash fence containing the comment # GAPA is used as a system prompt optimizer — no install/run command, no configuration, and no link to the GAPA project.
Name and document all 8 Tier-3 external memory providers with a configuration example — the section lists only "Knowledge graphs, Temporal knowledge graphs, Honcho, Mem0, and others".
Add the setup steps for the Neo and Pixel agents (profile creation, where soul.md goes, how the skill is installed) — only Deep Researcher gets a runnable hermes cron create command.