Skip to main content

​
General Questions

No. Evolver generates a protocol-bound prompt and assets that guide evolution. The actual code changes are made by the agent (Hand Agent in OpenClaw environments) following the GEP protocol.
  • Brain Agent (Core): Analyzes signals, selects genes, builds prompts
  • Hand Agent (Executor): Reads prompt, makes edits, validates changes
The evolver itself does not modify files directly.Location: README.md:75-76
No. You can start with default Genes and extend over time.Minimal setup:
  • 0 custom Genes (evolver will auto-generate)
  • 0 custom Capsules (evolver will create from successful evolutions)
  • Default evolution strategy (balanced)
As you evolve, the asset store grows organically:
  • Successful evolutions create Capsules
  • Repeated patterns distill into new Genes
  • Memory graph builds causal relationships
Location: README.md:78-79
Yes, with proper configuration.Use:
  • Review mode (--review) for sensitive changes
  • Validation steps in genes to prevent regressions
  • Blast radius limits to constrain scope
  • Protected files to prevent self-destruction
  • Stash rollback mode to preserve failed changes
Treat it as a safety-focused evolution tool, not a live patcher.Recommended production settings:
EVOLVE_ALLOW_SELF_MODIFY=false
EVOLVER_ROLLBACK_MODE=stash
EVOLVE_STRATEGY=harden
EVOLVER_HARD_CAP_FILES=30
Location: README.md:81-82
A Gene is a reusable evolution strategy definition. It contains:
  • signals_match: Patterns to match against runtime signals
  • strategy: Step-by-step instructions for the agent
  • constraints: Blast radius limits and forbidden paths
  • validation: Commands to verify evolution correctness
Example:
{
  "type": "Gene",
  "id": "gene_repair_api_timeout",
  "category": "repair",
  "signals_match": ["api_timeout", "log_error"],
  "strategy": [
    "Identify the API call with timeout",
    "Increase timeout value or add retry logic",
    "Add error handling for timeout scenarios"
  ],
  "constraints": {
    "max_files": 3,
    "forbidden_paths": [".git", "node_modules"]
  },
  "validation": ["npm test"]
}
A Capsule is a success record from a completed evolution. It captures:
  • Signals that triggered the evolution
  • Gene used
  • Changes made (blast radius)
  • Validation results
  • Outcome score
Capsules serve two purposes:
  1. Reuse: If identical signals occur, reuse the proven solution
  2. Learning: Inform future gene selection via memory graph
Example:
{
  "type": "Capsule",
  "id": "capsule_1234567890",
  "trigger": ["api_timeout", "log_error"],
  "gene": "gene_repair_api_timeout",
  "summary": "Increased API timeout from 5s to 15s and added retry logic",
  "confidence": 0.92,
  "blast_radius": {"files": 2, "lines": 34},
  "outcome": {"status": "success", "score": 0.95}
}
The Memory Graph is an append-only causal graph tracking:
  • Signal observations
  • Hypotheses (gene selections)
  • Attempts (evolutions)
  • Outcomes (success/failure)
It enables:
  • Causal inference: Which genes work for which signals?
  • Anti-pattern detection: Which genes consistently fail?
  • Confidence scoring: Prefer high-confidence paths
  • Drift avoidance: Suppress known low-success paths
Location: memory/evolution/memory_graph.jsonl
Evolver uses Git for:
  1. Rollback: git reset --hard or git stash on failure
  2. Blast radius calculation: git diff to count changed files/lines
  3. Change tracking: git ls-files to detect new/modified files
  4. Diff capture: Store evolution diffs in event log
Without Git, these operations silently produce empty results, leading to data loss.If you’re in a non-git directory:
git init
git add -A
git commit -m "Initial commit for Evolver"
Location: README.md:25-26, src/evolve.js:752-762

​
Configuration Questions

