Skip to content
vavio

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-prompts where 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.md or an AGENTS.md shadows CLAUDE.md and .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. A SOUL.md you wrote yourself still loads with a warning. A SOUL.md installed 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

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.

More from the Vavio blog: Hermes Agent guides