Hermes Architecture, in Full

1.918 million lines of Python · 4,772 files · a single-system deep dive · no comparisons

0 · The Project at a Glance, and a Map of the Code

0.1 What This Software Is

The project states its own positioning in the first sentence of its README:

Unpack that paragraph and it makes four core claims, and each claim maps onto a major block of the architecture:

0.2 Directory Map

File counts are in parentheses, so you can see at a glance where the bulk lives:

0.3 Three Things You Can Read Off This Map

First: the periphery is far bigger than the core, and the periphery is the product

Notice that context_engine.py is only 490 lines, while context_compressor.py right next to it is 419 KB. The former is the interface (it specifies “what a context engine must be able to do”); the latter is one built-in implementation.

That ratio runs through the whole system: thin abstraction layer, thick implementation layer, and the implementation layer can be swapped out wholesale.

Second: there is a layer called the “gateway,” and it is the largest module

gateway/run.py is a single 1.55 MB file — the largest file in the entire project.

This layer solves one very specific problem: how does a long-running agent get reached by 22 different chat apps in a uniform way?

What it buys you: you can be halfway through a conversation with the agent on Slack at your desk, walk out the door, switch to Telegram on your phone, and pick up right where you left off, with the conversation context fully intact. To the agent, it has been the same session all along; only the message inlet and outlet changed.

Third: almost every key decision point is an abstract base class

An “abstract base class” (ABC) is Python's version of a wall-socket standard: it specifies “anything that wants to plug in must provide these functions,” but says nothing about how they are implemented.

0.4 The Full Journey of One Message

0.5 Chapter Index

1 · The Gateway Layer

gateway/: 99 files, including run.py, a single 1.55 MB file — the largest module in the whole project. This chapter is about how one always-on process lets 22 chat apps reach the same agent.

1.1 The Problem It Solves

Start with what happens without a gateway. Say you want the agent to support two platforms, Slack and Telegram:

The gateway is the layer that pulls all of that shared logic out. It is a background process that never shuts down, connected to every platform at once, and it is responsible for:

• Normalizing the wildly different message formats of each platform into a uniform event object
• Session routing — deciding which conversation a message belongs to
• User authorization
• Dispatching slash commands
• Driving the clock for scheduled tasks
• Managing the cache of agent instances (the same session reuses the same instance)
• Sending replies out according to each platform's rules

1.2 The Platform Adapter Abstract Base Class

gateway/platforms/base.py, 333 KB. This is the “wall-socket standard” — it specifies what any platform must provide in order to plug in.

The core idea: turn the differences into “capability query methods”

class BasePlatformAdapter(ABC):

    # —— message length limits ——
    def max_message_length_for_chat(self, chat_id: str) -> int
    def message_len_fn(self) -> Callable[[str], int]
    def message_len_fn_for_chat(self, chat_id: str) -> Callable[[str], int]

    # —— streaming capabilities ——
    def supports_draft_streaming(self, ...) -> bool
    def prefers_fresh_final_streaming(self, ...) -> bool
    def streaming_overflow_limit(self) -> Optional[int]
    async def send_draft(self, ...)

    # —— permission model ——
    def enforces_own_access_policy(self) -> bool
    def authorization_is_upstream(self) -> bool

    # —— rendering ——
    def render_message_event(self, event, sink) -> None
    def format_tool_event(self, event, *, mode: str = "all", ...) -> str
    def format_tool_preview(self, preview: "ToolPreview") -> str
    def set_status_text(self, chat_id: str, text: Optional[str]) -> None

hermes-agent/gateway/platforms/base.py

# Style A: branch on the platform in the main flow
if platform == 'slack':
    max_len = 40000
elif platform == 'discord':
    max_len = 2000
elif platform == 'telegram':
    max_len = 4096
elif platform == 'sms':
    max_len = 160
# ... 22 branches, and checks like this scattered across dozens of places

# Style B: ask the adapter
max_len = adapter.max_message_length_for_chat(chat_id)

How big are the differences being abstracted away?

1.3 Normalizing Message Events

Every platform has a completely different message format. The gateway unifies them into one event object:

class MessageType(Enum): ...
class ProcessingOutcome(Enum): ...

class MessageEvent:
    ...
    def is_command(self) -> bool                 # is this a slash command?
    def get_command(self) -> Optional[str]       # command name
    def get_command_args(self) -> str            # command arguments

class CachedMedia:
    def context_note(self) -> str                # context note for an attachment

class TextDebounceState: ...                     # ★ text debouncing
class SendResult: ...

class EphemeralReply(str):                       # ★ a temporary reply with an expiry
    def __new__(cls, text: str, ttl_seconds: Optional[int] = None): ...
    def text(self) -> str: ...

Two classes worth calling out

TextDebounceState handles this scenario:

EphemeralReply is a class that inherits from str and carries an expiry time. It is for messages that “should disappear once said” — status hints like “Thinking…”. On platforms that support it, these messages delete themselves after a while and don't clutter the chat history.

Inheriting from str is a very practical design: every piece of code that already handles strings keeps working unchanged; only the code that cares about expiry checks whether it is an EphemeralReply.

1.4 The Defensive Mechanisms in the Gateway Main Loop

The function names in run.py are, on their own, a checklist of “what goes wrong for a long-running process”:

① Hygiene cooldown: stop retrying failed compaction

def _hygiene_cooldown_for_failure(...)
def _reset_hygiene_failure_streak(gateway, session_key: str) -> None
def hygiene_compaction_recovered(...)
def _record_hygiene_cooldown(...)

“Hygiene” here means the automatic context tidying done in the background. If compaction keeps failing for a session, give it a cooldown period rather than trying again and again — otherwise it burns resources continuously and fails continuously.

The name _reset_hygiene_failure_streak tells you it tracks a count of consecutive failures, reset to zero on the first success. This is the same idea as the idempotency lock in Chapter 3.

② Recognizing transient network errors

def _is_transient_network_error(exc: BaseException) -> bool

A long-running process has to tell “the network hiccuped” apart from “something is actually broken.” The former should retry silently; the latter should alert. If you don't distinguish them, users drown in meaningless alerts about network blips and eventually mute all alerts.

③ Redacting secrets from user-visible text

def _redact_gateway_user_facing_secrets(text: str) -> str
def _redact_approval_command(cmd: "str | None") -> str

The gateway sends some internal information into the chat window (error messages, approval requests). That text may carry API keys, tokens, and passwords. And a chat window is visible to many people, searchable, and archived. So it must be redacted before it goes out.

Note that there are two redaction functions: one for general text, one specifically for “the command awaiting approval.” Secrets in a command take different shapes (in an environment variable assignment, in an argument, in a pipeline).

④ Making provider errors user-friendly

def _gateway_provider_error_reply(text: str) -> str
def _looks_like_gateway_provider_error(text: str) -> bool
def _sanitize_gateway_final_response(platform: Any, text: str) -> str

Error messages from model services are usually written for developers (stack traces, internal error codes, request IDs). Sent straight into a chat window, they mean nothing to the user. So they have to be recognized and translated into plain language.

⑤ Restart guard

gateway/restart.py
gateway/restart_loop_guard.py     ← ★ restart storm protection

A restart storm is the classic failure of a long-running process: the process crashes → auto-restarts → crashes again on startup → restarts again → forever. Dozens of restarts per second, logs flooded, CPU pinned.

The usual guard: record recent restart counts and intervals, and if there are too many restarts in a short window, stop auto-restarting and stay down — so a human takes a look.

⑥ Memory monitoring and graceful drain

gateway/memory_monitor.py           memory usage monitoring
gateway/agent_cache_pressure.py     agent cache pressure
gateway/drain_control.py            ★ graceful drain
gateway/disk_status.py              disk status

Agent cache pressure: the gateway caches agent instances (the same session reuses the same one). But every instance holds the full message history — a few dozen active sessions can eat several GB of memory. So the pressure has to be monitored, and inactive instances evicted when necessary.

Graceful drain: when the gateway needs to shut down, you can't just kill it — messages currently being processed would be lost. The right way is “stop accepting new messages, finish what's in hand, then exit.”

⑦ Delivery ledger

gateway/delivery.py
gateway/delivery_ledger.py     ← ★ delivery ledger
gateway/rich_sent_store.py
gateway/message_timestamps.py
gateway/dead_targets.py        ← dead targets (a deleted channel, say)

The delivery ledger records “which reply has already been sent where.” It guards against duplicate delivery: on a network timeout you don't know whether the message went out, and a retry could make the user see it twice. With a ledger, you can tell.

Dead targets covers the cases where the channel the agent wants to reply to has been deleted, the bot has been kicked from the group, or the user has blocked it. These deliveries will fail forever, and they must be recognized and retries stopped, or the retry queue grows without bound.

1.5 Status Messages and Progress Feedback

def _status_template_to_regex(template: str) -> str
def _gateway_compression_progress_notices_enabled() -> bool
def _prepare_gateway_status_message(platform, event_type: str, message: str) -> Optional[str]
async def _send_or_update_status_coro(adapter, chat_id, status_key, content, metadata)
def render_notice_line(notice) -> str

During a long task the agent needs to tell the user “I'm still working.” But doing that inside a chat app is delicate:

• Too many status messages → spam
• None → the user thinks it died
• Updating by editing the same message → only works on platforms that support editing

The function _status_template_to_regex deserves a note: it converts a status-message template into a regular expression. The likely purpose is “recognize which messages in the chat history are status messages I sent earlier,” so they can be updated or deleted — because the message IDs returned by the platform API may already be lost, and matching on content is the only way to find them.

1.6 Interruption and Recovery

def _is_fresh_gateway_interruption(...)
def build_resume_recovery_note(...)
def _prepare_resume_pending_message(...)
def _build_replay_entry(...)
def _startup_restore_drain_timeout_secs() -> float
def _auto_continue_freshness_window() -> float

This group of functions handles: after the gateway restarts, what happens to the sessions that were “halfway through”?

1.7 Built-in Gateway Hooks

gateway/hooks.py
gateway/builtin_hooks/

