Wiki · Features in depth
Context files
A rules file is the fastest way to explain your conventions to the agent — and the fastest way to ruin it. Practical, no theory.
📄
A rules file is the fastest way to explain to the agent how things work at your place — and the fastest way to ruin it.
The agent reads it on every task. A short, concrete file works; a long one gets truncated and some
rules never reach it. Where things belong matters too: how to speak goes in one file,
how to work in a project in another.
Two different files, two different jobs
| File | What it is for | Where it lives |
|---|---|---|
| SOUL.md | Who the agent is and how it speaks: tone, brevity, directness, what to avoid. Applies everywhere | ~/.hermes/SOUL.md (only there — it is looked up in the Hermes home directory alone) |
| AGENTS.md | How work is done in this project: paths, commands, conventions, what is forbidden | In the project (git root and subdirectories) |
A simple rule: what should apply everywhere goes into SOUL.md; what belongs to one project goes into AGENTS.md. Put a specific project's ports and paths into SOUL.md and you will be hunting and deleting them a month later.
Which files the agent knows
| File | Meaning |
|---|---|
.hermes.md / HERMES.md | Project instructions with the highest priority |
AGENTS.override.md | Your personal per-directory override — usually not committed, so you can run different rules than the shared file |
AGENTS.md | Project instructions, conventions, architecture notes |
CLAUDE.md | A file from another tool that Hermes also recognises |
.cursorrules, .cursor/rules/*.mdc | Cursor IDE rules — your existing conventions apply here too |
SOUL.md | The agent's identity; always loaded, independently of the rest |
Only one project file is loaded — the first found in the order
.hermes.md → AGENTS.override.md → AGENTS.md →
CLAUDE.md → .cursorrules. So with both AGENTS.md and
CLAUDE.md side by side, AGENTS.md wins and the other is ignored.
SOUL.md is always added on top as the agent's identity — that is the exception.
When the files are loaded
| When | What happens |
|---|---|
| At startup | The working directory is scanned (upwards to the git root). Content is read, checked for injected instructions and truncated if needed |
| During the session | When the agent touches a file in a subdirectory, rules from that directory and up to five parents are added. Great for large projects: each part carries its own rules |
That is why you do not need one giant instruction file for a whole project. The frontend has its rules, the backend its own — and the agent gets them exactly when it starts working in that directory.
Limits worth knowing
| Limit | Value |
|---|---|
| Maximum file length | Configurable; otherwise it scales with the model (floor 20,000 characters, ceiling 500,000) |
| Truncating an over-long file | The head (70%) and tail (20%) are kept, with a marker in the middle |
| Time to read one file | 5 seconds. A file on a slow drive (iCloud, OneDrive, a network share) may be skipped with a warning |
| An empty SOUL.md | Nothing at all is added — which is also a choice |
# this is the marker when a file was truncated:
[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]
Writing a file that works
| Principle | An example from practice |
|---|---|
| Short and concrete | Ten concrete rules beat five pages of description |
| Write down what is forbidden too | "Never add a light theme, the site is dark only" — without it the agent improvises |
| State the commands and paths to use | The agent does not have to hunt for them and cannot mix them up |
| Headers and bullets | The agent navigates the file better, and so do you |
| Update it when the project changes | Stale rules are worse than none — the agent follows them |
The easiest start: have the agent walk the project and write the first version, which you then edit.
❯ Walk through this project and draft an AGENTS.md — only the essentials
that must be followed: how to run tests, where things live and what must not be done.
Pitfalls from our systems
| What happened | What to do |
|---|---|
| A long rules file was truncated and part of it vanished | That is exactly why we keep files short. If a rule matters, put it near the top |
| Two rules contradicted each other (old one in AGENTS.md, new one in SOUL.md) | The agent leaned towards whichever it read first. Keep rules in one place — personality in SOUL.md, work in AGENTS.md |
| Rules from a subdirectory overrode the main ones | Expect subdirectory files to be added during the session. When they conflict, the more specific (closer) file wins |
| A CLAUDE.md existed and its rules never applied | Only one project file is loaded — the highest priority one. Delete the others or merge them |
| A SOUL.md in the project was ignored | Correct: identity comes only from the Hermes home directory. Project rules belong in AGENTS.md |
| A file on a network share was never read | Reading has a 5-second cap. Keep rules on local storage |
| We accidentally pasted foreign text into a rules file (copied web content, say) | Content is scanned for injected instructions, but rely on yourself: only put what you wrote into a rules file |
Our tips
| Tip | Why |
|---|---|
| Start with three rules and add more when it hurts | An empty file beats a five-page one that gets truncated |
| Say in SOUL.md how long answers should be | One sentence saves thousands of words across every reply |
| "What not to do" belongs in AGENTS.md | Prohibitions work better than wishes |
| Keep the files in git with the project | You can see when and why a rule changed |
Put personal tweaks in AGENTS.override.md | You do not overwrite the team file and your change stays yours |