Context Files: AGENTS.md and Project Awareness

The Problem This Solves

SOUL.md, from the previous lesson, gives your agent a consistent identity no matter what you are working on. But identity is not the same as project knowledge. If you work across five different codebases, you do not want to re-explain your architecture, conventions, and restrictions at the start of every single session. Context files solve this: drop a file in a project, and Hermes picks it up automatically whenever you work in that directory.

Which Files Hermes Looks For

Hermes checks for context files in this priority order, and the first match wins:

1. .hermes.md or HERMES.md -- highest priority, Hermes-specific project instructions
2. AGENTS.md -- general project structure, conventions, architecture
3. CLAUDE.md -- Claude-specific context, if you also use other AI coding tools
4. .cursorrules -- picked up automatically if you already use Cursor

SOUL.md is loaded independently of this list -- it is not a context file in this sense, it is the identity layer from Lesson 5.

In practice, AGENTS.md is the one most people write. If you already have a CLAUDE.md or .cursorrules file from using other tools, Hermes will use it without you doing anything extra -- one more reason AGENTS.md and SOUL.md should not duplicate each other's job.

How Discovery Actually Works

At session startup, Hermes scans your current working directory and walks up to the git root, loading the first matching file it finds into the system prompt -- after running it through security scanning, truncation if needed, and assembly into the prompt.

But it does not stop there. As the agent navigates during a session -- reading files, running terminal commands, searching -- it progressively discovers context files in whatever subdirectories it touches, and injects them into the conversation right when they become relevant. This is deliberate: loading every context file in a large project up front would bloat the system prompt and hurt prompt-cache stability. Instead, reading backend/src/main.py will discover backend/AGENTS.md on its own, even if intermediate directories along the way have no context file at all. Each directory is checked only once per session, so this does not repeat unnecessarily.

What to Actually Put in AGENTS.md

The documentation recommends AGENTS.md cover:

• Architecture overview -- the shape of the system at a glance
• Coding conventions and patterns specific to this project
• Important restrictions -- the kind of thing you would otherwise have to remember to mention every time ("never modify migration files directly")
• Key paths and service ports
• Technology stack details

A useful test: if you have ever caught yourself typing the same explanation to an AI tool at the start of multiple sessions in the same project, that explanation belongs in AGENTS.md instead.

Security: Files Are Scanned, Not Trusted Blindly

Because context files can come from a cloned repository you did not write yourself, Hermes treats them as untrusted input by default. Every context file is scanned for prompt injection attempts -- override instructions, hidden directives, credential exfiltration patterns -- before being included in the system prompt.

There is also a size limit: files over 20,000 characters are truncated, keeping 70% from the head and 20% from the tail, with a marker indicating content was removed. This keeps a single oversized file from blowing out your context budget.

A Practical First AGENTS.md

Pick one real project you work in regularly and create an AGENTS.md at its root. Keep the first version short -- four or five sentences is enough to start:

# AGENTS.md

This is a [language/framework] project. The main entrypoint is [path].
Database migrations live in [path] -- never edit existing migration
files, always create a new one. Tests run with [command]. The staging
environment is at [URL/port]; production deploys require [process].

Start a fresh session in that project directory and ask the agent what it knows about the codebase. You should see it reference what you just wrote, without you having said anything about the project in the conversation itself.

With both identity (SOUL.md) and project awareness (AGENTS.md) in place, the next lesson covers a different way to bring information into a conversation: pulling specific files, diffs, and even web pages in directly using @ syntax.