The gateway layer has its own hook system, letting plugins insert logic at the key points where messages enter and leave. Together with the plugin system in Chapter 9, this gives you the ability to “extend gateway behavior without changing core code.”

1.8 What This Layer Costs

2 · Identity and Session Routing

This chapter covers two related but distinct things: which “agent identity” a message belongs to, and which “conversation” it belongs to.

2.1 Profiles: One Process, Many Identities

In Hermes, a “Profile” is a complete agent identity. The first sentence of the docs defines it clearly:

A Profile owns its own:

2.2 Four-Level Routing and the “Specificity” Score

Routing rules live in the config file:

gateway:
  profile_routes:
    - name: server-default          # rule name
      platform: discord
      guild_id: "SERVER_ID"
      profile: server-profile       # which identity to route to

    - name: special-channel
      platform: discord
      guild_id: "SERVER_ID"
      chat_id: "CHANNEL_ID"
      profile: channel-profile

    - name: thread-route
      platform: discord
      chat_id: "CHANNEL_ID"
      thread_id: "THREAD_ID"
      profile: thread-profile

The specificity score

@dataclass(frozen=True)
class ProfileRoute:
    name: str
    platform: str
    profile: str
    guild_id:  Optional[str] = None      # server
    chat_id:   Optional[str] = None      # channel
    thread_id: Optional[str] = None      # thread
    enabled: bool = True

    @property
    def specificity(self) -> int:
        """Higher value = more specific match."""
        s = 0
        if self.guild_id:  s += 2        # server   weight 2
        if self.chat_id:   s += 4        # channel  weight 4
        if self.thread_id: s += 8        # thread   weight 8
        return s

hermes-agent/gateway/profile_routing.py

The score uses binary bit weights (2, 4, 8), so the four priority levels line up exactly with the table in the docs:

(Strictly speaking the score is only a sort key; the actual priority 14 > 6 > 2 falls out naturally from the bit weights. The advantage of 2/4/8 over 1/2/3 is that no combination produces a duplicate score, so the ordering is always deterministic.)

Matching is conjunctive

def matches(self, platform, guild_id=None, chat_id=None,
            thread_id=None, parent_chat_id=None) -> bool:
    if not self.enabled:                                       return False
    if self.platform != platform:                              return False
    if self.thread_id and self.thread_id != thread_id:         return False
    if self.chat_id and self.chat_id != chat_id \
                    and self.chat_id != parent_chat_id:        return False    # ★
    if self.guild_id and self.guild_id != guild_id:            return False
    return True

The docs spell out the semantics:

Parent-chain matching: Discord forums and threads

That parent_chat_id branch handles a hierarchy specific to Discord:

2.3 When an Explicit Route Is Rejected

class ProfileRouteRejected(RuntimeError):
    """An explicit route matched a profile this gateway does not serve."""

In other words: an explicit route matched an identity that “this gateway doesn't serve.”

The scenario: you can run several gateway processes, each serving only a subset of identities (for resource isolation, say). A message may then match an identity that “isn't mine” — that's not a misconfiguration; the message just belongs to a different gateway.

Using a dedicated exception type rather than “silently fall back to the default identity” is the right call — a silent fallback would let the wrong identity handle the message, and the user would have a hard time noticing.

2.4 SOUL.md: The Persona File

Each identity has a SOUL.md. Its relationship to the system prompt looks like this:

This layering is the same kind of thing as CLAUDE.md in Claude Code, with one important difference: Hermes splits “persona,” “memory,” and “understanding of the user” into three separate files.

2.5 Session Routing: Continuity Across Platforms

Identity routing decides “which persona to use”; session routing decides “which conversation to continue.”

This is one of the gateway's most valuable capabilities: you can be halfway through a conversation on Slack at your desk, walk out the door, switch to Telegram on your phone, and pick up right where you left off, with the conversation context fully intact.

How it does that

The related modules:

gateway/channel_directory.py    channel directory
gateway/pairing.py              ★ pairing (links accounts on different platforms to the same user)
gateway/mirror.py               mirroring
gateway/profile_routing.py      identity routing

pairing.py is the foundation of this mechanism: the system needs to know that “@alice on Slack” and “alice_w on Telegram” are the same person. The link is usually established with something like a one-time verification code.

2.6 Caching Agent Instances

The gateway caches AIAgent instances, reusing the same one for the same session. That has two consequences:

The upside: state carries over naturally

Message history, the context engine's bookkeeping, and compaction counters all live in the instance; nothing has to be rebuilt from disk every time.

The cost: the risk of state leaking across turns

The top of the main loop has a block of code dedicated to this, and the comment says it plainly:

There is another block that handles hot config reloads:

3 · The Main Loop ★

agent/conversation_loop.py, 8,676 lines. The core function, run_conversation, starts at line 1,834.

3.1 The Loop Entry: A Triple Budget Gate

while (api_call_count < agent.max_iterations              # call count under the hard cap
       and agent.iteration_budget.remaining > 0)          # iteration budget still has balance
      or agent._budget_grace_call:                        # or: one "grace call" left

hermes-agent/agent/conversation_loop.py:2029

What each of the three conditions does:

How the grace call is implemented

if agent._budget_grace_call:
    agent._budget_grace_call = False               # ★ consume the flag; the next iteration must exit
elif not agent.iteration_budget.consume():         # try to deduct one unit of budget; nothing left
    _turn_exit_reason = "budget_exhausted"
    if not agent.quiet_mode:
        agent._safe_print(f"\n⚠️  Iteration budget exhausted "
                          f"({agent.iteration_budget.used}/{agent.iteration_budget.max_total} "
                          f"iterations used)")
    break

3.2 Per-Turn Preparation: build_turn_context

Before the loop starts there is a long “per-turn prologue,” which the source pulls out into agent/turn_context.py:

Taking those nine items one at a time:

“Restore or build” for the system prompt

def _restore_or_build_system_prompt(agent, system_message, conversation_history)
def _stored_prompt_matches_runtime(agent, prompt: str) -> bool
def _ensure_cached_system_prompt_static(agent, system_message=None) -> None

The existence of these three functions tells you: the system prompt is cached and reused across turns, and there is a check that “verifies it still matches the current runtime configuration.”

Why verify? Because the runtime configuration may have changed — the user switched models, enabled a new toolset, edited SOUL.md. Then the cached prompt is stale and must be rebuilt. But if nothing changed, it must not be rebuilt — rebuilding could produce different bytes and break the prompt cache.

3.3 Mid-Turn Interjection: /steer

This is one of Hermes's distinctive capabilities: while the model is thinking, the user can slip in a line, and that line takes effect within the current turn.

Two hard parts

The solution: append to the end of the most recent tool-result message

_pre_api_steer = agent._drain_pending_steer()          # take the pending interjection
if _pre_api_steer:
    _injected = False
    for _si in range(len(messages) - 1, -1, -1):       # search backward from the last message
        _sm = messages[_si]
        if isinstance(_sm, dict) and _sm.get("role") == "tool":   # found the most recent tool message
            from agent.prompt_builder import format_steer_marker
            marker = format_steer_marker(_pre_api_steer)
            existing = _sm.get("content", "")
            if isinstance(existing, str):
                _sm["content"] = existing + marker      # ★ append; don't add a new message
            else:
                # multimodal content blocks — append a text block
                try:
                    blocks = list(existing) if existing else []
                    blocks.append({"type": "text", "text": marker})
                    _sm["content"] = blocks
                except Exception:
                    pass
            _injected = True
            break
    if not _injected:
        # no tool message yet (first iteration) — put it back in the queue
        # and inject it when the next batch of tool results appears.
        # Injecting a user message would break role alternation, and there's no tool output to ride on yet
        agent._pending_steer = _pre_api_steer

hermes-agent/agent/conversation_loop.py · draining interjections before the API call

And a stronger one: redirect

_redirect_text = agent._drain_pending_redirect()
if _redirect_text:
    _apply_active_turn_redirect(agent, messages, _redirect_text)
    if isinstance(original_user_message, str):
        original_user_message = (
            f"{original_user_message}\n\n"
            f"User correction during the turn: {_redirect_text}"     # the user's mid-turn correction
        )
    agent._persist_session(messages, conversation_history)

A “redirect” is stronger than an “interjection”: it modifies the record of the “original user message,” attaching the correction to it. That way, even if compaction happens later, the correction survives in the material the summary is built from — because it has become part of the user's request.

3.4 The Wall-Clock Budget Wrap-Up Reminder

if getattr(agent, "run_budget_seconds", None):
    _maybe_inject_run_budget_wrapup(agent, messages)

The function's comment explains the mechanism: one-shot — when a run budget (--run-budget) is active and 80% of it has been consumed, remind the model to start wrapping up and deliver with the state it already has. Uses the same cache-safe channel as /steer (appended to the latest tool result); fully dormant when no budget is set.

3.5 The Interrupt Check

if agent._interrupt_requested:
    interrupted = True
    _turn_exit_reason = "interrupted_by_user"
    if not agent.quiet_mode:
        agent._safe_print("\n⚡ Breaking out of tool loop due to interrupt...")
    break

Hermes uses flag polling: an interrupt request sets a boolean flag, and the loop checks it once at the top of each iteration.

There is a finer-grained interrupt type too — the input budget of a review task running out:

if _review_input_budget_exhausted(agent):
    _turn_exit_reason = "review_input_budget_exhausted"
    if not agent.quiet_mode:
        agent._safe_print(
            f"\n⏹️  Review input budget exhausted "
            f"({int(agent.session_input_tokens):,} tokens) — stopping "
            f"the review tool loop before the next provider call.")
    break

The comment explains where it fits: “An aggregate input budget for detached background review tasks: compaction limits a single request, while this limits the whole review task. It fires between iterations — the request that crossed the budget line has already completed (its tool writes have landed), and then the tool loop stops before the next model call, matching how the iteration budget exits.”

3.6 The Step Callback: An Observation Point for the Gateway

