Why Your SOUL.md Is Making Your Agent Dumber (And How to Fix It)

There's a point where your OpenClaw agent stops getting smarter and starts getting dumber. You added more to SOUL.md — more personality, more context, more rules — and somewhere along the way it crossed a line. Responses got slower. Instructions got ignored. The agent started hedging on things it used to handle confidently.

This is the dumb zone. And the most common cause is a bloated SOUL.md.

What the Dumb Zone Actually Is

Your SOUL.md loads into the system prompt on every single request. Every word in it competes for space with the actual task the agent is trying to do. When SOUL.md is lean and focused, the model has plenty of room to reason about your request. When it's stuffed with backstory, redundant rules, and personality traits that never come up, you're handing the model a cluttered desk and expecting clean output.

The effect compounds. A 400-word SOUL.md is fine. An 800-word one might be OK. But once you're past 1,200 words of system prompt weight — especially with a model that has a relatively small effective reasoning window — you'll start seeing degraded behavior. The model isn't ignoring your instructions. It's drowning in them.

Concretely: a 1,200-word SOUL.md is roughly 1,600 tokens. At a typical 200K context window, that sounds like nothing — but the effective attention window where the model actually reasons well is much smaller, and every token in SOUL.md is paid on every single turn. Across a 30-step task, a 1,600-token SOUL.md adds up to ~48,000 tokens of repeated cost that produces zero new information.

LangChain co-founder Harrison Chase identified this problem in April 2026, naming OpenClaw's SOUL.md as the canonical example of agent-level context learning — but also flagging that the mechanism only works when the content stays curated. Community creators like BoxminingAI and Openclaw Labs have been independently rediscovering it.

Measure your own SOUL.md right now

Before you can fix it, see how heavy yours is:

# Word count
wc -w SOUL.md

# Character count (rough proxy when no tokenizer is handy)
wc -c SOUL.md

# Token count (most accurate — install tiktoken)
python3 -c "import tiktoken; print(len(tiktoken.get_encoding('cl100k_base').encode(open('SOUL.md').read())))"

Read the result against this scale:

• Under 300 words / ~400 tokens — lean. Keep it that way.
• 300–800 words / ~400–1,100 tokens — fine, but audit before you add more.
• 800–1,200 words / ~1,100–1,600 tokens — caution zone. Start moving content out.
• Over 1,200 words / ~1,600+ tokens — you're in the dumb zone. Refactor now.

The Three Ways SOUL.md Gets Bloated

1. Personality creep

You start with a one-paragraph personality description. Then you add tone guidelines. Then examples of how the agent should respond. Then examples of how it shouldn't respond. By the time you're done, the personality section alone is 600 words.

Most of this never fires in practice. The agent doesn't need a five-paragraph essay about its communication style — it needs three clear sentences. Here's the typical bloat pattern:

## Personality
You are warm but professional, friendly but not overly casual, helpful
but not sycophantic, direct but not abrupt, technical but accessible,
patient but efficient, curious but focused...

## Communication Style
- Use contractions to sound natural
- Avoid corporate jargon
- Don't be too formal
- But also don't be too casual
- Match the user's energy level
- Use emojis sparingly (but use them sometimes)
- Lead with the answer
- ...18 more bullet points...

## Example Responses
User: "How do I deploy this?"
Bad: "Hello! I would be delighted to help you deploy..."
Good: "Run `openclaw deploy`. Add --dry-run first if you want..."
[12 more before/after examples]

That's 400+ words explaining a personality the model can express in three sentences. Cut it to: "Direct and practical. Lead with the answer, not the preamble. Match the user's level of technical depth."

2. Rule accumulation

Every time the agent does something wrong, you add a rule to SOUL.md. "Never do X." "Always do Y first." "If Z happens, respond with W." Over weeks, this turns into a dense legal document. The agent can't hold all of it in effective working memory, so it pattern-matches on the ones that feel most recent or most prominent — and drops the rest.

Watch for SOUL.md sections that look like this:

## Rules
1. Never call delete-user without confirmation
2. Always check git status before running git push
3. If the user mentions production, ask for double confirmation
4. Never write to /etc without sudo and confirmation
5. Always summarize changes before applying them
...rules 6 through 47...

Operational rules belong in AGENTS.md, not SOUL.md. SOUL.md keeps only the hard, never-cross-this lines (a max of 4–6 of them). Everything procedural — "first do X, then Y, then Z" — moves out.

3. Context that belongs somewhere else

Background about the business, long lists of product features, historical context about previous decisions — none of this belongs in SOUL.md. It belongs in USER.md, MEMORY.md, or a dedicated reference file the agent loads only when it needs it. Putting it all in SOUL.md means the agent carries that weight on every single call, whether it's relevant or not.

The litmus test: if a paragraph wouldn't matter for most of the agent's interactions, it doesn't belong in the always-on system prompt.

How to Diagnose Your SOUL.md

Open your SOUL.md and ask three questions about every paragraph:

1. Does this affect every interaction, or only specific ones?
2. Would the agent behave incorrectly without this sentence? (Try removing it and see.)
3. Is this already implied by something else in the file?

If the answer to any of these points toward "this doesn't need to be here," cut it. Ruthlessly. A good SOUL.md is 150–300 words. The best ones are under 200.

You can also test empirically. Strip 30% of the content, run the agent on your three most common task types, and compare:

# Save current SOUL.md
cp SOUL.md SOUL.md.bak

