English | 中文

Learn Hermes Agent

Build a production-grade autonomous AI agent from scratch in Python. A 27-chapter, code-first tutorial covering the agent loop, tool system, session persistence, memory, skills, context compression, MCP, multi-platform gateway (Telegram / Discord / Slack / WeChat), and RL-based self-evolution — inspired by Hermes Agent.

Every chapter ships a runnable reference implementation under agents/sNN_*.py, paired with a prose explanation under docs/en/ (and docs/zh/ for the Chinese mainline). Read, run, tweak, repeat.

This repo does not try to mirror every product detail from the Hermes Agent codebase. It focuses on the mechanisms that actually decide whether an agent can work autonomously across platforms:

• the conversation loop
• tool registry and dispatch
• session persistence
• prompt assembly
• context compression
• memory and skill management
• skill system
• permission and safety
• multi-platform gateway
• terminal backends
• scheduling
• external capability routing

The goal is simple:

understand the real design backbone well enough that you can rebuild it yourself.

What This Repo Is Really Teaching

One sentence first:

The model does the reasoning. The harness gives the model a working environment that spans platforms, persists across sessions, and manages its own skills.

That working environment is made of a few cooperating parts:

• Agent Loop: send messages to the model, execute tool calls, append results, continue
• Tool System: a self-registering dispatch layer — the agent's hands
• Session Store: SQLite with FTS5 — conversation memory that survives restarts
• Prompt Builder: assemble system prompts from personality, memory, config, and context
• Context Compression: keep the active window small when conversations grow long
• Memory & Skills: durable knowledge and agent-managed skill files
• Permission System: detect dangerous commands before execution
• Gateway: a single agent loop that listens on Telegram, Discord, Slack, WeChat, and more
• Terminal Backends: run commands locally, in Docker, over SSH, or on serverless platforms
• Cron / MCP / Voice: grow the single-agent core into a full working platform

This is the teaching promise of the repo:

• teach the mainline in a clean order
• explain unfamiliar concepts before relying on them
• stay close to real system structure
• avoid drowning the learner in irrelevant product details

What This Repo Deliberately Does Not Teach

This repo is not trying to preserve every detail that exists in the production system.

If a detail is not central to the agent's core operating model, it should not dominate the teaching line. That includes things like:

• packaging, Nix flakes, and release mechanics
• landing pages and marketing assets
• enterprise subscription and billing wiring
• telemetry and analytics
• RL training pipeline and batch runner internals
• platform-specific API quirks (WeChat XML parsing, Telegram inline keyboards)
• skin/theme engine cosmetics
• historical migration logic

Those details may matter in production. They do not belong at the center of a 0-to-1 teaching path.

Who This Is For

The assumed reader:

• knows basic Python
• understands functions, classes, async/await basics
• may be completely new to agent systems or multi-platform bots

So the repo tries to keep a few strong teaching rules:

• explain a concept before using it
• keep one concept fully explained in one main place
• start from "what it is", then "why it exists", then "how to implement it"
• avoid forcing beginners to assemble the system from scattered fragments

Recommended Reading Order

• Overview: docs/en/s00-architecture-overview.md
• Code Reading Order: docs/en/s00f-code-reading-order.md
• Glossary: docs/en/glossary.md
• Teaching Scope: docs/en/teaching-scope.md
• Data Structures: docs/en/data-structures.md

If This Is Your First Visit, Start Here

Do not open random chapters first.

The safest path is:

1. Read docs/en/s00-architecture-overview.md for the full system map.
2. Read docs/en/s00f-code-reading-order.md so you know which source files to open first.
3. Follow the five stages in order: s01-s06 -> s07-s11 -> s12-s15 -> s16-s20 -> s21-s27.
4. After each stage, stop and rebuild the smallest version yourself before continuing.

If the middle and late chapters start to blur together, reset in this order:

1. docs/en/data-structures.md
2. docs/en/entity-map.md
3. then return to the chapter body

Five Stages

1. s01-s06: build a working single-agent core with persistence
2. s07-s11: add intelligence — memory, skills, safety, delegation, and configuration
3. s12-s15: go multi-platform — gateway, adapters, terminal backends, and scheduling
4. s16-s20: add advanced capabilities — MCP, browser, voice, vision, and background review
5. s21-s27: self-improvement — skill creation, hooks, trajectory/RL, plugins, evaluation, and optimization

Main Chapters

Chapter Index: What to Focus on in Each Chapter

If this is your first time learning this material systematically, do not spread your attention evenly across all details. For each chapter, focus on 3 things:

1. What new capability this chapter adds.
2. Where the key state lives.
3. After finishing, can you hand-write this minimal mechanism yourself?