Skip to content

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] This guide is based on the masterclass video by Daily Dose of Data Science (48 min). Commands listed 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.

  • 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
# Full documentation: linked articles in the video description

[!TIP] Companion article: "How to beat GRPO without touching any model weights" — available in the channel's resources.

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

  1. Go to BotFather on Telegram.
  2. Run /newbot → name the bot (e.g., programmer).
  3. Copy the bot token.
  4. Get your user ID via @userinfobot.
  5. 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

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