@novora/forge

Self-Evolution System for Claude Code

A four-layer architecture for autonomous self-improvement, enabling Claude Code to evolve and optimize itself through iterative mutation, fitness evaluation, and human-in-the-loop approval.

Quick Start

# Install
npm install @novora/forge

# Interactive setup (first-time users)
npm run init

# Or manual setup
npm run setup

# Initialize
import { createEvolutionOrchestrator } from '@novora/forge';

const orchestrator = createEvolutionOrchestrator({
  dataDirectory: './evolution-data',
  autoApprove: false,  // Human approval required
  fitnessThreshold: 0.7
});

await orchestrator.initialize();

// Run evolution cycle
const result = await orchestrator.runEvolutionCycle(`
  # Improve Error Handling

  Priority: high

  Description: Add comprehensive error handling to async functions.

  Criteria:
  - All async functions have try-catch blocks
  - Errors are logged with context
  - User-friendly error messages returned
`);

console.log(result.success ? 'Evolution applied!' : 'Evolution rejected');

CLI Usage

# List pending reviews
forge review list

# Show review details
forge review show <id>

# Approve a review
forge review approve <id> "Looks good"

# Reject a review
forge review reject <id> "Fitness too low"

# Run evolution cycle
forge cycle "Add error handling to async functions"

# View system statistics
forge stats

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          forge CLI                                  │
│  review list | show | approve | reject | stats | cycle             │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────────┐
│                     EvolutionOrchestrator                            │
│  runEvolutionCycle(requirement) → EvolutionResult                   │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
    ┌───────────────────────────┼───────────────────────────┐
    │                           │                           │
┌───▼───────────────────┐  ┌────▼────────────────────┐  ┌────▼──────────────┐
│       L1: Metrics     │  │       L2: Experiment    │  │     L3: Evolution │
│                       │  │                        │  │                    │
│  MetricsRetention     │  │  RequirementsChannel   │  │  Coordinator       │
│  - recordCycle()      │  │  - ingestRequirement() │  │  - proposeMutation()│
│  - getLatestMetrics() │  │  - parseRequirement()   │  │  - evaluateFitness()│
│  - getAverageFitness() │  │                        │  │                    │
│                       │  │  ExperimentSnapshot    │  │  L3Review          │
│  CycleMetrics         │  │  - createSnapshot()    │  │  - createReview()  │
│  RetentionStats       │  │  - restoreSnapshot()   │  │  - approveReview() │
└───────────────────────┘  └────────────────────────┘  │  - rejectReview()  │
                                                      └────────────────────┘
                                                                │
                                                      ┌─────────▼──────────┐
                                                      │       L4: Meta     │
                                                      │                     │
                                                      │  L4Circuits        │
                                                      │  - performMetaReview()│
                                                      │  - generateInsights() │
                                                      │  - checkHealth()    │
                                                      └─────────────────────┘

Layers

| Layer | Purpose | Key Components | |-------|---------|----------------| | L1: Metrics | Fitness data collection & retention | MetricsRetentionManager, CycleMetrics | | L2: Experiment | Requirements parsing & state management | RequirementsChannelManager, ExperimentSnapshotManager | | L3: Evolution | Mutation proposals & human approval | SelfEvolutionCoordinator, L3ReviewInterface | | L4: Meta-Review | Higher-order reasoning & bias detection | L4Circuits, MetaReviewResult |

Evolution Flow

1. INGEST REQUIREMENT
   ↓ (RequirementsChannelManager)

2. PROPOSE MUTATION
   ↓ (SelfEvolutionCoordinator)

3. EVALUATE FITNESS
   ↓ (MetricsRetentionManager + Coordinator)

4. CREATE REVIEW
   ↓ (L3ReviewInterface)

5. AWAIT APPROVAL
   ↓ (Human: approve/reject)

6. CREATE SNAPSHOT (for rollback)
   ↓ (ExperimentSnapshotManager)

7. APPLY MUTATION
   ↓ (SelfEvolutionCoordinator)

8. RECORD CYCLE METRICS
   ↓ (MetricsRetentionManager)

9. RETURN RESULT

API Reference

EvolutionOrchestrator

Main entry point for running evolution cycles.

import { createEvolutionOrchestrator } from '@novora/forge';

const orchestrator = createEvolutionOrchestrator({
  dataDirectory: './evolution-data',  // Storage location
  autoApprove: false,                  // Require human approval
  fitnessThreshold: 0.7,                // Minimum fitness to auto-approve
  maxRetries: 3,                       // Max retries on failure
  snapshotBeforeApply: true            // Create snapshot before mutation
});

