learn-hermes-agent

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	Topic	What you get
s00	Architecture Overview	the global map, key terms, and learning order
s01	Agent Loop	the synchronous conversation loop — ask, tool-call, append, continue
s02	Tool System	a self-registering tool registry with dispatch orchestration
s03	Session Store	SQLite + FTS5 persistence — conversations that survive restarts
s04	Prompt Builder	section-based system prompt assembly from personality, memory, and config
s05	Context Compression	auto-triggered LLM summarization when context grows too long
s06	Error Recovery	API error classification, retry with backoff, and provider failover
s07	Memory System	cross-session persistent knowledge with MEMORY.md and USER.md
s08	Skill System	agent-managed skills — create, edit, and execute
s09	Permission System	dangerous command detection and approval gates
s10	Subagent Delegation	spawn fresh context for isolated subtasks
s11	Configuration System	YAML config, env vars, profiles, and runtime migration
s12	Gateway Architecture	the multi-platform message dispatch loop
s13	Platform Adapters	building integrations for Telegram, Discord, Slack, WeChat, and more
s14	Terminal Backends	run commands in Docker, over SSH, on Modal, or Daytona
s15	Cron Scheduler	time-based automation with duration strings and cron expressions
s16	MCP Integration	external capability routing via Model Context Protocol
s17	Browser Automation	Playwright + Browserbase for web interaction
s18	Voice & Vision	TTS/STT pipelines and image analysis
s19	CLI Interface	prompt_toolkit + Rich for an interactive terminal experience
s20	Background Review	every N turns, a background pass updates memory and extracts skills
s21	Skill Creation Loop	background review extracts patterns into reusable skills
s22	Hook System	lifecycle hooks for extensibility without modifying core code
s23	Trajectory & RL	conversation trajectories become training data for model improvement
s24	Plugin Architecture	pluggable memory, compression, and capability providers
s25	Self-Evolution Overview	the core insight, four evolution targets, and full pipeline overview
s26	Evaluation System	eval datasets, LLM-as-judge fitness scoring, and constraint gates
s27	Optimization & Deploy	the feedback→mutate→select loop, full pipeline, and Phase 2-4 concepts

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?

Chapter	Key Data Structures / Entities	What you should have after this chapter
s01	messages list / AIAgent class / run_conversation()	a minimal working synchronous conversation loop
s02	ToolRegistry / ToolEntry / tool_result	a self-registering, self-discovering tool system
s03	SessionDB / state.db / FTS5 index	a SQLite persistence layer — conversations survive restarts
s04	build_context_files_prompt() / build_skills_system_prompt()	a pipeline assembling prompts from personality, memory, and config
s05	ContextCompressor / compression trigger threshold	an auto-summarization layer when context grows too long
s06	ClassifiedError / FailoverReason / classify_api_error()	error classification + backoff retry + provider failover
s07	MemoryStore / MemoryManager / MEMORY.md / USER.md	a layer that separates "temporary context" from "cross-session memory"
s08	SkillMeta / SkillBundle / skill SKILL.md files	a skill system that can create, edit, and execute
s09	DANGEROUS_PATTERNS / detect_dangerous_command() / _ApprovalEntry	a "dangerous operations must pass the gate" approval pipeline
s10	delegate_tool / child messages / isolated AIAgent	a subagent mechanism with isolated context for one-off delegation
s11	config dict / Profile management / migration functions	YAML config + profiles + runtime migration
s12	GatewayRunner / MessageEvent / platform routing	a unified multi-platform message dispatch loop
s13	BasePlatformAdapter / MessageType / SendResult	a reusable platform adapter pattern
s14	BaseEnvironment / local / docker / ssh / modal / daytona	abstract execution environments: local, Docker, SSH, cloud
s15	parse_schedule() / create_job() / get_due_jobs() / job dicts	a "when the time comes, work starts" scheduling layer
s16	mcp_tool / MCP config / tool schema bridging	a bus for plugging external tools and capabilities into the system
s17	browser_tool / Playwright / Browserbase provider	a browser automation layer for web interaction
s18	tts_tool / voice_mode / vision_tools	multimodal pipelines: voice I/O + image analysis
s19	HermesCLI / CommandDef / KawaiiSpinner / Rich rendering	a fully-featured interactive terminal interface
s20	BackgroundReviewer / _MEMORY_REVIEW_PROMPT / dual trigger counters	an "every N turns, auto-reflect → update memory/skills" background review mechanism
s21	skill creation loop / pattern extraction prompt / skill persistence pipeline	the "discover patterns → create reusable skills" prerequisite for self-evolution
s22	HookRegistry / PluginHookRegistry / BOOT.md handler	lifecycle hooks — inject custom logic without modifying core code
s23	convert_to_trajectory() / compress_trajectory() / reward functions	conversation data → training pipeline for model improvement
s24	plugin interfaces / memory providers / compression providers	pluggable memory and compression without touching core code
s25	EvalExample / EvalDataset	the foundational data structures for self-evolution
s26	SyntheticDatasetBuilder / FitnessScore / ConstraintValidator	measurement infrastructure — generate data, score outputs, gate changes
s27	SkillOptimizer / EvolutionResult / evolve_skill()	the optimization loop and full 7-step pipeline

