Use your AgentSoul files with Hermes

Hermes reads a SOUL.md for personality and an AGENTS.md for project conventions without any configuration. To use an AgentSoul soul, place your forged soul.md as SOUL.md in your Hermes home folder so it applies to every session, and put the working procedure from agents.md into each project’s AGENTS.md. The result is a consistent voice everywhere and the right rules in each repository.

How Hermes finds its instructions

Hermes discovers context files that sit alongside the code it is working on, including SOUL.md and AGENTS.md, and loads them automatically: if the file is there, it shapes behaviour. A SOUL.md placed in the Hermes home folder seeds a personality across every session — tone, verbosity and what to push back on. A per-project AGENTS.md holds the things you would otherwise re-explain each time: decisions, conventions, preferred libraries. Hermes also offers built-in personality presets per session; a forged soul is a more personal alternative to those.

Mapping four files onto two

AgentSoul produces four files, while Hermes looks for two. The mapping is straightforward:

• SOUL.md: start with your soul.md. Add the agent’s name and a short description of its voice from identity.md, then a few lines from user.md about how you like answers and what the agent may access.
• AGENTS.md: use agents.md as the skeleton — job, role, steps and escalation — then add the project’s own conventions.
• Keep the original four files in a safe folder as the source you edit from.

Step by step

1. In the AgentSoul app, open your soul, tap “Get the four files”, then “Send to computer” and AirDrop, save to Files or email them to yourself.
2. Create SOUL.md in the .hermes folder in your home directory, using soul.md as the base and the merged lines from identity.md and user.md.
3. In a project you use with Hermes, create or open AGENTS.md at the root and add the steps and escalation rule from agents.md.
4. Start a new Hermes session and ask it to describe how it works and what it values.
5. Adjust. If it is too verbose or too cautious for your taste, edit that line in SOUL.md.

Global voice, local conventions

The value of this layering is that personality and procedure change at different speeds. Your soul — temperament, values, the shadow it watches for — changes rarely. Project conventions change often and differ between repositories. Keeping them apart means you can refine your soul once and every project benefits, while each project keeps rules that only make sense there. If you switch between roles, such as a careful reviewer and a brainstorming partner, forge a soul for each and swap SOUL.md before a session.

If the soul does not seem to load

• Check the file name. Hermes looks for SOUL.md in capitals; a file still called soul.md may not be picked up where you expect.
• Check the location. A global soul belongs in the .hermes folder in your home directory, not inside a project subfolder.
• Start a new session. Context files are read when a session begins, so edits made mid-session will not show until the next one.
• Look for competing instructions. A CLAUDE.md or .cursorrules file in the same project that describes a different tone can pull the agent in two directions.
• Ask directly. “What does your SOUL.md say about how you should respond to me?” is a quick way to see what Hermes actually loaded.

Keep it lean

A bloated context file is worse than none, because every line is in every prompt. The AgentSoul files are written to be readable by people, so they explain themselves. For Hermes, keep the essence: a paragraph of character, the ranked values, the shadow, and two or three preferences about how you want to be addressed. And remember the reading behind the soul is an AI-generated hypothesis, not a diagnosis — keep what fits and cut the rest.