hermes-context-file-loading
Skill3 starsChanged 53 days agoMITView on GitHub
Trace how Hermes assembles its system prompt from instruction files: which file loads from which directory, which project file wins when several exist, and which tier each rule lands in. Use when auditing or editing SOUL/AGENTS/MEMORY/USER files, deciding where a durable rule belongs, debugging an instruction file that did or did not take effect, or reasoning about subagent context and prompt cache stability. Not for editing the runtime source, and not for other harnesses' context files.
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-harness-settings-paritySkill
- agent-operating-contract-evolutionSkill
- ai-coding-agent-delegationSkill
- arch-improvement-planSkill
- contract-bound-deliverablesSkill
- cross-agent-repair-routingSkill
- define-goalSkill
- delegated-work-acceptanceSkill
- design-an-interfaceSkill
- design-mdSkill
- discord-rich-messageSkill
- dotnet-repo-workflowSkill
- evidence-backed-analytical-writingSkill
- evidence-boundary-disciplineSkill
- find-nearbySkill
- gddSkill
- generated-runtime-repairsSkill
- ghc-searchSkill
- git-auto-sync-pipelinesSkill
- github-code-reviewSkill
- github-repo-managementSkill
- grounded-citationsSkill
- harness-engineeringSkill
- hermes-modelsSkill
- hermes-updatesSkill
- hoa-introspect-distillSkill
- hoa-introspectSkill
- hoa-skill-reviewSkill
- hoa-skill-workSkill
- html-artifactSkill
- jupyter-live-kernelSkill
- kanban-workflowsSkill
- m365-copilot-cdpSkill
- measurement-campaign-evidenceSkill
- microsoft-officeSkill
- notes-to-prdSkill
- ocr-and-documentsSkill
- official-document-verificationSkill
- omp-headless-orchestrationSkill
- ops-claim-verificationSkill
- package-release-verificationSkill
- plan-to-issuesSkill
- project-phase-closeoutSkill
- report-claim-auditSkill
- research-stream-consolidationSkill
- review-revision-candidatesSkill
- rss-feedsSkill
- skill-library-curationSkill
- skill-porting-and-publishingSkill
- spec-convergenceSkill
- structural-validity-gatesSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- teams-cdpSkill
- tmux-agent-controlSkill
- whisperSkill
- writing-plansSkill
- writingSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 101
Subagent delegation skips project context + SOUL: When skip_context_files / skip_soul is set (e.g.
- Very specific: line 157
Never create HERMES.md and AGENTS.md side by side expecting both — first-match eats one.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hermes Context File Loading
<!-- install-root: `$HERMES_HOME` below means the install root; it defaults to `~/.hermes` -->How Hermes builds its system prompt from instruction files. Source-verified against
$HERMES_HOME/hermes-agent/agent/prompt_builder.py (functions cited by line below) and the
official docs. Mechanics here override any vibe-based assumption — when in doubt, re-read
prompt_builder.py and the docs at the homepage above.
When to use this skill
- Auditing / editing
SOUL.md,AGENTS.md,MEMORY.md,USER.md, or any context file. - Deciding which layer a durable rule belongs in (identity vs project vs memory).
- Debugging "why did/didn't this instruction file take effect?"
- Reasoning about subagent context, cwd dependence, or prompt-cache stability.
For a step-by-step audit + surgical de-dup procedure (backup → verify-paths → owner decisions → collapse-duplicates-to-pointer → memory-cap handling → verify), see
references/auditing-instruction-files-workflow.md. Run it whenever the owner asks to clean, de-dup, or fix conflicts across the four instruction files.
The one table that matters: file → mechanism
| File | Loader fn (prompt_builder.py) | Discovery scope | git? | Global? |
SOUL.md | load_soul_md() (L1401) | HERMES_HOME/SOUL.md ONLY — never probes cwd | no | ✅ YES — the only truly global file |
.hermes.md / HERMES.md | _load_hermes_md → _find_hermes_md (L80) | cwd, then walk up parents to git root | uses git root as the walk's stop boundary (no git → walks to filesystem root) | ❌ project-scoped |
AGENTS.md / agents.md | _load_agents_md (L1452) | cwd / name — that ONE directory only. No walk up, no recursion, no git | no | ❌ binds to exact cwd |
CLAUDE.md / claude.md | _load_claude_md (L1468) | cwd only | no | ❌ |
.cursorrules + .cursor/rules/*.mdc | _load_cursorrules (L1484) | cwd only | no | ❌ |
MEMORY.md | volatile tier (memory tool) | HERMES_HOME/memories/MEMORY.md | no | ✅ injected every turn |
USER.md | volatile tier (memory tool) | HERMES_HOME/memories/USER.md | no | ✅ injected every turn |
HERMES_HOME = $HERMES_HOME/ (or $HERMES_HOME/profiles/<name>/ under a named profile; $HERMES_HOME
defaults to ~/.hermes — substitute the install root in commands when yours is relocated).
Critical precedence rule (project context = ONE slot)
build_context_files_prompt() (L1514) loads exactly one project-context type,
first match wins, in this order:
.hermes.md / HERMES.md → AGENTS.md → CLAUDE.md → .cursorrules- They are mutually exclusive. If a
.hermes.mdexists, yourAGENTS.mdis silently ignored (HERMES.md outranks it). CreatingHERMES.mdnext to a workingAGENTS.mdis a footgun, not an upgrade. SOUL.mdis independent — always loaded as identity (slot #1), regardless of the project slot. It does not compete in the first-match race.
Prompt-assembly tiers (cache discipline)
agent/system_prompt.py joins three tiers: stable → context → volatile.
| Tier | Holds | Cache behavior |
| stable | SOUL.md identity (or DEFAULT_AGENT_IDENTITY fallback), tool/model guidance, skills index, env/platform hints | cached; stable across turns |
| context | caller system_message + the ONE project file (.hermes.md/AGENTS.md/CLAUDE.md/.cursorrules) | cached |
| volatile | MEMORY.md snapshot, USER.md snapshot, external memory block, timestamp/session/model line | cached but refreshed; injected every turn |
Implication for de-dup: SOUL (stable) and AGENTS (context) sit in different tiers — any rule duplicated across them is pure prompt weight. MEMORY + USER (volatile) re-inject every turn — duplicating facts across those two costs tokens on every call. De-dup volatile first.
Hard facts to design around
- Want a rule global / cwd-independent / loaded every session → it MUST live in
SOUL.md.AGENTS.md,HERMES.md,CLAUDE.md,.cursorrulesare ALL cwd-bound. None can be made global by relocating into$HERMES_HOME/— that is not their mechanism. PuttingHERMES.mdorAGENTS.mdin$HERMES_HOME/does nothing unless your session cwd happens to be there. AGENTS.mdbinds to the EXACT cwd directory, not a subtree.- cwd =
~/proj→~/proj/AGENTS.mdloads ✓ - cwd =
~/proj/sub→ top-levelAGENTS.mddoes NOT auto-load (no walk-up). SubdirectoryAGENTS.mdfiles load via a separate progressive-discovery mechanism (agent/subdirectory_hints.py), appended to tool results only when the agent reads files in that subdir, and only that subdir's own file. - AGENTS.md does NOT require a git repo. Verified: a non-git dir still loads its AGENTS.md.
- cwd =
HERMES.mduses git root only as a search boundary, not a requirement. No.git→ it walks up to the filesystem root. It still works without git; git just caps the walk.- Subagent delegation skips project context + SOUL. When
skip_context_files/skip_soulis set (e.g.delegate_task), Hermes uses the hardcodedDEFAULT_AGENT_IDENTITYand loads no project file. → Subagents do NOT see your SOUL persona or AGENTS contract. Pass anything they need explicitly in the delegationcontext. - Limits & processing: each context file is security-scanned (
_scan_context_content, prompt-injection patterns fromtools/threat_patterns.py), then truncated at ~20,000 chars (head/tail). YAML frontmatter is stripped from.hermes.mdbefore injection (_strip_yaml_frontmatter). Empty file → nothing added. cdinto a directory with its ownAGENTS.mdcosts context, silently. Command-level directory changes trigger the subdirectory-hint loader, socd ~/repos/<repo> && …or a shell call withworkdir=<subdir>appends that directory'sAGENTS.md(up to 20k chars) to the tool result — a monorepo worktree can inject a full project map you never asked for. Operate withgit -C <path> …, absolute paths, or--workdirat the level you actually need, and note that a detached git worktree carries its own copy of every instruction file in that snapshot.A profile home's
terminal.cwddecides which repo contract that bot reads every turn. Profile homes are independentHERMES_HOMEs, but the project slot still follows the session cwd, so a bot whoseterminal.cwdpoints at the front-door workspace loads the front door's operating contract (routing tables, delivery channels, board rules it has no authority to act on) as its own project context — a silent multi-thousand-token tax per turn. Audit before proposing any instruction restructure:python3 - <<'PY' import yaml, pathlib H = pathlib.Path.home() for f in [H/'.hermes/config.yaml', *sorted((H/'.hermes/profiles').glob('*/config.yaml'))]: d = yaml.safe_load(open(f)) or {} cwd = ((d.get('terminal') or {}).get('cwd')) agents = pathlib.Path(cwd)/'AGENTS.md' if cwd else None size = agents.stat().st_size if agents and agents.exists() else 0 print(f"{str(f).replace(str(H),''):42} cwd={cwd} AGENTS={size} B") PYFix shape: give each bot its own workspace dir plus a short
AGENTS.md(role delta + pointers to the shared clauses by name, never copies), and leave the front-door contract in the front door's cwd. Confirm the split did not drop a safety gate — pointer lines are the review surface.Prove the split by the loaded title, not by the config value. Run one one-shot in the bot's own home and ask it to reply with the first
#heading of itsAGENTS.md; then run the identical probe with cwd set to the front-door workspace. Two different headings (Forge — 执行协议vsAGENTS.md — Zoe Operating Contract) is the proof that cwd is doing the work; aconfig getonly echoes what you wrote. A local-terminal CLI takes the caller'sos.getcwd(), so the front-door run must be launched from that directory (or with--in <dir>) — otherwise both runs read the same file and look falsely identical.
Decision shortcut
- "Make X apply everywhere, always" → put X in
SOUL.md. - "Project-specific rules for repo Y" →
AGENTS.mdat repo root (or.hermes.mdif you want git-root reach across subdirs — but it then displaces AGENTS.md). - "Stable fact / preference" →
MEMORY.md(orUSER.mdfor identity-of-the-user facts). - "Reusable procedure" → a skill (not memory, not AGENTS).
- Never create
HERMES.mdandAGENTS.mdside by side expecting both — first-match eats one.
Verification recipe (re-confirm after Hermes upgrades)
SRC="${HERMES_HOME:-$HOME/.hermes}/hermes-agent/agent/prompt_builder.py"
# Confirm the loader functions and their scopes still match this skill:
grep -n "_load_agents_md\|_load_hermes_md\|_load_claude_md\|load_soul_md\|_find_git_root\|build_context_files_prompt" "$SRC"Then read each function body. If scopes changed, patch this skill immediately
(skill_manage action='patch'). Docs: homepage URL in frontmatter +
website/docs/developer-guide/prompt-assembly.md in the repo.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

