Hermes Agent prompting

Checked against the Nous Research documentation on 2 August 2026, the day before the v0.20.0 Herald release of 3 August 2026 added real-time voice with barge-in, on-device wake words and Agent-to-Agent support. Hermes Agent ships often, so verify any flag against hermes --help before you rely on it.

Hermes Agent rewards a particular way of working, and it is not the way most people arrive with. Chat assistants train you to type a short request and iterate. An agent with terminal access, a file system, a memory and a library of its own procedures wants something different: a full brief the first time, then room to work.

This guide covers the commands worth knowing on day one, the three files that shape every session before you type anything, how to stop an agent folding the moment you disagree with it, when a piece of work should become a skill, and how to keep a long session from becoming an expensive one.

The first hour

Installation is one line, and the setup wizard covers the rest. If you are using Nous Portal, a single sign-in covers a model and the bundled tools rather than four separate accounts.

Write the brief, not the request

The single biggest lever is the first message. Every clarification round costs a turn, and a turn costs tokens on both sides of it.

Give the agent the file paths, the exact error, the expected behaviour and the constraint you care about, all at once. Paste the whole traceback rather than describing it. Then stop, and let it work.

The second lever is restraint. Telling an agent which file to open and which line to read wastes the capability you are paying for: it has file search, a terminal and code execution, and it is better at finding things than you are at describing where they are. Describe the outcome and the constraints, then let it choose the route.

The anatomy of a brief that works

The three files that shape every session

Anything you find yourself repeating belongs in a file rather than in a message.

~/.hermes/SOUL.md, the identity

This is the first thing in the system prompt and it defines who the agent is. Keep it to voice and standing preferences, stable across every project. It is created for you with a default, and once you have edited it, Hermes never overwrites it.

# Soul

You are a senior backend engineer. Be terse and direct.
Skip explanations unless asked. Prefer one-liners over verbose solutions.
Always consider error handling and edge cases.

AGENTS.md, the project’s rules

This lives in the project root, is read at session start, and carries the things a new colleague would need on day one: the stack, the conventions, the things never to do. Keep it short, because it is paid for on every message.

# Project Context

- FastAPI backend with SQLAlchemy ORM
- Always use async/await for database operations
- Tests go in tests/ and use pytest-asyncio
- Never commit .env files

If you already keep .cursorrules or .cursor/rules/*.mdc files, Hermes reads those too. There is no need to duplicate them.

Memory, which is deliberately small

MEMORY.md holds what the agent has worked out about your environment, capped at roughly 2,200 characters. USER.md holds your preferences and communication style, capped at roughly 1,375. The caps are enforced: a write that would overflow returns an error rather than silently dropping an entry, so the agent has to consolidate instead of hoarding.

Feed it deliberately. After a good session, “remember this for next time” works, but a specific instruction works better: “save to memory that our CI uses GitHub Actions with the deploy.yml workflow”. When it feels stale, “clean up your memory” triggers a consolidation pass.

One behaviour to know, because it looks like a bug: memory is rendered into the system prompt as a frozen block at session start, to preserve the prefix cache. Something the agent saves mid-session is on disk immediately but does not appear in its own prompt until the next session.

Stopping it agreeing with everything

The failure people complain about most is the assistant that caves the instant you push back. Nous Research’s reading of it: this is not loyalty but reward hacking. The agreeable reply keeps you typing, and typing is what the model’s training rewards.

The way that you get out of sycophancy is the same way you get a human being out of a bad habit or a routine: by introducing new context, by introducing new distribution.

In practice that is three moves, in order:

1. SetChange the personality/personality overlays a session-level shift on top of SOUL.md. Fourteen presets ship, including concise, technical, teacher and critic-flavoured modes, and you can define your own under agent.personalities in ~/.hermes/config.yaml.
2. AttackSpawn a critic with no historyAfter each pass, ask for a fresh subagent whose only job is to tear the work down. It has not sat through the conversation that produced the answer, so it has nothing to be agreeable about.
3. KeepSave the critique that landedTurn the review step into a skill. Every later session starts with the habit already installed, which is what makes the improvement stick rather than needing to be re-established each time.

The same logic applies to everything else you want changed: give the model examples of the behaviour you want, or get it to produce some and then save them. In-context learning moves an agent further than any amount of firmer instruction.

When to make a skill

The rule of thumb from the documentation is a recurring task of five or more steps. The moment to act is immediately after it has gone well:

save what you just did as a skill called deploy-staging

Next time, /deploy-staging runs it. Skills stack, so /deploy-staging /slack-notify ship the hotfix composes two of them in one message, and hermes bundles create groups several under a single command when a combination becomes routine.

You do not have to author them by hand either. /learn will read a directory, a URL or a described procedure and write a standards-compliant skill from it, which is the fastest route to teaching an agent an unfamiliar tool or code base.

Keeping a long session cheap

Four habits do most of the work here.

Do not break the prompt cache. A stable system prompt means later messages hit the cache and cost a fraction of the first. An explicit /model switch, a provider fallback or a credential rotation all invalidate it, so choose the model for a piece of work before you start rather than halfway through.

Compress before you hit the wall. When replies slow down, /compress summarises the history while keeping the important context. /usage shows where you stand; /insights gives thirty days of pattern.

Delegate anything parallel. Ask it to use delegate_task for subtasks that do not depend on each other. Each subagent keeps its own context and only the summary comes back, so the main conversation stays small.

Ask for a script, not a hundred tool calls. “Write a Python script to rename all .jpeg files to .jpg, then run it” is faster and cheaper than watching an agent rename files one at a time. Batch work belongs in execute_code.

Work that happens without you

Once a workflow is reliable, stop typing it. hermes cron create turns a prompt into a scheduled job with its own skills loaded, hermes webhook subscribe wakes the agent on an external event, and /sethome in a Telegram or Discord chat sets where scheduled output lands. hermes kanban gives the whole arrangement a board that humans and agent profiles can both work from.

Proactive behaviour beyond that is a comfort decision rather than a setting. An agent with your calendar, an account and standing permission to cover your gaps will start acting on them; an agent that must ask first will ask first. Decide which you want before you hand over credentials, not after.

The defaults worth leaving alone

Hermes checks commands against dangerous patterns, recursive deletes, SQL drops, piping a download into a shell, and asks before running them. The prompt offers once, session, always and deny. Reach for session rather than always: “always” permanently allowlists a pattern, and the pattern is usually broader than the command you were looking at. hermes approvals can later mine your history into a sensible allowlist proposal, which is a better route to the same convenience.

Two more that are cheap to get right:

• Working on a repository you do not trust? Set TERMINAL_ENV=docker in .env. Inside a container the destructive-command checks are skipped on purpose, because the container has become the boundary.
• Running a messaging bot with terminal access? Never set GATEWAY_ALLOW_ALL_USERS=true. Use GATEWAY_ALLOWED_USERS, or the per-platform lists, and approve people individually with hermes pairing approve.

The --yolo flag exists and bypasses the approval prompts. It is for a sandbox you can throw away, not for your laptop.

When something is wrong

Sources

• Tips and best practices, CLI command reference, skills system, memory system and personality and SOUL.md, Nous Research documentation, checked 2 August 2026.
• Karan Malhotra, co-founder of Nous Research, interviewed by Peter Yang: Hermes Co-Founder on Building an AI Agent That Improves Itself, for the quoted material on sycophancy and in-context learning.

More on the agent itself, its origins and the argument behind its design: Hermes Agent. For the wider field, see the agentic AI hub.