Why Hermes Agent Gets Smarter Over Time: 90K‑Star Open‑Source AI Framework Explained

Problem: Forgetting in AI Agents

Every AI agent loses all context when a new session starts. Corrections to code style, bug fixes, or any interaction are forgotten, forcing developers to repeat work. This is an industry‑wide architectural defect.

Core Difference of Hermes Agent

Hermes wraps the learning agent inside a message gateway, making the agent the core and all channels (Terminal, Telegram, API) merely access layers. The system runs from a single file AIAgent via run_agent.py, ensuring the same agent instance is used across CLI, bots, or IDE plugins.

Three‑Layer Memory System

Hermes implements a three‑layer memory architecture:

Layer 1 – Two Small Markdown Files

MEMORY.md

(max 2200 characters) stores environment information, project conventions, and tool pitfalls. USER.md (max 1375 characters) records personal profile, communication preferences, skill level, and red‑flags.

Both files are injected into the system prompt at session start; new entries are written immediately but become active only in the next session. When memory reaches 80 % capacity, Hermes automatically merges similar entries to preserve useful information.

Layer 2 – SQLite Full‑Text Search

All dialogues are persisted in a SQLite database with FTS5 full‑text search, enabling cross‑session context retrieval over weeks.

Layer 3 – External Memory Plugins

Hermes supports eight plug‑in memory providers for long‑term storage. Before each round the agent pre‑fetches relevant memories; after each round it syncs the round’s content; upon session end it extracts key information.

Skills: Self‑Written Operation Manuals

Skills are Markdown files with a YAML header that describe a procedure, pitfalls, and verification steps. Example of a Kubernetes pod‑debug skill:

---
name: k8s-pod-debug
description: >
  Activate for crashing pods, CrashLoopBackOff,
  "why is my pod restarting", container failures.
version: 1.2.0
author: agent
---
## Procedure
1. Get pod status → check events → pull logs
2. Look for OOMKilled, ImagePullBackOff, config errors
## Pitfalls
- Forgetting --previous flag on restarted containers
## Verification
- Pod stays Running with 0 restarts for 5+ minutes

To save tokens, Skills are loaded progressively:

Level 0 – name + description summary, loaded each round (≈3 k tokens total).

Level 1 – full skill content, loaded on demand.

Level 2 – embedded reference files, loaded when deep details are needed.

Self‑Evolution: Agent Creates Its Own Skills

The agent uses the skill_manage tool to generate a new skill automatically when any of the following occurs:

Completion of a complex task that required more than five tool calls.

Encountering an error or dead‑end and finding a workaround.

User correction of the agent’s approach.

Discovery of a non‑obvious workflow.

Logic: encounter problem → trial‑and‑error → store successful path as a Skill → reuse on similar future problems.

Curator: Skill Library Garbage Collector

Curator runs lazily when a skill has not been used for 30 days (marked “stale”) or 90 days (marked “archived”) and the agent has been idle for ≥2 hours. It performs two stages:

Automatic state change based on deterministic rules (30 days → stale, 90 days → archived).

LLM review (up to eight rounds) to decide whether to keep, patch, merge, or archive each skill.

Curator never touches built‑in or community‑installed skills, only those created by the agent. It never deletes automatically; archived skills reside in ~/.hermes/skills/.archive/ and can be restored with a single command. A tar.gz snapshot of the entire skills directory is taken before each run.

GEPA: Offline Evolution Engine

Agents tend to be over‑optimistic about their performance and may overwrite manually crafted skills with inferior versions. GEPA (Genetic‑Pareto Prompt Evolution) addresses this offline. The optimizer lives in the separate repository NousResearch/hermes-agent-self-evolution and earned an ICLR 2026 oral presentation.

GEPA workflow:

Read the current skill.

Generate an evaluation dataset (Claude Opus synthetic cases, real conversation history, or a manually curated gold set).

Analyze execution traces, identify failure points, and generate candidate variants via evolutionary search.

Score candidates with an LLM using a multi‑dimensional rubric (not a binary pass/fail).

Enforce constraints: test suite must pass 100 %, skill size ≤15 KB, and semantic intent must not drift.

Submit the best variant as a pull request (no direct commit).

GEPA runs on API calls only (no GPU) and costs roughly $2–10 per optimization.

Quick Start

Installation and Initialization

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc  # or ~/.zshrc

hermes setup  # interactive: model provider, API key, tool config
hermes        # start a conversation

Connecting Telegram

Obtain a Bot Token from @BotFather and your Telegram User ID from @userinfobot, then configure during setup to chat with the agent on your phone.

Directory Layout (~/.hermes/)

~/.hermes/
├── config.yaml           # non‑secret configuration
├── .env                  # API keys and secrets
├── SOUL.md               # Agent identity (first System Prompt entry)
│
├── memories/
│   ├── MEMORY.md         # Persistent memory
│   └── USER.md           # User profile
│
├── skills/               # All skills
│   ├── mlops/
│   ├── devops/
│   └── .hub/
│
├── sessions/             # Session metadata
├── state.db              # SQLite (FTS5) for conversation search
├── cron/                 # Scheduled tasks
└── logs/

Key files: config.yaml (single source of non‑secret config), .env (stores secrets), SOUL.md (defines agent persona), and state.db (searchable conversation data).

Multiple Profiles (1 → 10 Agents)

Hermes supports independent Profiles; each Profile has its own configuration, memory, skills, and SOUL.md. The article demonstrates three Profiles: programmer, researcher, and designer, each with a dedicated Telegram bot.

SOUL.md: Distinct Personas

Designer persona focuses on hand‑drawn illustrations and AI/ML concept explanations. Programmer persona emphasizes concise, pragmatic engineering. Researcher persona delivers a daily deep AI/ML digest covering GitHub trends, big‑tech announcements, new papers, and community pulse.

Programmer Agent Using Claude Code

System prompt example:

I already have a Claude Max subscription. You are my staff engineer who helps me with my day‑to‑day coding tasks, and under the hood you use Claude Code for all the executions. Set yourself up accordingly.

The agent installs the autonomous-ai-agents/claude-code skill, verifies that claude is in PATH, and routes all coding tasks through Claude Code.

Researcher Agent Setting a Natural‑Language Cron Job

Prompt example:

Every weekday at 8am India time, prepare a deep digest of what's new in the AI and machine learning space over the last 24 hours. Cover four streams in this order: Trending GitHub repos, Big tech and lab announcements, Fresh research papers, Social pulse from X/Reddit/HN. Keep it under 800 words. Deliver to Telegram. Set this up as a recurring cron job.

The agent creates the cron entry, which can be verified with:

hermes -p researcher cron list

Hermes Skills Hub

The official hub contains 687 skills across 18 categories:

Built‑in skills (default): 87

Optional skills (enable on demand): 79

Anthropic official: 16

Community contributions (LobeHub): 505

Custom skill sources can be added from any GitHub repository:

hermes skills tap add yourname/your-skills-repo
hermes skills install yourname/your-skills-repo/skill-name

Community Insight

A comment notes that closed‑source AI companies cannot provide vendor‑neutral runtimes because they lock models, whereas the open‑source approach of Nous Research does.

Conclusion

Hermes Agent’s three‑layer memory, self‑generated skills, and offline GEPA optimizer form a compounding “flywheel” that improves the agent the longer it is used, rather than resetting each session. In two months the project amassed 90 K GitHub stars, and its repository growth outpaces Claude Code. The open‑source agent ecosystem is still forming, making this direction worth serious attention.