# Create the slim version
$EDITOR SOUL.md   # cut everything you flagged

# Run a regression test with both versions
openclaw agent --message "your typical task 1" --agent main
openclaw agent --message "your typical task 2" --agent main
openclaw agent --message "your typical task 3" --agent main

If the slim version handles all three tasks correctly, the cut content wasn't doing anything useful anyway.

The Fix: Redistribute, Don't Just Trim

Cutting content isn't always the right move — sometimes you need that context, just not in SOUL.md. Here's where things belong:

• SOUL.md — Core identity, mission statement, tone in 3–5 sentences, hard behavioral boundaries (what the agent will never do), and the security guardrails that apply to every action. Loaded on every call.
• USER.md — Who the human is, their preferences, their context. The agent reads this to understand who it's talking to, not what it is. Loaded on every call.
• MEMORY.md — Facts that accumulate over time — previous decisions, things the agent learned, preferences that emerged. Index file loaded; individual entries loaded on demand.
• AGENTS.md — Operational rules — how to handle specific tasks, what tools to use when, how memory works. Loaded on every call, but kept tight.

Here's the AGENTS.md pattern for moving operational rules out of SOUL.md:

# AGENTS.md

## Task: deploy
- Always run `openclaw doctor` first
- Confirm with user before pushing to production
- Run `git status` before any commit

## Task: refactor
- Read the relevant files first; never edit blind
- Show the user a diff before applying
- Run tests before declaring done

## Task: customer-email
- Draft first; never send without explicit "send it" from user
- Use signature block from /home/user/.signature

Each task block is a small, focused operating manual. SOUL.md just says who you are; AGENTS.md says how to do specific things.

This separation keeps each file focused and ensures the model only loads heavy context when it's actually relevant. Your AGENTS.md setup handles the task-specific logic so SOUL.md can stay lean.

A Lean SOUL.md Template

Here's what a properly scoped SOUL.md looks like:

# SOUL.md

## Who You Are
You are [Name], a [role] for [organization]. Your job is [specific
mission in one sentence].

## How You Work
- Direct and practical. No filler.
- Ask for clarification before taking irreversible actions.
- When in doubt, do less and confirm with the user.

## What You Never Do
- You never execute commands that modify production systems
  without explicit approval.
- You never store API keys, passwords, or credentials in any file.
- You never send external communications without reviewing the
  content with the user first.

## Tone
Professional but not formal. Write like a knowledgeable colleague,
not a corporate document.

That's it. 117 words. About 150 tokens. Everything else — task procedures, tool configs, memory rules — lives in the appropriate file.

This is exactly the structure that OpenAgents.mom's wizard generates. The OpenClaw workspace files explained post covers the full bundle in detail, but the short version is: each file has a job, and SOUL.md's job is narrow by design.

Before / After: A Real Refactor

Here's the diff from a real SOUL.md that crossed into the dumb zone, showing the cuts:

 # SOUL.md - Project Manager Agent

 ## Identity
 You are PMA, a project management assistant for the engineering team.

-## Personality
-You are warm and friendly but also professional. You communicate
-clearly and concisely. You are patient with newcomers and efficient
-with veterans. You celebrate wins and offer support during setbacks.
-You ask thoughtful follow-up questions. You never use excessive
-emojis but you do use them sparingly. You match the user's energy.
-...
-(420 more words of personality description)

+## How You Work
+- Direct and clear. Lead with the answer.
+- Match the user's level of technical depth.

-## Rules (47 total)
-1. Never close a sprint without retro notes
-2. Always confirm story point estimates before saving
-3. If a user mentions a deadline, immediately check the timeline
-...
-(45 more rules)
+(moved to AGENTS.md)

-## Project History
-The project started in March 2024 when... [870 words]
+(moved to MEMORY.md/project-history.md, loaded on demand)

 ## What You Never Do
 - Never close a sprint without explicit user confirmation.
 - Never modify the canonical project plan without sign-off.
 - Never share customer data outside the team workspace.

Before: 1,847 words, ~2,400 tokens. After: 184 words, ~240 tokens. 10x reduction, with no loss of agent capability — the operational rules and project history are still there, just in the right files.

What Happens When You Fix It

The improvement is usually immediate. Agents that were ignoring instructions start following them. Response times drop because the model spends less time processing irrelevant context. You get more consistent behavior across different request types because the signal-to-noise ratio in the system prompt improved.

Specific things to expect after a refactor:

• Faster first-token latency — less prompt to process means the model starts responding sooner.
• More instruction-following — the model isn't dropping rules to make room for the actual task.
• Lower per-turn cost — fewer repeated tokens across long sessions adds up fast on metered models.
• Easier debugging — when something goes wrong, the relevant rules are in a small, scannable file.

The deeper benefit is maintainability. A 180-word SOUL.md is easy to audit, easy to update, and easy to understand. A 1,400-word one is a liability — every edit risks unintended side effects, and debugging degraded behavior becomes a guessing game.

This is one of the core lessons from the MCP context bloat problem: more context is not always better context. The agents that perform best in production are the ones with lean, well-structured prompts and memory systems that load context on demand.

The Fastest Fix

If you want to rebuild your SOUL.md from scratch with a lean structure that won't hit the dumb zone, the OpenAgents.mom wizard generates a correctly scoped SOUL.md as part of the full workspace bundle. It enforces the 150–300 word target, separates identity from operational rules, and includes the security guardrails by default.

You're not buying a template — you're getting the right separation of concerns baked in from the start.