if agent.step_callback is not None:
    try:
        prev_tools = []
        # search backward for the most recent model message that carried tool calls
        for _idx, _m in enumerate(reversed(messages)):
            if _m.get("role") == "assistant" and _m.get("tool_calls"):
                _fwd_start = len(messages) - _idx
                _results_by_id = {}
                # collect all the tool results that immediately follow it
                for _tm in messages[_fwd_start:]:
                    if _tm.get("role") != "tool": break
                    _tcid = _tm.get("tool_call_id")
                    if _tcid: _results_by_id[_tcid] = _tm.get("content", "")
                prev_tools = [
                    { "name":      tc["function"]["name"],
                      "result":    _results_by_id.get(tc.get("id")),
                      "arguments": tc["function"].get("arguments") }
                    for tc in _m["tool_calls"] if isinstance(tc, dict)
                ]
                break
        agent.step_callback(api_call_count, prev_tools)
    except Exception as _step_err:
        logger.debug("step_callback error (iteration %s): %s", api_call_count, _step_err)

This callback lets the gateway know in real time “which step the agent is on, which tools the last step used, and what the results were,” so it can push progress to the chat window.

Notice the whole block is wrapped in try/except, and a failure is logged only at debug level. That is correct: observation code must never affect the main flow. If step_callback throws because of a network problem, the agent should not stop working over it.

3.7 Other State Inside the Loop

The long comment at the top of the loop reveals the state maintained across iterations:

That “re-arming” mechanism deserves a closer look

3.8 Why the Loop Exited

The values of _turn_exit_reason we've already seen in the code:

Like the step callback in section 3.6, this field exists purely for observability — it plays no part in business logic, but it turns “why did this agent stop” into a data field you can query directly, instead of something you infer by digging through logs.

3.9 An Optional Bypass: The Codex App Server Runtime

# Optional opt-in runtime: if api_mode == codex_app_server,
# hand this turn to the codex app server subprocess (terminal operations, file operations,
# and patching all happen inside Codex). The default Hermes path is bypassed entirely.

This is a very thorough extension point: the entire main loop can be taken over by an external subprocess.

