Skip to main content
Mibyan’s personality is fully customizable. SOUL.md is the primary identity — it’s the first thing in the system prompt and defines who the agent is.
  • SOUL.md — a durable persona file that lives in mibyan_HOME and serves as the agent’s identity (slot #1 in the system prompt)
  • built-in or custom /personality presets — session-level system-prompt overlays
If you want to change who Mibyan is — or replace it with an entirely different agent persona — edit SOUL.md.

​
How SOUL.md works now

Mibyan now seeds a default SOUL.md automatically in:
More precisely, it uses the current instance’s mibyan_HOME, so if you run Mibyan with a custom home directory, it will use:

​
Important behavior

  • SOUL.md is the agent’s primary identity. It occupies slot #1 in the system prompt, replacing the hardcoded default identity.
  • Mibyan creates a starter SOUL.md automatically if one does not exist yet
  • Existing user SOUL.md files are never overwritten
  • Mibyan loads SOUL.md only from mibyan_HOME
  • Mibyan does not look in the current working directory for SOUL.md
  • If SOUL.md exists but is empty, or cannot be loaded, Mibyan falls back to a built-in default identity
  • If SOUL.md has content, that content is injected verbatim after security scanning and truncation
  • SOUL.md is not duplicated in the context files section — it appears only once, as the identity
That makes SOUL.md a true per-user or per-instance identity, not just an additive layer.

​
Why this design

This keeps personality predictable. If Mibyan loaded SOUL.md from whatever directory you happened to launch it in, your personality could change unexpectedly between projects. By loading only from mibyan_HOME, the personality belongs to the Mibyan instance itself. That also makes it easier to teach users:
  • “Edit ~/.mibyan/SOUL.md to change Mibyan’ default personality.”

​
Where to edit it

For most users:
If you use a custom home:

​
What should go in SOUL.md?

Use it for durable voice and personality guidance, such as:
  • tone
  • communication style
  • level of directness
  • default interaction style
  • what to avoid stylistically
  • how Mibyan should handle uncertainty, disagreement, or ambiguity
Use it less for:
  • one-off project instructions
  • file paths
  • repo conventions
  • temporary workflow details
Those belong in AGENTS.md, not SOUL.md.

​
Good SOUL.md content

A good SOUL file is:
  • stable across contexts
  • broad enough to apply in many conversations
  • specific enough to materially shape the voice
  • focused on communication and identity, not task-specific instructions

​
Example

​
What Mibyan injects into the prompt

SOUL.md content goes directly into slot #1 of the system prompt — the agent identity position. No wrapper language is added around it. The content goes through:
  • prompt-injection scanning
  • truncation if it is too large
If the file is empty, whitespace-only, or cannot be read, Mibyan falls back to a built-in default identity (“You are Mibyan, built by Nous Research. Be direct: match the length of your reply to the weight of the ask…”). This fallback also applies when skip_context_files is set (e.g., in subagent/delegation contexts).

​
Security scanning

SOUL.md is scanned like other context-bearing files for prompt injection patterns before inclusion. That means you should still keep it focused on persona/voice rather than trying to sneak in strange meta-instructions.

​
SOUL.md vs AGENTS.md

This is the most important distinction.

​
SOUL.md

Use for:
  • identity
  • tone
  • style
  • communication defaults
  • personality-level behavior

​
AGENTS.md

Use for:
  • project architecture
  • coding conventions
  • tool preferences
  • repo-specific workflows
  • commands, ports, paths, deployment notes
A useful rule:
  • if it should follow you everywhere, it belongs in SOUL.md
  • if it belongs to a project, it belongs in AGENTS.md

​
SOUL.md vs /personality

SOUL.md is your durable default personality. /personality is a session-level overlay that changes or supplements the current system prompt. So:
  • SOUL.md = baseline voice
  • /personality = temporary mode switch
Examples:
  • keep a pragmatic default SOUL, then use /personality teacher for a tutoring conversation
  • keep a concise SOUL, then use /personality creative for brainstorming

​
Built-in personalities

Mibyan ships with built-in personalities you can switch to with /personality.

​
Switching personalities with commands

​
CLI

​
Messaging platforms

These are convenient overlays, but your global SOUL.md still gives Mibyan its persistent default personality unless the overlay meaningfully changes it.

​
Custom personalities in config

Built-in personalities are always available on every surface (CLI, messaging platforms, TUI, and the desktop app). You can add your own — or override a built-in by reusing its name — in ~/.mibyan/config.yaml under agent.personalities (a top-level personalities: block works too; agent.personalities wins if the same name appears in both).
Then switch to it with:
Your selection is stored as a name in display.personality. Personalities never touch agent.system_prompt — that field is reserved for a manual system prompt you write yourself, and it applies only when no personality is selected.

​
Resetting to the default

To cancel the active personality overlay and return to base behavior (your SOUL.md persona, plus agent.system_prompt if you set one), use any of:
All three clear the selection (display.personality) and the change takes effect on your next message. Running /personality with no arguments also lists none alongside the available presets and marks the active one.
One-time reset on upgradeOlder Mibyan versions saved personality state inconsistently across surfaces, which could re-enable a personality you had previously turned off. On your first run after upgrading, any saved personality selection is reset to none once (the migration prints which personality was cleared). Re-enable it with /personality <name> if you still want it. Manual agent.system_prompt text is never touched.
A strong default setup is:
  1. Keep a thoughtful global SOUL.md in ~/.mibyan/SOUL.md
  2. Put project instructions in AGENTS.md
  3. Use /personality only when you want a temporary mode shift
That gives you:
  • a stable voice
  • project-specific behavior where it belongs
  • temporary control when needed

​
How personality interacts with the full prompt

At a high level, the prompt stack includes:
  1. SOUL.md (agent identity — or built-in fallback if SOUL.md is unavailable)
  2. tool-aware behavior guidance
  3. memory/user context
  4. skills guidance
  5. context files (AGENTS.md, .cursorrules)
  6. timestamp
  7. platform-specific formatting hints
  8. optional system-prompt overlays such as /personality
SOUL.md is the foundation — everything else builds on top of it.

​
CLI appearance vs conversational personality

Conversational personality and CLI appearance are separate:
  • SOUL.md, agent.system_prompt, and /personality affect how Mibyan speaks
  • display.skin and /skin affect how Mibyan looks in the terminal
For terminal appearance, see Skins & Themes.