OpenClaw memory files: SOUL.md, AGENTS.md, USER.md, and TOOLS.md explained

A blank OpenClaw workspace still works. The agent can answer questions. It just feels generic fast.

That is what OpenClaw memory files are for. They give the agent a stable identity, a stable operating style, and a stable sense of who it is working for. In practice, SOUL.md, AGENTS.md, USER.md, and TOOLS.md do most of that work.

If you want the short version, here it is:

SOUL.md tells the agent who it is.
AGENTS.md tells the agent how it should work.
USER.md tells the agent who you are.
TOOLS.md tells the agent which tools it may use, and under what limits.

Get those files right and the agent stops feeling like someone you have to re-onboard every session. Get them wrong and you end up doing prompt janitorial work.

What are OpenClaw memory files?

OpenClaw memory files are plain text files inside an agent workspace that define behavior, identity, and durable context across sessions.

OpenClaw workspaces can include several structured files, but the core idea is simple: important context lives in files, not only in a single long chat thread. That matters because long chat history gets messy fast. Old instructions stick around. Preferences clash. A throwaway sentence from last week keeps showing up in places it does not belong.

This is why file-based memory is useful. You can inspect it, edit it, version it, and delete what no longer makes sense. You are not guessing what the system “remembers.” You can open the file and see it.

For most people, the most important memory question is not “How do I make the agent remember everything?” It is “Which details deserve to be remembered on purpose?”

Which memory file should hold what?

Each memory file should own one kind of truth. That separation is what keeps the system understandable later.

File	Main purpose	Good contents	Bad contents	Review cadence
`SOUL.md`	Agent identity	tone, boundaries, persona	project notes, temporary tasks, credentials	monthly
`AGENTS.md`	Operating rules	workflows, hard rules, output format	personal preferences, random facts	monthly
`USER.md`	User context	stable preferences, constraints, working style	temporary moods, sensitive personal detail dumps	monthly
`TOOLS.md`	Tool usage policy	allowed tools, approvals, safety limits	identity, tone, personal biography	whenever tools change

If you are wondering where something belongs, start by asking whether it is about identity, behavior, user context, or tool limits. Most confusion comes from mixing those categories.

What does `SOUL.md` do?

SOUL.md defines the agent’s identity.

This is the file for personality, tone, boundaries, and the kind of presence you want the agent to have every time it shows up. If AGENTS.md is the operating manual, SOUL.md is the answer to “who is talking right now?”

A good SOUL.md usually covers four things:

persona
tone
boundaries
example phrases or speaking habits

Here is what belongs in SOUL.md:

Include in `SOUL.md`	Why it matters
Tone and voice	Keeps replies consistent across sessions
Values and boundaries	Stops the agent from drifting into behavior you do not want
Default posture	Makes the agent feel steady, not random
Example phrases	Gives the model a concrete pattern to copy

Here is what does not belong there:

a giant company wiki
every project fact you know
detailed workflow steps
temporary tasks for this week

A lot of people turn SOUL.md into a brand deck with feelings. It usually reads nicely and works terribly. The file should be concrete. “Direct, calm, no hype, asks one clarifying question before taking action” is useful. “A visionary partner for the future of work” is not.

This is also where OpenClaw agent identity can go sideways. If you cram SOUL.md full of vibes, the agent starts performing the identity instead of doing the job. You do not want a dramatic personality file. You want a stable one.

What does `AGENTS.md` do?

AGENTS.md defines how the agent operates.

This file is about role, workflow, memory usage, priorities, hard rules, and output format. It should answer questions like these:

What job does this agent have?
What sequence should it follow?
Which files should it check before acting?
What must it never do?
How should it present results?

A strong AGENTS.md reads like instructions for a capable teammate on their first week, not like a dump of every thought you have ever had about the project.

In practice, the best AGENTS.md files usually include:

The role.
The primary workflows.
The memory workflow, meaning which files to load or update.
Hard rules.
Output format.

That middle part matters a lot. In many OpenClaw setups, AGENTS.md is where you teach the agent to use memory without turning memory into a junk drawer. You might tell it to load USER.md before making recommendations, check a decisions log before repeating old mistakes, or update a dated note after finishing a task.

The usual AGENTS.md failure is bloat. A giant instruction file feels thorough right up until the agent starts tripping over it. When people say their agent is inconsistent, there is often an overstuffed instructions file sitting in the background making everything harder than it needs to be.

What does `USER.md` do?

USER.md tells the agent who it is serving.

