Inside Hermes: How the Agent Loop, Context, Memory, Gateways, and Cron Jobs Work Together

A conceptual guide to the architecture behind an always-on Hermes agent.

Hermes becomes easier to operate when its internal pieces are separated mentally. A request does not travel directly from Telegram to a model and back. It passes through a gateway, is associated with a session, assembled into context, processed by an agent loop, and stored for later use. Scheduled jobs enter the same system through a different door.

This architecture is simple enough to understand without reading the code, but understanding it changes how problems are diagnosed. A bad answer may be a model problem, a context problem, or a memory problem. A missing message may be a gateway or session problem. A repeated scheduled result may be a cron design problem.

The bird’s-eye view

At the center is the agent loop. Around it are four supporting systems:

• Context construction decides what information the model sees now.
• Session and gateway management connects messages to the correct conversation.
• Memory preserves selected knowledge beyond the active context.
• Cron scheduling creates work at defined times without a live user message.

Persistent records, often stored in a database such as SQLite, connect these components across restarts.

The agent loop

The agent loop is the cycle through which Hermes handles a task. It receives a message and assembled context, calls the model, examines the result, and may invoke a tool. The tool result is added to the working context, and the model is called again. This continues until the model produces a final answer or a safety and iteration limit stops the loop.

A simplified sequence is:

1. Receive an event or message.
2. Identify the session and user.
3. Construct the model context.
4. Ask the model for the next action.
5. Execute an allowed tool if requested.
6. Add the result to context.
7. Repeat until the task is complete.
8. Save the response and relevant state.

This explains why tool-based tasks consume more tokens than a single answer. Each tool call may create another model turn containing the previous messages and the new result.

Context is a constructed view, not the entire history

A model has a context window: a limit on the amount of text it can consider in one request. Hermes therefore cannot send every message, file, memory, and tool result forever.

Context construction selects and orders the material most relevant to the current step. It may include identity instructions, user information, recent conversation turns, summaries of earlier turns, relevant memory, skill instructions, and tool results.

Ordering matters. Critical behavior and safety instructions must be clear. Large tool outputs should be trimmed or summarized. If irrelevant material crowds the context, the model may overlook the user’s actual request.

Context problems often look like intelligence problems. Before changing models, inspect whether the correct facts and instructions were available to the model at all.

Compression keeps long sessions usable

When a conversation grows beyond a practical limit, Hermes compresses older material. Compression creates a shorter representation of the important decisions, facts, unresolved questions, and task state.

A good compression prompt should preserve:

• the user’s goal;
• decisions and their reasons;
• important facts and constraints;
• files or tools involved;
• incomplete tasks;
• errors that should not be repeated.

It should remove greetings, repetition, obsolete attempts, and low-value narration.

Compression is lossy: some detail will disappear. Important durable information should therefore move into explicit memory or project files rather than relying solely on a session summary.

Gateways connect external channels

A gateway receives messages from services such as Telegram or Slack and translates them into events Hermes understands. It also sends the final response back to the originating channel.

The gateway must map each incoming message to the correct session. A Telegram topic, Slack thread, and desktop chat may need separate histories even when they use the same Hermes instance.

The gateway is also a security boundary. It must validate users, protect tokens, and avoid accepting arbitrary commands from the public internet. If messages arrive but Hermes does not respond, check gateway logs, authentication, network connectivity, and session routing before blaming the model.

SQLite and durable state

A lightweight database can store sessions, messages, cron definitions, and other operational state. The database allows Hermes to restart without forgetting which conversations or schedules exist.

Durability still requires backups. A database file on a single VPS can be lost through disk failure, accidental deletion, or a failed migration. Back up the database and configuration while the system is in a consistent state, and test restoration.

Not every file belongs in the database. Skills and identity files may remain ordinary text because they are easier to inspect and version. The important point is to know which location is authoritative for each type of state.

Long-term memory is selected knowledge

Memory differs from conversation history. History records what was said; memory records what should matter later.

Hermes may retrieve memories relevant to the current task and insert them into context. Good memory entries are concise, attributable, and stable. A preference such as “use Traditional Chinese for user-facing explanations” is more durable than a temporary note such as “the user is travelling today.”

Memory needs maintenance. Contradictory or stale entries can cause persistent errors. Systems that automatically write memory should provide a way to inspect, correct, and delete it.

Cron jobs enter the same pipeline

A cron job creates an event at a scheduled time. Instead of a user sending a message, the scheduler supplies the prompt and associated configuration. The agent loop then handles it like other work and delivers the result through a specified gateway or storage location.

