Start with the shape of the system

If you open Hermes by reading function bodies first, the repository feels noisy.
If you open it by reading responsibilities first, the structure is surprisingly clean.

The useful first claim is:

Hermes is a multi-surface agent platform, not just a tool-using chatbot.

That means the codebase is organized less like a script and more like a runtime.

The four-layer map

Entrypoints

The user can reach Hermes through multiple surfaces:

• CLI
• TUI
• messaging gateways
• ACP/editor integrations

The point is not that there are many interfaces. The point is that they all try to converge on the same execution core.

Runtime

run_agent.py owns the turn-level execution contract:

• assemble prompt state
• call the model
• handle tool calls
• maintain loop invariants
• finalize output

This is the kernel of the system.

Capabilities

Tools do not live inline inside the loop. They are exposed through:

• the registry
• tool discovery
• toolsets
• dispatch logic

That lets Hermes decide which capability surface is visible in which context.

State

The last layer turns Hermes from a stateless loop into a long-lived system:

• session DB
• memory providers
• skills
• cron jobs

This is the layer where “the agent remembers, searches, reuses, and wakes itself up later.”

Why this map is not optional

Without this map, readers mix up:

• product surface with execution logic
• tool implementation with loop orchestration
• history storage with memory recall
• scheduled autonomy with normal turn handling

That confusion is exactly what makes large agent repos feel opaque. The map is your boundary-setting device.

A good reading order

Read in this order:

1. AGENTS.md
2. run_agent.py
3. model_tools.py
4. hermes_state.py
5. agent/memory_manager.py
6. tools/delegate_tool.py
7. cron/scheduler.py

The point is to move from system skeleton to subsystem detail.

What you should now be able to say

If this chapter worked, you should now be able to say:

Hermes separates user-facing entrypoints, turn execution, capabilities, and durable state so the platform can grow without collapsing into one giant loop.