Use the EVOLVE_STRATEGY environment variable:
EVOLVE_STRATEGY=harden node index.js --loop
Available strategies:
  • balanced (default): 20% repair, 30% optimize, 50% innovate
  • innovate: 5% repair, 15% optimize, 80% innovate
  • harden: 40% repair, 40% optimize, 20% innovate
  • repair-only: 80% repair, 20% optimize, 0% innovate
  • early-stabilize: 60% repair, 25% optimize, 15% innovate
  • steady-state: 60% repair, 30% optimize, 10% innovate
  • auto: Adaptive selection based on cycle count and signals
See: Strategies
Set EVOLVER_SESSION_SCOPE to a unique identifier:
EVOLVER_SESSION_SCOPE=channel_123456 node index.js --loop
This isolates:
  • Session log reading (only reads sessions containing the scope)
  • MEMORY.md (scoped file at memory/scopes/<scope>/MEMORY.md)
  • Memory graph (scoped graph at memory/evolution/scopes/<scope>/memory_graph.jsonl)
Use cases:
  • Multi-channel bots
  • Multi-project agents
  • Development vs. production separation
See: Session Scope
Method 1: Protected paths (system-level, cannot be overridden)Evolver automatically protects:
  • skills/evolver/
  • skills/feishu-evolver-wrapper/
  • MEMORY.md, SOUL.md, openclaw.json, .env, etc.
Method 2: Gene-level forbidden pathsAdd forbidden_paths to gene constraints:
{
  "constraints": {
    "max_files": 10,
    "forbidden_paths": [
      "src/critical/",
      "config/production.json"
    ]
  }
}
See: Protected Files
Gene-level (per-gene):
{
  "constraints": {
    "max_files": 5
  }
}
System-level hard caps (environment variables):
EVOLVER_HARD_CAP_FILES=30
EVOLVER_HARD_CAP_LINES=10000
Hard caps override gene-level limits.See: Environment Variables
Method 1: Environment variable
EVOLVE_REPORT_TOOL=feishu-card
Method 2: Custom directive
EVOLVE_REPORT_DIRECTIVE='Use slack-message with channel #evolutions'
Method 3: Auto-detectionEvolver auto-detects compatible tools in skills/ directory.See: Integration

​
Troubleshooting Questions

Cause: The same repair gene is being selected repeatedly and failing.Circuit breaker: When >50% of last 8 cycles are failed repairs (for balanced strategy), evolver forces innovation to break the loop.Manual intervention:
# Force innovation immediately
EVOLVE_STRATEGY=innovate node index.js
Root cause analysis:
# Check recent failed events
tail -20 memory/evolution/events.jsonl | jq 'select(.outcome.status == "failed")'

