Hermes on Jamie's Blog

The Self-Improvement Agent in Hermes: A Deep Dive

Fri, 29 May 2026 00:00:00 +0000

The Self-Improvement Agent in Hermes: A Deep Dive

Staff-engineer-level notes on Hermes Agent’s procedural self-improvement loop: how the runtime turns solved problems, user corrections, and hard-won debugging paths into durable skills without interrupting the foreground task.

[!NOTE]

Executive TL;DR

Hermes self-improvement is not a magic auto_create_skill() function. It is a runtime pattern composed from five pieces:

Foreground guidance: the main agent is told to save or patch skills when a complex workflow succeeds.

Iteration counters: the runtime tracks how much tool-heavy work has happened since the last skill review.

Background review fork: after the user-visible answer is delivered, Hermes starts a quiet review agent with the conversation transcript.

Narrow tool whitelist: the review fork may call only memory and skill tools, not arbitrary shell, web, or browser tools.

Procedural memory tool: skill_manage writes, patches, deletes, and annotates skills under Hermes’ skill library.

The architecture matters more than the prompt. The learning loop is isolated from the foreground answer, bounded by tool permissions, marked with provenance, and implemented through the same skill API the main agent can use.

Exception Handling for LLM Calls in Production Agentic Systems

Wed, 27 May 2026 00:00:00 +0000

Exception Handling for LLM Calls in Production Agentic Systems

A deep dive into agent/auxiliary_client.py from Hermes Agent. Written for engineers building production agentic applications who need to go beyond “catch Exception and retry.”

Why LLM Exception Handling Is Different

Most backend services talk to one upstream. When it fails, you retry or return an error.

LLM-backed agents are different in three ways that make naive exception handling dangerous:

The call is expensive. A failed LLM call that retried five times against a dead endpoint burned five API round-trips, five timeouts, and potentially five billing events — before the user saw anything.

Designing Context Compression for Production Agents: A Deep Dive into Hermes

Sun, 24 May 2026 00:00:00 +0000

Designing Context Compression for Production Agents: A Deep Dive into Hermes

Staff-engineer-level notes on agent/context_compressor.py: how Hermes preserves task continuity when a long-running agent outgrows the model context window, and what the implementation teaches about summarization, compression, and failure-tolerant agent design.

[!NOTE]

Executive TL;DR

Hermes context compression is not “summarize the chat when it gets long.” It is a transcript rewrite algorithm with strict invariants:

Head / middle / tail partitioning: keep the system prompt and first turns intact, summarize the middle, and protect the recent tail by token budget.

Active task anchoring: the latest user message must stay outside the summary. A summarized “pending ask” is reference material, not a live user turn.

Tool-aware compaction: old tool outputs are deduplicated, summarized, and pruned before any LLM call; tool call/result pairs are sanitized afterward so providers never receive invalid message history.

Iterative summaries: second and later compactions update the existing handoff instead of recursively summarizing summaries as ordinary turns.

Multimodal budgeting: images are charged a fixed token estimate so image sessions do not accidentally preserve far more context than the model can fit.

Failure visibility: if the summary model fails, Hermes inserts an explicit fallback marker and records dropped-turn metadata instead of silently losing context.

How to Use This Deep Dive

Read this document in four passes:

Hermes Agent — Deep Dive Learning Notes

Thu, 21 May 2026 00:00:00 +0000

Hermes Agent — Deep Dive Learning Notes

Staff-engineer-level notes for senior AI engineers designing and implementing production agents. Written after reading run_agent.py, model_tools.py, toolsets.py, agent/, and tools/ in full.

1. High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Entry Points                                │
│  cli.py (HermesCLI)  │  gateway/run.py  │  batch_runner.py         │
│  tui_gateway/server  │  acp_adapter/    │  run_agent.py __main__    │
└──────────────────────┬──────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      AIAgent  (run_agent.py)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Conversation │  │  Tool Loop   │  │  Provider / Transport    │  │
│  │   History    │  │  Orchestrator│  │  (Anthropic / OpenAI /   │  │
│  │  (messages)  │  │              │  │   Bedrock / Codex / ACP) │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │  ContextComp │  │  MemoryMgr   │  │  CredentialPool          │  │
│  │  -ressor     │  │  (builtin +  │  │  (multi-key failover)    │  │
│  │              │  │   plugins)   │  │                          │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
└──────────────────────┬──────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    model_tools.py                                   │
│  get_tool_definitions()  │  handle_function_call()                  │
│  _run_async()            │  _should_parallelize_tool_batch()        │
└──────────────────────┬──────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    tools/registry.py  (singleton)                   │
│  ToolRegistry.register()  │  .dispatch()  │  .get_definitions()     │
└──────────────────────┬──────────────────────────────────────────────┘
                       │
          ┌────────────┴────────────┐
          ▼                         ▼
┌──────────────────┐     ┌──────────────────────────────────────────┐
│  tools/*.py      │     │  plugins/<name>/__init__.py              │
│  (built-in tools)│     │  (user / pip-installed plugins)          │
└──────────────────┘     └──────────────────────────────────────────┘

Key insight: The architecture is a strict layered DAG. tools/registry.py has zero imports from any other Hermes module — it is the root. Every tool file imports from it. model_tools.py imports from the registry and triggers discovery. run_agent.py imports from model_tools.py. This prevents circular imports and makes the tool system independently testable.

Building a Multi-Platform Agentic Gateway: A Deep Dive into Hermes Gateway

Tue, 19 May 2026 00:00:00 +0000

Building a Multi-Platform Agentic Gateway: A Deep Dive into Hermes Gateway

A Staff-Engineer-level study of the Hermes Agent messaging gateway — from process lifecycle to platform adapters, session management to streaming delivery, and the design patterns that make it production-grade across 15+ messaging platforms.

[!NOTE]

Executive TL;DR

This document is a comprehensive deep dive into the Hermes Gateway — ~75,000+ lines of Python across 50+ modules connecting an AI agent to 15+ messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, and more). Key architectural patterns:

Building Production Agentic CLIs: A Deep Dive into Hermes

Sun, 17 May 2026 00:00:00 +0000

Building Production Agentic CLIs: A Deep Dive into Hermes

A Staff-Engineer-level study of the Hermes Agent command-line interface — from filesystem layout to REPL internals, model selection to plugin extensibility, and the design patterns that make it production-grade.

[!NOTE]

⚡ Executive TL;DR

This document is a comprehensive, Staff-Engineer level deep dive into the architecture, execution pipeline, and design patterns of the Hermes Agent CLI. If you are building production-grade agentic command-line interfaces, these are your key takeaways: