Context Files — Project Manuals

Imagine walking into a new job and finding a well-worn employee handbook on your desk. It tells you the company rules, how to write code, and who to ask when you’re stuck. Hermes Agent’s context files are that handbook — they let the AI read your project’s playbook before it writes a single line.

---

What Manuals Exist?

Hermes automatically looks for several file types, each with its own “jurisdiction”:

File	Purpose	Where It’s Found
.hermes.md / HERMES.md	Highest-priority project instructions	From current dir up to git root
AGENTS.md	Project structure, conventions, architecture	Current dir + subdirectories (on-demand)
CLAUDE.md	Legacy Claude Code instructions (also recognized)	Same as above
SOUL.md	Global “personality” (tone, style)	Only from HERMES_HOME
.cursorrules	Cursor editor coding conventions	Current directory only
.cursor/rules/*.mdc	Cursor rule modules	Current directory only

Key rule: Only one file per category loads (priority: .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules). But SOUL.md always loads independently, acting as the AI’s fixed “persona” in the first position.

---

AGENTS.md: The Most-Used Master Manual

AGENTS.md is the core description file for your project. It tells the AI how your project is organized, what conventions exist, and any special requirements.

The Directory Chain: From Git Root to Current Directory

Say your working directory is packages/webapp/. Hermes will merge and load all levels of AGENTS.md in order:

monorepo/                   (git root)
├── AGENTS.md              ← loaded first (repo-wide rules)
└── packages/
    ├── AGENTS.md          ← loaded second
    └── webapp/
        └── AGENTS.md      ← loaded last (most specific, highest priority)

Deeper files load later, so more specific rules override general ones. Each file is tagged with its source (e.g., ## ../../AGENTS.md), and duplicate content is automatically deduplicated.

Note: If you’re not in a git repo, only the current directory is checked — no upward search — preventing files in /tmp or $HOME from “polluting” unrelated projects.

---

Progressive Discovery: Load Only What You Need

At startup, Hermes puts only the current directory’s AGENTS.md into the system prompt. When the AI enters a subdirectory (say, reading files in frontend/), it discovers and injects that directory’s AGENTS.md in real time:

my-project/
├── AGENTS.md              ← loaded at startup
├── frontend/
│   └── AGENTS.md          ← loaded when reading frontend/ files
├── backend/
│   └── AGENTS.md          ← loaded when reading backend/ files
└── shared/
    └── AGENTS.md          ← loaded when reading shared/ files

Two big benefits:

• No wasted “brain space” — irrelevant instructions don’t eat up the AI’s context window
• Protects prompt caching — avoids frequent refreshes that hurt performance

---

Summary & Practical Tips

Context files are your project’s instruction manual — they let the AI follow your rules without you repeating yourself. Core takeaways:

1. Priority: .hermes.md > AGENTS.md > CLAUDE.md > .cursorrules
2. Merge chain: All levels of AGENTS.md auto-merge inside a git repo
3. On-demand loading: Subdirectory rules only activate when the AI enters that directory

Practical tip: Put a concise AGENTS.md in your project root, covering “project structure + code style + forbidden practices.” For example:

# Project Conventions
- Use TypeScript, no `any`
- Components go in src/components/
- Commit messages use conventional commits
- Test files live in __tests__/ directory

That way, the AI follows your rules on its very first task — saving you time and headaches.