Hermes Context Injection

Hermes builds the system prompt for each session from a fixed stack of files and indexes. This page lists what is injected, what is loaded on demand, and how the prompt tiers behave.

Injected at session start

Source	File location	Injected?	Notes
Identity	<HERMES_HOME>/SOUL.md (profile home)	Always	Loaded directly by Hermes from the profile home; independent of the working directory
Project context	AGENTS.md chain, git root → cwd	When the session has a working directory	One family per session, see AGENTS.md chain; CONTEXT.md is never auto-discovered
Host card	<HERMES_HOME>/AGENTS.md	Hosted sessions (desktop, gateway)	Injected directly by the gateway, independently of the cwd — a separate mechanism from the AGENTS.md chain, see AGENTS.md chain
Skills index	Built from ~/.hermes/skills + configured sources	With the skills tools enabled	Interleaved ## Skills block; skill bodies load on demand via skill_view, never at startup
Memory / user profile	<HERMES_HOME>/memories/ (MEMORY.md, USER.md)	With the memory toolset	Subject to memory.write_approval and memory.nudge_interval
Workspace snapshot	Runtime states (recent files, terminal)	With the relevant toolsets	Volatile by nature

CONTEXT.md is a library read with read_file when needed. A Markdown link inside an injected file is a pointer for the agent to follow with a tool — links are never followed during prompt assembly.

Prompt tiers

The assembled system prompt is organized in three tiers, ordered here as they are built:

Tier	Contents	Role
stable	Identity (SOUL.md), guidance, part of the work brief	Stable prefix, reused across turns
context	Optional system message, project context (AGENTS chain), workspace snapshot	Rebuilt when the working directory or project state changes
volatile	Skills index, memory/user profile, plugins, timestamp, runtime environment	Rebuilt on cache invalidation; the skills index moved here so skill edits do not invalidate the cached identity prefix

Tier names describe construction and cache stability — they are not an attention-priority ranking. Design decisions rely on file scope and explicit instruction specificity, not on prompt position.

What stays on disk

Item	Read cost
Skill body (SKILL.md)	On demand, once loaded into the conversation
CONTEXT.md glossary	On demand
WIKI.md repo wiki	On demand — see the LLM wiki skill
Documentation and sources	On demand

Measuring the injected size

hermes prompt-size reports the fixed prompt budget of a fresh session, offline, without any API call:

hermes prompt-size              # human-readable breakdown
hermes prompt-size --json       # full breakdown: skills index, memory, tools, per-skill index cost
hermes prompt-size --platform cli

Numbers are characters and bytes of the actually rendered blocks — not raw file sizes. The heuristic 4 chars/token is an approximation; billing and cache hits depend on the provider tokenizer.

Sessions and working directories

The session working directory selects the AGENTS.md chain and the project skills. Mechanism facts (verified 2026-09-12):

• Gateway, cron, and desktop sessions pin a per-session working directory (HERMES_SESSION_CWD / TERMINAL_CWD scopes).
• CLI one-shot sessions (hermes chat -q) resolve the working directory from terminal.cwd in config.yaml; a shell cd does not change it.
• hermes --in DIR sets the terminal environment and command working directory to DIR, but CLI one-shot catalog builds were observed not to include project skills even with --in (reproduced 2026-09-12); project-trusted repos are best exercised from a desktop session bound to the repo, a gateway session, or a cron job with workdir set.