hermes - 💡(How to fix) Fix feat(prompt_builder): scan HERMES_HOME for global context files (HERMES.md, AGENTS.md, CLAUDE.md)

Summary

Hermes currently scans cwd (walking to git root for .hermes.md/HERMES.md, top-level for AGENTS.md/CLAUDE.md/.cursorrules) for project context files. There's no mechanism to load global context from HERMES_HOME (~/.hermes/ by default), so users who want persistent cross-project config currently duplicate it in every project OR maintain their own out-of-tree patches.

Proposal

Add a _load_global_context_md() function in agent/prompt_builder.py that scans HERMES_HOME for HERMES.md, AGENTS.md, CLAUDE.md (in that priority order, first match wins) and injects the first found as ## Global Hermes Context: ~/.hermes/<name> ahead of the project-context section.

This mirrors Claude Code's ~/.claude/CLAUDE.md global memory pattern that solo devs already rely on.

Behavior

1. Scan HERMES_HOME for HERMES.md → AGENTS.md → CLAUDE.md. First non-empty wins.
2. Apply existing safety pipeline: _strip_yaml_frontmatter → _scan_context_content (prompt-injection scan: regex + invisible unicode) → _truncate_content.
3. Wrap as ## Global Hermes Context: ~/.hermes/<name>\n\n<content>.
4. Pass the resolved path to project-context loaders via a new exclude_paths kwarg so a file isn't re-injected when cwd == HERMES_HOME.
5. Order in build_context_files_prompt(): global first (if found), then project (first-match-wins among .hermes.md/HERMES.md → AGENTS.md → CLAUDE.md → .cursorrules).

Optional config flag

Consider adding agent.global_context_files: true|false (default true) to allow users to opt out.

Motivation

Solo devs benefit from a single source of truth for cross-project preferences (tone, dev defaults, browser stack, memory provider hints) without duplicating into every repo. Currently the workaround is either:

• Copy the same context file into every project (drift inevitable), or
• Maintain a local patch (already several users doing this; happy to contribute mine).

Implementation sketch

~64 lines, surgical:

• New constant _GLOBAL_CONTEXT_NAMES = (\"HERMES.md\", \"AGENTS.md\", \"CLAUDE.md\").
• New function _load_global_context_md() -> tuple[str, Optional[Path]].
• Add exclude_paths: Optional[set[Path]] = None kwarg to _load_hermes_md, _load_agents_md, _load_claude_md (default None, backward-compat).
• Update build_context_files_prompt() to call global first, populate exclude_paths, then project.

Tests: extend tests/agent/test_prompt_builder.py with fixtures covering:

• Global file present + project absent → only global injected
• Global + project both present (different files) → both injected, ordered
• Global file at same path as project (cwd == HERMES_HOME) → only one injection
• Empty global file → fallback to next priority
• Prompt-injection content in global file → blocked by existing scanner

Security

Reuses existing _scan_context_content() so no new attack surface. Same regex patterns + invisible unicode detection apply. If a global file contains suspected injection (e.g. "ignore previous instructions"), it's blocked with [BLOCKED: ...] marker, identical to project-file handling.

Backward compatibility

• All new kwargs have None defaults.
• If no global file exists in HERMES_HOME, behavior identical to today.
• Project-context loading order unchanged.

Happy to open a PR — I have the patch running locally and it's been stable for a couple weeks.