Agent Context and Personality Configuration (AGENTS.md and SOUL.md)
Summary
The Sokrates project utilizes a dual-file configuration system to govern AI agent behavior: AGENTS.md for project-specific technical constraints and SOUL.md for persistent personality traits. These files are automatically injected into agent sessions to provide consistent context without manual prompting.
Details
To ensure that AI agents (such as the Hermes Agent or Claude Code sessions) adhere to specific architectural standards and maintain a consistent persona, the Sokrates environment implements a hierarchical context injection system. This system relies on two primary markdown files: AGENTS.md and SOUL.md.
AGENTS.md: Project-Specific Context
The AGENTS.md file serves as the “brain” of a specific project or directory. It is designed to store recurring instructions, coding style preferences, API endpoints, and testing frameworks. When an agent session starts, the system automatically reads and injects the contents of this file into the prompt context.
Key features of AGENTS.md include:
- Hierarchical Discovery: In monorepos or complex directory structures, the system performs hierarchical discovery. It searches for
AGENTS.mdfiles throughout the directory tree, from the root down to the current working directory. - Concatenation: If multiple
AGENTS.mdfiles are found (e.g., one at the organization root and one in a specific service subdirectory), their contents are concatenated. This allows for global conventions to be defined at the top level while specific team or service rules are defined locally. - Typical Content: Common entries include technology stack definitions (e.g., “FastAPI backend with SQLAlchemy ORM”), operational constraints (e.g., “Always use async/await”), and security policies (e.g., “Never commit .env files”).
SOUL.md: Agent Personality
While AGENTS.md focuses on what the agent does and how it codes, SOUL.md defines who the agent is. This file establishes a stable default voice and persona for the Hermes Agent.
- Location: Typically stored in
~/.hermes/SOUL.mdor a custom path defined by the$HERMES_HOMEenvironment variable. - Persona Definition: It contains instructions regarding the agent’s tone, verbosity, and professional identity. For example, a
SOUL.mdmight instruct the agent to act as a “senior backend engineer” who is “terse and direct,” preferring one-liners and prioritizing error handling over verbose explanations. - Durability: Unlike project-specific rules, the “Soul” is intended to be a durable personality that persists across different projects.
Implementation Constraints
Because these files are injected into every message or session start, they consume part of the LLM’s token budget. The system guidelines emphasize keeping these files concise. Every character counts against the context window, and overly verbose configuration files can limit the agent’s ability to process large codebases or long conversation histories.