evolve.run()

Main orchestrator for the Evolver framework

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

async function run()

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

AGENT_NAME · string · default: "main"

Name of the agent instance

RANDOM_DRIFT · boolean · default: "false"

Enable random drift mode for exploration

EVOLVE_LOOP · boolean · default: "false"

Enable continuous loop mode

EVOLVE_BRIDGE · boolean · default: "true"

Enable bridge mode for hand agent integration

EVOLVE_LOAD_MAX · number

Maximum system load threshold (auto-calculated based on CPU cores if not set)

EVOLVE_AGENT_QUEUE_MAX · number · default: "10"

Maximum active user sessions before backing off

FORCE_INNOVATION · boolean · default: "false"

Force innovation intent (internal use)

CLI Flags

--review · flag

Enable review mode (pause before applying changes)

--dry-run · flag

Run without making actual changes

--drift · flag

Enable random drift mode

--loop · flag

Run in continuous loop mode

Return Value

void · Promise<void>

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;
}

Phase 2: Signal Extraction

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

// 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';
}

Related Functions

• extractSignals() - Extract structured signals from logs
• selectGeneAndCapsule() - Select appropriate gene
• recordSignalSnapshot() - Record signals to memory
• buildMutation() - Build mutation object
• solidify() - Validate and commit changes

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/
  }
}