mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-25 00:51:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(soul): add comprehensive SOUL.md guide

Browse source 
Document the new global-only SOUL behavior, add a dedicated use guide, update personality/context/config docs, and fix docs language that still described cwd-local SOUL loading.
This commit is contained in:
teknium1 2026-03-14 09:37:26 -07:00
parent 8d5563b3f6
commit f8b30d1035
8 changed files with 493 additions and 177 deletions
Download patch file Download diff file Expand all files Collapse all files

28
website/docs/user-guide/features/context-files.md
View file

@ -1,19 +1,19 @@
---
sidebar_position: 8
title: "Context Files"
description: "Project context files — AGENTS.md, SOUL.md, and .cursorrules — automatically injected into every conversation"
description: "Project context files — AGENTS.md, global SOUL.md, and .cursorrules — automatically injected into every conversation"
---
# Context Files
Hermes Agent automatically discovers and loads project context files from your working directory. These files are injected into the system prompt at the start of every session, giving the agent persistent knowledge about your project's conventions, architecture, and preferences.
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 |
|------|---------|-----------|
| **AGENTS.md** | Project instructions, conventions, architecture | Recursive (walks subdirectories) |
| **SOUL.md** | Personality and tone customization | CWD → `~/.hermes/SOUL.md` fallback |
| **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 |
@ -71,14 +71,18 @@ This is a Next.js 14 web application with a Python FastAPI backend.
`SOUL.md` controls the agent's personality, tone, and communication style. See the [Personality](/docs/user-guide/features/personality) page for full details.
**Discovery order:**
**Location:**
1. `SOUL.md` or `soul.md` in the current working directory
2. `~/.hermes/SOUL.md` (global fallback)
- `~/.hermes/SOUL.md`
- or `$HERMES_HOME/SOUL.md` if you run Hermes with a custom home directory
When a SOUL.md is found, the agent is instructed:
Important details:
> *"If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it."*
- 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
@ -97,7 +101,7 @@ Context files are loaded by `build_context_files_prompt()` in `agent/prompt_buil
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 like:
The final prompt section looks roughly like:
```
# Project Context
@ -112,13 +116,11 @@ The following project context files have been loaded and should be followed:
[Your .cursorrules content here]
## SOUL.md
If SOUL.md is present, embody its persona and tone...
[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: