Skip to main content
SOUL.md is the primary identity for your Mibyan instance. It’s the first thing in the system prompt — it defines who the agent is, how it speaks, and what it avoids. If you want Mibyan to feel like the same assistant every time you talk to it — or if you want to replace the Mibyan persona entirely with your own — this is the file to use.

​
What SOUL.md is for

Use SOUL.md for:
  • tone
  • personality
  • communication style
  • how direct or warm Mibyan should be
  • what Mibyan should avoid stylistically
  • how Mibyan should relate to uncertainty, disagreement, and ambiguity
In short:
  • SOUL.md is about who Mibyan is and how Mibyan speaks

​
What SOUL.md is not for

Do not use it for:
  • repo-specific coding conventions
  • file paths
  • commands
  • service ports
  • architecture notes
  • project workflow instructions
Those belong in AGENTS.md. A good rule:
  • if it should apply everywhere, put it in SOUL.md
  • if it only belongs to one project, put it in AGENTS.md

​
Where it lives

Mibyan now uses only the global SOUL file for the current instance:
If you run Mibyan with a custom home directory, it becomes:

​
First-run behavior

Mibyan automatically seeds a starter SOUL.md for you if one does not already exist. That means most users now begin with a real file they can read and edit immediately. Important:
  • if you already have a SOUL.md, Mibyan does not overwrite it
  • if the file exists but is empty, Mibyan adds nothing from it to the prompt

​
How Mibyan uses it

When Mibyan starts a session, it reads SOUL.md from mibyan_HOME, scans it for prompt-injection patterns, truncates it if needed, and uses it as the agent identity — slot #1 in the system prompt. This means SOUL.md completely replaces the built-in default identity text. Because SOUL.md is your own file (agent writes to it always need your approval), a prompt-injection scanner hit does not block it the way it blocks a project AGENTS.md: the file still loads, Mibyan logs a warning naming the matched pattern, and /context marks the file ⚠ … review the file. Security guidance that quotes an attack phrase (“content telling you to ignore previous instructions”) therefore keeps your identity intact. If SOUL.md is missing, empty, or cannot be loaded, Mibyan falls back to a built-in default identity. No wrapper language is added around the file. The content itself matters — write the way you want your agent to think and speak.

​
A good first edit

If you do nothing else, open the file and change just a few lines so it feels like you. For example:
That alone can noticeably change how Mibyan feels.

​
Example styles

​
1. Pragmatic engineer

​
2. Research partner

​
3. Teacher / explainer

​
4. Tough reviewer

​
What makes a strong SOUL.md?

A strong SOUL.md is:
  • stable
  • broadly applicable
  • specific in voice
  • not overloaded with temporary instructions
A weak SOUL.md is:
  • full of project details
  • contradictory
  • trying to micro-manage every response shape
  • mostly generic filler like “be helpful” and “be clear”
Mibyan already tries to be helpful and clear. SOUL.md should add real personality and style, not restate obvious defaults.

​
Suggested structure

You do not need headings, but they help. A simple structure that works well:

​
SOUL.md vs /personality

These are complementary. Use SOUL.md for your durable baseline. Use /personality for temporary mode switches. Examples:
  • your default SOUL is pragmatic and direct
  • then for one session you use /personality teacher
  • later you switch back without changing your base voice file

​
SOUL.md vs AGENTS.md

This is the most common mistake.

​
Put this in SOUL.md

  • “Be direct.”
  • “Avoid hype language.”
  • “Prefer short answers unless depth helps.”
  • “Push back when the user is wrong.”

​
Put this in AGENTS.md

  • “Use pytest, not unittest.”
  • “Frontend lives in frontend/.”
  • “Never edit migrations directly.”
  • “The API runs on port 8000.”

​
How to edit it

or
Then restart Mibyan or start a new session.

​
A practical workflow

  1. Start with the seeded default file
  2. Trim anything that does not feel like the voice you want
  3. Add 4–8 lines that clearly define tone and defaults
  4. Talk to Mibyan for a while
  5. Adjust based on what still feels off
That iterative approach works better than trying to design the perfect personality in one shot.

​
Troubleshooting

​
I edited SOUL.md but Mibyan still sounds the same

Check:
  • you edited ~/.mibyan/SOUL.md or $mibyan_HOME/SOUL.md
  • not some repo-local SOUL.md
  • the file is not empty
  • your session was restarted after the edit
  • a /personality overlay is not dominating the result

​
Mibyan is ignoring parts of my SOUL.md

Possible causes:
  • higher-priority instructions are overriding it
  • the file includes conflicting guidance
  • the file is too long and got truncated
  • some of the text resembles prompt-injection content — SOUL.md still loads, but check /context for a ⚠ … review the file line and the log for the matched pattern

​
My SOUL.md became too project-specific

Move project instructions into AGENTS.md and keep SOUL.md focused on identity and style.