Context files

Context files give Hermes project-specific knowledge, similar to Claude's project knowledge base. They load automatically from your working directory when a session starts, so you stop re-explaining the same project every time.

Which files Hermes reads

Hermes looks for several context files in a fixed priority order, and the first match wins per directory:

File	Purpose	Discovery
.hermes.md / HERMES.md	Hermes-specific project rules (highest priority)	Walks parent dirs up to the git root
AGENTS.md	Portable project instructions, conventions, architecture	Current working directory at startup
CLAUDE.md	Claude Code context (also detected)	Current working directory
.cursorrules / .cursor/rules/*.mdc	Cursor IDE conventions	Current working directory

AGENTS.md is the one I use most: it's the cross-tool standard, so the same file works in Hermes, Claude Code, Codex, and others. Use .hermes.md when you want rules that inherit from a parent directory up to the git root.

SOUL.md is different

SOUL.md is global identity/personality and lives only in ~/.hermes/SOUL.md. Don't put project rules there. See SOUL.md & personality.

How loading works

When you start Hermes from a project directory, it scans for the files above, runs a prompt-injection safety check on the content, truncates anything over context_file_max_chars (default 20,000), and assembles it under a # Project Context header in the system prompt. As the agent navigates into subdirectories during the session, it picks up additional context files it finds along the way.

my-project/
├── AGENTS.md          # loaded automatically at startup
├── src/
│   └── AGENTS.md      # loaded if the agent works in src/
└── README.md

Example AGENTS.md

# Project: hermes-mastery-docs

A VitePress documentation site about Hermes Agent.

## Stack
- VitePress 1.6
- Node.js 22

## Commands
- npm run dev    -> local preview at :5173
- npm run build  -> output in docs/.vitepress/dist

## Conventions
- All content in English
- Sidebar defined in docs/.vitepress/config.mts
- Personal handbook tone, not official docs
- Don't commit without asking

When to use context files vs. memory

Context files	Memory
Project facts and conventions	Personal preferences and learned habits
Checked into git (portable, you write them)	Stored in ~/.hermes/memory/ (agent curates)
Static	Dynamic
Per-project	Cross-project

Disabling context for one session

To check whether a problem is your setup or Hermes itself, skip all auto-injected context (.hermes.md, AGENTS.md, CLAUDE.md, .cursorrules, and SOUL.md):

hermes --ignore-rules

Real use case

I keep an AGENTS.md in each course folder (claude-course/, hermes-course/) so Hermes knows the stack, conventions, and goals without me re-explaining every session. Because it's the cross-tool standard, the same file also works when I open the project in Claude Code or Cursor.

Tips

• Start with one AGENTS.md in the project root. Add per-directory files only when needed.
• Include commands Hermes should know (npm run, git, deploy steps).
• State what not to do (e.g. "don't commit without asking").
• Keep it well under 20,000 characters so nothing gets truncated.

Next: CLI & sessions.