What exactly is the difference between AGENTS.md and SOUL.md

[oak condor]

As titled. I see a lot of overlap between the "precinct" of these two files.

[merry aurora]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[sinful orbit]

Short version:

• AGENTS.md = the agent’s operating manual
• SOUL.md = the agent’s personality layer

A good rule of thumb:

• Put what it should do in AGENTS.md

  • standing orders
  • workflow
  • memory habits
  • permissions / red lines
  • task behavior

• Put how it should feel in SOUL.md

  • tone
  • humor

• bluntness
  • opinions
  • vibe / voice

So yeah, there’s some overlap, but the split is basically:

• AGENTS.md: behavior, policy, responsibilities
• SOUL.md: style, stance, personality

One important nuance: subagents only get AGENTS.md + TOOLS.md, not SOUL.md, so anything mission-critical should live in AGENTS.md.

Docs back this up pretty directly:

• AGENTS.md = “operating instructions + memory”
• SOUL.md = “persona, boundaries, tone”

Refs:

• https://docs.openclaw.ai/concepts/agent-workspace

• https://docs.openclaw.ai/concepts/soul

If you want, I can also give a few concrete examples of “this belongs in AGENTS” vs “this belongs in SOUL”.

[oak condor]

Where should I put this: **Language:** The user is very particular about the language used for responses. **CRITICAL:** Always detect the primary language of the user's most recent message and respond exclusively in that language. If the user's most recent message is primarily in English, always respond in English. If the user's most recent message is primarily in Hindi, always respond in Hindi. ? ... or should i put this into both?

[sinful orbit]

Put that in AGENTS.md, not both.

Why:

• it’s a hard response rule
• it changes behavior, not personality
• and if you ever use subagents, AGENTS.md carries over, SOUL.md usually doesn’t

I would not duplicate it in both files, because duplicated rules drift and can conflict.

I’d also tighten the wording a bit, like:

## Language
- Respond in the primary language of the user's most recent message.
- If the latest message is primarily English, respond in English.
- If the latest message is primarily Hindi, respond in Hindi.