SOUL.md, IDENTITY.md, USER.md: the files that make your agent
OpenClaw's identity and memory are plain markdown injected into the system prompt on every run. What each file does, the truncation budgets, and why editing them is the point.
Your agent’s personality, rules, and memory are plain markdown files in its workspace (~/.openclaw/workspace by default). SOUL.md is voice and boundaries, IDENTITY.md is name and vibe, USER.md is what it knows about you, AGENTS.md is operating rules, MEMORY.md is long-term memory. They’re injected into the system prompt at the start of every session. Editing them by hand is not just allowed, it’s the intended interface.
For documents you want the agent to work on, rather than files that govern its behavior, see how to share files with OpenClaw and receive the finished work.
The files, one by one
AGENTS.mdholds the operating instructions: rules, priorities, how to behave and how to use memory. Loaded every session.SOUL.mdis persona, tone, and boundaries. The docs’ own advice draws the line well: operating rules go in AGENTS.md; voice, stance, and style live here.IDENTITY.mdis the agent’s name, vibe line, and emoji, written during first-run setup.USER.mdis your preferences, communication style, and active projects. Loaded every session with its own 4,000-character budget.MEMORY.mdandmemory/are curated long-term memory plus one dated log file per day. MEMORY.md only loads in the agent’s main private session, deliberately not in group contexts, so your agent doesn’t recite your life into a shared channel.BOOTSTRAP.mdis the one-time first-run script (more below).BOOT.mdis an optional checklist run on gateway restart.skills/holds workspace-local skills, the highest-precedence skill location.
One freshness note, since older guides still cite it: TOOLS.md is retired: tool and environment notes now belong in a ## Tools section of AGENTS.md, and openclaw doctor --fix archives the old file.
The layout has travelled beyond OpenClaw: Meta’s Muse agent keeps files it calls Soul.md, Identity.md and Memory.md, and the head of product at Meta Superintelligence Labs has said OpenClaw’s creator “got those things exactly right.”
How the files become behavior
There’s no hidden machinery: OpenClaw rebuilds the system prompt on every run and injects these files into its Project Context. That’s the whole trick, which is why editing a file changes the agent, and why the docs’ line about memory is worth framing: the model only remembers what gets saved to disk; there is no hidden state. The practical corollaries: a missing file injects a one-line marker rather than breaking anything; blank files are skipped; and big files get truncated, at roughly 20,000 characters per file and 60,000 total by default (configurable via agents.defaults.bootstrapMaxChars), with USER.md’s separate 4,000-character cap. An agent whose SOUL.md has grown into a novel is quietly losing the end of it.
BOOTSTRAP.md: the file that deletes itself
A brand-new workspace gets one extra file. BOOTSTRAP.md scripts the first conversation (the community calls it hatching; the docs say “birth sequence”), a deliberately short ritual: the agent asks what you want to call it, offers a one-line sense of self, asks about plugin preferences. The answers get written into IDENTITY.md and SOUL.md, and then the agent deletes BOOTSTRAP.md so the ritual can never run again. If you ever wondered what happened to that file: consuming itself is its job. On OpenClaw 2 there is a second way it goes. The nightly dreaming run creates a memory/ folder, a workspace with one counts as configured, and an agent nobody has spoken to by its first 03:00 drops the file without the ritual ever running; the identity files then stay on their templates until you edit them.
Edit them, with two habits
These files are yours to edit with any text editor, and the docs treat rewriting SOUL.md by hand as the normal way to reshape an agent’s voice. Your agent edits them too: tell it “remember I prefer short answers” and it writes the note to the right file itself. Two habits keep this healthy. First, version the workspace: OpenClaw auto-initializes it as a git repository, and the official recommendation is a private remote as backup (the deploy-key pattern works well for this; note the repo belongs to the agent’s user, so inspecting it as root trips git’s “dubious ownership” guard). Second, keep secrets out: identity files travel into every session’s prompt and into every backup, which is exactly where API keys shouldn’t live. Where the workspace sits in the larger directory layout (config, sessions, credentials) is its own map.
Because the character lives in these files, it outlasts any one model: what a model switch changes and what it keeps is its own guide.