# Migration Guide

How to migrate an existing hand-crafted or v1 persona setup to the AI Persona Engine v2.

---

## Overview

If you already have SOUL.md, USER.md, and other workspace files — either hand-written or generated by v1 — the migration tool can reverse-engineer a `persona-config.json` from them. This config can then be used with `persona-update`, `persona-export`, or to regenerate files with new features like personality blending.

---

## Quick Migration

```bash
# Step 1: Run the migration tool
python3 scripts/persona-migrate.py --workspace ~/.openclaw/workspace --output persona-config.json

# Step 2: Review the extracted config
cat persona-config.json

# Step 3: Validate your workspace
python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace

# Step 4: See what would change with regeneration
python3 scripts/persona-diff.py --workspace ~/.openclaw/workspace
```

---

## What Gets Extracted

The migration tool reads your workspace files and extracts:

| Source File | Extracted Fields |
|-------------|-----------------|
| SOUL.md | Name, emoji, traits, communication style, boundaries, archetype detection |
| IDENTITY.md | Name, emoji, creature type, vibe, nickname |
| USER.md | User name, pronouns, timezone |
| MEMORY.md | (Presence checked, not parsed for content) |
| AGENTS.md | (Presence checked, not parsed for content) |

### Archetype Detection

The tool uses heuristic matching to detect which built-in archetype your persona most closely resembles:

- Compares extracted traits against known archetype trait sets
- Checks communication style alignment (humor, swearing level)
- Checks boundary alignment (emotional depth)
- Requires a minimum confidence score (3+ matching signals) to assign an archetype
- Falls back to `"custom"` if no strong match is found

---

## Handling Edge Cases

### Hand-Written Files

If your files were written by hand (not generated by the engine):

- The tool uses regex patterns to find standard markdown sections
- Non-standard headers may not be detected — the tool will still extract what it can
- Check `filesMissing` in the output to see which files couldn't be read

### Missing Files

The migration gracefully handles missing files:

```json
{
    "filesFound": ["SOUL.md", "USER.md"],
    "filesMissing": ["IDENTITY.md", "MEMORY.md", "AGENTS.md"]
}
```

You can generate missing files after migration:

```bash
# Regenerate missing files from the extracted config
python3 scripts/generate-identity.py --name "Pepper" --emoji "🌶️" --creature "Assistant" --output ~/.openclaw/workspace/IDENTITY.md
python3 scripts/generate-memory.py --name "Pepper" --emoji "🌶️" --workspace ~/.openclaw/workspace
```

### Non-Standard Sections

If your SOUL.md has custom sections not recognized by the tool, they'll be preserved in the workspace files but won't appear in the extracted config. After migration, you can:

1. Use `persona-diff.py` to see differences
2. Edit the generated config to include custom settings
3. Hand-edit SOUL.md after regeneration to add your custom sections back

---

## After Migration

### Validate

Always validate after migration:

```bash
python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace --config ~/.openclaw/openclaw.json
```

### Preview

See how the extracted persona would behave:

```bash
python3 scripts/persona-preview.py --input persona-config.json --user-name "YourName"
```

### Safe Regeneration

If you want to regenerate files from the new config:

```bash
# This creates a backup first, shows diffs, and asks for confirmation
openclaw persona update --regen-soul

# Or force it (skip diff review)
openclaw persona update --regen-soul --force
```

### Enable New Features

After migration, you can take advantage of v2 features:

```bash
# Add personality blending
# Edit persona-config.json to use archetypes array:
# "archetypes": [{"name": "companion", "weight": 0.7}, {"name": "creative", "weight": 0.3}]

# Export for sharing
openclaw persona export --name my-persona

# List all your personas
python3 scripts/persona-list.py
```

---

## Backward Compatibility

- v2 is fully backward-compatible with v1 persona configs
- Single archetype configs (`"archetype": "companion"`) continue to work
- Blend syntax (`"archetypes": [...]`) is additive — old configs are unaffected
- All v1 commands work identically
- Generated files have the same format and structure