feat(agent): load global AGENTS.md

[enzo2]

What does this PR do?

Hermes currently loads global SOUL.md from HERMES_HOME, but there is no equivalent global, user-authored context file for non-personality instructions (eg. homelab environment), equivalent to TOOLS.md in OpenClaw. This change adds an optional HERMES_HOME/AGENTS.md layer to prompt assembly, loaded before project-local AGENTS.md files.

The intent is to complement SOUL.md with a static global instruction layer. It is not meant to replace Hermes memory, and it should not be treated as agent-managed state.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Note: I would almost see it as a bug fix, because users may mistakenly assume that ~/.hermes/AGENTS.md is always loaded.

Changes Made

• load HERMES_HOME/AGENTS.md first in build_context_files_prompt() when present
• keep recursive project-local AGENTS.md loading unchanged
• reuse the existing prompt-injection scan and truncation behavior for the global file
• update docs to describe global AGENTS.md as a user-authored complement to SOUL.md
• add tests for:
  • loading global AGENTS.md
  • ordering: global before project AGENTS.md
  • prompt-injection blocking for global AGENTS.md

Files changed: agent/prompt_builder.py, tests/agent/test_prompt_builder.py, website/docs/user-guide/features/context-files.md

How to Test

1. Create HERMES_HOME/AGENTS.md with recognizable content.
2. Start a Hermes session outside any project with AGENTS.md.
3. Confirm the global AGENTS.md content appears in the assembled project context.
4. Add a project-local AGENTS.md and confirm both are present, with the global content first.
5. Put a known injection string in HERMES_HOME/AGENTS.md and confirm the content is blocked rather than injected.

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: Ubuntu 24.04

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) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

[teknium1]

Thanks for the thoughtful PR! We're going to pass on this one though — SOUL.md already serves as the global user-authored context file, and it's the right place for environment details, homelab setup, persistent instructions, etc.

The current design intentionally keeps these two layers separate:

• SOUL.md → global, loaded every session, user-authored personality + environment + instructions
• AGENTS.md → project-scoped, loaded per working directory, meant for repo/project-specific context

Adding a global ~/.hermes/AGENTS.md would blur that boundary and create confusion about where users should put global instructions. We'd rather keep the single clear answer: if it's global, put it in SOUL.md.

[enzo2]

Makes sense; but I didn't perceive this capability from the docs. It says

Use SOUL.md for: tone, personality, communication style...

Basically a list of things internal or innate to the agent -- so I wouldn't have assumed it should contain things external to Hermes like the environment.