await orchestrator.initialize();
const result = await orchestrator.runEvolutionCycle(requirementText);

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | dataDirectory | string | './evolution-data' | Storage directory | | autoApprove | boolean | false | Auto-approve above threshold | | fitnessThreshold | number | 0.7 | Fitness threshold for auto-approve | | maxRetries | number | 3 | Max retry attempts | | snapshotBeforeApply | boolean | true | Create rollback snapshot |

Methods

| Method | Returns | Description | |--------|---------|-------------| | initialize() | Promise<void> | Initialize all components | | runEvolutionCycle(text) | Promise<EvolutionResult> | Run full evolution cycle | | getPendingReviews() | Promise<ReviewItem[]> | List pending reviews | | approveReview(id, reviewer, notes) | Promise<void> | Approve a review | | rejectReview(id, reviewer, notes) | Promise<void> | Reject a review | | getStats() | Promise<Stats> | Get system statistics |

MetricsRetentionManager

Collects and retains fitness metrics across evolution cycles.

import { createMetricsRetentionManager } from '@novora/forge';

const metrics = createMetricsRetentionManager({
  dataDirectory: './metrics-data',
  rawMetricsRetention: 30,      // cycles
  aggregatedRetention: 90,       // days
  historicalRetention: 12        // months
});

await metrics.initialize();

// Record cycle metrics
await metrics.recordCycle({
  cycle: 1,
  timestamp: new Date(),
  data: {
    fitnessScore: 0.85,
    performance: 0.8,
    accuracy: 0.9,
    efficiency: 0.85,
    stability: 0.8,
    adaptability: 0.9
  }
});

// Get latest metrics
const latest = await metrics.getLatestMetrics();

// Calculate average fitness
const avgFitness = await metrics.getAverageFitness();

L3ReviewInterface

Human-in-the-loop approval workflow.

import { createL3ReviewInterface } from '@novora/forge';

const review = createL3ReviewInterface({
  storageDirectory: './review-data',
  reviewExpirationHours: 24,
  requireNotesForRejection: true,
  maxPendingReviews: 100
});

await review.initialize();

// Create review
const reviewItem = await review.createReview(
  'mutation',
  'target-file.ts',
  'Add error handling',
  'orchestrator',
  'high',
  { proposalId: 'mut_123' }
);

// Approve
await review.approveReview(reviewItem.id, 'human-reviewer', 'Approved');

// Reject
await review.rejectReview(reviewItem.id, 'human-reviewer', 'Insufficient coverage');

// Get dashboard data
const dashboard = await review.getDashboardData();

L4Circuits

Meta-review layer for bias detection and strategy optimization.

import { createL4Circuits } from '@novora/forge';

const l4 = createL4Circuits({
  storageDirectory: './l4-storage',
  metaReviewThreshold: 0.8,
  learningConfidenceThreshold: 0.7,
  enableAutoAdjustment: true
});

await l4.initialize();

// Perform meta-review on L3 decisions
const metaResult = await l4.performMetaReview([
  { decision: 'approve', reviewer: 'alice', notes: 'Good' },
  { decision: 'approve', reviewer: 'bob', notes: 'OK' }
]);

console.log(metaResult.biasDetected);    // true/false
console.log(metaResult.biasTypes);       // ['confirmation-bias']
console.log(metaResult.recommendation);   // 'revise' | 'approve' | 'reject' | 'escalate'

// Generate learning insights
const insights = await l4.generateInsights(evolutionHistory);

// Check circuit health
const health = await l4.checkHealth();
console.log(health.overall);  // 0-1 score

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | FORGE_DATA_DIR | ./evolution-data | Base data directory |

Retention Policy

Default retention for metrics data:

| Tier | Retention | Description | |------|-----------|-------------| | Raw | 30 cycles | Per-cycle detailed metrics | | Aggregated | 90 days | Daily summary data | | Historical | 12 months | Monthly trend analysis |

Error Handling

try {
  const result = await orchestrator.runEvolutionCycle(requirement);
} catch (error) {
  if (error instanceof EvolutionError) {
    console.log(`Evolution failed: ${error.code}`);
  }
}

Error Types

| Error Class | Code | Description | |-------------|------|-------------| | EvolutionError | Base class | General evolution errors | | MutationNotFoundError | MUTATION_NOT_FOUND | Proposal not found | | CycleNotFoundError | CYCLE_NOT_FOUND | Evolution cycle not found | | FitnessError | FITNESS_ERROR | Fitness evaluation failed | | ReviewError | Base class | Review workflow errors | | ReviewNotFoundError | REVIEW_NOT_FOUND | Review not found | | CircuitBreakerError | CIRCUIT_BREAKER_OPEN | Safety circuit tripped |

Testing

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run performance benchmarks
npm run test:perf

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for security policy.