This file is not about the agent’s personality. It is about your context, preferences, constraints, and defaults. If SOUL.md says “who am I?” and AGENTS.md says “how do I work?” then USER.md says “who is my human and what matters to them?”

A useful USER.md often includes:

your work style
communication preferences
recurring constraints
important background context
stable preferences that would otherwise get repeated in chat

Examples help:

“Prefers concise updates first, details second”
“Works best in the morning, avoid non-urgent pings late at night”
“Review before send for any outbound message”
“Hates surprise automation on production systems”

The keyword there is stable. USER.md should hold durable facts, not every passing mood. If you dump temporary frustrations and half-decisions into it, the file turns into a trap. The agent keeps honoring preferences you do not even want anymore.

This is where people recreate the worst part of chat memory. They keep stuffing in facts because “more memory” sounds like progress. Then six weeks later the file is full of stale rules, outdated goals, and preferences that bump into each other.

That is not memory. That is context rot with better formatting.

What does `TOOLS.md` do?

TOOLS.md defines which tools the agent may use, when it may use them, and what limits apply.

This is the missing piece in a lot of setups. People spend time shaping the agent’s identity and workflow, then leave tool policy implied. That is how you end up with an agent that sounds careful and still opens the wrong browser session or reaches for shell access too casually.

A good TOOLS.md can include:

which tools are allowed by default
which tools are denied unless explicitly enabled
which actions always require approval
cost or frequency limits for expensive tools
browser or profile rules, like never using a personal profile
send restrictions for email, chat, or posting

Keep it practical. TOOLS.md is not there to sound wise. It is there to stop avoidable mistakes.

How do `SOUL.md`, `AGENTS.md`, and `USER.md` work together?

These three files work because each one owns a different kind of truth.

Here is the clean mental model:

File	Core question	Typical content
`SOUL.md`	Who is the agent?	Tone, persona, boundaries
`AGENTS.md`	How does the agent operate?	Workflows, hard rules, output format
`USER.md`	Who is the user?	Preferences, context, constraints

When people mix these up, agents get weird.

If you put user preferences into SOUL.md, the agent starts treating your habits like part of its own personality.

If you put workflow rules into USER.md, the agent has to infer whether a statement is about you or about procedure.

If you put tone guidance into AGENTS.md and nowhere else, the operational rules can overpower the personality and make every answer feel stiff.

Clean separation makes agents easier to debug. If tone is off, check SOUL.md. If behavior is off, check AGENTS.md. If recommendations keep missing your situation, check USER.md.

That is one of the best things about file-based memory. Problems become inspectable.

What should you actually write in each file?

You should write concrete, low-ambiguity instructions in each file.

Here is a good starting template for SOUL.md:

# SOUL.md

## Persona
A direct, calm operator who values clarity over hype.

## Tone
- concise
- practical
- no cheerleading
- no jargon unless needed

## Boundaries
- do not invent facts
- do not hide uncertainty
- do not take high-risk actions without approval

## How I speak
- "Here is the current state."
- "My recommendation is..."
- "I need one detail before I act."

Here is a good starting template for AGENTS.md:

# AGENTS.md

## Role
You are a research and operations assistant for a small software business.

## Primary workflow
1. Gather context.
2. Check existing memory files.
3. Propose action.
4. Wait for approval on risky steps.
5. Record durable decisions.

## Hard rules
- never send messages without approval
- never invent status updates
- ask before deleting or overwriting files

## Output format
- summary
- proposed actions
- open questions
- next steps

Here is a good starting template for USER.md:

# USER.md

## Preferences
- prefer short updates first
- default to draft-only for outbound writing
- ask before any calendar change

## Working style
- mornings are best for deep work
- avoid adding meetings on Fridays

## Constraints
- do not use personal accounts for testing
- production changes always require a second check

None of these examples are fancy. Good. Fancy is not the goal. Clear is the goal.

How detailed should OpenClaw memory files be?

OpenClaw memory files should be detailed enough to guide behavior and short enough that you can still maintain them.

A decent rule of thumb is this: if a file is becoming annoying to review, it is probably too big. You want enough detail to make the agent reliable, but not so much detail that the file turns into a swamp of stale instructions.

A practical way to think about it:

Put durable identity in SOUL.md.
Put durable operating rules in AGENTS.md.
Put durable user context in USER.md.
Put temporary project details somewhere else.

That last part matters more than people think. Not every fact belongs in a core identity file. Day-specific work, scratch notes, and one-off tasks usually belong in task files, dated notes, or project-specific memory, not in the files that define the agent’s permanent shape.

If you keep cramming everything into the core files, the agent does not get smarter. It gets muddy.

