Context Files: CLAUDE.md, AGENTS.md, and Beyond

Context Files: CLAUDE.md, AGENTS.md, and Beyond

Hermes Agent doesn't just execute your commands — it understands your project through a system of context files that guide its behavior in every session. Instead of repeating the same instructions over and over, you place your preferences in a markdown file, and the agent automatically integrates them into its system prompt.

This article explores Hermes Agent's context file system in depth: supported types, priority hierarchy, progressive subdirectory discovery, and best practices to get the most out of this feature.

What Is a Context File?

A context file is a simple Markdown file placed at the root (or in a subdirectory) of your project. It contains instructions that the agent reads automatically and injects into its system prompt. This allows it to "know" your project without you having to explain it every session.

Specifically, these files can contain:
- The project's technical architecture
- Code and naming conventions
- Build tools, ports, and test commands
- Restrictions and things to never do
- Deployment or environment-specific notes

Supported Context Files

Hermes Agent recognizes several context file formats, each with its origin and priority:

.hermes.md or HERMES.md — Maximum Priority

This is the file dedicated to Hermes Agent. If present at the root of your project (or walked up to the Git root), it is loaded with absolute priority. This is the recommended choice if you exclusively use Hermes Agent on a project.

Where to place it: at the project root or anywhere in the directory tree — Hermes walks up to the Git root to find it.

AGENTS.md — The Multi-Agent Standard

AGENTS.md is the primary default context file. It's designed to be shared across different AI agents (Hermes, Claude Code, Codex, etc.). It describes the project structure, conventions to follow, and special instructions.

Where to place it: at the project root and/or in subdirectories for local instructions.

Concrete example:

# Project Context

Next.js 14 application with a Python FastAPI backend.

## Architecture
- Frontend: Next.js 14 (App Router) in /frontend
- Backend: FastAPI with SQLAlchemy ORM in /backend
- Database: PostgreSQL 16
- Deployment: Docker Compose on Hetzner VPS

## Conventions
- TypeScript strict mode for all frontend code
- Python PEP 8 with type hints everywhere
- All APIs return JSON with {data, error, meta} shape
- Tests in __tests__/ (frontend) or tests/ (backend)

## Important Notes
- Never modify migration files directly — use Alembic commands
- The .env.local file contains real API keys, do not commit it
- Ports: frontend 3000, backend 8000, database 5432

CLAUDE.md — Claude Code Compatibility

CLAUDE.md is the format used by Anthropic's Claude Code. Hermes Agent detects it automatically, meaning your existing Claude Code-configured projects work immediately with Hermes, without any adaptation.

When to use it: if you already use Claude Code and want compatibility between both tools.