Because nobody may be watching, scheduled tasks require tighter boundaries. They should define time zone, timeout, maximum scope, model choice, delivery destination, and behavior when no action is needed.

Cron jobs should be idempotent when possible. Idempotent means that running the same job twice does not create harmful duplicates. A report can be regenerated safely; a payment or public post cannot.

Diagnose the correct layer

The architecture suggests a practical troubleshooting sequence:

• No message arrives: inspect the external service and gateway.
• Wrong conversation history appears: inspect session mapping.
• The model ignores known facts: inspect context construction and memory retrieval.
• Long sessions lose decisions: inspect compression and promote key facts into durable files.
• A tool repeats or loops: inspect the agent loop limits and tool error output.
• A schedule does not run: inspect cron state, time zone, and service uptime.
• A result runs but goes nowhere: inspect the configured delivery gateway.

This layered approach replaces vague debugging with specific evidence.

Architecture supports safe growth

Hermes is not one mysterious intelligent process. It is a collection of understandable components connected around a model. That is good news for operators: each component can be observed, tested, backed up, and restricted.

The agent loop provides action, context provides immediate knowledge, compression controls scale, memory provides continuity, gateways provide reach, and cron jobs provide initiative. When each layer has clear ownership and limits, Hermes can grow from a personal chat assistant into a reliable always-on system.

Hands-on lab: Trace one read-only turn through the Hermes runtime

• Outcome: Observe one tool-backed turn, confirm it becomes a resumable session, and map the observed evidence to entry point, agent loop, tool result, and persistence.
• Time: 15–20 minutes.
• Risk: Low. The task reads one disposable folder and performs no write or external action.

Before you start

• Confirm plain chat works and choose a small non-sensitive folder.
• Know the actual name of at least one top-level file so you can verify the answer.
• Keep approvals enabled; this lab does not require YOLO mode.

Use this source-verified state map for the repository’s pinned Hermes commit (4aa499ff). Here, <profile-home> means the active HERMES_HOME: ~/.hermes for the default profile or that profile’s directory under ~/.hermes/profiles/.

State	Authoritative location	Safe inspection rule
Sessions and messages	<profile-home>/state.db	Use hermes sessions list, resume, and session search; do not hand-edit SQLite.
Built-in memory	<profile-home>/memories/MEMORY.md and USER.md	Review concise durable entries; remember that a session receives a frozen snapshot at start.
Cron definitions	<profile-home>/cron/jobs.json	Use cron list, pause, resume, update, and remove controls; do not edit the JSON while the scheduler is active.
Per-run cron evidence	<profile-home>/cron/output/<job-id>/<timestamp>.md	Inspect the run artifact when a job claims success or failure.

The cron paths are defined in cron/jobs.py; session persistence is defined in hermes_state.py. Verify them again after changing the pinned Hermes version because storage contracts can evolve.

Build it

Run one bounded turn that requires filesystem evidence, then inspect session persistence:

hermes chat -q "Read only the current directory. Name one top-level file, state which tool result proves it exists, and make no changes."
hermes sessions list
hermes --continue

In the resumed session, send this follow-up:

Describe this completed turn in four labelled lines:
Entry point, agent loop decision, tool evidence, persisted session result.
Use only what happened in this session; do not claim hidden implementation details.

Finally, run the redacted runtime health check:

hermes status --deep

Verify it

• The named file really exists and the answer identifies tool evidence rather than guessing.
• hermes sessions list shows the completed session.
• hermes --continue restores enough context to describe the previous turn accurately.
• hermes status --deep completes without exposing secret values.

If it fails

• If no tool evidence appears, repeat in a folder with one obvious non-sensitive file and explicitly require a read-only inspection.
• If resume fails, confirm the same profile is active and inspect hermes sessions list.
• If the provider responds but tools fail, run hermes doctor and inspect hermes logs before changing models.
• Distinguish entry-point, provider, tool, and persistence failures instead of reinstalling immediately.

Safety, privacy, and cost

File names and contents may enter model context, so use a disposable folder. Do not use --yolo; deny any unexpected write. One tool-backed turn can require multiple model iterations, so a higher token count than a plain answer is expected, but repeated loops are not—interrupt and inspect logs if the task does not converge.

Official references

• Architecture
• Agent Loop Internals

---

Source video: Hermes Architecture EXPLAINED: Memory, Context & Gateways, Hugging Face. Adapted and reorganized from the full transcript and architecture walkthrough.