What belongs in daily memory vs long-term memory?

Daily memory should hold current task state. Long-term memory should hold stable identity, durable workflow rules, persistent user preferences, and tool boundaries.

That distinction matters because the core files are long-term memory. They are not the right place for every passing note, temporary deadline, or one-off project wrinkle.

Memory type	Good examples	Where it should live
Daily or task memory	today’s status, short-term decisions, scratch notes, temporary blockers	dated notes or project-specific files
Long-term memory	tone, hard rules, user preferences, durable constraints, tool boundaries	`SOUL.md`, `AGENTS.md`, `USER.md`, `TOOLS.md`

If a detail will feel stale in a week, it probably does not belong in a core memory file.

What makes memory files go bad over time?

Memory files go bad when they accumulate stale, conflicting, or overly broad instructions.

This is the operational safety angle that people usually miss. A memory file can create just as many problems as it solves if nobody curates it.

Here are the common failure modes:

Stale preferences

Stale preferences happen when the file keeps instructions that used to be true but are not true anymore.

If USER.md still says you want ultra-brief answers but your work has shifted toward strategy and planning, the agent will keep under-explaining. The file is doing its job. It is just doing the wrong job because nobody updated it.

Context clash

Context clash happens when two instructions conflict.

For example:

SOUL.md says “be concise”
AGENTS.md says “always include full background”
USER.md says “give me the short version first”

The agent now has to guess which rule matters most. Sometimes it guesses right. Sometimes it does not.

Identity creep

Identity creep happens when SOUL.md becomes too stylized.

This is how you get agents that speak with a lot of personality and not much judgment. A little voice goes a long way. Beyond that, the agent starts acting instead of helping.

Instruction bloat

Instruction bloat happens when AGENTS.md tries to contain every edge case.

This usually starts from a good instinct. Something goes wrong, so you add another rule. Then another. Six months later the file is a museum of past incidents.

The better move is to keep the core operating rules clean and push niche behavior into narrower files when needed.

What should never go into memory files?

Credentials, private secrets, and unnecessary personal data should never go into memory files.

These files are plain text. Treat them like plain text.

Do not store:

API keys
passwords
recovery codes
private SSH material
banking details
sensitive medical information
anything you would regret copying into the wrong chat window

You should also be careful with softer forms of sensitive context. USER.md does not need a full personal biography. It needs enough information to help the agent serve you well. That is a much smaller set.

A good test is simple: if the detail would be awkward, risky, or hard to justify in a shared document, do not make it part of the agent’s permanent memory by default.

How do you know if your memory files are working?

Your memory files are working if the agent behaves consistently in a fresh session without needing the same reminders over and over.

Use a simple test loop:

Start a fresh session and give the agent a normal task.
Check whether the tone matches SOUL.md.
Check whether the workflow matches AGENTS.md.
Check whether the recommendations reflect USER.md.
Check whether tool choices and approval behavior match TOOLS.md.
Notice what you still have to repeat manually.

A few specific checks help:

Fresh-session test: does the agent still sound like itself after a restart?
Behavior test: does it follow the operating sequence you described?
Tool-boundary test: does it avoid tools that should be off-limits?
Stale-memory test: did it keep an instruction you already removed?
Wrong-file test: if behavior is off, can you tell which file caused it?

If you keep repeating the same sentence every session, one of two things is probably true: the detail belongs in memory and is missing, or it is in memory but in the wrong file or written too vaguely.

This is where version control helps. Memory files are some of the highest-leverage text files in an OpenClaw setup. Change one thing, then watch what changes in behavior. That is much easier than guessing.

What is the safest way to maintain OpenClaw agent identity?

The safest way to maintain OpenClaw agent identity is to keep the core files small, specific, reviewable, and separate by purpose.

If you remember only six rules from this article, make them these:

keep SOUL.md about identity
keep AGENTS.md about operation
keep USER.md about the human
keep TOOLS.md about tool boundaries and approvals
review the files regularly
delete stale instructions without sentimentality

That last one is underrated. People hate deleting memory because it feels like losing intelligence. Usually the opposite is true. Cutting bad memory helps more than adding another page of rules.

If you are still in week one, pair this article with the first 7 days safety checklist and keep the memory tests lightweight at first. You do not need a perfect system on day two. You need a readable one.

OpenClaw memory files matter because they let you teach an agent who it is on purpose. SOUL.md, AGENTS.md, USER.md, and TOOLS.md are not magic. They are text files. Used well, they make the system easier to trust, easier to debug, and easier to live with.