Sókrates Wiki

Hermes Context Discovery and Priority System

3 min read

Hermes Context Discovery and Priority System

Summary

The Hermes Agent employs a deterministic hierarchy and discovery logic to load project-specific instructions and global personality traits from the filesystem. This system ensures that the agent adapts its behavior based on the working directory while maintaining a consistent identity via the SOUL.md configuration.

Details

The Hermes Agent utilizes a structured discovery mechanism to ingest context and instructions from the local filesystem. This system is designed to provide the agent with relevant project details, coding standards, and architectural constraints without manual intervention. The discovery process distinguishes between project-local context and global agent identity.

Project Context Priority

Project context is determined by a strict priority hierarchy. During a session, Hermes searches for specific files and loads only the first match it encounters in the following order:

  1. .hermes.md / HERMES.md: These are the highest priority project instructions. The agent discovers these by walking up the directory tree from the current working directory (CWD) to the git root.
  2. AGENTS.md: This file is used for project instructions, conventions, and architecture. It supports a hierarchical discovery model, making it ideal for monorepos. Hermes walks the directory tree from the CWD and loads all instances of AGENTS.md, sorting them by depth to build a layered understanding of the project.
  3. CLAUDE.md: Context files compatible with Claude Code, loaded only if present in the CWD.
  4. .cursorrules: Coding conventions used by the Cursor IDE, loaded only from the CWD.

If a higher-priority file is found (e.g., .hermes.md), the lower-priority files (e.g., .cursorrules) are ignored for that session to prevent conflicting instructions.

Hierarchical Discovery and Exclusions

When searching for AGENTS.md files, Hermes recursively walks the directory structure. To maintain performance and avoid irrelevant data, the agent explicitly skips specific directories:

  • Hidden directories (prefixed with .)
  • node_modules
  • __pycache__
  • Virtual environments (venv, .venv)

Global Identity via SOUL.md

While project context changes based on the working directory, the agent’s personality, tone, and communication style are governed by a global SOUL.md file. This file is loaded independently of the project context and is always injected into the agent’s prompt.

  • Location: SOUL.md is loaded exclusively from HERMES_HOME (typically ~/.hermes/SOUL.md). It is not discovered via the project directory walk.
  • Initialization: If SOUL.md is absent, Hermes automatically creates a default version to ensure the agent has a baseline personality.
  • Injection: Non-empty content from SOUL.md is injected verbatim into the agent’s system prompt after being scanned and truncated to fit context window constraints.

Cursor Compatibility

Hermes is designed to be compatible with existing developer workflows. It supports both the standard .cursorrules file and the modular .cursor/rules/*.mdc rule modules. These are treated as project context and are loaded if no higher-priority Hermes-specific files are present in the CWD.

Graph View

Backlinks