Project Context Files

Hermes injects project-level instructions into the system prompt by reading context files from the working directory. The discovery order is first match wins — only one project context source is loaded per session.

File (in priority order)	Discovery	Use when
`.hermes.md` / `HERMES.md`	Walks parents up to the git root, stops at git root	You want hierarchical project rules (root + per-package overrides)
`AGENTS.md` / `agents.md`	Cwd only — subdirectory and parent copies are ignored	You want portable agent instructions that work the same in Hermes, Claude Code, Codex, etc.
`CLAUDE.md` / `claude.md`	Cwd only	Same as AGENTS.md, Claude-flavored
`.cursorrules` / `.cursor/rules/*.mdc`	Cwd only	Migrating from Cursor

SOUL.md (in $HERMES_HOME) is independent and always loaded when present — it sets the agent's identity, not project rules.

Pick the right one

Use .hermes.md when you want Hermes-specific behavior that lives above the cwd (root + subtree), or when you want rules to inherit from a parent directory. The parent walk stops at the git root, so a home-level .hermes.md won't leak into every project (a git repo's root is the boundary).
Use AGENTS.md when the same project will also be worked on by other agents (Codex, Claude Code, OpenCode). Those tools all have their own conventions for AGENTS.md, and the "cwd only" contract keeps the file portable.
Don't put project rules in ~/.hermes/AGENTS.md (or any other home-level location). When Hermes runs with that directory as cwd, the file loads — but only for that one directory. For cross-project context, use SOUL.md (in $HERMES_HOME, identity-only) or install a skill via hermes skills install.

Size and truncation

Each context file is capped at 20,000 characters. Files longer than that get head + tail truncated (the middle is dropped, with a [...truncated...] marker). For large project rules, prefer splitting into multiple skills over cramming one file.

Security

All context files pass through the 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.

Disable for one session

hermes --ignore-rules skips auto-injection of all project context files (.hermes.md, AGENTS.md, CLAUDE.md, .cursorrules) and SOUL.md identity, plus user config, plugins, and MCP servers. Use it to isolate whether a problem is your setup or Hermes itself.

Example: a small `.hermes.md`

# My Project

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

## Build
- Always run `make test` before declaring a change done.
- Use `uv run` for Python, not `pip install`.

## Style
- Prefer `pathlib.Path` over `os.path`.
- No `print()` in production code — use the `logger`.

That file at /home/me/projects/myrepo/.hermes.md is auto-loaded when Hermes runs in any subdirectory of /home/me/projects/myrepo, but not when it runs in /home/me/other-project.

3.2 KiB Raw Blame History