SoulForce

The Core Problem ❌

Key Features

🔄 Auto Evolution

🔒 Safety & Reliability

🏢 Multi-Agent Isolation

🧠 hawk-bridge Integration

🔒 Safety

Before vs After — A Real Example

SOUL.md

# SOUL.md
## Who I Am
I'm an AI assistant that helps with tasks.
## How I Work
I try to be helpful and accurate.

# SOUL.md
## Who I Am
I'm an AI assistant that helps with tasks.
## How I Work
I try to be helpful and accurate.
---
<!-- SoulForge Update | 2026年04月05日 -->
## Behavior: User Prefers Numbered Options
**Source**: memory/2026-04-04.md, memory/2026-04-05.md
**Pattern Type**: communication
**Confidence**: High (observed 4 times)
**Content**:
User gets overwhelmed by long text options. ALWAYS present choices as numbered lists (1/2/3) instead of paragraphs. Keep it scannable.
<!-- /SoulForge Update -->
<!-- SoulForge Update | 2026年04月03日 -->
## Behavior: User Corrected "Do It Yourself" Pattern
**Source**: .learnings/LEARNINGS.md (correction)
**Pattern Type**: correction
**Confidence**: High (observed 3 times)
**Content**:
When user says "why does this keep happening" or expresses frustration, it means I should fix the root cause, not just patch symptoms. User values prevention over remediation.
<!-- /SoulForge Update -->

USER.md

# USER.md
## User
A person who uses this AI assistant.

# USER.md
## User
A person who uses this AI assistant.
---
<!-- SoulForge Update | 2026年04月04日 -->
## Discovered: User Prefers Concise Replies
**Source**: memory/2026-04-04.md
**Pattern Type**: preference
**Confidence**: High (observed 3 times)
**Content**:
User prefers concise, actionable replies over verbose explanations. Lead with the answer, then optionally explain briefly if needed.
<!-- /SoulForge Update -->
<!-- SoulForge Update | 2026年04月05日 -->
## Discovered: User Hates Manual Steps
**Source**: memory/2026-04-05.md
**Pattern Type**: preference
**Confidence**: High (observed 5 times)
**Content**:
User repeatedly asks to "automate this". Never suggests manual workarounds. If a task can be scripted, do it without asking.
<!-- /SoulForge Update -->

What Changed

How It Works

┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Memory │ ──▶ │ Analyzer │ ──▶ │ Evolver │
│ Sources │ │ (LLM) │ │ (Safe) │
└─────────────┘ └──────────────┘ └─────────────┘
 │ │ │
 ▼ ▼ ▼
memory/*.md Pattern Detection SOUL.md
.learnings/ ×ばつ threshold USER.md
hawk-bridge Confidence Scoring IDENTITY.md
 MEMORY.md

Quick Start

1. Install

# Via clawhub (recommended)
clawhub install soul-force --force
# Manual clone
git clone https://github.com/relunctance/soul-force.git ~/.openclaw/workspace/skills/soul-force

2. Run

# Manual trigger
python3 ~/.openclaw/workspace/skills/soul-force/scripts/soulforge.py run
# Preview mode (no writes)
python3 ~/.openclaw/workspace/skills/soul-force/scripts/soulforge.py run --dry-run
# Force apply all patterns (ignore confidence threshold)
python3 ~/.openclaw/workspace/skills/soul-force/scripts/soulforge.py run --force
# Review mode: generate patterns without writing
python3 ~/.openclaw/workspace/skills/soul-force/scripts/soulforge.py review
# Apply from review after confirmation
python3 ~/.openclaw/workspace/skills/soul-force/scripts/soulforge.py apply --confirm
# Check status
python3 ~/.openclaw/workspace/skills/soul-force/scripts/soulforge.py status

3. Schedule (Recommended)

# Set cron via command (every 2 hours)
soulforge.py cron-set --every 120
# Other intervals
soulforge.py cron-set --every 60 # every hour
soulforge.py cron-set --every 30 # every 30 minutes
soulforge.py cron-set --every 240 # every 4 hours
# View current schedule
soulforge.py cron-set --show
# Remove cron
soulforge.py cron-set --remove

4. Configuration

# View current config
soulforge.py config --show
# Set a config value (persists to ~/.soulforgerc.json)
soulforge.py config --set max_token_budget=8192
soulforge.py config --set rollback_auto_enabled=true

5. Maintenance

# Clean expired pattern blocks
soulforge.py clean --expired # dry run first
soulforge.py clean --expired --confirm # actually delete
# Manual backup snapshot
soulforge.py backup --create
# Rollback last failed write (auto-restore from backup)
soulforge.py rollback --auto
# View diff since last run
soulforge.py diff

openclaw cron add --name soulforce-evolve --every 120m \
 --message "exec python3 ~/.openclaw/workspace/skills/soul-force/scripts/soulforge.py run"

6. View Changelog

# View English changelog
soulforge.py changelog
# View Chinese changelog
soulforge.py changelog --zh
# View full changelog (no truncation)
soulforge.py changelog --full

Multi-Agent Usage

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

hawk-bridge Integration

# Install hawk-bridge first (if not present)
clawhub install hawk-bridge --force
# SoulForce auto-detects hawk-bridge
python3 soulforge.py run

Project Structure

soul-force/
├── SKILL.md # OpenClaw Skill definition
├── README.md # English documentation
├── README.zh-CN.md # 中文文档
├── soulforge/
│ ├── __init__.py # Package init (v2.1.0)
│ ├── config.py # Config (multi-agent isolation, config.json)
│ ├── memory_reader.py # Multi-source memory reading (incremental)
│ ├── analyzer.py # LLM-powered pattern analyzer (schema validation)
│ ├── evolver.py # Safe file updates (auto-rollback)
│ └── schema.py # Pydantic models for pattern validation
├── scripts/
│ └── soulforge.py # CLI entry point
├── references/
│ ├── ARCHITECTURE.md # Technical architecture
│ ├── help-en.md # English help text
│ └── help-zh.md # 中文帮助文本
└── tests/
 └── test_soulforge.py # Unit tests

Requirements

License