Choose the Right Hermes Context File
Hermes is shaped by several files, but they do not all do the same job. The fastest way to fix “the agent forgot” is to identify whether the information is personality, a durable fact, a project rule, configuration, or a reusable workflow.
Use this routing table
| Need | Best home | Why |
|---|---|---|
| Voice, values, tone, behavioral identity | SOUL.md | Defines how the agent behaves, not factual user history |
| Stable user preferences and durable facts | Profile memory and user-profile files | Keeps long-lived facts separate from procedures |
| Repository architecture, commands, conventions | .hermes.md, HERMES.md, or AGENTS.md | Loads project-specific operating context from the working tree |
| Models, tools, providers, gateway settings | config.yaml | Machine-readable runtime configuration |
| Credentials and local environment secrets | .env or an approved secret source | Keeps secret values out of public instructions and source control |
| Repeatable procedures | A skill's SKILL.md | Makes a workflow discoverable, maintainable, and reusable |
Hermes-specific .hermes.md or HERMES.md project instructions take priority over AGENTS.md when discovered for the same project scope. Nested project context may become relevant as the agent works inside subdirectories.
Separate identity, facts, and procedures
A common mistake is placing everything in SOUL.md. Personality files should not become a dumping ground for build commands, stale task progress, or account details.
Likewise, memory should not hold a deployment runbook. Procedures change differently from personal facts and belong in skills or project documentation where they can be reviewed and updated.
Context-placement checklist
- Is this about how the agent should sound or behave?
- Is it a stable fact that should survive sessions?
- Is it true only inside one repository or subdirectory?
- Is it runtime configuration rather than prose guidance?
- Is it secret material that should never enter a public file?
- Is it a multi-step procedure that deserves a reusable skill?
Common pitfalls
Editing the right file at the wrong scope
A project instruction stored globally can affect unrelated work. A global preference stored only in one repository will disappear elsewhere.
Expecting every edit to change an existing turn
Context is assembled for the running session and may be refreshed through specific runtime paths. When testing a file edit, use a fresh or deliberately refreshed context rather than assuming every in-flight turn rebuilt its prompt.
Duplicating conflicting instructions
If the same rule appears in personality, project context, and a skill with different wording, the agent must resolve unnecessary conflict. Keep one authoritative source and link to it where needed.
Verification steps
- State the fact or instruction in one sentence.
- Classify it using the routing table.
- Search for conflicting copies before adding another.
- Start or refresh a test session in the intended project scope.
- Ask the agent to identify the active instruction and its source.
- Confirm unrelated projects do not inherit project-only rules.
Official reference
See Which File Does What? in the official Hermes documentation.