Overview
Give a long-running personal agent four separate files: SOUL.md for who it is, USER.md for who it serves, AGENTS.md for how it operates, and MEMORY.md for what it has learned. As of November 2026 two open-source agent runtimes, OpenClaw and Nous Research’s Hermes Agent, both use this split and load the persona files into the system prompt at every session start. Keep each file small, because every character is paid on every turn: OpenClaw truncates each bootstrap file past 20,000 characters and the set past 60,000, and gives USER.md its own 4,000-character budget. The memory layer has its own page, agent-memory-files.
Put each kind of instruction in exactly one file
Mixing voice, rules, and facts in one prompt file makes every edit risky, because a tone tweak can delete a safety rule. Use this split.
| File | Holds | Written by | Changes |
|---|---|---|---|
SOUL.md | Persona, tone, values, boundaries | The human | Rarely |
IDENTITY.md (OpenClaw) | Name, vibe, emoji | Agent, during first-run bootstrap | Once |
USER.md | The person’s profile and standing preferences | Agent, from what the person says | Replaced in place |
AGENTS.md | Operating rules, tools, how to use memory, project commands | The human | With the workflow |
MEMORY.md | Durable facts the agent learned | Agent | Often |
Hermes states the test in one line: SOUL.md is who the agent is, so “if it should follow you everywhere, it belongs here,” while AGENTS.md is what a project needs. Hermes keeps SOUL.md in ~/.hermes/ and never in the working directory, so a cloned repository cannot swap the agent’s personality.
Write the soul as voice and boundaries, not facts
A soul file describes how the agent behaves across every task. Facts about the user drift and belong in USER.md; procedures belong in skills (claude-code-skills).
# SOUL.md
You are Juno, a terse research assistant for one engineer.
- Answer first, then the evidence. No filler.
- Say "I don't know" before guessing; cite a source for every number.
- Push back when a plan has a flaw; agreement is not the goal.
- Never send messages, spend money, or delete files without asking.Twenty lines is plenty. A role shapes voice and scope; it does not make the model more accurate (role-framing).
Enforce boundaries outside the soul
A boundary in SOUL.md is a request the model usually honors. OpenClaw’s own docs say the workspace is “the default cwd, not a hard sandbox,” and that memory “does not enforce policy.” Back every boundary that matters with a permission rule, an approval gate, or a sandbox (claude-code-permissions, prompt-injection-defense). Treat the soul line as the explanation and the gate as the control.
Keep the soul human-owned and versioned
- Let the agent write
USER.mdandMEMORY.md; route any change toSOUL.mdorAGENTS.mdthrough a human-reviewed diff. An agent that edits its own values drifts, and one poisoned web page can rewrite them (self-improving-agents). - Keep the workspace in a private Git repository, as OpenClaw recommends, so every persona change has a diff and an undo.
- Keep secrets out of every persona file. OpenClaw’s docs say to avoid API keys, OAuth tokens, and passwords “even in a private repo.”
- Load one project instruction file per session. Hermes reads the first of
.hermes.md,AGENTS.md,CLAUDE.md,.cursorrulesand always loadsSOUL.mdseparately; Claude Code’s equivalent is in claude-code-claude-md.
Give each agent its own soul when you run several
Two agents sharing one soul file answer in one voice and blur which one acted. In a multi-agent setup, give each agent its own workspace with its own SOUL.md, and keep the person’s profile and shared knowledge in a place every agent reads but only one writes. The layout is in agent-brains.
Related
- agent-memory-files: what goes in
MEMORY.mdand daily logs. - self-improving-agents: which files an agent may change on its own.
- agent-brains: per-agent workspaces and a main brain.
- role-framing: short role lines and anti-sycophancy rules.
- system-prompts: where persona text sits in the prompt.
- claude-code-claude-md: project instruction files in Claude Code.