Which instructions does Hermes Agent load for my project?
Hermes Agent builds each new session’s instructions from two independent places. It loads one type of project instruction file found from its working directory: .hermes.md, then AGENTS.md, then CLAUDE.md, then .cursorrules, with the first type found winning. Separately, it loads the profile’s global SOUL.md as its identity. A session that is already running keeps the instructions it started with, so an edited file takes effect in a new chat, after a prompt refresh, or when the conversation is compressed. On Vavio, the same rules apply on a computer that isn’t your laptop.
The order Hermes checks
These rules follow Hermes v0.23.1, commit 3b42157. Project instruction types are tried in this order. The first type with a non-empty file is loaded and the later types are ignored for that session.
| Priority | File | Where Hermes looks at session start |
|---|---|---|
| 1 | .hermes.md or HERMES.md |
The working directory, then each parent up to the git root. The nearest file wins. |
| 2 | AGENTS.override.md, AGENTS.md or agents.md |
Every directory from the git root down to the working directory. Each directory contributes one file, and an override beats the AGENTS.md beside it. |
| 3 | CLAUDE.md or claude.md |
The working directory only. |
| 4 | .cursorrules and .cursor/rules/*.mdc |
The working directory only. All non-empty files are combined. |
Outside a git repository, only the working directory itself is checked; Hermes doesn’t walk up into parent folders such as your home folder.
The most common surprise is a shadowed file. If a project has both AGENTS.md and CLAUDE.md, Hermes loads the AGENTS.md chain and ignores CLAUDE.md. If the nearest .hermes.md or HERMES.md between the working directory and the git root has content, it takes priority over every AGENTS.md.
How the AGENTS.md chain combines
Inside a git repository, Hermes reads the AGENTS.md at the repository root first and then one in each directory down to the working directory. Deeper files appear later, so the most specific guidance comes last. Identical copies along the chain are loaded once.
As Hermes works, it can find more instruction files. When a tool call touches a path inside the working-directory tree, Hermes checks that directory and its parents, up to five levels in all. In each directory it uses the first non-empty file of AGENTS.override.md, AGENTS.md, agents.md, CLAUDE.md, claude.md or .cursorrules. A file it finds is scanned and attached to that tool result, capped at 32,000 characters. Each directory is checked at most once per session, and dependency and build folders such as node_modules and dist are skipped. .hermes.md is not discovered this way; it is a session-start file.
This later discovery is switched off when the working directory is a home folder, or is /home, /root or /workspace or a folder directly inside one of them. If Hermes works from a home folder, start it in a project folder, or rely on the instructions loaded at session start.
What SOUL.md is for
SOUL.md sets the identity, tone and communication style of a Hermes profile. Hermes reads it only from that profile’s home: ~/.hermes/SOUL.md by default, or $HERMES_HOME/SOUL.md for a custom home or named profile. It never comes from a project folder. If the file is empty, Hermes uses its built-in default identity. If it is missing, Hermes writes a starter SOUL.md containing that same default text.
Because it is global to the profile, SOUL.md applies in every project that profile works on. Scheduled jobs also keep it: in v0.23.1, a cron job loads SOUL.md and loads project instruction files only when the job has a configured working directory.
Where should a rule go?
| You want | Put it in | Why |
|---|---|---|
| A tone or working style for everything this Hermes does | SOUL.md in the profile home |
Loaded as the identity for every session of that profile |
| Conventions for one project, shared with collaborators | AGENTS.md in the repository |
Loaded when Hermes works from that project, and readable by other tools |
| Your own variation on a shared project’s rules | AGENTS.override.md next to the committed file, usually gitignored |
Replaces the committed AGENTS.md for that directory without editing it |
| Different rules for one part of a project | A nested AGENTS.md in that directory |
Added to the chain, or found when Hermes works there |
| A short fact or preference Hermes should recall | Built-in memory | See what Hermes remembers after a new chat |
| A repeatable procedure used only sometimes | A skill | Loaded when relevant instead of on every turn; see skills, tools and plugins |
Every instruction file occupies context on every turn. A file over the size limit is cut to its beginning and end, with a marker in the middle. By default the limit grows with the model’s context window, from 20,000 up to 500,000 characters; context_file_max_chars in config.yaml sets it explicitly.
Check what Hermes actually loaded
Run /context in a session. In v0.23.1, on the command line and messaging platforms, its output ends with a Context files list showing each candidate file, an estimated token count and its status: loaded, truncated, flagged (loaded with an injection warning), shadowed by a higher-priority type, blocked, empty, unreadable or suppressed. It covers files loaded when the session started, not files found later in subfolders. That answers “why is my CLAUDE.md ignored?” without guessing. We have not run this check on a Vavio computer for this article; it is a documented Hermes command.
If an edited file seems to have no effect, check these cases:
- The session started before the edit. A running session reuses the instructions it was built with, even across a gateway restart, until its conversation is compressed. Start a new chat, or run
hermes sessions refresh-promptswhere you have the Hermes command line, so the session rebuilds on its next turn. - A different working directory. Project files are found from the directory Hermes is working in. A gateway usually uses its configured
terminal.cwd, which may not be the folder you edited. - A higher-priority file. A
.hermes.mdor anAGENTS.mdshadowsCLAUDE.mdand.cursorrules. - A different profile. Each profile has its own home and its own
SOUL.md. - A blocked file. Hermes scans project instruction files for prompt-injection patterns such as “ignore previous instructions” and replaces a matching file with a
[BLOCKED: ...]notice. ASOUL.mdyou wrote yourself still loads with a warning. ASOUL.mdinstalled by a profile distribution is blocked like a project file.
Asking Hermes to change its own instructions
Hermes protects files named AGENTS.md, CLAUDE.md, SOUL.md and .cursorrules, in any capitalisation, when they are outside its own home. By default, when its file-editing tools try to write one, Hermes asks you to approve that single write, even if auto-approval is on. If nobody is available to approve, the write fails. .hermes.md, HERMES.md, AGENTS.override.md and .cursor/rules/*.mdc are not covered unless you add them to security.protected_instruction_extra_patterns.
Files in Hermes’s own home, including the profile’s SOUL.md, are not covered by this check, so Hermes can edit its own SOUL.md without asking. Review changes to it yourself: like project instruction files, it steers every later session.
What managed hosting changes
Vavio supplies a managed Hermes computer for $14.99 per month, with model usage billed separately. Its MCP server and CLI let a supported assistant help manage the setup. Your projects and Hermes’s profile home live on that computer, so the instruction files Hermes reads are the ones there, not the copies on your laptop. Hosting doesn’t change the loading order above.
If you run Hermes on your own machine, the same rules apply there. If you want Hermes working away from your laptop without looking after its server, compare the current hosting offer. Either way, put a lasting style in SOUL.md, project rules in AGENTS.md, and check /context before assuming a file was read.
Sources
- Hermes v0.23.1 context-file discovery and loading, checked 12 November 2026
- Hermes v0.23.1 subdirectory instruction discovery, checked 12 November 2026
- Hermes v0.23.1 system prompt assembly, checked 12 November 2026
- Hermes v0.23.1 protected instruction-file writes, checked 12 November 2026
- Hermes v0.23.1 compression rebuilds the system prompt, checked 12 November 2026
- Hermes v0.23.1 context files documentation, checked 12 November 2026
- Hermes v0.23.1 refreshing prompts in running sessions, checked 12 November 2026
- Vavio hosting and limits, checked 12 November 2026
Written by Vavio with AI assistance and checked against official Hermes documentation and pinned v0.23.1 source. This is a source review, not a live instruction trial.