What is AGENTS.md?

Hermes automatically discovers and loads context files that shape how it behaves in a given project. AGENTS.md is the primary one: a Markdown file that tells the agent everything specific to this repo.

What goes in it

• Architecture — frontend/backend frameworks, the database, how things fit.
• Conventions — TypeScript strictness, PEP 8, the shape of your API responses.
• Warnings — “never edit migration files directly”, and other landmines.
• Key paths and ports — where things live and how to run them.

Where it lives, and how it’s found

AGENTS.md sits in your project root (and optionally subdirectories) — not in ~/.hermes. At startup Hermes walks up to the git root to find it and loads it into the system prompt. As the agent moves into subfolders during a session, it progressively discovers any deeper AGENTS.md files and pulls them in when relevant.

The loading cascade

Only one project-context file is loaded per session — first match wins:

.hermes.md  →  AGENTS.md  →  CLAUDE.md  →  .cursorrules

So AGENTS.md is the common default, and the format is shared across agent tools (Claude Code reads CLAUDE.md, Cursor reads .cursorrules) — same idea, different filename.

AGENTS.md vs SOUL.md

They load independently and do different jobs:

The rule of thumb: if it should follow you everywhere, it’s SOUL.md; if it belongs to a project, it’s AGENTS.md. SOUL.md is always loaded as the identity; AGENTS.md is loaded on top when you’re working in that project.

Why it matters: the agent stops guessing your project’s conventions and starts following them — the single highest-leverage file for getting useful output instead of generic output.

Try it: drop an AGENTS.md into latex-starter/ (open in VS Code at localhost:8080) describing the Flue agent + render tool and the “no Manim” rule, then ask Hermes or Claude Code to extend the app — watch it respect the conventions.

Docs: Hermes — context files.