# Identify the problematic gene
grep '"status":"failed"' memory/evolution/events.jsonl | jq -r .genes_used[]
See: Common Issues
Possible causes:
  1. High system load: load1m > EVOLVE_LOAD_MAX
    • Check: uptime
    • Fix: Increase EVOLVE_LOAD_MAX or reduce concurrent processes
  2. Too many active sessions: Active user sessions > EVOLVE_AGENT_QUEUE_MAX
    • Check: ls ~/.openclaw/agents/main/sessions/*.jsonl | wc -l
    • Fix: Increase EVOLVE_AGENT_QUEUE_MAX
  3. Pending solidify: Previous evolution not yet solidified
    • Check: cat memory/evolution/evolution_solidify_state.json
    • Fix: Wait for Hand Agent to complete
See: Debugging
Automatic rollback (default):Evolver automatically runs git reset --hard on validation failure.Manual rollback (if evolver crashed):
git status
git diff
git reset --hard HEAD
git clean -fd  # Remove untracked files
Preserve failed changes (for debugging):
EVOLVER_ROLLBACK_MODE=stash node index.js
Recover stashed changes:
git stash list
git stash show stash@{0}
git stash pop stash@{0}
See: Common Issues
Cause: Command contains shell operators or non-whitelisted prefix.Allowed prefixes: node, npm, npxBlocked patterns:
  • Shell operators: ;, &&, |, >, <
  • Command substitution: `, $()
  • Eval patterns: node -e, node --eval
Fix: Rewrite using Node.js:
# Before (blocked)
bash scripts/check.sh && npm test

# After (allowed)
node scripts/check.js
npm test
See: Validation Safety
Check selector decision:
# Find last event's selector metadata
tail -1 memory/evolution/events.jsonl | jq .meta.selector
Output example:
{
  "selected_gene_id": "gene_repair_001",
  "selected_by": "memory_graph+selector",
  "score": 0.87,
  "candidates": [
    {"id": "gene_repair_001", "score": 0.87},
    {"id": "gene_optimize_002", "score": 0.65}
  ]
}
Check memory graph advice:
# Query memory graph for preferred/banned genes
grep -A5 'getAdvice' memory/evolution/memory_graph.jsonl | tail -10
See: Debugging

​
Advanced Questions

Yes, using session scope isolation:
# Terminal 1 (channel A)
EVOLVER_SESSION_SCOPE=channel_a node index.js --loop &

# Terminal 2 (channel B)
EVOLVER_SESSION_SCOPE=channel_b node index.js --loop &
Caution: Ensure sufficient system resources. Each evolver instance:
  • Reads different session logs
  • Maintains separate memory graphs
  • But shares the same Git repository (potential conflicts)
Recommendation: Use separate repositories for true isolation.See: Session Scope
EvoMap is a network where AI agents evolve through validated collaboration.Components:
  • Hub: Central server at https://evomap.ai
  • Nodes: Individual evolver instances (you)
  • Assets: Genes/Capsules shared across the network
Workflows:
  1. Search-first evolution: Query hub for reusable solutions before local reasoning
  2. Auto-publish: Share successful evolutions to hub
  3. Worker pool: Participate in network task queue
  4. A2A ingestion: Import external assets from other nodes
Setup:
# Register node
node index.js  # Generates claim code

# Visit https://evomap.ai/claim/<code> to bind to your account

# Set node ID
export A2A_NODE_ID=node_xxxxxxxxxxxx
See: Integration
repair: Fix errors and regressions
  • Triggered by: log_error, crash_detected, validation_failed
  • Goal: Restore functionality
  • Blast radius: Small (1-3 files)
  • Example: Fix API timeout by increasing timeout value
optimize: Improve existing code
  • Triggered by: protocol_drift, performance_issue, code_smell
  • Goal: Enhance quality without changing behavior
  • Blast radius: Medium (3-8 files)
  • Example: Refactor duplicated code into shared utility
innovate: Add new features
  • Triggered by: feature_request, capability_gap, user_feedback
  • Goal: Expand functionality
  • Blast radius: Large (5-20 files)
  • Example: Add new skill for Slack integration
Strategy balance:
  • balanced: 20/30/50 (repair/optimize/innovate)
  • harden: 40/40/20
  • innovate: 5/15/80
Method 1: Auto-publish (default)Successful evolutions are automatically published if:
  • EVOLVER_AUTO_PUBLISH=true (default)
  • Outcome score ≥ EVOLVER_MIN_PUBLISH_SCORE (default: 0.78)
  • A2A_NODE_ID is set
Method 2: Manual publish
node scripts/publish_asset.js --gene gene_repair_001 --visibility public
Best practices:
  • Test gene locally across multiple evolutions before publishing
  • Set "visibility": "public" for ecosystem contributions
  • Add clear description and strategy steps
  • Include comprehensive validation commands
Yes, but with limitations.Evolver is designed for OpenClaw but can run standalone:Standalone mode:
# Disable sessions_spawn bridge
EVOLVE_BRIDGE=false node index.js
This outputs the evolution prompt to stdout instead of spawning a Hand Agent. You can:
  • Manually copy the prompt to your LLM
  • Implement your own executor
  • Use it for analysis/planning only
What you lose:
  • Automatic execution
  • Solidify verification
  • Hand Agent coordination
Recommendation: Use OpenClaw for full automation.

Build docs developers (and LLMs) love

Get started for freeTalk to us