HHermes Explained

Skills

BOOT.md

A user-defined gateway hook pattern that runs instructions from ~/.hermes/BOOT.md at gateway startup.

Importance 3/52 backlinks4 source refs
Concept-specific field plateBOOT.mdhx-graph-context-concept-boot-mdLoading visual preview…
View full-size visual

BOOT.md

What it is

A user-defined gateway hook pattern that runs instructions from ~/.hermes/BOOT.md at gateway startup.

In plain terms

A note taped to a building’s front door for whichever security guard opens up that morning — check the alarm log, note anything odd, then carry on — is roughly what BOOT.md gives Hermes’s gateway. It’s a plain-language checklist a person writes and saves themselves, which a background process reads and runs once every time the gateway restarts, rather than a routine the agent decides on its own to remember.

Why it matters

BOOT.md is not a built-in Hermes startup file. The documented pattern is a user-created gateway hook under ~/.hermes/hooks/boot-md/ that listens for gateway:startup, reads ~/.hermes/BOOT.md, and starts a one-shot AIAgent in a background thread; an empty or missing file returns without doing work. The tutorial handler logs a non-silent final response with logger.info and has no channel-delivery call. Any further side effect or delivery behavior must therefore be added explicitly by the operator’s handler rather than assumed to be a hidden runtime rule.

How it works

When the gateway process starts, HookRegistry.discover_and_load() walks every subdirectory under ~/.hermes/hooks/, and any folder whose HOOK.yaml declares the gateway:startup event gets its handler.py wired in (gateway/hooks.py). The boot-md handler is ordinary Python the operator writes: it reads ~/.hermes/BOOT.md, and its background agent is built using the gateway’s actual resolved model and provider credentials — via helpers like _resolve_gateway_model() and _resolve_runtime_agent_kwargs() — rather than bare defaults, since an unconfigured AIAgent() would fail authentication against any non-default endpoint (gateway/run.py). That credential-matching requirement is exactly why Hermes documents this as a pattern you wire up by hand instead of shipping it as a built-in: a generic built-in hook would have to guess every operator’s provider setup, so the docs hand you the working handler.py to adapt instead.

A concrete example

An operator writes a BOOT.md checklist that asks Hermes to inspect overnight cron failures and scan a deploy log for recent ERROR lines. After the operator installs the documented gateway:startup handler and restarts the gateway, the hook starts a one-shot agent in a background thread. The tutorial handler records up to the first 200 characters of a non-silent final response with logger.info, or logs that there was nothing to report; it does not contain a call that delivers that response to Discord, Slack, or another chat channel.

How it connects

This note belongs to the Skills family. Its closest neighboring concepts are: soul.md, Hooks, Agent Runtime, Personal OS.

Source evidence

  • file:website/docs/user-guide/features/hooks.md#BOOT.md — Explicit Source Map scope boundary: The documentation file is outside the approved Core scope.
  • vendor/hermes-agent/gateway/hooks.py#<file> — Structural Source Map fallback for gateway/hooks.py. A core source file in the Plugin Manager and Hooks structure within Skills and Plugins.
  • vendor/hermes-agent/gateway/run.py:7062-7068#GatewayRunner.start — Verified Source Map evidence for GatewayRunner. At Gateway startup, each adapter message handler is bound to the central _handle_message pipeline. The central handler covers authorization, commands, sessions, context, agent execution, and response delivery; before any await it acquires an active-session lease and creates a run generation.
  • vendor/hermes-agent/run_agent.py:1892-1902#AIAgent._flush_messages_to_session_db — Verified Source Map evidence for AIAgent. AIAgent uses thin forwarding methods to delegate system-prompt construction to agent.system_prompt.build_system_prompt, API kwargs construction to the chat-completion helper, and streaming requests to interruptible_streaming_api_call.

Workflows

  • No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
  • Ten Underused Hermes Features That Reveal Its Real Power