Externalizing Agent Decisions to Files: How a Three‑Layer Prompt Architecture Drives Behavior

Hermes treats the location of an agent's behavior decisions as a core design question and proposes to externalize every rule into human‑readable files instead of hard‑coding them in source code.

Why externalize decisions?

Hard‑coded system prompts are simple but become problematic as agents grow: they are immutable (changing a rule requires code changes and redeployment), opaque (the rule is hidden inside a string), and non‑isolated (the same prompt cannot be customized per project). Externalizing rules into files makes the agent's behavior transparent and directly editable by users.

How the industry handles this

AutoGPT stores name, role, and goals in ai_settings.yaml but keeps core behavior logic in Python.

LangChain uses PromptTemplate to inject variables, yet the template itself lives in code and is fetched from the LangChain Hub.

Claude Code and Cursor recognize CLAUDE.md and .cursorrules respectively, achieving project‑level behavior customization.

Hermes builds on the latter idea and extends it to the agent’s identity and memory layers.

Hermes' three‑layer file architecture

stable layer

This layer never changes during a session, ensuring maximum prefix‑cache hit rates. It contains: SOUL.md: defines the agent’s identity and personality.

Tool usage guidance.

Skills catalog.

Runtime hints (OS, working directory, etc.).

Because the stable portion stays constant, Anthropic’s prompt‑caching can reduce token‑calculation cost by about 90%.

context layer

Loaded per project directory, it isolates behavior across repositories. The priority chain is:

.hermes.md   → highest priority, searched upward to the git root
AGENTS.md    → generic project rules (cwd only)
CLAUDE.md    → Claude Code rules (cwd only)
.cursorrules → Cursor rules (cwd only)

Running cd ~/projects/my-backend && hermes loads the rules under my-backend, while cd ~/docs && hermes loads the rules under docs. Thus the same Hermes instance can exhibit completely different behavior in different projects.

volatile layer

Changes every turn and is placed at the end of the system prompt so it does not affect cache hits. It includes: MEMORY.md: a snapshot of the agent’s memory, writable by the agent. USER.md: user profile (preferences, background).

Current timestamp.

Source‑level details

SOUL.md loading

def load_soul_md():
    soul_path = get_hermes_home() / "SOUL.md"
    content = soul_path.read_text(encoding="utf-8").strip()
    content = _scan_context_content(content, "SOUL.md")  # inject scanning
    content = _truncate_content(content, "SOUL.md")   # truncate >20K chars
    return content

If ~/.hermes/SOUL.md does not exist, Hermes seeds a default version:

DEFAULT_SOUL_MD = (
    "You are Hermes Agent, an intelligent AI assistant created by Nous Research. "
    "You are helpful, knowledgeable, and direct. ..."
)

Context file priority implementation

def build_context_files_prompt(cwd=None, skip_soul=False):
    project_context = (
        _load_hermes_md(cwd_path)      # 1. .hermes.md (search upward to git root)
        or _load_agents_md(cwd_path)   # 2. AGENTS.md (cwd only)
        or _load_claude_md(cwd_path)   # 3. CLAUDE.md (cwd only)
        or _load_cursorrules(cwd_path) # 4. .cursorrules (cwd only)
    )

Only .hermes.md is searched upward; the other files are confined to the current directory to avoid rule leakage.

Truncation strategy

# Truncate: keep first 10K + last 5K, insert "[...truncated...]" marker

Security scanning of external files

External files are trusted but validated before injection. The scanner looks for known prompt‑injection patterns such as "ignore previous instructions" or "you are now" and either sanitizes or rejects the content.

def _scan_context_content(content: str, source: str) -> str:
    # Detect known prompt‑injection patterns
    # "ignore previous instructions", "ignore all instructions",
    # "you are now", "act as", "pretend you are", etc.
    # If found, purge risky paragraph or reject injection
    ...

This validation applies to all external files: SOUL.md, AGENTS.md, MEMORY.md, and USER.md.

Cache economics

The fixed stable layer sits at the front of the prompt, guaranteeing that the prefix cache hits remain above 90 %. Only the volatile layer changes each turn, so the Anthropic API can reuse cached tokens for long conversations (100+ turns), saving 60‑80 % of system‑prompt token computation cost.

Summary of principles

Transparency : All behavior rules live in files that anyone can read without digging into code.

Controllability : Users edit SOUL.md, AGENTS.md, or MEMORY.md to modify identity, project rules, or memory respectively.

Cache economics : The three‑layer separation maximizes prefix‑cache efficiency while keeping per‑turn flexibility.

Future articles will explore Hermes' ACP protocol adaptation for cross‑framework agent communication.