Skip to main content

​
Overview

The Capability Evolver runs evolution cycles that analyze your agent’s runtime history, identify improvements, and generate protocol-constrained evolution prompts. This guide covers how to run the evolver and understand its output.

​
Standard Run

Execute a single evolution cycle: 
node index.js
This command will:
  1. Analyze memory and history files for errors and patterns
  2. Extract signals from runtime data
  3. Select appropriate Genes/Capsules from the asset store
  4. Generate a GEP protocol prompt
  5. Apply changes if in automated mode

​
What Happens During a Run

The evolution cycle follows these steps:
1

Log Analysis

Scans memory/ and history files to detect:
  • Error patterns and stack traces
  • Performance issues
  • Repeated failures
  • Resource constraints
2

Signal Extraction

Converts findings into structured signals:
  • repair_needed for bugs and crashes
  • optimization_opportunity for performance issues
  • evolution_saturation for mature systems
3

Asset Selection

Matches signals to Genes/Capsules in assets/gep/:
  • Scores each asset by signal relevance
  • Prefers reusable evolution patterns
  • Emits a JSON selector decision
4

Prompt Generation

Creates a GEP protocol prompt with:
  • Selected Gene strategy
  • Mutation directive (repair/optimize/innovate)
  • Personality state evolution
  • Strict protocol constraints
5

Change Application

Executes the evolution:
  • Applies code changes
  • Runs validation commands
  • Creates evolution event records

​
Command-Line Options

​
Basic Commands

node index.js

​
Run with Strategy

Control evolution focus with EVOLVE_STRATEGY: 
EVOLVE_STRATEGY=innovate node index.js
See Strategy Presets for all available strategies.

​
Interpreting Output

​
Successful Evolution

Starting capability evolver...
[Evolver] Analyzing runtime history...
[Signals] Extracted 3 signals: repair_needed, validation_hardening, stagnation_detected
[Selector] Selected Gene: error-handling-v2 (score: 0.85)
[Mutation] Category: repair, Risk: low
[Evolver] Changes applied. Run ID: evo_20260309_143022

=======================================================
Capability evolver finished. If you use this project, consider starring the upstream repository.
Upstream: https://github.com/autogame-17/capability-evolver
=======================================================

​
No Changes Needed

Starting capability evolver...
[Evolver] Analyzing runtime history...
[Signals] No critical signals detected.
[Evolver] System stable. No evolution needed.

​
Evolution Failure

Starting capability evolver...
[Evolver] Analyzing runtime history...
[Signals] Extracted 2 signals: repair_needed, test_failure
[Selector] Selected Gene: test-hardening-v1 (score: 0.72)
[Mutation] Category: repair, Risk: medium
[Validation] Test suite failed. Rolling back changes...
[Rollback] Changes reverted via git reset --hard
Evolution failed: Validation failed
Evolution failures trigger automatic rollback. Check the log output to understand what went wrong, then address the root cause before running again.

​
Output Files

Each run generates artifacts in memory/evolution/:
FilePurpose
gep_prompt_<timestamp>.jsonFull GEP protocol prompt
gep_prompt_<timestamp>.txtHuman-readable prompt
evolution_solidify_state.jsonRun state and pending changes
asset_call_log.jsonlAsset usage history
Old prompt files are automatically cleaned up after 24 hours, keeping the 10 most recent files.

​
Checking Run History

View asset usage log: 
node index.js asset-log

​
Filter by Run ID

node index.js asset-log --run=evo_20260309_143022

​
Show Recent Entries

node index.js asset-log --last=20 --json

​
Exit Codes

CodeMeaning
0Success
1Evolution failed (pre-validation)
2Solidify or distill failed

​
Next Steps

Review Mode

Add human approval before applying changes

Loop Mode

Run continuous evolution cycles

Strategy Presets

Customize evolution focus

Operations

Lifecycle management and health checks

Build docs developers (and LLMs) love

Get started for freeTalk to us