cognitive-core 0.1.2 → 0.2.0

package/src/factory.ts

@@ -14,18 +14,22 @@
  * const memory = factory.createMemorySystem('./.memory');
  * await memory.init();
  *
- * const pipeline = factory.createLearningPipeline(memory, {
- *   minTrajectories: 5,
- * });
+ * const pipeline = factory.createLearningPipeline(memory);
+ * await pipeline.init();
  * ```
  */
 
-import type { Task, Trajectory, Step, Outcome, LearningConfig } from './types/index.js';
+import type { Task, Trajectory, Step, Outcome } from './types/index.js';
 import { createTask, createTrajectory, createStep, successOutcome, failureOutcome } from './types/index.js';
 import type { MemorySystem } from './memory/system.js';
 import { createMemorySystem } from './memory/system.js';
-import type { ProcessResult, BatchResult } from './learning/pipeline.js';
-import { createLearningPipeline } from './learning/pipeline.js';
+import { createSqlitePersistence } from './persistence/index.js';
+import type {
+  ImmediateResult,
+  UnifiedBatchResult,
+  UnifiedPipelineConfig,
+} from './learning/unified-pipeline.js';
+import { createUnifiedPipeline } from './learning/unified-pipeline.js';
 
 /**
  * Parameters for creating a Task
@@ -71,10 +75,10 @@ export interface OutcomeParams {
 }
 
 /**
- * Learning pipeline configuration
+ * Learning pipeline configuration (subset exposed to external consumers)
  */
 export interface LearningPipelineConfig {
-  creditStrategy?: 'simple' | 'contribution';
+  creditStrategy?: 'simple' | 'llm' | 'counterfactual';
   minTrajectories?: number;
   deduplicationThreshold?: number;
   minSuccessRate?: number;
@@ -84,11 +88,10 @@ export interface LearningPipelineConfig {
  * Interface for the LearningPipeline that external consumers need
  */
 export interface ILearningPipeline {
-  processTrajectory(trajectory: Trajectory): Promise<ProcessResult>;
-  shouldRunBatch(): boolean;
-  runBatchLearning(): Promise<BatchResult>;
+  init(): Promise<void>;
+  processTrajectory(trajectory: Trajectory): Promise<ImmediateResult>;
+  runBatch(): Promise<UnifiedBatchResult>;
   getAccumulatedCount(): number;
-  clearAccumulated(): void;
 }
 
 /**
@@ -159,16 +162,29 @@ export interface CognitiveCoreFactory {
  */
 class CognitiveCoreFactoryImpl implements CognitiveCoreFactory {
   createMemorySystem(storagePath: string): IMemorySystem {
-    return createMemorySystem(storagePath) as IMemorySystem;
+    const persistence = createSqlitePersistence({ baseDir: storagePath });
+    return createMemorySystem(persistence, storagePath) as IMemorySystem;
   }
 
   createLearningPipeline(
     memory: IMemorySystem,
     config?: LearningPipelineConfig
   ): ILearningPipeline {
-    return createLearningPipeline(
+    const pipelineConfig: Partial<UnifiedPipelineConfig> = config ? {
+      batch: {
+        learning: {
+          creditStrategy: config.creditStrategy,
+          minTrajectories: config.minTrajectories,
+          deduplicationThreshold: config.deduplicationThreshold,
+          minSuccessRate: config.minSuccessRate,
+        },
+        energy: {},
+      },
+    } : {};
+
+    return createUnifiedPipeline(
       memory as MemorySystem,
-      config as Partial<LearningConfig>
+      pipelineConfig,
     ) as ILearningPipeline;
   }
 
@@ -212,6 +228,7 @@ class CognitiveCoreFactoryImpl implements CognitiveCoreFactory {
  *   minTrajectories: 10,
  *   deduplicationThreshold: 0.85,
  * });
+ * await pipeline.init();
  *
  * // Create and process trajectory
  * const task = factory.createTask({
@@ -254,7 +271,7 @@ export const cognitiveCoreFactory = createCognitiveCoreFactory();
  */
 export {
   createMemorySystem,
-  createLearningPipeline,
+  createUnifiedPipeline as createLearningPipeline,
   createTask,
   createTrajectory,
   createStep,

package/src/index.ts

@@ -62,6 +62,29 @@ export {
   createTeamExperienceMemory,
   type TeamExperience,
   type TeamAnalysisResult,
+  // Reflexion episodes
+  ReflexionMemory,
+  createReflexionMemory,
+  // Coherence checking
+  CoherenceChecker,
+  createCoherenceChecker,
+  type CoherenceResult,
+  type CoherenceCheckerConfig,
+  // Reasoning bank (clustered experience retrieval)
+  ReasoningBank,
+  createReasoningBank,
+  type ExperienceCluster,
+  type ClusterStats,
+  type ReasoningBankConfig,
+  // Causal edge store
+  CausalStore,
+  createCausalStore,
+  type CausalEdge,
+  // Temporal compression
+  TemporalCompressor,
+  createTemporalCompressor,
+  type TemporalCompressorConfig,
+  type CompressionResult,
   // Knowledge bank (semantic memory)
   KnowledgeBank,
   KnowledgeGraphManager,
@@ -80,12 +103,8 @@ export {
 
 // Learning engine
 export {
-  LearningPipeline,
-  createLearningPipeline,
   TrajectoryAnalyzer,
   createAnalyzer,
-  type ProcessResult,
-  type BatchResult,
   type AnalysisResult,
   // Playbook-based learning
   PlaybookExtractor,
@@ -123,17 +142,70 @@ export {
   InMemoryTrajectorySource,
   FileTrajectorySource,
   PipelineTrajectorySource,
-  EntireTrajectorySource,
-  type EntireSynthesisOptions,
+  SessionTrajectorySource,
+  type SessionSynthesisOptions,
   DataclawTrajectorySource,
   type DataclawSourceOptions,
+  // Instant (hot-path) learning
+  InstantLoop,
+  createInstantLoop,
+  type InstantLoopResult,
+  type InstantLoopConfig,
+  // Reflexion generation
+  ReflexionGenerator,
+  createReflexionGenerator,
+  type ReflexionGeneratorConfig,
+  // Effectiveness tracking
+  LearningEffectivenessTracker,
+  createEffectivenessTracker,
+  type TaskAnnotation,
+  type EffectivenessMetrics,
+  type PlaybookEffectivenessEntry,
+  // Unified learning pipeline (three-speed: immediate + batch + maintenance)
+  UnifiedLearningPipeline,
+  createUnifiedPipeline,
+  type UnifiedPipelineConfig,
+  type UnifiedPipelineFeatures,
+  type ImmediateResult,
+  type UnifiedBatchResult,
+  type UnifiedPipelineStats,
+  // Energy evaluator
+  EnergyEvaluator,
+  createEnergyEvaluator,
+  type EnergyEvaluatorConfig,
+  type EnergyEvaluation,
+  type EnergySignal,
+  type EscalationReason,
+  type LaneTransition,
+  // Maintenance scheduler
+  MaintenanceScheduler,
+  createMaintenanceScheduler,
+  type MaintenanceSchedulerConfig,
+  type MaintenanceMode,
+  type MaintenanceCycleResult,
+  type MaintenanceTask,
+  type MaintenanceTaskResult,
+  // Healing orchestrator
+  HealingOrchestrator,
+  createHealingOrchestrator,
+  PlaybookDriftDetector,
+  MemoryBloatDetector,
+  MetricDriftDetector,
+  type HealingCycleResult,
+  type HealthContext,
+  type AnomalyDetector,
+  type RepairStrategy,
+  type Anomaly,
+  type RepairResult,
 } from './learning/index.js';
 
-// Session bank (Entire CLI integration)
+// Session bank (SessionLog checkpoint reader, with Entire CLI fallback)
 export {
   SessionBank,
-  EntireGitReader,
-  EntireTranscriptParser,
+  CheckpointGitReader,
+  CheckpointParser,
+  detectFormat,
+  type CheckpointFormat,
   type SessionRecord,
   type SessionMetadata,
   type TranscriptMessage,
@@ -159,6 +231,13 @@ export {
   createSolver,
   type RoutingDecision,
   type SolverResult,
+  // MoE-inspired routing gate
+  MoEGate,
+  createMoEGate,
+  extractTaskFeatures,
+  MOE_FEATURE_SIZE,
+  MOE_STRATEGIES,
+  type MoEGateState,
   // Refinement
   SolutionEvaluator,
   createSolutionEvaluator,
@@ -211,6 +290,9 @@ export {
   JsonStore,
   saveJson,
   loadJson,
+  // Domain-partitioned storage
+  PartitionedStore,
+  type PartitionedStoreOptions,
 } from './utils/index.js';
 
 // Embeddings - Vector search and similarity
@@ -230,6 +312,8 @@ export {
   SqliteVectorStore,
   createVectorStore,
   type VectorSearchResult,
+  // Inverted index (candidate narrowing)
+  InvertedIndex,
   // Embedding manager
   EmbeddingManager,
   createEmbeddingManager,
@@ -353,6 +437,22 @@ export {
   AgenticTaskOutputError,
 } from './workspace/index.js';
 
+// Persistence - Unified SQLite database for system-internal state
+export {
+  SqlitePersistence,
+  createSqlitePersistence,
+  type SqlitePersistenceConfig,
+  type ExperienceRow,
+  type PlaybookRow,
+  type ReflexionRow,
+  type CausalEdgeRow,
+  type MetaObservationRow,
+  type MetaStrategyRow,
+  JsonToSqliteMigrator,
+  runMigration,
+  type MigrationResult,
+} from './persistence/index.js';
+
 // Factory - Unified interface for external integration (e.g., skill-tree)
 export {
   createCognitiveCoreFactory,

package/src/learning/analyzer.ts

@@ -1,4 +1,6 @@
 import type { Trajectory, CreditStrategy } from '../types/index.js';
+import { classifyError } from '../utils/error-classifier.js';
+import { detectRepeatedActions } from '../utils/trajectory-helpers.js';
 
 /**
  * Analysis result from trajectory examination
@@ -189,48 +191,30 @@ export class TrajectoryAnalyzer {
     const patterns: ErrorPattern[] = [];
 
     if (!trajectory.outcome.success && trajectory.outcome.errorInfo) {
-      // Extract error type from error info
-      const errorInfo = trajectory.outcome.errorInfo;
-
-      // Common error patterns
-      const errorTypes: Array<[RegExp, string, string]> = [
-        [/timeout/i, 'timeout', 'Operation timed out'],
-        [/not found/i, 'not_found', 'Resource not found'],
-        [/permission denied/i, 'permission', 'Permission denied'],
-        [/syntax error/i, 'syntax', 'Syntax error in code'],
-        [/type error/i, 'type', 'Type mismatch error'],
-        [/assertion|assert/i, 'assertion', 'Assertion failed'],
-        [/exception|error/i, 'general', 'General error'],
-      ];
-
-      for (const [pattern, type, desc] of errorTypes) {
-        if (pattern.test(errorInfo)) {
-          patterns.push({
-            type,
-            signature: errorInfo.slice(0, 100),
-            description: desc,
-          });
-          break;
-        }
+      const classification = classifyError(trajectory.outcome.errorInfo);
+      if (classification) {
+        patterns.push({
+          type: classification.type,
+          signature: trajectory.outcome.errorInfo.slice(0, 100),
+          description: classification.description,
+        });
       }
     }
 
     // Check for repeated failed actions
-    const actionCounts = new Map<string, number>();
-    for (const step of trajectory.steps) {
-      const count = (actionCounts.get(step.action) ?? 0) + 1;
-      actionCounts.set(step.action, count);
-    }
+    const repeated = detectRepeatedActions(
+      trajectory.steps,
+      this.config.actionRepetitionThreshold,
+      (a) => a, // Use raw action strings for analyzer (preserves full action for signature)
+    );
 
-    for (const [action, count] of actionCounts) {
-      if (count >= this.config.actionRepetitionThreshold) {
-        patterns.push({
-          type: 'repetition',
-          signature: action,
-          description: `Action repeated ${count} times`,
-          suggestedFix: 'Try a different approach',
-        });
-      }
+    for (const { action, count } of repeated) {
+      patterns.push({
+        type: 'repetition',
+        signature: action,
+        description: `Action repeated ${count} times`,
+        suggestedFix: 'Try a different approach',
+      });
     }
 
     return patterns;

package/src/learning/energy-evaluator.ts

@@ -0,0 +1,282 @@
+/**
+ * EnergyEvaluator — Ruvector-inspired energy-threshold batch trigger.
+ *
+ * Instead of a simple count threshold, the evaluator measures "incoherence
+ * energy" from trajectory signals. A trajectory that introduces contradictions,
+ * encounters a novel domain with no playbooks, or triggers a high error rate
+ * can escalate to batch processing even before the count threshold is met.
+ *
+ * Inspired by ruvector's Compute Ladder (prime-radiant/execution/ladder.rs)
+ * which uses energy-driven escalation with named transition reasons.
+ */
+
+import type { Trajectory } from '../types/index.js';
+import type { InstantLoopResult } from './instant-loop.js';
+
+/**
+ * Reasons why a batch was triggered — named transitions for audit.
+ */
+export type EscalationReason =
+  | 'count_threshold'
+  | 'contradiction_detected'
+  | 'novel_domain'
+  | 'high_error_rate'
+  | 'pattern_shift'
+  | 'manual_override';
+
+/**
+ * Signals extracted from a trajectory that contribute to energy.
+ */
+export interface EnergySignal {
+  /** Whether a coherence contradiction was detected during instant loop */
+  contradictionDetected: boolean;
+  /** Whether this trajectory's domain has no existing playbooks */
+  novelDomain: boolean;
+  /** Error rate in the recent window exceeds threshold */
+  highErrorRate: boolean;
+  /** Significant shift in patterns (e.g., new tool usage, domain change) */
+  patternShift: boolean;
+}
+
+/**
+ * Result of an energy evaluation.
+ */
+export interface EnergyEvaluation {
+  /** Computed energy score (0.0 = calm, 1.0 = high incoherence) */
+  energy: number;
+  /** Whether the energy exceeds the batch trigger threshold */
+  shouldTriggerBatch: boolean;
+  /** Named reason(s) for the trigger decision */
+  reasons: EscalationReason[];
+}
+
+/**
+ * Lane transition record for audit purposes.
+ */
+export interface LaneTransition {
+  timestamp: Date;
+  fromPhase: 'immediate' | 'batch' | 'maintenance';
+  toPhase: 'immediate' | 'batch' | 'maintenance';
+  reasons: EscalationReason[];
+  energy: number;
+  trajectoryId: string;
+}
+
+/**
+ * Configuration for the EnergyEvaluator.
+ */
+export interface EnergyEvaluatorConfig {
+  /** Trajectories needed before count-based batch trigger (default: 10) */
+  countThreshold: number;
+  /** Trigger batch when a contradiction is detected (default: true) */
+  triggerOnContradiction: boolean;
+  /** Trigger batch when a novel domain is encountered (default: true) */
+  triggerOnNovelDomain: boolean;
+  /** Error rate threshold for triggering batch (default: 0.6) */
+  errorRateThreshold: number;
+  /** Minimum time between batches in ms — debounce (default: 30000) */
+  minIntervalMs: number;
+  /** Number of recent trajectories to consider for error rate (default: 5) */
+  recentWindowSize: number;
+  /** Energy threshold for triggering batch (0.0–1.0, default: 0.7) */
+  energyThreshold: number;
+  /** Energy contribution weights */
+  weights: {
+    contradiction: number;  // default: 0.4
+    novelDomain: number;    // default: 0.3
+    highErrorRate: number;  // default: 0.2
+    patternShift: number;   // default: 0.1
+  };
+}
+
+const DEFAULT_CONFIG: EnergyEvaluatorConfig = {
+  countThreshold: 10,
+  triggerOnContradiction: true,
+  triggerOnNovelDomain: true,
+  errorRateThreshold: 0.6,
+  minIntervalMs: 30_000,
+  recentWindowSize: 5,
+  energyThreshold: 0.7,
+  weights: {
+    contradiction: 0.4,
+    novelDomain: 0.3,
+    highErrorRate: 0.2,
+    patternShift: 0.1,
+  },
+};
+
+/**
+ * EnergyEvaluator — determines when batch processing should be triggered
+ * based on measured incoherence energy from trajectory signals.
+ */
+export class EnergyEvaluator {
+  private config: EnergyEvaluatorConfig;
+  private pendingCount = 0;
+  private lastBatchTime = 0;
+  private recentOutcomes: boolean[] = [];
+  private knownDomains = new Set<string>();
+  private transitionLog: LaneTransition[] = [];
+
+  constructor(config?: Partial<EnergyEvaluatorConfig>) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      weights: { ...DEFAULT_CONFIG.weights, ...config?.weights },
+    };
+  }
+
+  /**
+   * Record a trajectory and evaluate whether batch should be triggered.
+   */
+  evaluate(
+    trajectory: Trajectory,
+    _instantResult: InstantLoopResult,
+    signals?: Partial<EnergySignal>,
+  ): EnergyEvaluation {
+    this.pendingCount++;
+
+    // Track recent outcomes for error rate
+    this.recentOutcomes.push(trajectory.outcome.success);
+    if (this.recentOutcomes.length > this.config.recentWindowSize) {
+      this.recentOutcomes.shift();
+    }
+
+    // Build the energy signal
+    const domain = trajectory.task.domain ?? 'general';
+    const isNovelDomain = !this.knownDomains.has(domain);
+    this.knownDomains.add(domain);
+
+    const errorRate = this.recentOutcomes.length > 0
+      ? this.recentOutcomes.filter(s => !s).length / this.recentOutcomes.length
+      : 0;
+
+    const signal: EnergySignal = {
+      contradictionDetected: signals?.contradictionDetected ?? false,
+      novelDomain: isNovelDomain && (signals?.novelDomain ?? true),
+      highErrorRate: errorRate >= this.config.errorRateThreshold,
+      patternShift: signals?.patternShift ?? false,
+    };
+
+    // Compute energy
+    const energy = this.computeEnergy(signal);
+
+    // Determine reasons
+    const reasons: EscalationReason[] = [];
+
+    if (this.pendingCount >= this.config.countThreshold) {
+      reasons.push('count_threshold');
+    }
+    if (signal.contradictionDetected && this.config.triggerOnContradiction) {
+      reasons.push('contradiction_detected');
+    }
+    if (signal.novelDomain && this.config.triggerOnNovelDomain) {
+      reasons.push('novel_domain');
+    }
+    if (signal.highErrorRate) {
+      reasons.push('high_error_rate');
+    }
+    if (signal.patternShift) {
+      reasons.push('pattern_shift');
+    }
+
+    // Check debounce
+    const now = Date.now();
+    const withinDebounce = (now - this.lastBatchTime) < this.config.minIntervalMs;
+
+    // Trigger if count threshold reached OR energy exceeds threshold
+    const shouldTrigger = !withinDebounce && (
+      this.pendingCount >= this.config.countThreshold ||
+      energy >= this.config.energyThreshold
+    );
+
+    if (shouldTrigger && reasons.length > 0) {
+      this.transitionLog.push({
+        timestamp: new Date(),
+        fromPhase: 'immediate',
+        toPhase: 'batch',
+        reasons,
+        energy,
+        trajectoryId: trajectory.id,
+      });
+    }
+
+    return {
+      energy,
+      shouldTriggerBatch: shouldTrigger,
+      reasons: shouldTrigger ? reasons : [],
+    };
+  }
+
+  /**
+   * Compute energy from signal using weighted sum.
+   */
+  private computeEnergy(signal: EnergySignal): number {
+    const w = this.config.weights;
+    let energy = 0;
+
+    if (signal.contradictionDetected) energy += w.contradiction;
+    if (signal.novelDomain) energy += w.novelDomain;
+    if (signal.highErrorRate) energy += w.highErrorRate;
+    if (signal.patternShift) energy += w.patternShift;
+
+    return Math.min(1.0, energy);
+  }
+
+  /**
+   * Reset after a batch run completes.
+   */
+  resetAfterBatch(): void {
+    this.pendingCount = 0;
+    this.lastBatchTime = Date.now();
+  }
+
+  /**
+   * Force-trigger evaluation (for manual override).
+   */
+  forceEvaluate(): EnergyEvaluation {
+    return {
+      energy: 1.0,
+      shouldTriggerBatch: true,
+      reasons: ['manual_override'],
+    };
+  }
+
+  /**
+   * Seed known domains (e.g., from existing playbooks on init).
+   */
+  seedKnownDomains(domains: string[]): void {
+    for (const d of domains) {
+      this.knownDomains.add(d);
+    }
+  }
+
+  /**
+   * Get the current pending count.
+   */
+  getPendingCount(): number {
+    return this.pendingCount;
+  }
+
+  /**
+   * Get the transition log for audit/debugging.
+   */
+  getTransitionLog(): readonly LaneTransition[] {
+    return this.transitionLog;
+  }
+
+  /**
+   * Get current configuration.
+   */
+  getConfig(): Readonly<EnergyEvaluatorConfig> {
+    return this.config;
+  }
+}
+
+/**
+ * Create an EnergyEvaluator.
+ */
+export function createEnergyEvaluator(
+  config?: Partial<EnergyEvaluatorConfig>,
+): EnergyEvaluator {
+  return new EnergyEvaluator(config);
+}