soul-evolver Skill

soul-evolver automatically evolves your AI agent's identity files by analyzing memory sources and discovering patterns over time.

When to Use

• After significant conversations that reveal new behavioral patterns
• When USER.md or SOUL.md needs updating based on accumulated experience
• During periodic memory reviews (scheduled or manual)
• After the user provides corrections or new preferences

Quick Start

Run Manual Evolution

exec python3 ~/.openclaw/skills/soul-forge/scripts/soulforge.py run

Dry Run (Preview Changes)

exec python3 ~/.openclaw/skills/soul-forge/scripts/soulforge.py run --dry-run

Check Status

exec python3 ~/.openclaw/skills/soul-forge/scripts/soulforge.py status

Multi-Agent Isolation

SoulForge is designed for multi-agent environments. Each agent's data is completely isolated:

Example: workspace naming

~/.openclaw/workspace/         → .soulforge-main/     (main agent)
~/.openclaw/workspace-wukong/  → .soulforge-wukong/  (wukong agent)
~/.openclaw/workspace-tseng/   → .soulforge-tseng/   (tseng agent)

Each agent should run its own cron job pointing to its workspace:

# For main agent
python3 soulforge.py run --workspace ~/.openclaw/workspace

# For wukong agent
python3 soulforge.py run --workspace ~/.openclaw/workspace-wukong

Configuration

Set your MiniMax API key:

export MINIMAX_API_KEY="your-api-key"

Or in OpenClaw config:

{
  "env": {
    "MINIMAX_API_KEY": "your-key"
  }
}

How It Works

memory/*.md + .learnings/ → MiniMax Analysis → Pattern Discovery → File Updates

Trigger Conditions

soul-evolver updates files when:

Safety

• Incremental: Only appends, never overwrites existing content
• Backups: Creates timestamped backups in .soulforge-backups/
• Dry Run: Preview changes with --dry-run
• Threshold: Patterns must appear multiple times before promoting

Schedule (Recommended)

Set up a cron job for continuous evolution:

# Every 2 hours
openclaw cron add --name soulforge-evolve --every 120m \
  --message "exec python3 ~/.openclaw/skills/soul-forge/scripts/soulforge.py run"

Files Generated

• .soulforge-backups/*.bak — Timestamped backups
• .soulforge-state.json — Last run state (optional)

Memory Sources

Exit Codes

• 0 — Success
• 1 — Error (check output for details)