The Hermes Optimization Guide measures what each agent call actually costs

A runbook for the agent, not a description of it

The distinction the README draws is the whole point of the repository. The official docs tell you everything Hermes can do, and this guide tells you what to do, namely which settings matter, what they cost, what breaks, and the fixes that have been confirmed to work. That is a different genre of document. An official reference describes features in the order they were built, while an operations manual is organised around the decisions an operator actually has to make. The audience that follows from that is people who already have Hermes installed and are now living with the consequences: a developer running it locally, or a team putting it behind a gateway and leaving it running. The repository reinforces this with a routing table at the top of the README, pointing a newcomer at how it works, install and models, pointing a daily user at cost, personality, memory and skills, and pointing someone running it around the clock at security, production, messaging and troubleshooting.

Every number in the guide was measured on an install

The most distinctive part of the guide is that it quotes figures rather than advice, and states where they came from. Where it says something costs 2,311 tokens, that number was measured on a real install. The headline measurement is the fixed prefix that goes out with every model call, which the guide puts at about 13,000 tokens on a default install, with three quarters of that being tool schemas rather than conversation. From there the levers are concrete. Disabling the browser and tts toolsets alone saves about 2,300 tokens on every call, and the size of your always-on instruction file matters just as much: a 32 KB AGENTS.md measured at plus 8,600 tokens per call. Two more figures give the guide its shape. Local models need 64K of context set on the server, because Hermes refuses anything smaller and the default in Ollama is far below that. And anything older than v0.21.2 should be updated, for state.db safety, which is why the update path gets its own lever.

Cache warmth is why /btw and /bg exist

The second group of levers is about not breaking things while making them cheaper. The trap is switching models mid-session, which re-reads the whole conversation at full price and destroys the prompt cache. The alternative the guide recommends is to use the slash commands /btw and /bg, or a subagent, for side work instead. The same logic drives the auxiliary settings. Compression, titles, approvals and the background memory review all run on the main model by default, with auxiliary.* set to auto, and the guidance is to point them at a cheap model, with one exception: leave vision alone if the main model can see images. The same principle is applied to delegation.model and cron.model, so that subagents and scheduled jobs also avoid the expensive model. The through line is that the expensive model is for the work the user is actually waiting on, and everything else is a candidate for a smaller one.

An agent with a shell needs an allowlist

The security chapter is framed as a threat model for an agent with a shell, and the guidance in the README's list of top changes is blunt: lock down who can talk to your bot, use allowlists or DM pairing, and never allow everyone on an agent with a shell. That is a different posture from a chat bot, because a reachable agent can run commands. The messaging chapter covers the surfaces where that risk enters, with the gateway, Telegram end to end, Discord, Slack, WhatsApp and Signal. Production advice follows from the same model. Run the gateway as a service, because cron only fires while the gateway runs, and a user service dies at logout unless lingering is enabled. The production chapter also covers services, Docker, remote backends, backups, state.db care and monitoring, and the guide offers a hardened config as the concrete artefact to copy rather than a list of settings to remember.

The drift guard is the mechanism that keeps the advice current

Here is the part that makes this different from a blog post. The README states that the guide is verified against Hermes Agent v0.21.4, tagged v2026.9.21 and released on 2026-09-21, and that every command, flag, slash command, config key and official docs link in the repository is checked against that release by CI. A separate workflow, the drift guard, opens an issue when Hermes moves, on the stated reasoning that Hermes ships fast. In other words, the repository has an automated way of telling its readers that it may be out of date, rather than leaving them to notice that a flag no longer exists. The version history is handled with the same care: the guide was previously a 30 part v1 and has been rebuilt from scratch, with a CHANGELOG entry mapping every old part to its new chapter and the old files left in git history. The release line is a single tag, v1.4, published on 2026-08-22, and the last push was on 2026-09-24.

What the repository is not

It is worth being explicit about the boundaries, because a guide like this can be mistaken for the project. The code lives in the upstream Hermes Agent repository, and this repository contains no implementation of it. The top level is documentation and supporting files only: a guide directory holding the chapters, a skills directory, a templates directory, a scripts directory, an assets directory, and a CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING and LICENSE file. The skills directory in particular suggests the guide is meant to be used as a set of reusable skills rather than read once, which fits the guide's own argument that the part of an agent that improves with use is its skills. The alternative to following this guide is to follow the official documentation and the defaults, and the difference in approach is specific: the defaults cost you about 13,000 tokens of fixed prefix per call, the official docs do not tell you that, and nothing in the default setup flags the moment the upstream release invalidates the advice you followed.

Editorial conclusion

Adopt this guide if you already run Hermes Agent and want the operational decisions made for you, with measured token numbers rather than intuition, and a security and service chapter you can hand to whoever operates the box. Do not adopt it as a substitute for the upstream project or its official documentation, since this repository contains advice and no code, and the guide itself points readers to the official docs for what the agent can do. Before you follow it, check the verified-against badge against the Hermes version you run, read the drift guard issues to see how quickly the guide tracks upstream moves, and confirm that your deployment matches the assumptions in the security chapter about who can reach the agent.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. OnlyTerp/hermes-optimization-guide on GitHub
4. README
5. Releases