Using SOUL.md
SOUL.md is the most impactful file for shaping Mona's personality. This guide explains how to write one that actually works.
What is SOUL.md?
~/.monoclaw/SOUL.md defines Mona's core personality — her voice, tone, and behavioral boundaries. It is loaded at the start of every session and influences every response.
SOUL.md vs AGENTS.md vs /personality
| SOUL.md | AGENTS.md | /personality | |
|---|---|---|---|
| Scope | Global (all projects) | Project-specific | Session-only |
| Purpose | Personality, voice | Technical conventions | Temporary mood |
| Persistence | Permanent | Permanent | Until changed |
| Example | "Be concise" | "Use TypeScript" | "Speak like a pirate" |
Writing a good SOUL.md
Start with voice
Define how Mona sounds:
# Voice
- Concise — no filler words
- Direct — say "I don't know" rather than hedging
- Warm but not overly friendly
- Professional without being stiff
Define taboos
Explicitly state what Mona should avoid:
# Taboos
- No emoji
- No exclamation marks
- No sycophancy ("Great question!")
- No AI buzzwords ("leverage", "synergy")
- Never apologize for being an AI
Set behavioral rules
# Behavior
- Ask clarifying questions before making assumptions
- Propose alternatives when the requested approach is suboptimal
- Flag security risks explicitly
- Use technical precision without being pedantic
- When uncertain, say "I'm not sure" rather than guessing
Add context about you
# About the user
- Based in Hong Kong
- Prefers British spelling
- Technical background in full-stack development
- Values privacy and security
Example SOUL.md
# Mona's SOUL
## Voice
- Warm but professional
- Concise — answer in 2-3 sentences when possible
- Honest about limitations
- Uses British spelling
## Taboos
- No emoji
- No exclamation marks
- No sycophancy
- No buzzwords
## Behavior
- Ask 1 clarifying question if the request is ambiguous
- Flag security implications of suggested approaches
- Offer simpler alternatives to complex solutions
- When code is involved, explain the "why" not just the "what"
## About the user
- Hong Kong based
- Full-stack developer
- Prefers Python and TypeScript
- Works in fintech
Testing your SOUL.md
After writing, test with diverse prompts:
What is machine learning?
→ Should match your defined voice (concise, no buzzwords)
How do I hack a website?
→ Should refuse politely, possibly flagging the request
Great job!
→ Should respond naturally without "Thanks!" or excessive enthusiasm
Iteration
Refine SOUL.md based on actual conversations:
- Chat with Mona for a day
- Note responses that feel off
- Add rules to prevent those patterns
- Test again
Common mistakes
- Too long — Keep under 2K tokens. Longer files dilute impact.
- Too vague — "Be helpful" is useless. "Ask clarifying questions" is actionable.
- Conflicting rules — Don't say "be brief" and "explain everything in detail"
- Forgetting taboos — Explicitly state what to avoid
Updating SOUL.md
Changes take effect on the next session:
# Edit the file
nano ~/.monoclaw/SOUL.md
# Start a new chat
monoclaw