Overview The evolve.run() function is the core orchestration engine that manages the entire evolution cycle. It reads session logs, extracts signals, selects genes, executes mutations, and coordinates all evolution phases.
Function Signature This function is called from the Evolver entry point (index.js) and does not accept direct parameters. Configuration is managed through environment variables and CLI flags.
Configuration Environment Variables Name of the agent instance
Enable random drift mode for exploration
Enable continuous loop mode
Enable bridge mode for hand agent integration
Maximum system load threshold (auto-calculated based on CPU cores if not set)
Maximum active user sessions before backing off
Force innovation intent (internal use)
CLI Flags Enable review mode (pause before applying changes)
Run without making actual changes
Run in continuous loop mode
Return Value The function returns nothing but performs side effects including:
Writing to memory graph
Creating evolution events
Generating prompts for hand agent
Recording outcomes and metrics
Execution Flow Phase 1: Safety Guards // Check for concurrent evolver processes const psCheck = execSync ( 'ps aux | grep "evolver_hand_" | grep -v grep' ); if ( psCheck ) { console . log ( '[Evolver] Another evolver Hand Agent is already running. Yielding.' ); return ; } // Check active user sessions const activeUserSessions = getRecentActiveSessionCount ( 10 * 60 * 1000 ); if ( activeUserSessions > QUEUE_MAX ) { console . log ( '[Evolver] Agent has ${activeUserSessions} active sessions. Backing off.' ); return ; } // Check system load const sysLoad = getSystemLoad (); if ( sysLoad . load1m > LOAD_MAX ) { console . log ( '[Evolver] System load ${sysLoad.load1m} exceeds max ${LOAD_MAX}.' ); return ; }
Location: src/evolve.js:812
const recentMasterLog = readRealSessionLog (); const memorySnippet = readMemorySnippet (); const signals = extractSignals ({ recentSessionTranscript: recentMasterLog , todayLog , memorySnippet , userSnippet , recentEvents , });
Phase 3: Gene Selection Location: src/evolve.js:1298
const { selectedGene , capsuleCandidates , selector } = selectGeneAndCapsule ({ genes , capsules , signals , memoryAdvice , driftEnabled: IS_RANDOM_DRIFT , failedCapsules: recentFailedCapsules , });
Phase 4: Memory Graph Recording Location: src/evolve.js:1151
recordSignalSnapshot ({ signals , observations }); recordHypothesis ({ signals , mutation , personality_state , selectedGene , selector , driftEnabled , selectedBy , capsulesUsed , observations , }); recordAttempt ({ signals , mutation , selectedGene , ... });
Phase 5: Prompt Generation Location: src/evolve.js:1400+
const prompt = buildGepPrompt ({ signals , genes , capsules , selectedGene , recentEvents , memoryAdvice , ... });
Error Handling Circuit Breaker
Git Repository Check
// Detect repair loops const recent = allEvents . slice ( - REPAIR_LOOP_THRESHOLD ); const allRepairFailed = recent . every ( e => e . intent === 'repair' && e . outcome . status === 'failed' ); if ( allRepairFailed ) { process . env . FORCE_INNOVATION = 'true' ; }
Example Usage # Basic run node index.js run # Dry run (no changes) node index.js run --dry-run # Loop mode node index.js run --loop # Drift mode (exploration) node index.js run --drift # Review mode (manual approval) node index.js run --review
Health Monitoring Location: src/evolve.js:252
function checkSystemHealth () { const report = []; const uptime = ( os . uptime () / 3600 ). toFixed ( 1 ); const rssMb = ( process . memoryUsage (). rss / 1024 / 1024 ). toFixed ( 1 ); const diskStats = fs . statfsSync ( '/' ); // Returns: 'Uptime: 12.3h | Node: v18.0.0 | Agent RSS: 256.0MB | Disk: 45% (100G free)' }
Maintenance Operations Location: src/evolve.js:453
function performMaintenance () { // Clean up evolver hand sessions immediately const evolverFiles = files . filter ( f => f . startsWith ( 'evolver_hand_' )); for ( const f of evolverFiles ) { fs . unlinkSync ( path . join ( AGENT_SESSIONS_DIR , f )); } // Archive old sessions when count exceeds threshold if ( remaining > 100 ) { const toArchive = fileStats . slice ( 0 , fileStats . length - 50 ); // Move to archive/ } }
