cognitive-core 0.1.0 → 0.1.2

package/src/learning/knowledge-extractor.ts

@@ -0,0 +1,470 @@
+import type { Trajectory } from '../types/trajectory.js';
+import type { AnalysisResult } from './analyzer.js';
+import type {
+  ExtractedKnowledge,
+  EntityUpdate,
+  NewLink,
+  PlaybookLink,
+  KnowledgeNote,
+} from '../types/knowledge.js';
+import { createObservation } from '../types/knowledge.js';
+import { tokenize } from '../utils/similarity.js';
+
+/**
+ * Configuration for the KnowledgeExtractor.
+ */
+export interface KnowledgeExtractorConfig {
+  /** Minimum confidence for new observations (default: 0.3) */
+  initialConfidence: number;
+  /** Similarity threshold for matching entities in text (default: 0.6) */
+  entityMatchThreshold: number;
+  /** Config file patterns to detect (default: common config files) */
+  configFilePatterns: string[];
+}
+
+const DEFAULT_CONFIG: KnowledgeExtractorConfig = {
+  initialConfidence: 0.3,
+  entityMatchThreshold: 0.6,
+  configFilePatterns: [
+    'package.json',
+    'tsconfig.json',
+    'tsconfig',
+    '.eslintrc',
+    'eslint.config',
+    '.prettierrc',
+    'jest.config',
+    'vitest.config',
+    'vite.config',
+    'webpack.config',
+    'next.config',
+    'docker',
+    'Dockerfile',
+    '.env',
+    'Makefile',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+  ],
+};
+
+/**
+ * Context about existing knowledge for smarter extraction.
+ */
+export interface ExtractionContext {
+  /** Known entity names from the knowledge bank */
+  existingEntities?: string[];
+  /** Known note IDs (to avoid creating duplicates) */
+  existingNoteIds?: string[];
+}
+
+/**
+ * KnowledgeExtractor — heuristic engine for extracting factual knowledge
+ * from agent trajectories.
+ *
+ * Runs 4 strategies:
+ * 1. Error patterns → observations (from AnalysisResult.errorPatterns)
+ * 2. Config facts → observations (detect config file reads/writes)
+ * 3. Causal chains → observations + causal links (failure→recovery)
+ * 4. Entity identification → entity updates or new observations
+ *
+ * Plus cross-reference detection for playbook links.
+ */
+export class KnowledgeExtractor {
+  private config: KnowledgeExtractorConfig;
+
+  constructor(config?: Partial<KnowledgeExtractorConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Extract knowledge from a single trajectory and its analysis.
+   */
+  extract(
+    trajectory: Trajectory,
+    analysis: AnalysisResult,
+    context?: ExtractionContext
+  ): ExtractedKnowledge {
+    const observations: KnowledgeNote[] = [];
+    const entityUpdates: EntityUpdate[] = [];
+    const links: NewLink[] = [];
+    const playbookLinks: PlaybookLink[] = [];
+
+    // Strategy 1: Error patterns
+    const errorObs = this.extractErrorPatterns(trajectory, analysis);
+    observations.push(...errorObs);
+
+    // Strategy 2: Config facts
+    const configObs = this.extractConfigFacts(trajectory);
+    observations.push(...configObs);
+
+    // Strategy 3: Causal chains
+    const { observations: causalObs, links: causalLinks } =
+      this.extractCausalChains(trajectory);
+    observations.push(...causalObs);
+    links.push(...causalLinks);
+
+    // Strategy 4: Entity identification
+    const entityResults = this.extractEntityKnowledge(
+      trajectory,
+      analysis,
+      observations,
+      context
+    );
+    entityUpdates.push(...entityResults.updates);
+
+    // Cross-reference: playbook links
+    const pbLinks = this.extractPlaybookLinks(trajectory, observations);
+    playbookLinks.push(...pbLinks);
+
+    return {
+      observations,
+      entityUpdates,
+      contradictions: [], // Deferred to Phase 3
+      links,
+      playbookLinks,
+    };
+  }
+
+  // =========================================================================
+  // Strategy 1: Error Patterns → Observations
+  // =========================================================================
+
+  private extractErrorPatterns(
+    trajectory: Trajectory,
+    analysis: AnalysisResult
+  ): KnowledgeNote[] {
+    const observations: KnowledgeNote[] = [];
+
+    for (const pattern of analysis.errorPatterns) {
+      if (!pattern.suggestedFix) continue;
+
+      // Extract tool/library name from the error signature
+      const entities = this.extractEntitiesFromText(
+        `${pattern.signature} ${pattern.description}`
+      );
+
+      observations.push(
+        createObservation({
+          title: `${pattern.type} error: ${pattern.signature}`,
+          body: [
+            `## Error Pattern`,
+            '',
+            `**Type**: ${pattern.type}`,
+            `**Signature**: ${pattern.signature}`,
+            `**Description**: ${pattern.description}`,
+            `**Fix**: ${pattern.suggestedFix}`,
+            '',
+            `*Observed in trajectory ${trajectory.id}, domain: ${trajectory.task.domain}*`,
+          ].join('\n'),
+          domain: [trajectory.task.domain],
+          entities,
+          tags: ['error-pattern', pattern.type],
+          confidence: this.config.initialConfidence,
+          source: {
+            origin: 'extracted',
+            trajectories: [trajectory.id],
+          },
+        })
+      );
+    }
+
+    return observations;
+  }
+
+  // =========================================================================
+  // Strategy 2: Config Facts
+  // =========================================================================
+
+  private extractConfigFacts(trajectory: Trajectory): KnowledgeNote[] {
+    const observations: KnowledgeNote[] = [];
+    const seenConfigs = new Set<string>();
+
+    for (const step of trajectory.steps) {
+      const actionLower = step.action.toLowerCase();
+      const obsLower = step.observation.toLowerCase();
+
+      for (const pattern of this.config.configFilePatterns) {
+        const patternLower = pattern.toLowerCase();
+        if (
+          !actionLower.includes(patternLower) &&
+          !obsLower.includes(patternLower)
+        ) {
+          continue;
+        }
+
+        // Avoid duplicate observations for the same config file
+        if (seenConfigs.has(pattern)) continue;
+        seenConfigs.add(pattern);
+
+        // Extract version-like strings from the observation
+        const versions = this.extractVersions(step.observation);
+        const entities = this.extractEntitiesFromText(
+          `${step.action} ${step.observation}`
+        );
+
+        const bodyParts = [
+          `## Configuration: ${pattern}`,
+          '',
+          `**Action**: ${step.action.slice(0, 200)}`,
+        ];
+
+        if (versions.length > 0) {
+          bodyParts.push(`**Versions detected**: ${versions.join(', ')}`);
+        }
+
+        bodyParts.push(
+          '',
+          `**Observation**: ${step.observation.slice(0, 300)}`,
+          '',
+          `*Observed in trajectory ${trajectory.id}*`
+        );
+
+        observations.push(
+          createObservation({
+            title: `Config: ${pattern} settings`,
+            body: bodyParts.join('\n'),
+            domain: [trajectory.task.domain],
+            entities,
+            tags: ['config', pattern.replace(/[^a-zA-Z0-9]/g, '-')],
+            confidence: this.config.initialConfidence,
+            source: {
+              origin: 'extracted',
+              trajectories: [trajectory.id],
+            },
+          })
+        );
+      }
+    }
+
+    return observations;
+  }
+
+  // =========================================================================
+  // Strategy 3: Causal Chains (failure → recovery)
+  // =========================================================================
+
+  private extractCausalChains(trajectory: Trajectory): {
+    observations: KnowledgeNote[];
+    links: NewLink[];
+  } {
+    const observations: KnowledgeNote[] = [];
+    const links: NewLink[] = [];
+
+    for (let i = 0; i < trajectory.steps.length - 1; i++) {
+      const step = trajectory.steps[i];
+      const isFailure = this.isFailureStep(step);
+
+      if (!isFailure) continue;
+
+      // Look for recovery in the next 1-3 steps
+      const recoverySteps = [];
+      for (
+        let j = i + 1;
+        j < Math.min(i + 4, trajectory.steps.length);
+        j++
+      ) {
+        const nextStep = trajectory.steps[j];
+        if (!this.isFailureStep(nextStep)) {
+          recoverySteps.push(nextStep);
+          break;
+        }
+      }
+
+      if (recoverySteps.length === 0) continue;
+
+      const recovery = recoverySteps[0];
+      const entities = this.extractEntitiesFromText(
+        `${step.action} ${step.observation} ${recovery.action}`
+      );
+
+      const failureObs = createObservation({
+        title: `Failure-recovery: ${step.action.slice(0, 50)}`,
+        body: [
+          `## Causal Chain`,
+          '',
+          `**Failed action**: ${step.action.slice(0, 200)}`,
+          `**Error**: ${step.observation.slice(0, 200)}`,
+          `**Recovery action**: ${recovery.action.slice(0, 200)}`,
+          `**Result**: ${recovery.observation.slice(0, 200)}`,
+          '',
+          `*Observed in trajectory ${trajectory.id}*`,
+        ].join('\n'),
+        domain: [trajectory.task.domain],
+        entities,
+        tags: ['causal-chain', 'failure-recovery'],
+        confidence: this.config.initialConfidence,
+        source: {
+          origin: 'extracted',
+          trajectories: [trajectory.id],
+        },
+        links: [
+          {
+            target: `recovery-${trajectory.id}-${i}`,
+            relation: 'led-to',
+          },
+        ],
+      });
+
+      observations.push(failureObs);
+
+      links.push({
+        from: failureObs.frontmatter.id,
+        to: `recovery-${trajectory.id}-${i}`,
+        relation: 'led-to',
+        layer: 'causal',
+      });
+    }
+
+    return { observations, links };
+  }
+
+  // =========================================================================
+  // Strategy 4: Entity Identification
+  // =========================================================================
+
+  private extractEntityKnowledge(
+    trajectory: Trajectory,
+    _analysis: AnalysisResult,
+    newObservations: KnowledgeNote[],
+    context?: ExtractionContext
+  ): { updates: EntityUpdate[] } {
+    const updates: EntityUpdate[] = [];
+    const existingEntities = new Set(context?.existingEntities ?? []);
+
+    if (existingEntities.size === 0) return { updates };
+
+    // For each existing entity, check if new observations mention it
+    for (const entityName of existingEntities) {
+      const entityLower = entityName.toLowerCase();
+      const relevantObs = newObservations.filter((obs) => {
+        const text =
+          `${obs.frontmatter.entities.join(' ')} ${obs.body}`.toLowerCase();
+        return text.includes(entityLower);
+      });
+
+      if (relevantObs.length === 0) continue;
+
+      // Produce an entity update with new evidence
+      const summaries = relevantObs
+        .map((obs) => `- ${obs.body.split('\n')[0].replace(/^#+ /, '')}`)
+        .join('\n');
+
+      updates.push({
+        entityId: entityName.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+        section: `## Evidence from trajectory ${trajectory.id}\n\n${summaries}`,
+        trajectoryId: trajectory.id,
+      });
+    }
+
+    return { updates };
+  }
+
+  // =========================================================================
+  // Cross-Reference: Playbook Links
+  // =========================================================================
+
+  private extractPlaybookLinks(
+    trajectory: Trajectory,
+    observations: KnowledgeNote[]
+  ): PlaybookLink[] {
+    const links: PlaybookLink[] = [];
+
+    // Check trajectory metadata for injected playbooks
+    const injectedPlaybooks = trajectory.metadata?.injectedPlaybooks;
+    if (!Array.isArray(injectedPlaybooks) || injectedPlaybooks.length === 0) {
+      return links;
+    }
+
+    // Link each new observation to each injected playbook
+    for (const obs of observations) {
+      for (const playbookId of injectedPlaybooks) {
+        if (typeof playbookId !== 'string') continue;
+
+        links.push({
+          noteId: obs.frontmatter.id,
+          playbookId,
+          relation: 'supports',
+        });
+      }
+    }
+
+    return links;
+  }
+
+  // =========================================================================
+  // Helpers
+  // =========================================================================
+
+  private isFailureStep(step: { action: string; observation: string }): boolean {
+    const obs = step.observation.toLowerCase();
+    return (
+      obs.includes('error') ||
+      obs.includes('failed') ||
+      obs.includes('exception') ||
+      obs.includes('cannot') ||
+      obs.includes('unable to') ||
+      obs.includes('not found')
+    );
+  }
+
+  private extractEntitiesFromText(text: string): string[] {
+    const entities: string[] = [];
+    const tokens = tokenize(text);
+
+    // Known tool/library patterns
+    const knownPatterns = [
+      /\b(node|npm|yarn|pnpm|bun)\b/i,
+      /\b(react|vue|angular|svelte|next|nuxt)\b/i,
+      /\b(express|fastify|koa|hono)\b/i,
+      /\b(prisma|drizzle|typeorm|sequelize|knex)\b/i,
+      /\b(postgres|mysql|sqlite|mongodb|redis)\b/i,
+      /\b(docker|kubernetes|k8s)\b/i,
+      /\b(typescript|javascript|python|rust|go)\b/i,
+      /\b(vitest|jest|mocha|playwright|cypress)\b/i,
+      /\b(eslint|prettier|biome)\b/i,
+      /\b(webpack|vite|esbuild|rollup|turbopack)\b/i,
+      /\b(git|github|gitlab)\b/i,
+    ];
+
+    for (const pattern of knownPatterns) {
+      const match = text.match(pattern);
+      if (match) {
+        const entity = match[1].toLowerCase();
+        if (!entities.includes(entity)) {
+          entities.push(entity);
+        }
+      }
+    }
+
+    // Also extract npm package-like names (scoped or simple)
+    const packagePattern = /@?[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)?/g;
+    const matches = text.match(packagePattern);
+    if (matches) {
+      for (const m of matches) {
+        if (m.length >= 3 && m.length <= 50 && !entities.includes(m)) {
+          // Only include if it looks like a real package name
+          if (tokens.includes(m) || text.includes(`"${m}"`)) {
+            entities.push(m);
+          }
+        }
+      }
+    }
+
+    return entities.slice(0, 10); // Cap at 10 entities
+  }
+
+  private extractVersions(text: string): string[] {
+    const versionPattern = /\b\d+\.\d+(?:\.\d+)?(?:-[a-zA-Z0-9.]+)?\b/g;
+    const matches = text.match(versionPattern);
+    return matches ? [...new Set(matches)] : [];
+  }
+}
+
+/**
+ * Create a KnowledgeExtractor with optional config overrides.
+ */
+export function createKnowledgeExtractor(
+  config?: Partial<KnowledgeExtractorConfig>
+): KnowledgeExtractor {
+  return new KnowledgeExtractor(config);
+}

package/src/learning/meta-learner.ts

@@ -16,6 +16,7 @@ import type {
 import { createMetaObservation, createMetaStrategy } from '../types/index.js';
 import type { MetaMemory } from '../memory/meta.js';
 import type { PlaybookMatch } from '../memory/playbook.js';
+import type { MetaReflectionOutput } from '../workspace/templates/meta-reflection.js';
 
 /**
  * Routing decision from the router
@@ -129,6 +130,59 @@ export class MetaLearner {
     return observation;
   }
 
+  /**
+   * Record a meta-observation from workspace-based reflection output.
+   * Bridges MetaReflectionOutput (from the meta-reflection template)
+   * into the MetaObservation storage format.
+   */
+  async recordFromReflection(
+    reflection: MetaReflectionOutput,
+    trajectoryId: string,
+    routing: RoutingDecision,
+    playbookIds: string[],
+    actualEffort: number,
+  ): Promise<MetaObservation> {
+    const observation = createMetaObservation({
+      trajectoryId,
+      routing: {
+        decision: routing.strategy,
+        confidence: routing.confidence,
+        reasoning: routing.reasoning,
+      },
+      memoryUsage: {
+        experiencesRetrieved: 0,
+        playbooksApplied: playbookIds,
+        retrievalQuality: reflection.retrievalQuality,
+      },
+      execution: {
+        decompositionUsed: reflection.decompositionUsed,
+        refinementIterations: reflection.refinementIterations,
+        backtrackingOccurred: reflection.backtrackingOccurred,
+        toolsUsed: [],
+      },
+      outcome: {
+        success: reflection.outcomeQuality !== 'poor',
+        quality: reflection.outcomeQuality,
+        effortActual: actualEffort,
+        effortEstimate: routing.estimatedBudget,
+      },
+      lessons: {
+        whatWorked: reflection.whatWorked,
+        whatFailed: reflection.whatFailed,
+        suggestions: reflection.suggestions,
+      },
+    });
+
+    await this.meta.recordObservation(observation);
+    this.observationCount++;
+
+    if (this.observationCount % this.config.strategyGenerationInterval === 0) {
+      await this.learn();
+    }
+
+    return observation;
+  }
+
   /**
    * Analyze accumulated observations and generate meta-strategies
    */

package/src/learning/pipeline.ts

@@ -2,6 +2,7 @@ import type {
   Trajectory,
   LearningConfig,
 } from '../types/index.js';
+import type { TrajectoryWithAnalysis } from '../types/trajectory-source.js';
 import type { MemorySystem } from '../memory/system.js';
 import {
   TrajectoryAnalyzer,
@@ -12,6 +13,9 @@ import {
   PlaybookExtractor,
   createPlaybookExtractor,
 } from './playbook-extractor.js';
+import type { AgenticTaskRunner } from '../workspace/runner.js';
+import { trajectoryAnalysisTemplate } from '../workspace/templates/trajectory-analysis.js';
+import { playbookExtractionTemplate } from '../workspace/templates/playbook-extraction.js';
 
 /**
  * Result of processing a single trajectory
@@ -44,6 +48,9 @@ export class LearningPipeline {
   private memory: MemorySystem;
   private config: LearningConfig;
 
+  // Optional agentic task runner for workspace-based analysis
+  private taskRunner: AgenticTaskRunner | null = null;
+
   // Accumulated trajectories for batch learning
   private accumulated: Trajectory[] = [];
   private accumulatedAnalyses: AnalysisResult[] = [];
@@ -69,6 +76,14 @@ export class LearningPipeline {
     });
   }
 
+  /**
+   * Set the agentic task runner for workspace-based analysis.
+   * When set, analysis tasks are delegated to templates (with heuristic fallback).
+   */
+  setTaskRunner(runner: AgenticTaskRunner): void {
+    this.taskRunner = runner;
+  }
+
   /**
    * Process a single trajectory
    */
@@ -76,8 +91,13 @@ export class LearningPipeline {
     // Store in experience memory
     await this.memory.storeTrajectory(trajectory);
 
-    // Analyze the trajectory
-    const analysis = await this.analyzer.analyze(trajectory);
+    // Analyze: workspace-based when runner available, heuristic otherwise
+    let analysis: AnalysisResult;
+    if (this.taskRunner) {
+      analysis = await this.analyzeWithTemplate(trajectory);
+    } else {
+      analysis = await this.analyzer.analyze(trajectory);
+    }
 
     // Accumulate for batch learning
     this.accumulated.push(trajectory);
@@ -92,6 +112,28 @@ export class LearningPipeline {
     };
   }
 
+  /**
+   * Run trajectory analysis via the workspace template.
+   * The template's assessComplexity() routes simple cases to heuristicFallback()
+   * (which calls the existing TrajectoryAnalyzer), so this is safe for all inputs.
+   */
+  private async analyzeWithTemplate(trajectory: Trajectory): Promise<AnalysisResult> {
+    try {
+      const result = await this.taskRunner!.run(trajectoryAnalysisTemplate, {
+        trajectory,
+        creditStrategy: this.config.creditStrategy,
+      });
+      return result.output;
+    } catch (error) {
+      // If workspace-based analysis fails, fall back to heuristic
+      console.error(
+        'Workspace-based trajectory analysis failed, falling back to heuristic:',
+        error instanceof Error ? error.message : error
+      );
+      return this.analyzer.analyze(trajectory);
+    }
+  }
+
   /**
    * Check if batch learning should run
    */
@@ -137,14 +179,10 @@ export class LearningPipeline {
       };
     }
 
-    // Extract playbooks from trajectories
+    // Extract playbooks: workspace-based when runner available, heuristic otherwise
     let playbooksAdded = 0;
     const existingPlaybooks = await this.memory.playbooks.getAll();
-    const playbookExtraction = await this.playbookExtractor.extract(
-      this.accumulated,
-      this.accumulatedAnalyses,
-      existingPlaybooks
-    );
+    const playbookExtraction = await this.extractPlaybooks(existingPlaybooks);
 
     // Add new playbooks
     for (const playbook of playbookExtraction.new) {
@@ -207,6 +245,36 @@ export class LearningPipeline {
     };
   }
 
+  /**
+   * Run playbook extraction via the workspace template.
+   * Falls back to heuristic extractor on failure.
+   */
+  private async extractPlaybooks(
+    existingPlaybooks: import('../types/index.js').Playbook[]
+  ): Promise<import('./playbook-extractor.js').ExtractedPlaybooks> {
+    if (this.taskRunner) {
+      try {
+        const result = await this.taskRunner.run(playbookExtractionTemplate, {
+          trajectories: this.accumulated,
+          analyses: this.accumulatedAnalyses,
+          existingPlaybooks,
+        });
+        return result.output;
+      } catch (error) {
+        console.error(
+          'Workspace-based playbook extraction failed, falling back to heuristic:',
+          error instanceof Error ? error.message : error
+        );
+      }
+    }
+
+    return this.playbookExtractor.extract(
+      this.accumulated,
+      this.accumulatedAnalyses,
+      existingPlaybooks
+    );
+  }
+
   /**
    * Get accumulated trajectory count
    */
@@ -214,6 +282,17 @@ export class LearningPipeline {
     return this.accumulated.length;
   }
 
+  /**
+   * Get accumulated trajectories with their analyses.
+   * Read-only view — does not clear the accumulator.
+   */
+  getAccumulated(): TrajectoryWithAnalysis[] {
+    return this.accumulated.map((trajectory, i) => ({
+      trajectory,
+      analysis: this.accumulatedAnalyses[i],
+    }));
+  }
+
   /**
    * Clear accumulated trajectories
    */