Project Context Files

Every time you start a new Hermes session in a project, you re-explain the same things: which test runner to use, where the config files live, the naming conventions, which Python environment to activate. Context files solve this by injecting project-specific instructions into the system prompt automatically, so Hermes walks into a new session already knowing your environment.

What you'll learn

• .hermes.md walks up the directory tree to the git root, loading rules that apply to the entire project
• AGENTS.md and CLAUDE.md are cwd-only, they're portable across different agent tools, not just Hermes
• SOUL.md sets Hermes's global identity and personality, independent of any project
• All context files are capped at 20,000 characters and pass through a security scanner before reaching the model

The problem

You start a new Hermes session in your project. You say "run the tests." Hermes tries pytest but your project uses tox. You correct it. Next session, same thing. You're spending the first few messages of every conversation re-establishing context that never changes.

Context files are the fix. Write down the project rules once, in a file, and Hermes loads them automatically at session start. No more re-explaining the build system, the linting rules, or the Python environment.

Options & when to use each

File	Discovery	Use when
.hermes.md / HERMES.md	Walks parents up to the git root; stops at git root	You want Hermes-specific rules that apply to the whole project, inherited by subdirectories
AGENTS.md / agents.md	Cwd only, subdirectory and parent copies are ignored	The same project is worked on by multiple agents (Claude Code, Codex, OpenCode). Portable across tools
CLAUDE.md / claude.md	Cwd only	Same as AGENTS.md, Claude-flavored
.cursorrules / .cursor/rules/*.mdc	Cwd only	Migrating from Cursor
SOUL.md	$HERMES_HOME (usually ~/.hermes/)	Sets the agent's identity, not project rules. Always loaded when present

The discovery order is first match wins , only one project context source is loaded per session. If you have both .hermes.md and AGENTS.md in the same directory, .hermes.md wins.

Build it

Step 1: Create a .hermes.md for your project

In the root of your git repo, create .hermes.md:

# My Project

Hermes: when working in this repo, follow these rules.

## Build
- Run `make test` before declaring a change done.
- Use `uv run` for Python, not `pip install`.
- The virtual environment is at `.venv/` ,  activate it before running Python.

## Style
- Prefer `pathlib.Path` over `os.path`.
- No `print()` in production code, use the `logger` module.
- Type hints are required on all function signatures.

## Conventions
- Config files live in `config/`, not the project root.
- Database migrations are managed by Alembic, run `alembic upgrade head` after schema changes.
- Secrets are in `.env` ,  never commit them, never read them aloud.

Step 2: Verify it loads

To verify that your project-specific rules are successfully detected and injected, navigate into the project directory and run a test query query:

cd /path/to/your/project
hermes chat -q "What build system does this project use?"

If Hermes answers with make test (from your .hermes.md), the context file is loading correctly. If it guesses or says it doesn't know, the file isn't being discovered. Check that:

• The file is in the git root (or a parent directory up to the git root)
• The file is named .hermes.md (not hermes.md or HERMES.md.txt)
• You're running Hermes from within the project directory (or a subdirectory)

Step 3: Create a SOUL.md for global identity

Write your global personality and system role instructions into your user-level configuration file ~/.hermes/SOUL.md:

You are a senior infrastructure engineer. You prefer direct, technical answers
without hedging. When you're unsure about a command, you say so and suggest
verification steps rather than guessing.

You work primarily in Python and shell. You default to uv for Python package
management and prefer systemd for service management.

SOUL.md is independent of project context, it's loaded for every session, in every directory, on every platform. Use it for identity and communication style, not project-specific rules.

Step 4: Understand the security scanning

Every context file passes through a threat-pattern scanner before reaching the system prompt. Patterns matching prompt injection or promptware are replaced with a [BLOCKED: ...] placeholder. This means an AGENTS.md containing obvious injection attempts won't reach the model, the scanner blocks the content, not the file, so the rest of the file still loads.

This is automatic. You don't need to configure it. It's worth knowing about because if you ever write something in a context file that looks like an injection attempt (even as a documented example of what not to do), the scanner will block it.

Step 5: Disable context files for one session

To start a clean, uncustomized session where all local rules files and SOUL profiles are ignored, use the ignore flag:

hermes --ignore-rules

This skips auto-injection of all project context files and SOUL.md, plus user config, plugins, and MCP servers. Use it to isolate whether a problem is your setup or Hermes itself.

What goes wrong

Mistake	How you notice it	The fix
.hermes.md in a subdirectory doesn't load	Hermes ignores rules you wrote in a subdirectory	.hermes.md walks up from cwd to git root. If the file is in a subdirectory below cwd, Hermes won't find it. Put it in the git root, or cd to the subdirectory before launching Hermes
AGENTS.md in the home directory leaks into every session	Hermes references project-specific rules in unrelated directories	AGENTS.md is cwd-only, it only loads when you launch Hermes from that specific directory. If you see it loading everywhere, you're launching Hermes from the directory where it lives. Move it to the project directory instead
Context file is too long and gets truncated	Hermes misses rules at the end of a long file	The cap is 20,000 characters. Files longer than that get head+tail truncated (the middle is dropped). Split large rule sets into multiple skills instead of cramming everything into one file
Context file mentions a tool that doesn't work	Hermes references a command that fails	The scanner only blocks injection patterns, not invalid commands. If your context file says "run frobnicate to build," Hermes will try to run frobnicate and fail. Verify every command in your context file actually works

Confirm it worked

To execute a complete sanity check on context resolution, create a temporary rule file and query the agent to confirm it obeys the custom instruction:

# 1. Create a test .hermes.md with a unique instruction:
echo '# Test
Hermes: when asked about your favorite color, say "chartreuse."' > .hermes.md

# 2. Verify it loads:
hermes chat -q "What is your favorite color?"

# 3. Expected: "chartreuse" (from the context file)
# If it says anything else, the file isn't loading

# 4. Clean up:
rm .hermes.md

Next: Day 2 , Memory, Skills & Self-Improvement , the memory system that keeps context cheap across sessions, and the skill system that lets Hermes learn from experience.