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#

text

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

Dry Run (Preview Changes)#

text

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

Check Status#

text

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:

DataIsolation StrategyBackup files.soulforge-{agent}/backups/ — agent-specific subdirectoryState files.soulforge-{agent}/ — agent-specific directoryMemory sourcesRead only from agent's own memory/ and .learnings/Target filesUpdate only agent's own SOUL.md, USER.md, etc.

Example: workspace naming

text

~/.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:

bash

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

bash

export MINIMAX_API_KEY="your-api-key"

Or in OpenClaw config:

json

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

How It Works#

text

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

Trigger Conditions#

soul-evolver updates files when:

FileTriggersSOUL.mdSame behavior seen 3+ times, user corrections, new principlesUSER.mdNew user preferences, project changes, habit changesIDENTITY.mdRole/responsibility changes, team structure changesMEMORY.mdImportant decisions, milestones, lessons learnedAGENTS.mdNew workflow patterns, delegation rulesTOOLS.mdNew tool usage patterns, workarounds

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:

bash

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

SourcePathPriorityDaily logsmemory/YYYY-MM-DD.mdHighLearnings.learnings/LEARNINGS.mdHighErrors.learnings/ERRORS.mdMediumhawk-bridgeVector storeMedium

Exit Codes#

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