.cursorrules and .cursor/rules/*.mdc — Cursor Compatibility

Hermes Agent is also compatible with Cursor IDE rule files. If your project contains a .cursorrules at the root or rule modules in .cursor/rules/, Hermes will load them automatically — provided no higher-priority context file is present.

Typical use case: you have an existing Cursor-configured project and want to try Hermes Agent without duplicating configuration.

The Priority Hierarchy

A crucial point: only one project context type is loaded per session. The first file found wins, in this priority order:

1. .hermes.md / HERMES.md — Maximum priority
2. AGENTS.md — Multi-agent standard
3. CLAUDE.md — Claude Code compatibility
4. .cursorrules — Cursor compatibility

Exception: SOUL.md is always loaded independently, in slot #1, as the agent's identity. It doesn't participate in this competition.

This design is intelligent: it avoids conflicts between different conventions and guarantees predictable behavior.

SOUL.md: The Global Personality

Unlike other context files that are local to the project, SOUL.md is global to the Hermes instance. It is placed only in HERMES_HOME (default ~/.hermes/):

• ~/.hermes/SOUL.md
• or $HERMES_HOME/SOUL.md if you use a custom home directory

Important points:
- Hermes generates a default SOUL.md if one doesn't exist yet
- Hermes does not probe the working directory for SOUL.md
- If the file is empty, nothing from SOUL.md is added to the prompt
- If the file has content, it is injected verbatim after security scanning

SOUL.md controls the agent's personality, tone, and communication style — not the project's technical rules.

Progressive Subdirectory Discovery

This is one of Hermes Agent's most elegant features. At startup, only the root context file is loaded. Then, as the session progresses, when the agent navigates into subdirectories (via read_file, terminal, search_files, etc.), it progressively discovers local context files.

Example monorepo structure:

my-project/
├── AGENTS.md              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

Example frontend subdirectory:

# Frontend Context
- Use pnpm, not npm, for package management
- Components in src/components/, pages in src/app/
- Tailwind CSS only, never inline styles
- Run tests with pnpm test

Example backend subdirectory:

# Backend Context
- Use poetry for dependency management
- Dev server: poetry run uvicorn main:app --reload
- All endpoints need OpenAPI docstrings
- Models in models/, schemas in schemas/

Advantages of Progressive Discovery

• No system prompt bloat — subdirectory hints only appear when relevant
• Prompt cache preservation — the system prompt stays stable across turns
• Each subdirectory is checked at most once per session
• Parent directory walk works too: reading backend/src/main.py discovers backend/AGENTS.md even if backend/src/ has no context file

Automatic Injection into the System Prompt

The loading process, implemented in agent/prompt_builder.py, follows these steps:

1. Scan the working directory by priority (.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules)
2. Read the file as UTF-8
3. Security scan to detect prompt injection attempts
4. Truncation if the file exceeds 20,000 characters (70% head, 20% tail, 10% marker)
5. Assembly under a # Project Context header
6. Injection into the system prompt

The final prompt looks like this:

# Project Context
The following project context files have been loaded and should be followed:

## AGENTS.md
[Your AGENTS.md content]

[SOUL.md content inserted directly]

Context Files vs. Persistent Memory

It's essential to distinguish two often-confused mechanisms:

• Context files are static Markdown files written by the developer, stored in the project directory and HERMES_HOME. They define project rules and conventions. They are modified manually.

• Persistent memory consists of auto-generated notes stored in Hermes's internal database. They record what the agent learned from past experiences, corrections, and learned preferences. They are modified automatically through the learning cycle.

Context files define the rules of the game. Persistent memory records what the agent learned while playing.

Security: Prompt Injection Protection

Hermes Agent includes a security scanner that analyzes all context files before injection. It detects:

• Instruction override attempts: "ignore previous instructions"
• Deception patterns: "do not tell the user"
• System prompt overrides
• Hidden HTML comments or invisible divs
• Credential exfiltration attempts
• Secret file access (cat .env)
• Invisible characters (zero-width spaces, bidirectional overrides)

If a threat is detected, the file is blocked with a clear message: [BLOCKED: AGENTS.md contained potential prompt injection...].

Recommendation: this scanner protects against common patterns, but doesn't replace vigilance. Always validate AGENTS.md content in projects you didn't author.

Size Limits

• Max characters per file: 20,000 (~7,000 tokens)
• Head truncation ratio: 70%
• Tail truncation ratio: 20%
• Truncation marker: 10%

Subdirectory files are capped at 8,000 characters each.

HERMES_HOME and File Organization

The HERMES_HOME environment variable defines Hermes Agent's home directory (default ~/.hermes/). This is where you find:

• SOUL.md — The agent's global personality
• skills/ — Installed skills
• Global configuration
• Persistent memory database

Typical structure:

~/.hermes/
├── SOUL.md              # Agent personality and tone
├── skills/              # Installed skills
│   ├── sat-content-creator/
│   └── ...
├── config.toml          # Global configuration
└── memory.db            # Persistent memory database

Project context files remain in the project's Git repository. Only SOUL.md and global configuration live in HERMES_HOME.

Best Practices

Do:
- Keep context files concise — well under 20,000 characters
- Structure with ## headers for each section (architecture, conventions, notes)
- Include concrete examples of preferred code patterns
- Explicitly mention what not to do
- List key paths and service ports
- Update the file as the project evolves — stale context is worse than no context
- Use per-subdirectory AGENTS.md for monorepos
- Commit context files to Git for team sharing

Avoid:
- Duplicating information between AGENTS.md and SOUL.md
- Putting secrets or API keys in context files
- Writing contradictory instructions in subdirectories
- Ignoring the maximum size — a too-long file gets truncated and loses information
- Placing AGENTS.md or CLAUDE.md outside your project — Hermes might load them by mistake

Pitfalls to Avoid

1. Stale context — a context file that no longer matches the project misleads the agent. Make it a habit to review it during major refactors.

2. Instruction overload — too many rules drown the agent in details. Focus on what's truly discriminating: code conventions, critical paths, and prohibitions.

3. File conflicts — with progressive subdirectory discovery, a subdirectory AGENTS.md can contradict the root one. Ensure consistency.

4. Parasitic AGENTS.md — if you work from a parent directory containing an AGENTS.md for another project, Hermes might load it accidentally. Always work from your project's root.

Conclusion

Context files are one of the pillars of productivity with Hermes Agent. They transform each session into an agent that "knows" your project, without repetitive effort. The priority hierarchy (.hermes.md > AGENTS.md > CLAUDE.md > .cursorrules) ensures compatibility with other market tools, while progressive subdirectory discovery optimizes context usage without overloading the prompt.

To deepen your mastery of Hermes Agent, check out our introduction and installation guide, our guide to configuring models and providers, the available tools overview, and mastering the CLI.