Its existence reveals a Hermes stance: not even the “agent loop” itself has to be implemented in-house. If a user wants a different agent runtime (here, OpenAI's Codex), Hermes can shrink down to a shell of “gateway + session management + memory.”

4 · The Tool System

162 tool files, plus a 39 KB exposure-policy file. This chapter is about how tools are organized, how they are exposed, and how call arguments get coerced.

4.1 The Most Important Design Decision: Implementation Separated from Exposure

The core tool list

# The tool list shared by the CLI and every messaging platform.
# Change it here and every platform is updated at once.
_HERMES_CORE_TOOLS = [
    # web
    "web_search", "web_extract",
    # terminal and process management
    "terminal", "process",
    # Note: desktop-GUI capabilities (read_terminal, open_preview, etc.)
    # are deliberately not listed here, for the same reason as the project tools below:
    # they only make sense where a graphical renderer can respond. They live in the desktop_ui
    # toolset and are enabled solely by the GUI gateway for sessions whose SOURCE is the desktop app —
    # never keyed on a process env var, which is blind to "a desktop client talking to a remote backend."
    # file operations
    "read_file", "write_file", "patch", "search_files",
    # vision and image generation
    "vision_analyze", "image_generate",
    # skills
    "skills_list", "skill_view", "skill_manage",
    # browser automation
    "browser_navigate", "browser_snapshot", "browser_click",
    "browser_type", "browser_scroll", "browser_back",
    "browser_press", "browser_get_images",
    "browser_vision", "browser_console", "browser_cdp", "browser_dialog",
    "browser_exec",          # replaces the other browser tools when browser.backend is "browser-use"
    # text-to-speech
    "text_to_speech",
    # planning and memory
    "todo", "memory",
    # session history search
    "session_search",
    # clarifying questions
    "clarify",
    # code execution and delegation
    "execute_code", "delegate_task",
    # scheduled tasks
    "cronjob",
    # smart home (enabled via check_fn, which looks for HASS_TOKEN)
    "ha_list_entities", "ha_get_state", "ha_list_services", "ha_call_service",
    # kanban multi-agent collaboration — only enters the schema when the agent was spawned
    # as a kanban worker (HERMES_KANBAN_TASK env var set), or the current profile has explicitly
    # enabled the kanban toolset. Controlled via check_fn.
    "kanban_show", "kanban_list", "kanban_complete", "kanban_block",
    "kanban_request_review", "kanban_request_changes", "kanban_heartbeat",
    "kanban_comment", "kanban_create", "kanban_link", "kanban_unblock",
    "kanban_attach", "kanban_attach_url", "kanban_attachments",
    # computer use (macOS; check_fn verifies cua-driver is installed)
    "computer_use",
]

hermes-agent/toolsets.py

The design principles those two comments reveal

Narrowing the trust boundary: the webhook toolset

# Webhook events may originate from untrusted third-party content (for example,
# pull request titles or comments on a public repository). The default webhook toolset is
# deliberately kept narrow so prompt injection can't trigger local file I/O or system command execution.
_HERMES_WEBHOOK_SAFE_TOOLS = [
    "web_search",       # web search (read-only)
    "web_extract",      # extract web page content (read-only)
    "vision_analyze",   # analyze images (read-only)
    "clarify",          # ask the user a question (no side effects)
]

4.2 Composing and Resolving Toolsets

TOOLSETS = {
    "web": {
        "description": "Web research and content extraction tools",
        "tools": ["web_search", "web_extract"],
        "includes": []                          # ★ can include other toolsets
    },
    "search": {
        "description": "Web search only (no content extraction/scraping)",
        "tools": ["web_search"],
        "includes": []
    },
    "vision": { "tools": ["vision_analyze"], ... },
    "video":  { "description": "…(opt-in, not in the default toolsets)",
                "tools": ["video_analyze"], ... },
    "image_gen": { "tools": ["image_generate"], ... },
    ...
}

Each toolset has three fields: a description (for humans), a tool list, and other toolsets it includes.

The resolution functions

def get_toolset(name: str, *, include_registry: bool = True) -> Optional[Dict]
def bundle_non_core_tools(toolset_name: str) -> Set[str]
def resolve_toolset(name: str, visited: Set[str] = None, *,
                    include_registry: bool = True) -> List[str]     # ★ with cycle detection
def resolve_multiple_toolsets(toolset_names: List[str]) -> List[str]
def _get_plugin_toolset_names() -> Set[str]                # toolsets provided by plugins
def _get_registry_toolset_aliases() -> Dict[str, str]      # aliases
def get_all_toolsets() -> Dict[str, Dict[str, Any]]
def get_toolset_names() -> List[str]
def validate_toolset(name: str) -> bool
def create_custom_toolset(...)
def get_toolset_info(name: str) -> Dict[str, Any]

The visited parameter of resolve_toolset is cycle detection: toolset A includes B, B includes A, infinite recursion. A “visited set” prevents it.

The existence of bundle_non_core_tools tells you that the system needs to distinguish “core tools” from “add-on tools” — presumably so they can be treated differently when computing token cost or making exposure decisions.

Toolsets from three sources

The function names show that toolsets come from three places:

• Built-in — hard-coded in the TOOLSETS dictionary
• Plugin-provided — _get_plugin_toolset_names()
• The registry — controlled by the include_registry parameter, with alias support via _get_registry_toolset_aliases()

4.3 Central Tool Dispatch

Hermes has no Tool class abstraction; every tool call goes through the same function:

def handle_function_call(...)      # model_tools.py, line 1240

The registry machinery that goes with it:

TOOL_TO_TOOLSET_MAP:   Dict[str, str]  = registry.get_tool_to_toolset_map()
TOOLSET_REQUIREMENTS:  Dict[str, dict] = registry.get_toolset_requirements()

def get_all_tool_names() -> List[str]
def get_toolset_for_tool(tool_name: str) -> Optional[str]
def get_available_toolsets() -> Dict[str, dict]
def check_toolset_requirements() -> Dict[str, bool]      # ★ dependency check
def check_tool_availability(quiet: bool = False) -> Tuple[List[str], List[dict]]

TOOLSET_REQUIREMENTS is an important mechanism: some tools need external conditions to work.

The comments in the core list say these are “controlled via check_fn” — meaning each tool can supply a check function that decides at runtime whether it is available. Unavailable tools never enter the model's tool list, so they cost no tokens and can't be called only to fail.

4.4 The Argument Coercion Layer

This layer is unique to Hermes, and extremely practical:

def coerce_tool_args(tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]    # line 845
def _schema_accepts_kind(schema: Any, kind: str) -> bool                       # 953
def _normalize_json_strings_for_schema(value: Any, schema: Any) -> Any         # 974
def _coerce_value(value: str, expected_type, schema: dict | None = None)       # 1051
def _schema_allows_null(schema: dict | None) -> bool                           # 1080
def _coerce_json(value: str, expected_python_type: type)                       # 1104
def _coerce_number(value: str, integer_only: bool = False)                     # 1135
def _coerce_boolean(value: str)                                                # 1153
def _canonicalize_tool_call_arguments(arg_str: str) -> str                     # 1293

hermes-agent/model_tools.py

Why this layer is needed

Coercion follows the schema; it is not blind conversion

Look at the signature: _coerce_value(value, expected_type, schema) — it receives the target schema. So coercion has a basis:

• _schema_accepts_kind(schema, kind) — first ask “does this schema accept this kind of value?”
• _schema_allows_null(schema) — “is null allowed?”, which decides whether "null" becomes None
• _normalize_json_strings_for_schema(value, schema) — recursively handle JSON strings inside nested structures, guided by the schema

Blind conversion (say, “every string that looks like a number becomes a number”) would introduce new bugs — a version number "1.20" that should stay a string would become the number 1.2. Deciding by schema avoids that.

4.5 Sanitizing Tool Error Messages

_TOOL_ERROR_ROLE_TAG_RE = re.compile(...)          # strip forged role tags
_TOOL_ERROR_FENCE_OPEN_RE  = re.compile(r'^\s*```(?:json|xml|html|markdown)?\s*',
                                        re.MULTILINE)
_TOOL_ERROR_FENCE_CLOSE_RE = re.compile(r'\s*```\s*$', re.MULTILINE)
_TOOL_ERROR_CDATA_RE = re.compile(r'<!\[CDATA\[.*?\]\]>', re.DOTALL)

def _sanitize_tool_error(error_msg: str) -> str: ...

What attack this defends against

The four regexes each handle one kind of carrier:

4.6 Observing Tool Results, and Hooks

def suppress_post_tool_call_hook()                 # context manager: temporarily disable the hook
def _tool_result_observer_fields(...)
def _emit_post_tool_call_hook(...)

suppress_post_tool_call_hook() is a context manager. Its purpose: certain internal tool calls should not fire the user's hooks.

For example: the agent calls some tool internally in order to do compaction. That isn't part of the user's task, and it shouldn't fire the user-configured “log something after every tool call” hook — otherwise the log drowns in internal operations.

4.7 Recognizing a Delegation Context

def _is_delegated_child_context() -> bool      # am I a delegated subagent?
def _is_dispatcher_owned_worker() -> bool      # am I a worker owned by the dispatcher?
def _get_tool_loop()                           # get the event loop for tool execution
def _get_worker_loop()                         # get the worker's event loop
def _run_async(coro)                           # run a coroutine on the correct event loop

This group of functions deals with a practical problem in Python async programming: subagents may run on different event loops (even different threads). When a tool executes, it has to find the right loop to schedule its coroutine on, or it throws “event loop is closed” or deadlocks.

_is_delegated_child_context() also has a business purpose: a subagent needs to know it is a subagent, so it can apply different behavior (an auto-approval policy, for instance; see Chapter 10).

4.8 Caching Tool Definitions

_TOOL_DEFS_CACHE_MAX = 8
def _clear_tool_defs_cache() -> None
def get_tool_definitions(...)          # line 323, cached
def _compute_tool_definitions(...)     # line 417, the actual computation
def _resolve_active_context_length() -> int

Tool definitions (the list of tools and parameter descriptions sent to the model) are cached, up to 8 copies.

Why multiple copies? Because different situations use different toolsets: one for the main agent, one for subagents, one for kanban workers, one for webhooks… and computing each one means walking every tool, parsing schemas, and checking requirements, which isn't cheap.

The appearance of _resolve_active_context_length() here suggests that generating tool definitions may depend on the size of the context window — presumably trimming some tools or shortening descriptions when the window is small.

5 · Approval and Safety Red Lines ★

tools/approval.py, 5,802 lines. This is the single file in the whole project with the densest adversarial thinking.

5.1 The Overall Structure

5.2 The 12 Hard Red Lines

HARDLINE_PATTERNS = [
  # rm recursively deleting the root filesystem or a protected root directory
  (_RM_FLAG_PREFIX + _hardline_rm_path(r'/(?:(?:\.\.?)?/)*(?:\.\.?)?\**|/ \*'),
                                          "recursive delete of root filesystem"),
  (_RM_FLAG_PREFIX + _hardline_rm_path(_HARDLINE_SYSTEM_DIRS),
                                          "recursive delete of system directory"),
  (_RM_FLAG_PREFIX + _hardline_rm_path(r'(?:~|\$\{?HOME\}?)(?:/?|/\*)?'),
                                          "recursive delete of home directory"),
  # formatting a filesystem
  (_CMDPOS + r'mkfs(\.[a-z0-9]+)?\b',     "format filesystem (mkfs)"),
  # writing straight to a raw disk device
  (_CMDPOS + r'dd\b[^\n]*\bof=/dev/(sd|nvme|hd|mmcblk|vd|xvd)[a-z0-9]*',
                                          "dd to raw block device"),
  (r'>\s*/dev/(sd|nvme|hd|mmcblk|vd|xvd)[a-z0-9]*\b',
                                          "redirect to raw block device"),
  # fork bomb: a process that replicates itself endlessly and locks up the machine
  (r':\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:',        "fork bomb"),
  # killing every process on the system
  (_CMDPOS + r'kill\s+(-[^\s]+\s+)*-1\b', "kill all processes"),
  # shutdown / reboot (four spellings)
  (_CMDPOS + r'(shutdown|reboot|halt|poweroff)\b',      "system shutdown/reboot"),
  (_CMDPOS + r'init\s+[06]\b',                          "init 0/6"),
  (_CMDPOS + r'systemctl\s+(poweroff|reboot|halt|kexec)\b', "systemctl poweroff/reboot"),
  (_CMDPOS + r'telinit\s+[06]\b',                       "telinit 0/6"),
]

_HARDLINE_SYSTEM_DIRS = (
    r'/home|/home/\*|/root|/root/\*|/etc|/etc/\*|/usr|/usr/\*|'
    r'/var|/var/\*|/bin|/bin/\*|/sbin|/sbin/\*|/boot|/boot/\*|/lib|/lib/\*'
)

hermes-agent/tools/approval.py

“Unconditional” means: nothing the user configures matters; these commands will never be executed.

5.3 The Real Difficulty: Telling “Command” from “Data”

A real incident

The most naive implementation is if "rm -rf /" in command: block. A source comment records the problem it caused:

The solution: command-position anchoring

_CMDPOS = (
    # start of line / after a command separator / after a subshell opener / after a sudo|env|exec wrapper
    ...
)

# rm plus its flag group, shared by the three rm rules. Kept as plain string concatenation
# (rather than an f-string) so the regex's backslashes never appear inside an f-string
# replacement field — which is unsupported on Python 3.11.
_RM_FLAG_PREFIX = _CMDPOS + r'rm\s+(-[^\s]*\s+)*'

_CMDPOS matches only in these positions:

In --title "block rm -rf / spellings", what precedes rm is a space and a quote, which is none of the positions above — so there's no match, and the command runs normally.

Path normalization: which spellings actually mean the root directory

The regex in that root-directory rule is /(?:(?:\.\.?)?/)*(?:\.\.?)?\**|/ \*, and the comment explains its design:

The comment also notes: “the explicit "/ \*" branch preserves the ‘slash-space-glob’ spelling (rm -rf / *, which the shell sees as two arguments: / and the glob *)” — a classic slip-of-the-finger disaster (you meant to delete /tmp/* and typed one extra space).

5.4 Quote Masking: But Leave a Way In for “the Part That Really Executes”

Two of the red-line rules have no command name to anchor on — the redirect > /dev/sda and the fork bomb's function definition are effective at any position on the command line.

_QUOTE_MASKED_HARDLINE_DESCRIPTIONS = frozenset({
    "redirect to raw block device",
    "fork bomb",
})

HARDLINE_PATTERNS_COMPILED = [
    (re.compile(pattern, _RE_FLAGS),
     description,
     description in _QUOTE_MASKED_HARDLINE_DESCRIPTIONS)     # ★ third field: whether to mask
    for pattern, description in HARDLINE_PATTERNS
]

The exact semantics of the masking function

def _mask_quoted_prose(command: str) -> str:
    """Blank out quoted string CONTENT for positionless hardline matching.

    Detection-only rewrite used by the quote-masked hardline rules
    (redirect-to-block-device, fork bomb): text inside single or double
    quotes is data the shell passes as an argument, so `echo "cat f >
    /dev/sda"` must not trip the unconditional floor. Structure is
    preserved: the quote characters themselves stay, and inside double
    quotes `$(...)` command substitutions and backtick spans are kept RAW
    because the shell really executes them (`echo "$(cat f > /dev/sda)"`
    remains a true positive). Unquoted text is untouched.
    """

In plain terms: for the positionless red-line rules, blank out the content inside quotes. This is a rewrite used only for detection… quoted text is data the shell passes as an argument, so echo "cat f > /dev/sda" must not hit the unconditional red line. Structure is preserved: the quote characters themselves stay, and inside double quotes, $(...) command substitutions and backtick spans are left unmasked, because the shell really does execute them. Unquoted text is untouched.

5.5 Quoting Is Not a Bypass

_SHELL_CARRIER_NAMES = frozenset({
    "eval", "sh", "bash", "zsh", "ksh", "dash", "source", ".",
})

def _contains_shell_carrier(command: str) -> bool:
    """Return whether any command-position word is a shell-carrying command."""
    for _, _, word in _iter_shell_command_word_spans(command):
        name = os.path.basename(
            _deobfuscate_shell_word_for_detection(word)     # ★ de-obfuscation
        ).lower()
        if name in _SHELL_CARRIER_NAMES:
            return True
    return False

The logic: if the command contains something like sh -c "...", bash -c "...", or eval "..." — a command that “hands quoted content to another shell to execute” — then what's inside the quotes is code, not prose. The masking rule is switched off entirely, and the raw string must be scanned.

The comment sums it up in one line: “quoting is not a bypass”.

Three layers of defense, stacked

And de-obfuscation

_deobfuscate_shell_word_for_detection handles spellings like these:

5.6 Sensitive Paths and Write Targets

Beyond dangerous commands, there is a set of patterns for writes to sensitive files:

_SSH_SENSITIVE_PATH   = r'(?:~|\$home|\$\{home\})/\.ssh(?:/|$)'
_HERMES_ENV_PATH      = ...        # ~/.hermes/.env (the agent's own credentials)
_HERMES_CONFIG_PATH   = ...        # ~/.hermes/config.yaml (the agent's own configuration)
_PROJECT_ENV_PATH     = r'(?:(?:/|\.{1,2}/)?(?:[^\s/"\'`]+/)*\.env(?:\.[^/\s"\'`]+)*)'
_PROJECT_CONFIG_PATH  = r'(?:(?:/|\.{1,2}/)?(?:[^\s/"\'`]+/)*config\.yaml)'
_SHELL_RC_FILES       = (...)      # .bashrc / .zshrc and other shell startup scripts
_CREDENTIAL_FILES     = (...)
_MACOS_PRIVATE_SYSTEM_PATH = r'/private/(?:etc|var|tmp|home)/'
_SYSTEM_CONFIG_PATH   = (...)

_SENSITIVE_WRITE_TARGET         = (...)
_USER_SENSITIVE_WRITE_TARGET    = (...)
_PROJECT_SENSITIVE_WRITE_TARGET = rf'(?:{_PROJECT_ENV_PATH}|{_PROJECT_CONFIG_PATH})'

_COMMAND_TAIL           = r'(?:\s*(?:&&|\|\||;).*)?$'
_WRITE_TARGET_BOUNDARY  = r'(?=[\s;&|<>"\']|$)'

Two other regexes deserve attention:

• _COMMAND_TAIL — matches the case where “more commands follow this one” (&&, ||, ;). Prevents spellings like echo ok && rm -rf / that hide the dangerous command at the end.
• _WRITE_TARGET_BOUNDARY — a lookahead assertion requiring the write target to be followed by whitespace, a separator, or end of line. Prevents .env from falsely matching a different file like .envrc.

5.7 The sudo Stdin Guard

_SUDO_STDIN_RE = re.compile(...)
def _check_sudo_stdin_guard(command: str) -> tuple: ...
def _sudo_stdin_block_result(description: str) -> dict: ...

This defends against spellings like echo PASSWORD | sudo -S DANGEROUS_COMMAND — sudo -S means “read the password from standard input,” so the password can be piped in, bypassing the interactive password prompt entirely.

And the interactive password prompt was supposed to be the last human gate. Bypassing it means the agent can run arbitrary privileged commands without the user ever knowing.

5.8 Performance: Why Precompile

# Building these at module load eliminates the ~2.6 ms cold-cache re.compile fan-out
# on each process's first terminal() call
# (12 HARDLINE + 47 DANGEROUS patterns, any of which can be evicted from Python's
#  512-entry re._cache by unrelated regex work elsewhere in the program).
_RE_FLAGS = re.IGNORECASE | re.DOTALL
HARDLINE_PATTERNS_COMPILED = [...]

Two layers of problem:

1. First-compile cost — 59 regexes compiled on first use, about 2.6 milliseconds
2. Cache eviction — Python's built-in regex cache holds only 512 entries. Whenever the rest of the program gets busy (log formatting, text processing), these safety regexes get evicted, causing repeated recompilation

Precompiled into module-level constants, both problems disappear.

5.9 Retaining Blocked Commands

def _save_blocked_payload(command: str) -> Optional[str]: ...
def _hardline_block_result(description: str, command: str = "") -> dict: ...
def _user_deny_block_result(pattern: str) -> dict: ...

_save_blocked_payload stores the commands that got blocked. Two uses:

• Forensics — if an attack really happened, you can trace what the attacker tried to execute
• False-positive analysis — if a user complains “a normal command got blocked,” you can see exactly which rule matched what

5.10 Smart Approval: An Optional Model Judgment

def _prepare_smart_approval_observer(...)
def _observe_smart_approval_verdict(payload: dict | None, verdict: str) -> None
def _fire_approval_hook(hook_name: str, **kwargs) -> None

Beyond the deterministic rules, Hermes has an optional “smart approval” — using a model to judge whether an operation is safe.

Note the words observer and verdict in the function names: the mechanism is designed to be observable, and every verdict is recorded. That is what makes it possible to evaluate “how accurate is smart approval, and what did it get wrong.”

5.11 Context Awareness: Different Situations, Different Policies

def set_hermes_interactive_context(interactive: bool) -> contextvars.Token
def reset_hermes_interactive_context(token: contextvars.Token) -> None
def _is_interactive_cli() -> bool
def _is_cron_approval_context() -> bool
def _is_single_query_approval_context() -> bool
def _is_gateway_approval_context() -> bool
def _get_session_platform() -> str
def _resolve_cli_approval_callback(approval_callback=None)
def _should_fall_through_to_cli_approval(...)

def set_current_session_key(session_key: str) -> contextvars.Token[str]
def get_current_session_key(default: str = "default") -> str
def set_current_observability_context(...)

This uses Python's contextvars — a variable mechanism that “propagates automatically through an async call chain, with each coroutine isolated from the others.”

And the policy differences across situations are:

5.12 Where This Layer Sits: Outermost, and Thinnest

6 · Execution Environments

tools/environments/, 12 files. This chapter is about where tools actually run — which is the only truly hard boundary in the defense-in-depth stack.

6.1 Seven Environments to Choose From

Plus two supporting modules: base.py (68.3 KB, the abstract base class and shared logic) and file_sync.py (20.2 KB, file synchronization between the host and the environment).

6.2 One Thing That Has to Be Said Plainly

6.3 Shared Logic in the Abstract Base Class

base.py is 68.3 KB — it isn't just an interface definition; it also contains the implementation shared by every environment.

A dedicated exception for connection-class failures

class EnvironmentConnectionError(RuntimeError):
    """Infrastructure/connection-class failure of a terminal backend."""

    def __init__(self, reason: str, *, retry_hint: str = ""):
        ...

Why a separate exception type? Because two kinds of failure need to be told apart:

Without the distinction, the model receives “connection failed” and tries to “fix” it — but there's nothing it can do, and it just burns a few rounds of attempts. The retry_hint field shows that the exception also carries information about “how to retry.”

The bounded output collector

class _BoundedOutputCollector:
    """Retain a bounded 40/60 head-tail window of streamed text."""

    def __init__(self, max_chars: int, spill_path: "Path | None" = None): ...
    def _maybe_spill(self, text: str) -> None:
        """Tee ``text`` to the spill file (opened lazily on first overflow)."""
    def close_spill(self) -> "str | None":
        """Close the spill file and return its path if it was used."""
    def buffered_chars(self) -> int
    def total_chars(self) -> int
    def append(self, text: str) -> None
    def render(self, *, suffix: str = "") -> str:
        """Render within ``max_chars``, preserving a required status suffix."""

The design of _maybe_spill is also very practical: the full output beyond the window is written to a file, and the file is “opened lazily on the first overflow.” Most command output is short and never overflows — so no file I/O happens at all. When it really does overflow, the model gets the file path and can read the whole thing.

The “preserving a required status suffix” in render(suffix=...) also deserves attention: however the output is truncated, status information like “what was the command's exit code” must survive. It can't get cut off just because the output was too long.

The activity callback: a heartbeat for long commands

def set_activity_callback(cb: Callable[[str], None] | None) -> None:
    """Register a callback that _wait_for_process fires periodically."""
def get_activity_callback() -> Callable[[str], None] | None:
    """Return the thread-local activity callback…"""
def touch_activity_if_due(...):
    """Fire the activity callback at most once every ``state['interval']`` seconds."""

A command may run for minutes (compiling, testing, downloading). During that time:

• The user needs to know “still running, not dead”
• The gateway needs to update the status message in the chat window
• But not every second — that spams the channel and trips the platform's rate limits

touch_activity_if_due is the throttle: fire the callback at most once every N seconds. And it is thread-local — because several tools may be executing in parallel on different threads, and each needs its own callback.

The sandbox directory

def get_sandbox_dir() -> Path:
    """Return the host-side root for all sandbox storage (Docker workspaces, …)"""

All host-side sandbox storage lives under one root directory. That gives cleanup, backup, and disk-quota management a single entry point.

6.4 File Synchronization

file_sync.py (20.2 KB) solves a problem that is bound to come up: if tools execute inside a container or on a remote host, where are the files they read and write?

The existence of this layer explains why isolation has a cost: not just “containers are slow to start,” but ongoing file-sync overhead and consistency problems. That is also why local mode is the default — it's the fastest and simplest, at the price of no isolation.

6.5 When the Environment Is Chosen

The environment is configured per session/identity, not per tool call. There's a reason for that granularity:

• If the environment switched per call, a sequence like “write a file, then read it” would break across environments
• And every switch carries startup overhead

So the more sensible pattern is: high-trust situations (your own terminal) run local; low-trust situations (public webhooks, multi-user group chats) run in a container. And that judgment is the same axis as the toolset exposure in Chapter 4 — the trust boundary.

7 · The Context Engine ★

agent/context_engine.py, 490 lines. This file does no actual work — it only defines a contract. But it is the most concentrated expression of Hermes's architectural stance.

7.1 What It Defines

“Only one engine is active” is the important sentence — it classifies the context engine as a “mutually exclusive strategy” rather than a “stackable capability.” Chapter 9 explains why this distinction has to be made at the plugin-system level.

7.2 Lifecycle

"""
Lifecycle:
  1. Engine is instantiated and registered (plugin register() or default)
  2. on_session_start() called when a conversation begins
  3. update_from_response() called after each API response with usage data
  4. should_compress() checked after each turn
  5. compress() called when should_compress() returns True
  6. on_session_end() called at real session boundaries (CLI exit, /reset,
     gateway session expiry) — NOT per-turn
"""

Note the phrase “NOT per-turn” in step 6. This is an easy thing to get wrong:

7.3 The Three Methods You Must Implement

class ContextEngine(ABC):

    @property
    @abstractmethod
    def name(self) -> str:
        """Short identifier (e.g. 'compressor', 'lcm')."""

    @abstractmethod
    def update_from_response(self, usage: Dict[str, Any]) -> None:
        """Update tracked token usage from an API response."""

    @abstractmethod
    def should_compress(self, prompt_tokens: int = None) -> bool:
        """Return True if compaction should fire this turn."""

    @abstractmethod
    def compress(self, messages, current_tokens=None, focus_topic=None,
                 force=False, memory_context="") -> List[Dict[str, Any]]:
        """Compact the message list and return the new message list."""

Backward-compatible design of the usage dict

This is a textbook example of “interface evolution”: old fields are never removed (so old engines keep running), new fields are optional (so new engines can use the finer-grained data), and the compatibility contract is spelled out explicitly in the docs.

Each of compress's four optional parameters has a job

The docs also spell out how parameter evolution is handled: “Older engines may omit this parameter; the host filters unsupported optional parameters by signature.” — the host uses reflection to inspect the engine method's signature and passes only the parameters it accepts. So adding a parameter never breaks an old engine.

7.4 The Sharpest Design Decision: select and compress Are Two Orthogonal Verbs

def select_context(
    self,
    request_messages: List[Dict[str, Any]],
    *,
    conversation_messages: List[Dict[str, Any]] = None,
    incoming_message: Dict[str, Any] = None,
    budget_tokens: int = 0,
) -> List[Dict[str, Any]]:
    """Optionally choose/replace the context for THIS request, pre-generation."""
    return None      # default: no-op

This interface was forced into existence by real misuse

Reconstructing the story:

The key constraint: request-only

The cache contract is spelled out more clearly than anything else

7.5 The Post-Turn Observation Hook

def on_turn_complete(self, messages, usage: Dict[str, Any] = None, **kwargs) -> None:
    """Observe a finished user turn (post-turn ingestion / observation)."""
    return None

This is the mirror image of select_context(): selection happens before the request; observation happens after the turn.

An honest note on coverage

7.6 Other Optional Hooks

# Deterministic pruning, no model call
def prune_tool_results_only(self, messages, current_tokens=None) -> tuple[List, int]:
    return messages, 0                     # default: safe no-op

# Cheap preflight
def should_compress_preflight(self, messages) -> bool:
    return False
def should_defer_preflight_to_real_usage(self, rough_tokens: int) -> bool:
    return False

# Preflight guard for manual /compress
def has_content_to_compress(self, messages) -> bool:
    return True

# Session lifecycle
def on_session_start(self, session_id: str, **kwargs) -> None
def on_session_end(self, session_id: str, messages) -> None
def on_session_reset(self) -> None

# ★ Engines can bring their own tools
def get_tool_schemas(self) -> List[Dict[str, Any]]:
    return []
def handle_tool_call(self, name: str, args: Dict[str, Any], **kwargs) -> str

# Status display
def get_status(self) -> Dict[str, Any]

# Model switching
def update_model(self, model, context_length, base_url="", api_key="",
                 provider="", api_mode="") -> None

Pruning without a model call: why it gets its own hook

The key is “an independent, low trigger.” With a model that has a one-million-token window, should_compress might not fire for dozens of turns — but that stale tool output is re-sent every turn and costs money every turn. So you need a cost-driven pruning trigger that has nothing to do with “will we overflow the window.”

Engines can bring their own tools

get_tool_schemas() / handle_tool_call() let an engine expose its own tools to the model. The example in the docs: the LCM engine can offer tools like lcm_grep, lcm_describe, and lcm_expand — that is, it lets the model actively search, describe, and expand context that has been folded away.

7.7 Default Parameter Values

threshold_percent: float = 0.75      # start compacting at 75% of the window
protect_first_n:   int   = 3         # protect the first 3 (beyond the system prompt)
protect_last_n:    int   = 6         # protect the last 6

emit_automatic_compaction_status: bool = True    # notify the user on automatic compaction?

The semantics of protect_first_n come with an evolution note:

7.8 Control Over User-Visible Status

def automatic_compaction_status_message(engine, *, phase: str,
                                        default_message: str, **context) -> str | None:
    """Resolve host-visible status for an automatic compaction event.

    Engines can suppress routine automatic status with
    ``emit_automatic_compaction_status = False`` or customize it by defining
    ``get_automatic_compaction_status_message(...)``. Empty strings and
    ``None`` mean "do not emit a lifecycle status".
    """

The thinking here: different engines see “compaction” very differently.

• The built-in compressor: compaction is a big deal (lossy, irreversible), and the user should be told
• Some retrieval-style engine: reorganizing context is routine background maintenance, done every turn, and notifying the user would just be noise

And it is finely grained: “warnings, errors, and manual commands the user explicitly runs still notify” — only “routine automatic success” can be silenced.

7.9 Size Comparison of the Built-in Implementation

8 · The Memory System ★

This chapter covers how Hermes “remembers things across sessions.” It has three parts: a pluggable provider interface, a built-in holographic memory implementation, and a SQLite state layer.

8.1 The Memory Provider Interface

Two reasons behind the “only one” limit

So memory providers, like context engines, are a “mutually exclusive strategy” rather than a “stackable capability.” Chapter 9 develops this distinction.

Eight optional backends

plugins/memory/
├── holographic/      ★ built-in: HRR holographic memory (see 8.6)
├── honcho/           external service
├── hindsight/        external service
├── mem0/             external service
├── byterover/        external service
├── openviking/       external service
├── retaindb/         external service
├── supermemory/      external service
├── query_rewrite.py  query rewriting (shared helper)
└── config_schema.py

8.2 Lifecycle and Hooks

"""
Lifecycle (called by MemoryManager, wired in run_agent.py):
  initialize()           — connect, create resources, warm up
  system_prompt_block()  — static text for the system prompt
  prefetch(query)        — background recall before each turn
  sync_turn(user, asst)  — async write after each turn
  get_tool_schemas()     — tool schemas to expose to the model
  handle_tool_call()     — dispatch a tool call
  shutdown()             — clean exit

Optional hooks (override to opt in):
  on_turn_start(turn, message, **kwargs)      — per-turn clock tick, with runtime context
  on_session_end(messages)                    — extraction at session end
  on_session_switch(new_session_id, **kwargs) — mid-process session ID rotation
  on_pre_compress(messages) -> str            — ★ extraction before context compaction
  on_memory_write(action, target, content, metadata=None)
                                              — mirror writes to the built-in memory
  on_delegation(task, result, **kwargs)       — parent-side observation of subagent work
  backup_paths() -> list[str]                 — extra on-disk paths to include in backups
"""

hermes-agent/agent/memory_provider.py

Three hooks worth calling out

on_pre_compress(messages) -> str (pre-compaction extraction) is the single most important piece of the whole design:

on_delegation(task, result) (delegation observation) solves this problem: a subagent's work happens outside the parent's context (that is precisely the point of subagents; see chapter 10). But the subagent may have discovered facts worth remembering long-term. This hook lets the parent-side memory system observe the subtask's input and result.

backup_paths() (backup paths) is a very practical operational concern: the hermes backup command needs to know which extra on-disk locations a memory provider stores its data in before it can make a complete backup.

8.3 The Interface's Versioned Contract

# Version 1 is the historical, implicit contract every provider is already
# on: best-effort on_pre_compress() with the raw message list. Version 2 is
# the opt-in fail-closed checkpoint contract (normalized evidence handoff +
# strict-mode failure propagation).
PRE_COMPRESS_CHECKPOINT_API_VERSION = 2

In plain terms: version 1 is the historical, implicit contract that every existing provider is already on: get the raw message list, do on_pre_compress on a best-effort basis. Version 2 is the opt-in “fail-closed” checkpoint contract (a normalized evidence handoff plus failure propagation in strict mode).

8.4 The Trivial-Prompt Filter

This is a small but very practical optimization:

# Prompts that carry no semantic signal — trivial acknowledgements, greetings,
# slash commands, empty input. Single source of truth shared by the core
# per-turn prefetch gate and provider-side classifiers so the two can never
# drift apart.
TRIVIAL_PROMPT_RE = re.compile(
    r'^(yes|no|ok|okay|sure|thanks|thank you|y|n|yep|nope|yeah|nah|'
    r'hi|hey|hello|yo|sup|'
    r'continue|go ahead|do it|proceed|got it|cool|nice|great|done|next|lgtm|k)'
    r'[\s!?.:;,"\'~…—–()\[\]{}<>*&^%$#@!+=` ]*$',
    re.IGNORECASE,
)

def is_trivial_prompt(text: Optional[str]) -> bool:
    """Callers use this to skip memory-provider prefetch/injection on turns
    that carry no semantic signal — saving a blocking network round-trip
    and preventing stale user-model context from derailing one-word replies."""
    if not text: return True
    stripped = text.strip()
    if not stripped: return True
    if stripped.startswith("/"): return True         # slash command
    return bool(TRIVIAL_PROMPT_RE.match(stripped))

What it saves

When the user says something like “ok,” “thanks,” or “continue”:

• It saves one blocking network round-trip — retrieval from an external memory service goes over the network, typically a few hundred milliseconds
• It keeps a stale user model from derailing a one-word reply — the user just said “ok,” but you injected three paragraphs of their history into the context, and the model may inexplicably start talking about that material

The regex's anchoring design

Note the “single source of truth” mentioned in the comment: this regex is shared by the core per-turn prefetch gate and the provider-side classifiers, “so the two can never drift apart.” If each kept its own copy, sooner or later you would get the inconsistency where “the core thinks it's trivial, the provider thinks it isn't.”

8.5 The Memory-Usage Indicator

INDICATOR_GLYPH = "🧠"     # default glyph; providers can override with their own brand mark
                            # (Hindsight uses "👁️", for example)

@dataclass(frozen=True)
class RecallStatus:
    """Summary of what a provider's most recent prefetch injected this turn.

    …so the agent can emit a deterministic, model-independent
    "memory was used" indicator. ``count`` is the number of discrete
    memories injected; ``0`` means content was injected but has no discrete
    count (e.g. a synthesized reflect answer), which the indicator renders
    generically rather than as "0 memories".
    """
    provider_label: str
    count: int
    glyph: str = INDICATOR_GLYPH

8.6 The Built-in Holographic Memory

plugins/memory/holographic/, four files: holographic.py (the HRR math), store.py (SQLite storage), retrieval.py (retrieval), and __init__.py (the provider implementation).

What HRR is

The three core operations

def bind(a, b):        # bind = circular convolution = element-wise phase addition
    return (a + b) % _TWO_PI
    # Binds two concepts into one composite vector.
    # The result resembles neither input (mathematically, "quasi-orthogonal")

def unbind(memory, key):   # unbind = circular correlation = phase subtraction
    return (memory - key) % _TWO_PI
    # unbind(bind(a, b), a) ≈ b   (up to superposition noise)

def bundle(*vectors):  # bundle = superposition = circular mean of complex exponentials
    complex_sum = np.sum([np.exp(1j * v) for v in vectors], axis=0)
    return np.angle(complex_sum) % _TWO_PI
    # The result resembles every input;
    # holds O(√dim) items, degrades beyond that

def similarity(a, b):  # similarity = phase cosine, range [-1, 1]
    return float(np.mean(np.cos(a - b)))

hermes-agent/plugins/memory/holographic/holographic.py

You don't need the math to understand what these are for:

• Bind glues a “key” and a “value” into one vector — say, binding “the user's editor” to “Vim”
• Unbind is the inverse: given a key, it recovers the corresponding value
• Bundle squeezes many memories into one vector, so a single vector can stand for a whole category

The source also explains why phase encoding was chosen: “Phase encoding is numerically stable, avoids the magnitude collapse of traditional complex-number HRRs, and maps cleanly to cosine similarity.” (That is, it holds up numerically, sidesteps the magnitude collapse of traditional complex-number HRRs, and maps neatly onto cosine similarity.)

The most notable engineering decision: SHA-256 instead of random numbers

def encode_atom(word: str, dim: int = 1024) -> "np.ndarray":
    """Deterministic phase vector via SHA-256 counter blocks.

    Uses hashlib (not numpy RNG) for cross-platform reproducibility.

    Algorithm:
    - Generate enough SHA-256 blocks by hashing f"{word}:{i}" for i=0,1,2,...
    - Concatenate digests, interpret as uint16 values via struct.unpack
    - Scale to [0, 2π): phases = values * (2π / 65536)
    - Truncate to dim elements
    """
    values_per_block = 16                    # each SHA-256 digest is 32 bytes = 16 uint16 values
    blocks_needed = math.ceil(dim / values_per_block)
    uint16_values = []
    for i in range(blocks_needed):
        digest = hashlib.sha256(f"{word}:{i}".encode()).digest()
        uint16_values.extend(struct.unpack("<16H", digest))
    phases = np.array(uint16_values[:dim], dtype=np.float64) * (_TWO_PI / 65536.0)
    return phases

An honest capacity ceiling

def snr_estimate(dim: int, n_items: int) -> float: ...

Because the bundle() operation can only hold about √dim items — at 1024 dimensions, it starts degrading after roughly 32 items. This function estimates “the signal-to-noise ratio after packing N memories into a given number of dimensions.”

Exposing your own scheme's capacity ceiling as a callable function is a mature move. It admits that “this method has limits,” and lets users measure where those limits are.

8.7 The Storage Layer and Trust Scores

CREATE TABLE IF NOT EXISTS facts (...)          -- facts, with trust_score and category
CREATE TABLE IF NOT EXISTS entities (...)       -- entities (people, projects, technical terms)
CREATE TABLE IF NOT EXISTS fact_entities (...)  -- fact↔entity many-to-many links
CREATE INDEX IF NOT EXISTS idx_facts_trust    ON facts(trust_score DESC);
CREATE INDEX IF NOT EXISTS idx_facts_category ON facts(category);
CREATE INDEX IF NOT EXISTS idx_entities_name  ON entities(name);
CREATE VIRTUAL TABLE IF NOT EXISTS facts_fts   -- ★ FTS5 full-text index
CREATE TABLE IF NOT EXISTS memory_banks (...)  -- HRR bundle vectors aggregated per category

hermes-agent/plugins/memory/holographic/store.py

class MemoryStore:
    def add_fact(...)
    def search_facts(...)
    def update_fact(...)
    def remove_fact(fact_id: int) -> bool
    def list_facts(...)
    def record_feedback(self, fact_id: int, helpful: bool) -> dict     # ★ feedback loop
    def _extract_entities(self, text: str) -> list[str]
    def _resolve_entity(self, name: str) -> int
    def _link_fact_entity(self, fact_id: int, entity_id: int) -> None
    def _compute_hrr_vector(self, fact_id: int, content: str) -> None
    def _rebuild_bank(self, category: str) -> None
    def rebuild_all_vectors(self, dim: int | None = None) -> int
    @classmethod
    def release_all_under(cls, directory) -> int
    def close(self) -> None
    def __enter__ / __exit__       # supports the with statement

The existence of rebuild_all_vectors(dim) is also worth noting: if you want to change the vector dimension (say, from 1024 up to 4096), the whole database has to be recomputed. SHA-256 encoding is deterministic and immune to model versions, but the dimension is a parameter — change it and you still recompute. This function turns that into a single explicit, controlled operation.

8.8 The SQLite State Layer

Beyond memory, there is a larger state store:

The existence of hermes_state_portability.py is where the “not tied to your laptop” claim becomes real: you try it on your local machine, like it, and want to move it to a cloud server — session history, memory, and configuration all have to move over as a whole.

And the session_search tool (on the core tool list) lets the model search its own past conversations — matching the README's line, “searches its own past conversations.” It relies on the FTS5 index in hermes_state_search.py.

8.9 Summing Up the Division of Labor Among Three Kinds of Memory

9 · The Plugin System

plugins/, 351 files. This chapter covers how third parties extend the system without touching core code.

9.1 Three Discovery Sources

~/.hermes/plugins/     user-level    — applies to every project on this machine
./.hermes/plugins/     project-level — travels with the repo, shared by the team
pip entry points       package-level — pip install a package and it takes effect automatically

“pip entry points” are a standard Python mechanism: a package declares in its own metadata “I provide this kind of plugin,” and after installation the framework discovers it automatically, with no manual registration by the user.

9.2 What a Plugin Can Provide

plugins/
├── platforms/          22 chat platform adapters        → chapter 1
├── memory/             8 memory backends                → chapter 8
├── context_engine/     context engines                  → chapter 7
├── model-providers/    model providers                  → chapter 11
├── cron_providers/     scheduled-task providers         → chapter 12
├── kanban/             kanban collaboration             → chapter 10
├── browser/            browser automation
├── image_gen/          image generation
├── video_gen/          video generation
├── observability/      observability
├── dashboard_auth/     dashboard authentication
├── security-guidance/  security guidance
├── google_meet/        meeting integration
├── spotify/            music
├── teams_pipeline/     Teams pipeline
├── disk-cleanup/       disk cleanup
├── hermes-achievements/ achievement system
├── web/                web-related
├── plugin_storage.py   ★ persistent storage for plugins
└── plugin_utils.py     ★ plugin utility functions

Through a “context API,” a plugin registers three kinds of things with the system: tools, hooks, and CLI subcommands.

9.3 The Most Important Design Decision: “Stackable Capabilities” vs. “Mutually Exclusive Strategies”

Two places in the source make this constraint explicit:

// Context engine (chapter 7)
“Selection is config-driven: `context.engine` in config.yaml.
  Default is "compressor" (the built-in). Only one engine is active.”

// Memory provider (chapter 8)
“The MemoryManager enforces a one-external-provider limit to prevent
  tool schema bloat and conflicting memory backends.
  Only one external provider runs at a time.”

What happens if you don't make this distinction

9.4 Plugin Storage

plugins/plugin_storage.py

Plugins need to persist their own data (configuration, caches, state). The system provides a unified storage abstraction rather than letting each plugin decide where to write.

This solves three problems:

• Unified paths — backup, cleanup, and migration all have a single entry point (echoing backup_paths() from chapter 8)
• Isolation — plugins can't see each other's data
• Cleanup — uninstalling a plugin can remove all of its data cleanly

9.5 How Plugins Tie into Toolsets

Recall the toolset resolution functions from chapter 4:

def _get_plugin_toolset_names() -> Set[str]        # toolsets provided by plugins
def _get_registry_toolset_aliases() -> Dict[str, str]
def resolve_toolset(name, visited=None, *, include_registry: bool = True)

A plugin doesn't just “register a few tools”; it can register an entire toolset. That way a user can write toolsets: [my_plugin_set] in their config to enable everything the plugin offers, without listing tool names one by one.

That include_registry parameter tells you something: the system distinguishes “built-in toolsets” from “toolsets in the registry (including plugins')”, and in some scenarios it can resolve only the built-in ones — presumably so things still work before plugins have finished loading, or to exclude third-party tools in security-sensitive contexts.

9.6 Plugin Hooks

Plugins can hook into several key points in the system:

The permission gap between pre_llm_call and select_context

9.7 MCP: The Other Extension Path

Besides plugins, Hermes also supports MCP (Model Context Protocol) — an open standard for connecting agents to external tool services.

tools/mcp_tool.py       378 KB    MCP client
mcp_serve.py            38 KB     ★ exposes Hermes itself as an MCP server
optional-mcps/          65 files  built-in optional MCP servers

The mcp_serve.py entry deserves attention: Hermes can expose itself as an MCP server. In other words, another agent can call Hermes as a tool — which makes “agents calling agents” possible.

9.8 The Overall Shape of This Extension System

10 · Delegation and Multi-Agent

tools/delegate_tool.py, 5,071 lines. This is the longest single tool file in Hermes — longer than the core of the entire approval system. This chapter covers how one agent sends another agent off to do work.

10.1 Why Delegation Is Needed

10.2 The Depth Limit: One Level Only

MAX_DEPTH = 1

This one line is the single most important constant in the whole multi-agent system. It means: the main agent may spawn subagents, but a subagent may not spawn grandchild agents.

What happens without a depth limit

10.3 Concurrency Limits

_DEFAULT_MAX_CONCURRENT_CHILDREN = 10
_RECENT_SUBAGENTS_CAP = 200

Together with MAX_DEPTH = 1, these two numbers lock the resource footprint of the whole multi-agent system into a predictable range: at any moment, at most 1 + 10 = 11 agents are running, and the history holds at most 200 records.

10.4 Tool Restrictions on Subagents

DELEGATE_BLOCKED_TOOLS

Subagents cannot use certain tools. The most important rule: a subagent cannot call the delegate tool — this is MAX_DEPTH = 1 enforced at the tool layer.

10.5 Approval Policy for Subagents

def _subagent_auto_deny(...)
def _subagent_auto_approve(...)

There is a problem here that has to be solved: when a running subagent asks for approval, who approves?

10.6 In-Flight Control

Subagents aren't “fire and forget.” There are three control interfaces:

def interrupt_subagent(...)    # interrupt a specific subagent
def steer_subagent(...)        # inject an instruction into a running subagent
def set_spawn_paused(...)      # pause/resume spawning of new subagents

10.7 The Lineage Check

def _is_descendant_of(..., max_hops: int = 8)

“Determine whether agent A is a descendant of agent B.” Uses:

• When interrupting an agent, interrupt all of its descendants along with it
• When tallying cost, charge the descendants' spending to their ancestor
• Permission checks: some operations are only allowed on your own descendants

That max_hops = 8 is defensive. Given MAX_DEPTH = 1, in theory you only ever need to check 1 hop. Setting it to 8 is for:

• Compatibility with a depth limit that might be relaxed in the future
• More importantly: if a cycle ever shows up in the data (A's parent is B, B's parent is A), this cap guarantees the function returns instead of looping forever

10.8 Kanban: Collaboration Between Agents

plugins/kanban/ offers a different multi-agent model — not “hand it down and wait for the result,” but “share one task board.”

kanban_create_task       create a task
kanban_claim_task        claim a task
kanban_update_task       update progress
kanban_complete_task     complete a task
kanban_list_tasks        view the task list
kanban_heartbeat         ★ heartbeat

Why kanban_heartbeat has to exist

10.9 Why the Delegation System Is 5,071 Lines

Back to the number from the top. The core logic that actually “spawns a subagent” probably needs 200 lines. What are the other 4,800 doing?

11 · Model Providers and the Credential Pool

agent/credential_pool.py + plugins/model-providers/. This chapter covers how the system deals with multiple model providers, and what happens when an API key runs dry.

11.1 Why You Can't Support Just One

11.2 The Provider Adapter Roster

agent/providers/
├── anthropic.py           Anthropic's official API
├── bedrock.py             AWS Bedrock (calling Claude inside your own AWS account)
├── vertex.py              Google Cloud Vertex AI (calling Claude inside GCP)
├── azure.py               Azure OpenAI
├── gemini_native.py       Google Gemini's native interface
└── codex_responses.py     OpenAI Codex's responses interface

11.3 The Credential Pool: The Core Mechanism

agent/credential_pool.py

"""Persistent multi-credential pool for same-provider failover."""

In plain terms: “a persistent pool of multiple credentials, for failover within a single provider.” Taking it word by word:

Why it's needed

11.4 PooledCredential: The State of a Single Credential

class PooledCredential:
    ...
    _exhausted_ttl        # how long the "exhausted" state lives
    priority              # priority ordering

_exhausted_ttl: “how long to cool down” depends on the HTTP status code

TTL = Time To Live. Here it means “after this key is marked unusable, how long until we try it again.”

The key design decision: the cooldown isn't fixed; it's determined by the error code the API returned.

priority: priority ordering

Credentials aren't equal. Typical reasons to rank them:

• Cost — some are flat-rate subscriptions (marginal cost zero), others are pay-as-you-go. Use the flat-rate ones first
• Quota — some accounts have high limits; others are small backup accounts
• Speed — some accounts sit on a higher service tier

So the credential selection logic is: from the available credentials, take the first by priority. Unavailable ones (in cooldown) are skipped outright.

11.5 Why “Persistent” Is Necessary

11.6 How It Works with Other Mechanisms

With the budget gate from chapter 3

The budget gate governs “how much has this conversation turn cost”; the credential pool governs “which key to spend with.” The two are orthogonal: the budget gate decides “can we still spend,” the credential pool decides “which pocket to pay from.”

With the fallback from chapter 3

Recall chapter 3: when the model returns an error, the system tries to fall back to a backup model. Now the complete failure-handling chain comes into view:

11.7 How Deep the Provider Abstraction Should Go

This is the decision most often gotten wrong when designing multi-provider support.

12 · Scheduled Tasks (Cron)

cron/, 14 files, of which scheduler.py is 367 KB. This chapter covers letting the agent run on its own when nobody is around — and the whole new class of problems that brings.

12.1 What “cron” Is

cron is the Unix scheduled-task tool; the name comes from the Greek chronos (time). At its heart is an expression format:

0 9 * * 1-5      9:00 a.m., Monday through Friday
*/15 * * * *     every 15 minutes
0 0 1 * *        midnight on the 1st of every month

Field order: minute hour day-of-month month day-of-week

12.2 Scenarios for Scheduled Agents

12.3 The Single Most Important Class: CronPromptInjectionBlocked

class CronPromptInjectionBlocked(...)

“Prompt injection” is the central security threat to agent systems. Let's pin down what it is with a concrete example.

Why the scheduled setting is especially dangerous

12.4 Narrowing the Toolset for Scheduled Tasks

def _resolve_cron_disabled_toolsets(...)

Echoing chapter 4: when a scheduled task runs, certain toolsets are disabled.

This is the second layer of defense. Even if injection detection is bypassed, a hijacked agent can't perform the most dangerous operations — because those tools simply aren't on its tool list.

12.5 Failure Handling

def _failure_streak_nudge(...)          # nudge on consecutive failures
def _upsert_incident_for_failure(...)   # create/update an incident record for a failure

_failure_streak_nudge: the nudge on consecutive failures

The word “streak” is the key: it counts consecutive failures, and one success resets it. That way sporadic failures never accumulate into an alert, while a persistent fault hits the threshold quickly.

_upsert_incident_for_failure: deduplicating incident records

“upsert” = update + insert, meaning “update if it exists, insert if it doesn't.”

12.6 Preventing Duplicate Runs

def try_register_running_job(...)

The try_ in the function name is the key: “try to register” — if an identical job is already running, registration fails and this run is skipped.

One more detail: this registration record must be persistent and carry an expiry.

• Persistent — because the scheduler may be multi-process, and an in-memory flag is invisible to other processes
• With an expiry — if the task process crashes and the registration record isn't cleaned up, that task will never run again. There has to be a timeout that releases the lock automatically (the same problem as the kanban heartbeat in chapter 10)

12.7 Why scheduler.py Is 367 KB

“Run tasks on a schedule” sounds like a while True: sleep(); run() affair. What are 367 KB doing?

12.8 Where Scheduled Tasks Sit in the Overall Architecture

13 · The Skill System

81 SKILL.md files, spread across 15 categories. skills_hub.py is 4,956 lines. This chapter covers how to teach an agent, using plain text, to do something it didn't know how to do.

13.1 What a Skill Is

A skill is one Markdown file. No code, no compilation, no registration.

---
name: deploy-to-staging
description: Deploy the current branch to staging and verify the health check
version: 1.2.0
author: platform-team
license: MIT
platforms: [slack, cli]
metadata:
  hermes:
    tags: [deploy, ci, infra]
related_skills: [rollback-deploy, check-service-health]
---

# Deploy to staging

## Pre-flight checks
1. Confirm CI is all green on the current branch: `gh pr checks`
2. Confirm there are no uncommitted changes: `git status --porcelain`

## Deployment steps
1. Tag: `git tag staging-$(date +%Y%m%d-%H%M%S)`
2. Push: `git push origin --tags`
3. Wait for the deploy pipeline: `gh run watch`

## Verification
- Hit https://staging.example.com/health; it should return 200
- If it hasn't gone green within 5 minutes, run the rollback-deploy skill

13.2 The Front Matter, Field by Field

The part between the --- markers at the top of the file is called “front matter”: structured information in YAML format.

13.3 Progressive Disclosure: The Core Mechanism of the Skill System

How much text is it if all 81 skills are expanded? At 3 KB each, that's 243 KB ≈ 60,000 tokens.

The fix: keep only the “catalog” resident, and load contents on demand.

13.4 The Infrastructure Around Skills

A skill itself is plain text, but a whole engineering apparatus surrounds it:

skills_hub.py          4,956 lines   loading, retrieval, and execution orchestration of skills
skill_ledger.py                      ★ skill ledger
skill_provenance.py                  ★ provenance tracking
skill_usage.py                       ★ usage statistics
skill_linter.py                      ★ format checking
skills_guard.py                      ★ security guard
skills_sync.py                       ★ sync

skill_provenance.py: provenance tracking

skills_guard.py: the security guard

Runs security checks before a skill is loaded or executed. These may include:

• Whether the skill's content contains suspicious instruction patterns (same lineage as chapter 12's injection detection)
• Whether the tools the skill wants to use are allowed in the current context
• Whether the source is trusted (working together with provenance)

skill_linter.py: format checking

A “linter” is the general term for a code-style checker. The skill linter checks:

• Whether any required front-matter fields are missing
• Whether the skills referenced in related_skills exist
• Whether the description is too short or too vague
• Whether the format follows the spec

Why a linter is needed: skills are written by people, and people make mistakes. Misspell the description field name and that skill will never be matched — and nothing errors out; it just “mysteriously doesn't work.” The linter turns that kind of silent failure into an explicit error.

skill_usage.py: usage statistics

Records which skills were used, how many times, and with what success rate. Uses:

• Find skills that have never been used — either the description is poorly written (never matches), or nobody needs it (delete it)
• Find skills that fail often — the steps are out of date, the environment has changed
• Find high-frequency skills — worth investing effort to optimize, or worth turning into a real tool

skill_ledger.py and skills_sync.py

The ledger records the complete inventory of skills and their state (enabled/disabled, version, origin). Sync keeps skills consistent across multiple locations — for example, pulling the team's skill library from a shared repository.

13.5 Skills vs. Tools vs. Plugins

13.6 An Implicit Design in the Skill System: Composability

The related_skills field, plus references inside skill bodies like “run the rollback-deploy skill,” form a web of relationships between skills.

13.7 The 15 Skill Categories

The 81 skills are spread across 15 categories. The categories themselves reflect the range of work the agent is expected to take on:

This distribution shows what the skill system is really for: specializing a general-purpose agent into “this team's engineering assistant.” The model itself is generic; the skill library is team-specific. The same model + a different skill library = a completely different assistant.

13.8 Looking Back Across the Book: The Overall Shape of Hermes