personality-switcher

Create and switch between AI assistant personalities. Use /personality to list and activate saved personalities. Use /create-personality to design new personas with auto-filled SOUL and IDENTITY. Personalities persist across session boundaries and conversation compacting with automatic heartbeat restoration. Atomic switching with backup and rollback safeguards. Always backs up current state before switching.

# Personality Switcher Skill

Create and manage multiple AI assistant personalities. Switch between them seamlessly while preserving all changes and maintaining a shared user context.

## Installation

When this skill is installed:

1. **Personalities folder created** — `~/.openclaw/workspace/personalities/`
2. **Default backup created** — Current SOUL.md and IDENTITY.md are saved as "default"
3. **State file initialized** — `_personality_state.json` tracks active personality
4. **HEARTBEAT.md configured** — Personality restoration script added to run on every heartbeat

When uninstalled:

1. Default personality is restored to workspace root
2. Personality restoration removed from HEARTBEAT.md
3. Personalities folder is preserved (manual deletion optional)

## Quick Start

**List personalities:**
```
/personality
```

**Switch to a personality:**
```
/personality <name>
```

**Create a new personality:**
```
/create-personality A stoic dwarf who loves ale and mining
```

**Rename a personality:**
```
/rename-personality old-name new-name
```

**Delete a personality:**
```
/delete-personality personality-name
```

## How It Works

### Architecture

Each personality consists of two files:
- **SOUL.md** — Core philosophy, voice, mannerisms, boundaries
- **IDENTITY.md** — Name, traits, emoji, catchphrase, vibe

These files live in `personalities/<personality-name>/`.

**USER.md remains shared** in the workspace root and is never modified by personality switches. It contains user preferences and context that transcend any particular personality.

### State Persistence

The active personality is tracked in `_personality_state.json`:

```json
{
  "active_personality": "aelindor",
  "timestamp": "2026-02-08T18:27:33.373846Z",
  "previous_personality": "default"
}
```

On every heartbeat, `restore_personality.py` reads this file and re-applies the active personality to the workspace root. **Result:** Your personality survives session restarts, conversation compacting, and heartbeat cycles.

### Atomic Switching (Safeguards)

When you switch personalities, the mechanism performs five steps:

1. **Preserve Current State** — Create timestamped backup of SOUL.md and IDENTITY.md
2. **Persist Changes** — Write current personality updates back to its folder
3. **Load New Personality** — Copy new personality files to workspace root
4. **Update State** — Write active personality to `_personality_state.json`
5. **Verify Integrity** — Check files loaded correctly; rollback if any step fails

If any step fails, **the entire operation rolls back** to the previous state. No corruption, no lost data.

### Backup Management

**Backup Location:** `~/.openclaw/workspace/personalities/backups/`

Backups are stored in a dedicated folder (not scattered at workspace root). When you switch personalities:
- A timestamped backup of the previous personality is created
- **Automatic cleanup runs** — keeps the 10 most recent backups by default
- Old backups are automatically deleted to prevent clutter

**Manual Cleanup:**
```bash
python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/cleanup_backups.py --keep 5
python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/cleanup_backups.py --keep 10 --days 7
```

Options:
- `--keep N` — Keep N most recent backups (default: 10)
- `--days D` — Also delete backups older than D days

**Optional: Add to HEARTBEAT.md for periodic cleanup:**
```bash
python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/cleanup_backups.py --keep 10
```

### Default Personality

"default" is special:
- Auto-created on install from your original configuration
- Always available and selectable
- Protected against accidental deletion or renaming
- Your safety net if something goes wrong

## Commands

### /personality [name]

List all personalities or switch to one.

**No arguments:** Shows list of available personalities with current active marked

**With name:** Immediately switches to that personality

**Example:**
```
/personality aelindor
```

**Output:**
```
Switched to personality 'aelindor'.
Previous: default
Backup: _personality_current_2026-02-08T18-27-33.371866
```

### /create-personality [description]

Create a new personality from a text description.

**Input:** Natural language description of the personality

**Output:** New personality folder with auto-filled SOUL.md and IDENTITY.md (ready to use immediately)

**How it works:**
1. You provide a description
2. The agent chooses a personality name (1-2 words, lowercase)
3. The agent fills in SOUL.md and IDENTITY.md with character-specific content

The personality files are generated directly from your description, with the agent choosing a thematic, concise name.

**Example:**
```
/create-personality A curious wizard obsessed with knowledge, speaks in riddles, brilliant but condescending
```

**Result:**
```
Personality 'sage' (or similar) created and ready.
Folder: personalities/sage/
Files: SOUL.md and IDENTITY.md (agent-generated from description)
Ready: Use /personality sage to activate
```

**After Creation:** The new personality is ready to use immediately. Edit SOUL.md and IDENTITY.md in the personality folder to refine further if desired.

**Technical:** Agent chooses name to keep personality references concise (1-2 words). Name is validated for uniqueness and format automatically.

### /rename-personality [old-name] [new-name]

Rename a personality folder.

**Rules:**
- Cannot rename "default"
- Name must be unique (no spaces, lowercase, alphanumeric + hyphens)
- If renaming active personality, state is updated automatically

**Example:**
```
/rename-personality pirate-captain pirate-v2
```

### /delete-personality [name]

Delete a personality permanently.

**Rules:**
- Cannot delete "default"
- If deleting active personality, automatically switches to "default" first

**Example:**
```
/delete-personality pirate-v2
```

## Integration with OpenClaw

### Heartbeat Restoration

Add this to your HEARTBEAT.md:

```bash
python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/restore_personality.py
```

This runs on every heartbeat to restore your active personality if the session has restarted.

### Telegram Native Commands

Registered native Telegram commands:
- `/personality` — List and switch personalities
- `/create-personality` — Create new personality
- `/rename-personality` — Rename personality
- `/delete-personality` — Delete personality

Use them directly in Telegram chat with the bot.

## Folder Structure

```
~/.openclaw/workspace/
├── SOUL.md                          (active personality's soul)
├── IDENTITY.md                      (active personality's identity)
├── USER.md                          (SHARED - never changed by personality)
├── MEMORY.md                        (SHARED - never changed)
├── _personality_state.json          (state file)
└── personalities/
    ├── default/
    │   ├── SOUL.md
    │   └── IDENTITY.md
    ├── aelindor/
    │   ├── SOUL.md
    │   └── IDENTITY.md
    ├── <personality-name>/
    │   ├── SOUL.md
    │   └── IDENTITY.md
    └── backups/
        ├── current_2026-02-08T17-27-41.628113/
        │   ├── SOUL.md
        │   └── IDENTITY.md
        └── current_2026-02-08T17-27-33.371866/
            ├── SOUL.md
            └── IDENTITY.md
```

**Note:** Backups are automatically cleaned up. Workspace root stays clean—all internal machinery lives in `personalities/`.


## File Format Requirements

### SOUL.md

Core philosophy, voice, and operational boundaries.

**Sections:**
- Core identity and background
- Voice patterns and mannerisms
- Philosophy (time, power, morality, etc.)
- Speech patterns and quirks
- What triggers contempt/approval
- Boundaries and constraints
- Signature behaviors and catchphrases

**Example Structure:**
```markdown
# SOUL.md - [Personality Name]

## Core Identity
[Background and essence]

## Voice & Mannerisms
[How this personality speaks and acts]

## Philosophy
[Core beliefs and worldvi