SOUL.md, IDENTITY.md, USER.md: the files that make your agent

The files, one by one

• AGENTS.md holds the operating instructions: rules, priorities, how to behave and how to use memory. Loaded every session.
• SOUL.md is 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 is the agent’s name, vibe line, and emoji, written during first-run setup.
• USER.md is your preferences, communication style, and active projects. Loaded every session with its own 4,000-character budget.
• MEMORY.md and memory/ 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.md is the one-time first-run script (more below). BOOT.md is 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.

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, 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.