Context Files

Hermes Agent automatically discovers and loads context files that shape how it behaves. Some are project-local and discovered from your working directory. SOUL.md is now global to the Hermes instance and is loaded from HERMES_HOME only.

AGENTS.md is the primary project context file. It tells the agent how your project is structured, what conventions to follow, and any special instructions.

Directory Chain (git root → working directory)

When your working directory sits inside a git repository, Hermes loads a merged chain of AGENTS.md files at session start: the git-root AGENTS.md first, then the AGENTS.md in every intermediate directory down to your working directory. Deeper files appear later in the prompt, so more specific guidance takes precedence. Each file gets its own provenance header (e.g. ## ../../AGENTS.md), and identical copies along the chain are deduplicated.

monorepo/                   (git root, cwd = packages/webapp/)
├── AGENTS.md              ← Loaded first (repo-wide conventions)
└── packages/
    ├── AGENTS.md          ← Loaded second
    └── webapp/
        └── AGENTS.md      ← Loaded last (most specific, takes precedence)

Outside a git repository, only the working directory itself is checked — parents are never consulted, so an AGENTS.md planted in /tmp or $HOME can't leak into unrelated sessions.

Progressive Subdirectory Discovery

At session start, Hermes loads the AGENTS.md from your working directory into the system prompt. As the agent navigates into subdirectories during the session (via read_file, terminal, search_files, etc.), it progressively discovers context files in those directories and injects them into the conversation at the moment they become relevant.

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

This approach has two advantages over loading everything at startup:

• No system prompt bloat — subdirectory hints only appear when needed
• Prompt cache preservation — the system prompt stays stable across turns

Each subdirectory is checked at most once per session. The discovery also walks up parent directories, so reading backend/src/main.py will discover backend/AGENTS.md even if backend/src/ has no context file of its own.

Example AGENTS.md

# Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

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

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

## Important Notes
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md controls the agent's personality, tone, and communication style. See the Personality page for full details.

Location:

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

Important details:

• Hermes seeds a default SOUL.md automatically if one does not exist yet
• Hermes loads SOUL.md only from HERMES_HOME
• 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, the content is injected verbatim after scanning and truncation

Hermes is compatible with Cursor IDE's .cursorrules file and .cursor/rules/*.mdc rule modules. If these files exist in your project root and no higher-priority context file (.hermes.md, AGENTS.md, or CLAUDE.md) is found, they're loaded as the project context.

This means your existing Cursor conventions automatically apply when using Hermes.

At startup (system prompt)

Context files are loaded by build_context_files_prompt() in agent/prompt_builder.py:

1. Scan working directory — checks for .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules (first match wins)
2. Content is read — each file is read as UTF-8 text
3. Security scan — content is checked for prompt injection patterns
4. Truncation — files exceeding the character cap are head/tail truncated (70% head, 20% tail, with a marker in the middle). The cap is an explicit context_file_max_chars from config.yaml when set; otherwise it scales dynamically with the model's context window (floor 20,000 chars, ceiling 500,000)
5. Assembly — all sections are combined under a # Project Context header
6. Injection — the assembled content is added to the system prompt

During the session (progressive discovery)

SubdirectoryHintTracker in agent/subdirectory_hints.py watches tool call arguments for file paths:

1. Path extraction — after each tool call, file paths are extracted from arguments (path, workdir, shell commands)
2. Ancestor walk — the directory and up to 5 parent directories are checked (stopping at already-visited directories)
3. Hint loading — if an AGENTS.md, CLAUDE.md, or .cursorrules is found, it's loaded (first match per directory)
4. Security scan — same prompt injection scan as startup files
5. Truncation — capped at 8,000 characters per file
6. Injection — appended to the tool result, so the model sees it in context naturally

The final prompt section looks roughly like:

# Project Context

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

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

Notice that SOUL content is inserted directly, without extra wrapper text.

All context files are scanned for potential prompt injection before being included. The scanner checks for:

• Instruction override attempts: "ignore previous instructions", "disregard your rules"
• Deception patterns: "do not tell the user"
• System prompt overrides: "system prompt override"
• Hidden HTML comments: ``
• Hidden div elements: <div style="display:none">
• Credential exfiltration: curl ... $API_KEY
• Secret file access: cat .env, cat credentials
• Invisible characters: zero-width spaces, bidirectional overrides, word joiners

If any threat pattern is detected, the file is blocked:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

When a file exceeds the configured limit, the truncation message reads:

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

Per-Subdirectory Context

For monorepos, put subdirectory-specific instructions in nested AGENTS.md files:

# Frontend Context

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

# Backend Context

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`