Reading Approaches for Beginners

Approach 1: Steady Mainline

Best for readers encountering agent systems for the first time.

Read in this order:

s00 -> s01 -> ... -> s20 -> s21 -> ... -> s27 (follow the numbers; s24 is docs-only).

Approach 2: Build First, Complete Later

Best for "get it running, then fill in the gaps" readers.

Read in this order:

1. s01-s06: build a core agent with persistence and context compression
2. s07-s11: add memory, skills, safety, delegation, and config
3. s12-s15: go multi-platform, learn cross-environment execution
4. s16-s20: advanced capabilities plus the background self-review
5. s21-s27: step into self-evolution — skill creation, hooks, trajectories, evaluation, and optimization

Approach 3: When You Get Stuck

If you hit a wall in the middle or late chapters, do not push forward blindly.

Reset in this order:

1. docs/en/s00-architecture-overview.md
2. docs/en/data-structures.md
3. docs/en/entity-map.md
4. the chapter you are stuck on

When readers truly get stuck, it is usually not "I can't read the code" but rather:

• which layer does this mechanism plug into?
• which data structure holds this state?
• what is the difference between this term and another that looks similar?

Quick Start

git clone <repo-url>
cd learn-hermes-agent
pip install -r requirements.txt
cp .env.example .env

Then configure your API key in .env, and run:

python agents/s01_agent_loop.py

Suggested order:

1. Run s01 and make sure the minimal loop really works.
2. Read s00, then move through s01 -> s06 in order.
3. Only after the single-agent core plus its persistence feel stable, continue into s07 -> s11.
4. Move into gateway and platform chapters s12 -> s15 only after the core agent makes sense.
5. Continue through s16 -> s20, then the self-evolution chapters s21 -> s27.

How To Read Each Chapter

Each chapter is easier to absorb if you keep the same reading rhythm:

1. what problem appears without this mechanism
2. what the new concept means
3. what the smallest correct implementation looks like
4. where the state actually lives
5. how it plugs back into the loop
6. where to stop first, and what can wait until later

If you keep asking:

• "Is this core mainline or just a side detail?"
• "Where does this state actually live?"

go back to:

• docs/en/teaching-scope.md
• docs/en/data-structures.md
• docs/en/entity-map.md

Repository Structure

learn-hermes-agent/
├── agents/              # runnable Python reference implementations per chapter (s24 is an exception, see below)
├── docs/zh/             # Chinese mainline docs
├── docs/en/             # English docs
├── illustrations/       # chalkboard-style diagrams for each chapter
├── tests/               # smoke tests
├── web/                 # web teaching platform (optional)
├── .env.example         # environment variable template
└── requirements.txt     # Python dependencies

Note: s24 Plugin Architecture currently ships with documentation only (docs/en/s24-plugin-architecture.md and the Chinese counterpart). There is no agents/s24_*.py reference implementation. The doc is self-contained and does not block the rest of the reading order.

Teaching Tradeoffs

To ensure "buildable from 0 to 1", this repo makes deliberate tradeoffs:

• Teach the minimal correct version first, then explain extension boundaries.
• If a real mechanism is complex but the core idea is not, teach the core idea first.
• If an advanced term appears, explain it — do not assume the reader already knows.
• If an edge case in the real system has low teaching value, remove it entirely.

This means the repo aims for:

High fidelity on core mechanisms, deliberate tradeoffs on peripheral details.

Language Status

Chinese is the canonical teaching line and the fastest-moving version.

• zh: most reviewed and most complete
• en: all chapters s00-s27 available; Chinese is updated first

If you want the fullest and most frequently refined explanation path, use the Chinese docs first.

End Goal

By the end of the repo, you should be able to answer these questions clearly:

• what is the minimum state an autonomous agent needs to persist across sessions?
• why is the tool registry the center of the agent's capability?
• how does a single conversation loop scale to 15+ messaging platforms?
• what problem do memory, skills, permissions, context compression, and error recovery each solve?
• how do terminal backends abstract away the execution environment?
• when should a single-agent system grow into gateway, scheduling, MCP, and voice?

If you can answer those questions clearly and build a similar system yourself, this repo has done its job.

---

This is not "copy the source code line by line." This is "grasp the designs that truly matter, then build it yourself."