feat(agent): load global HERMES.md, AGENTS.md, and CLAUDE.md from HERMES_HOME

[mhazim2]

What does this PR do?

Adds support for loading global context files (HERMES.md, AGENTS.md, CLAUDE.md) from HERMES_HOME (~/.hermes/) unconditionally on every session, after project context is assembled. This mirrors the existing SOUL.md global loading pattern.

This enables users to store project-independent agent operating preferences (e.g. orchestration model, delegation policies, preferred workflows) that survive across sessions without relying on the memory cap or skill loading.

Related Issue

Fixes #

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• agent/prompt_builder.py: Added _load_global_hermes_md(), _load_global_agents_md(), and _load_global_claude_md() functions. Called unconditionally at the end of build_context_files_prompt() after project context is assembled.
• tests/agent/test_prompt_builder.py: Added 15 tests covering global context loading, injection blocking, frontmatter stripping, truncation, case priority, P1 early-return fix, and P2 empty-file fallthrough fix.

Implementation Notes

• P1 fix: Removed early return "" that blocked global loaders when no project context existed and skip_soul=True. Global loaders now always run after project context assembly.
• P2 fix: Empty uppercase file (e.g. HERMES.md with whitespace only) falls through to lowercase variant (.hermes.md, agents.md, claude.md) via continue instead of return "".

How to Test

1. Create a global context file at ~/.hermes/HERMES.md (or AGENTS.md / CLAUDE.md)
2. Start a new Hermes session from any project directory
3. Verify the global file content appears in the system prompt after project context

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux (VPS)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

N/A — not a skill PR

Screenshots / Logs

N/A

[teknium1]

Thanks for the focused implementation and coverage. The global-context goal remains a maintainer design choice: current main documents SOUL.md as the sole HERMES_HOME context file and treats AGENTS.md / CLAUDE.md as project-local (website/docs/user-guide/features/context-files.md:9-23).

Problems

• The new unconditional append duplicates a file when the launch cwd is HERMES_HOME: normal project discovery runs first, then the added loaders read the same pathname again. Current selection is at agent/prompt_builder.py:1976-1984; the added global append has no exclusion.
• The branch concatenates all three global files, so it needs an explicit precedence contract before it can align with the documented first-match project model.

Suggested changes

• Choose and document the global-context precedence model, then add path-identity deduplication and a cwd == HERMES_HOME regression test.

Automated hermes-sweeper review.

[teknium1]

When cwd == HERMES_HOME, normal project discovery has already selected this same context path before this append block runs, so the file is injected twice. Add path-identity exclusion and a regression test for that launch directory.

[GottZ]

This was generated by AI during triage.

Summary

Three PRs propose persistent, non-project context files under HERMES_HOME; no underlying issue or reported defect is present in the supplied evidence. #1805 and #1812 add global AGENTS.md loading, while #12255 broadens the proposal to global HERMES.md, AGENTS.md, and CLAUDE.md loading.

Related pull requests

• #1805 [closed] related — (+69/-14) — closed overlapping implementation: Adds HERMES_HOME/AGENTS.md before project AGENTS.md, with injection scanning, truncation, tests, and documentation. It remains relevant because its diff substantially overlaps #1812, although the supplied evidence gives no closure or supersession reason.
• #1812 [closed] related — (+104/-32) — closed after maintainer design rejection: Implements the same global AGENTS.md concept with scanning, truncation, ordering tests, and documentation, but contributor teknium1 explicitly rejected blurring the intentional SOUL.md-global versus AGENTS.md-project boundary; the non-contributor documentation concern does not override that decision.
• #12255 related — (+244/-0) — keep open for design resolution and revision, not merge-ready: Extends the earlier concept to three unconditional global files and adds broad tests, but the keep_open review on #12255 identifies unresolved path-identity duplication when cwd equals HERMES_HOME and the absence of an explicit precedence contract; it also notes that adopting global context files remains a maintainer design choice.

Duplicates

#1805 and #1812 are substantially duplicate implementations of global HERMES_HOME/AGENTS.md loading. #12255 overlaps both on AGENTS.md but is broader because it also adds global HERMES.md and CLAUDE.md.

Suggested consolidation

Do not merge any PR yet. Keep #12255 as the sole active consolidation candidate only while maintainers explicitly reconsider the global-context design; before merge it must define and document precedence, deduplicate identical project/global paths, and test cwd == HERMES_HOME. #1805 and #1812 are already closed and need not be reopened; #1812 must remain closed absent an explicit resolution of teknium1's blocking design objection.

Cross-PR triage: Reviewed 3 pull requests and 0 issues in this complex. Each diff was read against this issue; Assessment working set: 32 kB of PR diffs, 9 kB of issue/PR text, 2 kB of discussion (3 comments), 1 verify verdict. verdicts reflect diff content, not PR titles. Part of an automated triage batch.