Project Context Files for Reliable Hermes Work

Context files give Hermes durable project instructions before work begins. They are the right place for architecture, conventions, test commands, release gates, and boundaries that should apply to every relevant task.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files

Discovery and priority

Hermes selects one project context type at startup using this priority: .hermes.md, AGENTS.md, CLAUDE.md, then .cursorrules. A global SOUL.md is loaded independently from the active Hermes home and controls identity and tone rather than project architecture.

Nested AGENTS.md or CLAUDE.md files can be discovered progressively when the agent enters a subdirectory. This lets a monorepo keep frontend, backend, infrastructure, and documentation rules close to the code they govern.

Context-file checklist

• State the project purpose and high-level architecture.
• Name the package manager, runtime, test, lint, and build commands.
• Document public and private boundaries.
• Record files or migrations that must not be edited directly.
• Put subdirectory-specific rules in the relevant subtree.
• Keep instructions concise enough to avoid truncation.
• Use fake examples rather than credentials, customer data, or personal paths.
• Review context files as code because they shape agent behavior.

What not to put there

Do not store secrets, temporary task progress, unstable incident notes, or giant generated references in a context file. Link or read source documents when needed. Long files are truncated according to the configured context-file limit, so the most important rules should be easy to find and free of contradictory history.

Context files are also scanned for suspicious prompt-injection patterns. That safety layer helps, but it does not replace repository review or access control.

Pitfalls

• Maintaining several competing root instruction files and assuming all load.
• Copying the same rule into every subdirectory until versions drift.
• Putting temporary work status into permanent project guidance.
• Mixing personality rules with project architecture.
• Hiding critical test or release commands near the end of an oversized file.
• Treating instructions from an untrusted dependency as authoritative project policy.

Verification steps

1. Start Hermes from the intended project directory.
2. Confirm which root context file was selected.
3. Ask Hermes to summarize the architecture, commands, and boundaries it loaded.
4. Read a file inside one nested subsystem and confirm its local context is discovered.
5. Run the documented narrow test or lint command.
6. Scan the context files for secrets, stale paths, and conflicting instructions.
7. Start a fresh session after edits and confirm the new guidance applies.