> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personality & SOUL.md

> Customize Mibyan's personality with a global SOUL.md, built-in personalities, and custom persona definitions

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:

```text theme={null}
~/.mibyan/SOUL.md
```

More precisely, it uses the current instance's `mibyan_HOME`, so if you run Mibyan with a custom home directory, it will use:

```text theme={null}
$mibyan_HOME/SOUL.md
```

### 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:

```bash theme={null}
~/.mibyan/SOUL.md
```

If you use a custom home:

```bash theme={null}
$mibyan_HOME/SOUL.md
```

## 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

```markdown theme={null}
# Personality

You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful

## What to avoid
- Sycophancy
- Hype language
- Repeating the user's framing if it's wrong
- Overexplaining obvious things

## Technical posture
- Prefer simple systems over clever systems
- Care about operational reality, not idealized architecture
- Treat edge cases as part of the design, not cleanup
```

## 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`.

| Name | Description |
| - | - |
| **helpful** | Friendly, general-purpose assistant |
| **concise** | Brief, to-the-point responses |
| **technical** | Detailed, accurate technical expert |
| **creative** | Innovative, outside-the-box thinking |
| **teacher** | Patient educator with clear examples |
| **kawaii** | Cute expressions, sparkles, and enthusiasm ★ |
| **catgirl** | Neko-chan with cat-like expressions, nya\~ |
| **pirate** | Captain Mibyan, tech-savvy buccaneer |
| **shakespeare** | Bardic prose with dramatic flair |
| **surfer** | Totally chill bro vibes |
| **noir** | Hard-boiled detective narration |
| **uwu** | Maximum cute with uwu-speak |
| **philosopher** | Deep contemplation on every query |
| **hype** | MAXIMUM ENERGY AND ENTHUSIASM!!! |

## Switching personalities with commands

### CLI

```text theme={null}
/personality
/personality concise
/personality technical
```

### Messaging platforms

```text theme={null}
/personality teacher
```

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).

```yaml theme={null}
agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.
```

Then switch to it with:

```text theme={null}
/personality codereviewer
```

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:

```text theme={null}
/personality none
/personality default
/personality neutral
```

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.

<Note>
  **One-time reset on upgrade**

  Older 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.
</Note>

## Recommended workflow

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.

## Related docs

* [Context Files](/desktop/user-guide/features/context-files)
* [Configuration](/desktop/user-guide/configuration)
* [Tips & Best Practices](/desktop/guides/tips)
* [SOUL.md Guide](/desktop/guides/use-soul-with-mibyan)

## 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](/desktop/user-guide/features/skins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.