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 each session. 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 — and editing them by hand is not just allowed, it’s the intended interface.
The files, one by one
AGENTS.md— operating instructions: rules, priorities, how to behave and how to use memory. Loaded every session.SOUL.md— 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.md— the agent’s name, vibe line, and emoji, written during first-run setup.USER.md— your preferences, communication style, and active projects. Loaded every session with its own 4,000-character budget.MEMORY.mdandmemory/— 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.md— the one-time first-run script (more below).BOOT.md— an optional checklist run on gateway restart.skills/— 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.
How the files become behavior
There’s no hidden machinery: on the first turn of a new session, OpenClaw injects these files into the system prompt’s 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 — 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: nothing went wrong — consuming itself is its job.
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). 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.