agentdb 3.0.0-alpha.2 → 3.0.0-alpha.4

package/src/controllers/SkillLibrary.ts

@@ -0,0 +1,795 @@
+/**
+ * SkillLibrary - Lifelong Learning Skill Management
+ *
+ * Promotes high-reward trajectories into reusable skills.
+ * Manages skill composition, relationships, and adaptive selection.
+ *
+ * Based on: "Voyager: An Open-Ended Embodied Agent with Large Language Models"
+ * https://arxiv.org/abs/2305.16291
+ */
+
+// Database type from db-fallback
+type Database = any;
+import { EmbeddingService } from './EmbeddingService.js';
+import { VectorBackend } from '../backends/VectorBackend.js';
+import type { GraphDatabaseAdapter } from '../backends/graph/GraphDatabaseAdapter.js';
+import { NodeIdMapper } from '../utils/NodeIdMapper.js';
+import { cosineSimilarity } from '../utils/vector-math.js';
+
+export interface Skill {
+  id?: number;
+  name: string;
+  description?: string;
+  signature?: {  // v1 API: optional
+    inputs: Record<string, any>;
+    outputs: Record<string, any>;
+  };
+  code?: string;
+  successRate: number;
+  uses?: number;  // v1 API: optional (defaults to 0)
+  avgReward?: number;  // v1 API: optional (defaults to 0)
+  avgLatencyMs?: number;  // v1 API: optional (defaults to 0)
+  createdFromEpisode?: number;
+  metadata?: Record<string, any>;
+}
+
+export interface SkillLink {
+  parentSkillId: number;
+  childSkillId: number;
+  relationship: 'prerequisite' | 'alternative' | 'refinement' | 'composition';
+  weight: number;
+  metadata?: Record<string, any>;
+}
+
+export interface SkillQuery {
+  /** v2 API: task description */
+  task?: string;
+  /** v1 API: query string (alias for task) */
+  query?: string;
+  k?: number;
+  minSuccessRate?: number;
+  preferRecent?: boolean;
+}
+
+export class SkillLibrary {
+  private db: Database;
+  private embedder: EmbeddingService;
+  private vectorBackend: VectorBackend | null;
+  private graphBackend?: any; // GraphBackend or GraphDatabaseAdapter
+
+  constructor(db: Database, embedder: EmbeddingService, vectorBackend?: VectorBackend, graphBackend?: any) {
+    this.db = db;
+    this.embedder = embedder;
+    this.vectorBackend = vectorBackend || null;
+    this.graphBackend = graphBackend;
+  }
+
+  /**
+   * Create a new skill manually or from an episode
+   */
+  async createSkill(skill: Skill): Promise<number> {
+    // Use GraphDatabaseAdapter if available (AgentDB v2)
+    if (this.graphBackend && 'storeSkill' in this.graphBackend) {
+      const graphAdapter = this.graphBackend as any as GraphDatabaseAdapter;
+
+      const text = this.buildSkillText(skill);
+      const embedding = await this.embedder.embed(text);
+
+      const nodeId = await graphAdapter.storeSkill({
+        id: skill.id ? `skill-${skill.id}` : `skill-${Date.now()}-${Math.random()}`,
+        name: skill.name,
+        description: skill.description || '',
+        code: skill.code || '',
+        usageCount: skill.uses ?? 0,
+        avgReward: skill.avgReward ?? 0,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        tags: JSON.stringify(skill.metadata || {})
+      }, embedding);
+
+      const numericId = parseInt(nodeId.split('-').pop() || '0', 36);
+      NodeIdMapper.getInstance().register(numericId, nodeId);
+      return numericId;
+    }
+
+    // Fallback to SQLite
+    const stmt = this.db.prepare(`
+      INSERT INTO skills (
+        name, description, signature, code, success_rate, uses,
+        avg_reward, avg_latency_ms, metadata
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    // v1 API compatibility: provide defaults for optional fields
+    const signature = skill.signature || { inputs: {}, outputs: {} };
+    const uses = skill.uses ?? 0;
+    const avgReward = skill.avgReward ?? 0;
+    const avgLatencyMs = skill.avgLatencyMs ?? 0;
+
+    const result = stmt.run(
+      skill.name,
+      skill.description || null,
+      JSON.stringify(signature),
+      skill.code || null,
+      skill.successRate,
+      uses,
+      avgReward,
+      avgLatencyMs,
+      skill.metadata ? JSON.stringify(skill.metadata) : null
+    );
+
+    const skillId = result.lastInsertRowid as number;
+
+    // Generate and store embedding in VectorBackend
+    const text = this.buildSkillText(skill);
+    const embedding = await this.embedder.embed(text);
+
+    // Store in VectorBackend with skill metadata (if available)
+    if (this.vectorBackend) {
+      try {
+        this.vectorBackend.insert(
+          `skill:${skillId}`,
+          embedding,
+          {
+            name: skill.name,
+            description: skill.description,
+            successRate: skill.successRate,
+            avgReward: skill.avgReward
+          }
+        );
+      } catch {
+        // VectorBackend insert failed — fall back to legacy
+        this.storeSkillEmbeddingLegacy(skillId, embedding);
+      }
+    } else {
+      // Legacy: store in database
+      this.storeSkillEmbeddingLegacy(skillId, embedding);
+    }
+
+    return skillId;
+  }
+
+  /**
+   * Update skill statistics after use
+   */
+  updateSkillStats(skillId: number, success: boolean, reward: number, latencyMs: number): void {
+    const stmt = this.db.prepare(`
+      UPDATE skills
+      SET
+        uses = uses + 1,
+        success_rate = (success_rate * uses + ?) / (uses + 1),
+        avg_reward = (avg_reward * uses + ?) / (uses + 1),
+        avg_latency_ms = (avg_latency_ms * uses + ?) / (uses + 1)
+      WHERE id = ?
+    `);
+
+    stmt.run(success ? 1 : 0, reward, latencyMs, skillId);
+  }
+
+  /**
+   * Retrieve skills relevant to a task
+   */
+  async searchSkills(query: SkillQuery): Promise<Skill[]> {
+    return this.retrieveSkills(query);
+  }
+
+  async retrieveSkills(query: SkillQuery): Promise<Skill[]> {
+    // v1 API compatibility: accept both 'query' and 'task'
+    const task = query.task || query.query;
+    if (!task) {
+      throw new Error('SkillQuery must provide either task (v2) or query (v1)');
+    }
+
+    const { k = 5, minSuccessRate = 0.5, preferRecent = true } = query;
+
+    // Generate query embedding
+    const queryEmbedding = await this.embedder.embed(task);
+
+    // Use GraphDatabaseAdapter if available (AgentDB v2)
+    if (this.graphBackend && 'searchSkills' in this.graphBackend) {
+      const graphAdapter = this.graphBackend as any as GraphDatabaseAdapter;
+
+      const searchResults = await graphAdapter.searchSkills(queryEmbedding, k);
+
+      return searchResults.map(result => {
+        // Handle metadata/tags parsing
+        let metadata: any = undefined;
+        if (result.tags) {
+          if (typeof result.tags === 'string') {
+            // Skip parsing if it's a String object representation
+            if (!result.tags.startsWith('String(')) {
+              try {
+                metadata = JSON.parse(result.tags);
+              } catch (e) {
+                // Invalid JSON, skip
+                metadata = undefined;
+              }
+            }
+          } else {
+            // Already an object
+            metadata = result.tags;
+          }
+        }
+
+        return {
+          id: parseInt(result.id.split('-').pop() || '0', 36),
+          name: result.name,
+          description: result.description,
+          code: result.code,
+          successRate: result.avgReward, // Use avgReward as successRate proxy
+          uses: result.usageCount,
+          avgReward: result.avgReward,
+          metadata
+        };
+      }).filter(skill => skill.successRate >= minSuccessRate);
+    }
+
+    // Use VectorBackend for semantic search (if available)
+    if (this.vectorBackend) {
+      try {
+        const searchResults = this.vectorBackend.search(queryEmbedding, k * 3);
+
+        // Map results back to skill IDs and fetch full skill data
+        const skillsWithSimilarity: (Skill & { similarity: number })[] = [];
+
+        // Prepare statement ONCE outside loop (better-sqlite3 best practice)
+        const getSkillStmt = this.db.prepare('SELECT * FROM skills WHERE id = ?');
+
+        for (const result of searchResults) {
+          // Extract skill ID from vector ID (format: "skill:123")
+          const skillId = parseInt(result.id.replace('skill:', ''));
+
+          // Fetch full skill data from database
+          const row = getSkillStmt.get(skillId);
+
+          if (!row) continue;
+
+          // Apply filters
+          if (row.success_rate < minSuccessRate) continue;
+
+          skillsWithSimilarity.push({
+            id: row.id,
+            name: row.name,
+            description: row.description,
+            signature: JSON.parse(row.signature),
+            code: row.code,
+            successRate: row.success_rate,
+            uses: row.uses,
+            avgReward: row.avg_reward,
+            avgLatencyMs: row.avg_latency_ms,
+            createdFromEpisode: row.created_from_episode,
+            metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+            similarity: result.similarity
+          });
+        }
+
+        // Compute composite scores
+        skillsWithSimilarity.sort((a, b) => {
+          const scoreA = this.computeSkillScore(a);
+          const scoreB = this.computeSkillScore(b);
+          return scoreB - scoreA;
+        });
+
+        return skillsWithSimilarity.slice(0, k);
+      } catch { /* vectorBackend search failed — fall through to SQL */ }
+    }
+
+    // Legacy: use SQL-based similarity search
+    return this.retrieveSkillsLegacy(query);
+  }
+
+  /**
+   * Legacy SQL-based skill retrieval (fallback when VectorBackend not available)
+   */
+  private async retrieveSkillsLegacy(query: SkillQuery): Promise<Skill[]> {
+    // v1 API compatibility: accept both 'query' and 'task'
+    const task = query.task || query.query;
+    if (!task) {
+      throw new Error('SkillQuery must provide either task (v2) or query (v1)');
+    }
+
+    const { k = 5, minSuccessRate = 0.5 } = query;
+    const queryEmbedding = await this.embedder.embed(task);
+
+    // Fetch all skills with embeddings
+    const stmt = this.db.prepare(`
+      SELECT s.*, e.embedding
+      FROM skills s
+      LEFT JOIN skill_embeddings e ON s.id = e.skill_id
+      WHERE s.success_rate >= ?
+    `);
+    const rows = stmt.all(minSuccessRate);
+
+    // Compute similarities
+    const skillsWithSimilarity: (Skill & { similarity: number })[] = [];
+    for (const row of rows) {
+      if (!row.embedding) continue;
+
+      const embedding = new Float32Array(row.embedding.buffer);
+      const similarity = cosineSimilarity(queryEmbedding, embedding);
+
+      skillsWithSimilarity.push({
+        id: row.id,
+        name: row.name,
+        description: row.description,
+        signature: JSON.parse(row.signature),
+        code: row.code,
+        successRate: row.success_rate,
+        uses: row.uses,
+        avgReward: row.avg_reward,
+        avgLatencyMs: row.avg_latency_ms,
+        createdFromEpisode: row.created_from_episode,
+        metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+        similarity
+      });
+    }
+
+    // Sort by composite score
+    skillsWithSimilarity.sort((a, b) => {
+      const scoreA = this.computeSkillScore(a);
+      const scoreB = this.computeSkillScore(b);
+      return scoreB - scoreA;
+    });
+
+    return skillsWithSimilarity.slice(0, k);
+  }
+
+  /**
+   * Store skill embedding (legacy fallback)
+   */
+  private storeSkillEmbeddingLegacy(skillId: number, embedding: Float32Array): void {
+    const stmt = this.db.prepare(`
+      INSERT INTO skill_embeddings (skill_id, embedding)
+      VALUES (?, ?)
+      ON CONFLICT(skill_id) DO UPDATE SET embedding = excluded.embedding
+    `);
+    const buffer = Buffer.from(embedding.buffer);
+    stmt.run(skillId, buffer);
+  }
+
+  /**
+   * Link two skills with a relationship
+   */
+  linkSkills(link: SkillLink): void {
+    const stmt = this.db.prepare(`
+      INSERT INTO skill_links (parent_skill_id, child_skill_id, relationship, weight, metadata)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(parent_skill_id, child_skill_id, relationship)
+      DO UPDATE SET weight = excluded.weight
+    `);
+
+    stmt.run(
+      link.parentSkillId,
+      link.childSkillId,
+      link.relationship,
+      link.weight,
+      link.metadata ? JSON.stringify(link.metadata) : null
+    );
+  }
+
+  /**
+   * Get skill composition plan (prerequisites and alternatives)
+   */
+  getSkillPlan(skillId: number): {
+    skill: Skill;
+    prerequisites: Skill[];
+    alternatives: Skill[];
+    refinements: Skill[];
+  } {
+    // Get main skill
+    const skill = this.getSkillById(skillId);
+
+    // Get prerequisites
+    const prereqStmt = this.db.prepare(`
+      SELECT s.* FROM skills s
+      JOIN skill_links sl ON s.id = sl.child_skill_id
+      WHERE sl.parent_skill_id = ? AND sl.relationship = 'prerequisite'
+      ORDER BY sl.weight DESC
+    `);
+    const prerequisites = prereqStmt.all(skillId).map(this.rowToSkill);
+
+    // Get alternatives
+    const altStmt = this.db.prepare(`
+      SELECT s.* FROM skills s
+      JOIN skill_links sl ON s.id = sl.child_skill_id
+      WHERE sl.parent_skill_id = ? AND sl.relationship = 'alternative'
+      ORDER BY sl.weight DESC, s.success_rate DESC
+    `);
+    const alternatives = altStmt.all(skillId).map(this.rowToSkill);
+
+    // Get refinements
+    const refStmt = this.db.prepare(`
+      SELECT s.* FROM skills s
+      JOIN skill_links sl ON s.id = sl.child_skill_id
+      WHERE sl.parent_skill_id = ? AND sl.relationship = 'refinement'
+      ORDER BY sl.weight DESC, s.created_at DESC
+    `);
+    const refinements = refStmt.all(skillId).map(this.rowToSkill);
+
+    return { skill, prerequisites, alternatives, refinements };
+  }
+
+  /**
+   * Consolidate high-reward episodes into skills with ML pattern extraction
+   * This is the core learning mechanism enhanced with pattern analysis
+   */
+  async consolidateEpisodesIntoSkills(config: {
+    minAttempts?: number;
+    minReward?: number;
+    timeWindowDays?: number;
+    extractPatterns?: boolean;
+  }): Promise<{
+    created: number;
+    updated: number;
+    patterns: Array<{
+      task: string;
+      commonPatterns: string[];
+      successIndicators: string[];
+      avgReward: number;
+    }>;
+  }> {
+    const {
+      minAttempts = 3,
+      minReward = 0.7,
+      timeWindowDays = 7,
+      extractPatterns = true
+    } = config;
+
+    const stmt = this.db.prepare(`
+      SELECT
+        task,
+        COUNT(*) as attempt_count,
+        AVG(reward) as avg_reward,
+        AVG(success) as success_rate,
+        AVG(latency_ms) as avg_latency,
+        MAX(id) as latest_episode_id,
+        GROUP_CONCAT(id) as episode_ids
+      FROM episodes
+      WHERE ts > strftime('%s', 'now') - ?
+        AND reward >= ?
+      GROUP BY task
+      HAVING attempt_count >= ?
+    `);
+
+    const candidates = stmt.all(timeWindowDays * 86400, minReward, minAttempts);
+    let created = 0;
+    let updated = 0;
+    const patterns: Array<{
+      task: string;
+      commonPatterns: string[];
+      successIndicators: string[];
+      avgReward: number;
+    }> = [];
+
+    for (const candidate of candidates as any[]) {
+      const episodeIds = candidate.episode_ids.split(',').map(Number);
+
+      // Extract patterns from successful episodes if requested
+      let extractedPatterns: string[] = [];
+      let successIndicators: string[] = [];
+      let enhancedDescription = `Auto-generated skill from successful episodes`;
+
+      if (extractPatterns) {
+        const patternData = await this.extractPatternsFromEpisodes(episodeIds);
+        extractedPatterns = patternData.commonPatterns;
+        successIndicators = patternData.successIndicators;
+
+        if (extractedPatterns.length > 0) {
+          enhancedDescription = `Skill learned from ${episodeIds.length} successful episodes. Common patterns: ${extractedPatterns.slice(0, 3).join(', ')}`;
+        }
+
+        patterns.push({
+          task: candidate.task,
+          commonPatterns: extractedPatterns,
+          successIndicators: successIndicators,
+          avgReward: candidate.avg_reward
+        });
+      }
+
+      // Check if skill already exists
+      const existing = this.db.prepare('SELECT id FROM skills WHERE name = ?').get(candidate.task);
+
+      if (!existing) {
+        // Create new skill with extracted patterns
+        const skill: Skill = {
+          name: candidate.task,
+          description: enhancedDescription,
+          signature: {
+            inputs: { task: 'string' },
+            outputs: { result: 'any' }
+          },
+          successRate: candidate.success_rate,
+          uses: candidate.attempt_count,
+          avgReward: candidate.avg_reward,
+          avgLatencyMs: candidate.avg_latency || 0,
+          createdFromEpisode: candidate.latest_episode_id,
+          metadata: {
+            sourceEpisodes: episodeIds,
+            autoGenerated: true,
+            consolidatedAt: Date.now(),
+            extractedPatterns: extractedPatterns,
+            successIndicators: successIndicators,
+            patternConfidence: this.calculatePatternConfidence(episodeIds.length, candidate.success_rate)
+          }
+        };
+
+        await this.createSkill(skill);
+        created++;
+      } else {
+        // Update existing skill stats
+        this.updateSkillStats(
+          (existing as any).id,
+          candidate.success_rate > 0.5,
+          candidate.avg_reward,
+          candidate.avg_latency || 0
+        );
+        updated++;
+      }
+    }
+
+    return { created, updated, patterns };
+  }
+
+  /**
+   * Extract common patterns from successful episodes using ML-inspired analysis
+   */
+  private async extractPatternsFromEpisodes(episodeIds: number[]): Promise<{
+    commonPatterns: string[];
+    successIndicators: string[];
+  }> {
+    // Retrieve episodes with their outputs and critiques
+    const episodes = this.db.prepare(`
+      SELECT id, task, input, output, critique, reward, success, metadata
+      FROM episodes
+      WHERE id IN (${episodeIds.map(() => '?').join(',')})
+      AND success = 1
+    `).all(...episodeIds) as any[];
+
+    if (episodes.length === 0) {
+      return { commonPatterns: [], successIndicators: [] };
+    }
+
+    const commonPatterns: string[] = [];
+    const successIndicators: string[] = [];
+
+    // Pattern 1: Analyze output text for common keywords and phrases
+    const outputTexts = episodes
+      .map(ep => ep.output)
+      .filter(Boolean);
+
+    if (outputTexts.length > 0) {
+      const keywordFrequency = this.extractKeywordFrequency(outputTexts);
+      const topKeywords = this.getTopKeywords(keywordFrequency, 5);
+
+      if (topKeywords.length > 0) {
+        commonPatterns.push(`Common techniques: ${topKeywords.join(', ')}`);
+      }
+    }
+
+    // Pattern 2: Analyze critique patterns for successful strategies
+    const critiques = episodes
+      .map(ep => ep.critique)
+      .filter(Boolean);
+
+    if (critiques.length > 0) {
+      const critiqueKeywords = this.extractKeywordFrequency(critiques);
+      const topCritiquePatterns = this.getTopKeywords(critiqueKeywords, 3);
+
+      if (topCritiquePatterns.length > 0) {
+        successIndicators.push(...topCritiquePatterns);
+      }
+    }
+
+    // Pattern 3: Analyze reward distribution
+    const avgReward = episodes.reduce((sum, ep) => sum + ep.reward, 0) / episodes.length;
+    const highRewardCount = episodes.filter(ep => ep.reward > avgReward).length;
+    const highRewardRatio = highRewardCount / episodes.length;
+
+    if (highRewardRatio > 0.6) {
+      successIndicators.push(`High consistency (${(highRewardRatio * 100).toFixed(0)}% above average)`);
+    }
+
+    // Pattern 4: Analyze metadata for common parameters
+    const metadataPatterns = this.extractMetadataPatterns(episodes);
+    if (metadataPatterns.length > 0) {
+      commonPatterns.push(...metadataPatterns);
+    }
+
+    // Pattern 5: Temporal analysis - learning curve
+    const learningTrend = this.analyzeLearningTrend(episodes);
+    if (learningTrend) {
+      successIndicators.push(learningTrend);
+    }
+
+    return { commonPatterns, successIndicators };
+  }
+
+  /**
+   * Extract keyword frequency from text array using NLP-inspired techniques
+   */
+  private extractKeywordFrequency(texts: string[]): Map<string, number> {
+    const frequency = new Map<string, number>();
+
+    // Common stop words to filter out
+    const stopWords = new Set([
+      'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+      'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are', 'were', 'been',
+      'be', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'should',
+      'could', 'may', 'might', 'must', 'can', 'this', 'that', 'these', 'those'
+    ]);
+
+    for (const text of texts) {
+      // Extract words (alphanumeric sequences)
+      const words = text.toLowerCase().match(/\b[a-z0-9_-]+\b/g) || [];
+
+      for (const word of words) {
+        if (word.length > 3 && !stopWords.has(word)) {
+          frequency.set(word, (frequency.get(word) || 0) + 1);
+        }
+      }
+    }
+
+    return frequency;
+  }
+
+  /**
+   * Get top N keywords by frequency
+   */
+  private getTopKeywords(frequency: Map<string, number>, n: number): string[] {
+    return Array.from(frequency.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, n)
+      .filter(([_, count]) => count >= 2) // Only keywords appearing at least twice
+      .map(([word, _]) => word);
+  }
+
+  /**
+   * Extract common patterns from episode metadata
+   */
+  private extractMetadataPatterns(episodes: any[]): string[] {
+    const patterns: string[] = [];
+    const metadataFields = new Map<string, Set<any>>();
+
+    for (const episode of episodes) {
+      if (episode.metadata) {
+        try {
+          const metadata = typeof episode.metadata === 'string'
+            ? JSON.parse(episode.metadata)
+            : episode.metadata;
+
+          for (const [key, value] of Object.entries(metadata)) {
+            if (!metadataFields.has(key)) {
+              metadataFields.set(key, new Set());
+            }
+            metadataFields.get(key)!.add(value);
+          }
+        } catch (e) {
+          // Skip invalid metadata
+        }
+      }
+    }
+
+    // Find fields with consistent values
+    metadataFields.forEach((values, field) => {
+      if (values.size === 1) {
+        // All episodes have the same value for this field
+        const value = Array.from(values)[0];
+        patterns.push(`Consistent ${field}: ${value}`);
+      }
+    });
+
+    return patterns;
+  }
+
+  /**
+   * Analyze learning trend across episodes
+   */
+  private analyzeLearningTrend(episodes: any[]): string | null {
+    if (episodes.length < 3) return null;
+
+    // Sort by episode ID (temporal order)
+    const sorted = [...episodes].sort((a, b) => a.id - b.id);
+
+    const firstHalfReward = sorted.slice(0, Math.floor(sorted.length / 2))
+      .reduce((sum, ep) => sum + ep.reward, 0) / Math.floor(sorted.length / 2);
+
+    const secondHalfReward = sorted.slice(Math.floor(sorted.length / 2))
+      .reduce((sum, ep) => sum + ep.reward, 0) / (sorted.length - Math.floor(sorted.length / 2));
+
+    const improvement = ((secondHalfReward - firstHalfReward) / firstHalfReward) * 100;
+
+    if (improvement > 10) {
+      return `Strong learning curve (+${improvement.toFixed(0)}% improvement)`;
+    } else if (improvement > 5) {
+      return `Moderate learning curve (+${improvement.toFixed(0)}% improvement)`;
+    } else if (Math.abs(improvement) < 5) {
+      return `Stable performance (±${Math.abs(improvement).toFixed(0)}%)`;
+    }
+
+    return null;
+  }
+
+  /**
+   * Calculate pattern confidence score based on sample size and success rate
+   */
+  private calculatePatternConfidence(sampleSize: number, successRate: number): number {
+    // Confidence increases with sample size and success rate
+    // Using a sigmoid-like function for smooth scaling
+    const sampleFactor = Math.min(sampleSize / 10, 1.0); // Saturates at 10 samples
+    const successFactor = successRate;
+
+    return Math.min(sampleFactor * successFactor, 0.99);
+  }
+
+  /**
+   * Prune underperforming skills
+   */
+  pruneSkills(config: {
+    minUses?: number;
+    minSuccessRate?: number;
+    maxAgeDays?: number;
+  }): number {
+    const { minUses = 3, minSuccessRate = 0.4, maxAgeDays = 60 } = config;
+
+    const stmt = this.db.prepare(`
+      DELETE FROM skills
+      WHERE uses < ?
+        AND success_rate < ?
+        AND created_at < strftime('%s', 'now') - ?
+    `);
+
+    const result = stmt.run(minUses, minSuccessRate, maxAgeDays * 86400);
+    return result.changes;
+  }
+
+  // ========================================================================
+  // Private Helper Methods
+  // ========================================================================
+
+  private getSkillById(id: number): Skill {
+    const stmt = this.db.prepare('SELECT * FROM skills WHERE id = ?');
+    const row = stmt.get(id);
+    if (!row) throw new Error(`Skill ${id} not found`);
+    return this.rowToSkill(row);
+  }
+
+  private rowToSkill(row: any): Skill {
+    return {
+      id: row.id,
+      name: row.name,
+      description: row.description,
+      signature: JSON.parse(row.signature),
+      code: row.code,
+      successRate: row.success_rate,
+      uses: row.uses,
+      avgReward: row.avg_reward,
+      avgLatencyMs: row.avg_latency_ms,
+      createdFromEpisode: row.created_from_episode,
+      metadata: row.metadata ? JSON.parse(row.metadata) : undefined
+    };
+  }
+
+  private buildSkillText(skill: Skill): string {
+    const parts = [skill.name];
+    if (skill.description) parts.push(skill.description);
+    parts.push(JSON.stringify(skill.signature));
+    return parts.join('\n');
+  }
+
+  /**
+   * Compute composite skill score from similarity and metadata
+   * VectorBackend provides normalized similarity (0-1)
+   */
+  private computeSkillScore(skill: Skill & { similarity: number }): number {
+    // Composite score: similarity * 0.4 + success_rate * 0.3 + (uses/1000) * 0.1 + avg_reward * 0.2
+    const uses = skill.uses ?? 0;
+    const avgReward = skill.avgReward ?? 0;
+
+    return (
+      skill.similarity * 0.4 +
+      skill.successRate * 0.3 +
+      Math.min(uses / 1000, 1.0) * 0.1 +
+      avgReward * 0.2
+    );
+  }
+}