ee3f3e756d
Cross-referenced all 84 docs pages against the actual codebase and corrected every discrepancy found. Reference docs: - faq.md: Fix non-existent commands (/stats→/usage, /context→/usage, hermes models→hermes model, hermes config get→hermes config show, hermes gateway logs→cat gateway.log, async→sync chat() call) - cli-commands.md: Fix --provider choices list (remove providers not in argparse), add undocumented -s/--skills flag - slash-commands.md: Add missing /queue and /resume commands, fix /approve args_hint to show [session|always] - tools-reference.md: Remove duplicate vision and web toolset sections - environment-variables.md: Fix HERMES_INFERENCE_PROVIDER list (add copilot-acp, remove alibaba to match actual argparse choices) Configuration & user guide: - configuration.md: Fix approval_mode→approvals.mode (manual not ask), checkpoints.enabled default true not false, human_delay defaults (500/2000→800/2500), remove non-existent delegation.max_iterations and delegation.default_toolsets, fix website_blocklist nesting under security:, add .hermes.md and CLAUDE.md to context files table with priority system explanation - security.md: Fix website_blocklist nesting under security: - context-files.md: Add .hermes.md/HERMES.md and CLAUDE.md support, document priority-based first-match-wins loading behavior - cli.md: Fix personalities config nesting (top-level, not under agent:) - delegation.md: Fix model override docs (config-level, not per-call tool parameter) - rl-training.md: Fix log directory (tinker-atropos/logs/→ ~/.hermes/logs/rl_training/) - tts.md: Fix Discord delivery format (voice bubble with fallback, not just file attachment) - git-worktrees.md: Remove outdated v0.2.0 version reference Developer guide: - prompt-assembly.md: Add .hermes.md, CLAUDE.md, document priority system for context files - agent-loop.md: Fix callback list (remove non-existent message_callback, add stream_delta_callback, tool_gen_callback, status_callback) Messaging & guides: - webhooks.md: Fix command (hermes setup gateway→hermes gateway setup) - tips.md: Fix session idle timeout (120min→24h), config file (gateway.json→config.yaml) - build-a-hermes-plugin.md: Fix plugin.yaml provides: format (provides_tools/provides_hooks as lists), note register_command() as not yet implemented
202 lines
7.5 KiB
Markdown
202 lines
7.5 KiB
Markdown
---
|
|
sidebar_position: 8
|
|
title: "Context Files"
|
|
description: "Project context files — .hermes.md, AGENTS.md, CLAUDE.md, global SOUL.md, and .cursorrules — automatically injected into every conversation"
|
|
---
|
|
|
|
# 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.
|
|
|
|
## Supported Context Files
|
|
|
|
| File | Purpose | Discovery |
|
|
|------|---------|-----------|
|
|
| **.hermes.md** / **HERMES.md** | Project instructions (highest priority) | Walks to git root |
|
|
| **AGENTS.md** | Project instructions, conventions, architecture | Recursive (walks subdirectories) |
|
|
| **CLAUDE.md** | Claude Code context files (also detected) | CWD only |
|
|
| **SOUL.md** | Global personality and tone customization for this Hermes instance | `HERMES_HOME/SOUL.md` only |
|
|
| **.cursorrules** | Cursor IDE coding conventions | CWD only |
|
|
| **.cursor/rules/*.mdc** | Cursor IDE rule modules | CWD only |
|
|
|
|
:::info Priority system
|
|
Only **one** project context type is loaded per session (first match wins): `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. **SOUL.md** is always loaded independently as the agent identity (slot #1).
|
|
:::
|
|
|
|
## AGENTS.md
|
|
|
|
`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.
|
|
|
|
### Hierarchical Discovery
|
|
|
|
Hermes walks the directory tree starting from the working directory and loads **all** `AGENTS.md` files found, sorted by depth. This supports monorepo-style setups:
|
|
|
|
```
|
|
my-project/
|
|
├── AGENTS.md ← Top-level project context
|
|
├── frontend/
|
|
│ └── AGENTS.md ← Frontend-specific instructions
|
|
├── backend/
|
|
│ └── AGENTS.md ← Backend-specific instructions
|
|
└── shared/
|
|
└── AGENTS.md ← Shared library conventions
|
|
```
|
|
|
|
All four files are concatenated into a single context block with relative path headers.
|
|
|
|
:::info
|
|
Directories that are skipped during the walk: `.`-prefixed dirs, `node_modules`, `__pycache__`, `venv`, `.venv`.
|
|
:::
|
|
|
|
### Example AGENTS.md
|
|
|
|
```markdown
|
|
# 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
|
|
|
|
`SOUL.md` controls the agent's personality, tone, and communication style. See the [Personality](/docs/user-guide/features/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
|
|
|
|
## .cursorrules
|
|
|
|
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.
|
|
|
|
## How Context Files Are Loaded
|
|
|
|
Context files are loaded by `build_context_files_prompt()` in `agent/prompt_builder.py`:
|
|
|
|
1. **At session start** — the function scans the working directory
|
|
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 20,000 characters are head/tail truncated (70% head, 20% tail, with a marker in the middle)
|
|
5. **Assembly** — all sections are combined under a `# Project Context` header
|
|
6. **Injection** — the assembled content is added to the system prompt
|
|
|
|
The final prompt section looks roughly like:
|
|
|
|
```text
|
|
# 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.
|
|
|
|
## Security: Prompt Injection Protection
|
|
|
|
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**: `<!-- ignore instructions -->`
|
|
- **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.]
|
|
```
|
|
|
|
:::warning
|
|
This scanner protects against common injection patterns, but it's not a substitute for reviewing context files in shared repositories. Always validate AGENTS.md content in projects you didn't author.
|
|
:::
|
|
|
|
## Size Limits
|
|
|
|
| Limit | Value |
|
|
|-------|-------|
|
|
| Max chars per file | 20,000 (~7,000 tokens) |
|
|
| Head truncation ratio | 70% |
|
|
| Tail truncation ratio | 20% |
|
|
| Truncation marker | 10% (shows char counts and suggests using file tools) |
|
|
|
|
When a file exceeds 20,000 characters, the truncation message reads:
|
|
|
|
```
|
|
[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]
|
|
```
|
|
|
|
## Tips for Effective Context Files
|
|
|
|
:::tip Best practices for AGENTS.md
|
|
1. **Keep it concise** — stay well under 20K chars; the agent reads it every turn
|
|
2. **Structure with headers** — use `##` sections for architecture, conventions, important notes
|
|
3. **Include concrete examples** — show preferred code patterns, API shapes, naming conventions
|
|
4. **Mention what NOT to do** — "never modify migration files directly"
|
|
5. **List key paths and ports** — the agent uses these for terminal commands
|
|
6. **Update as the project evolves** — stale context is worse than no context
|
|
:::
|
|
|
|
### Per-Subdirectory Context
|
|
|
|
For monorepos, put subdirectory-specific instructions in nested AGENTS.md files:
|
|
|
|
```markdown
|
|
<!-- frontend/AGENTS.md -->
|
|
# 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`
|
|
```
|
|
|
|
```markdown
|
|
<!-- backend/AGENTS.md -->
|
|
# 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/`
|
|
```
|