cognitive-core 0.1.2 → 0.2.1

package/src/learning/instant-loop.ts

@@ -0,0 +1,357 @@
+/**
+ * InstantLoop — Hot-path, per-trajectory learning
+ *
+ * Runs synchronously after every trajectory completion (<200ms budget).
+ * No LLM calls. No batch thresholds. Pure in-memory updates:
+ *
+ *   1. Store experience via MemorySystem.storeTrajectory()
+ *   2. Bump matched playbooks (recordSuccess / recordFailure)
+ *   3. Extract lightweight knowledge notes (heuristic only)
+ *   4. Access scores are bumped automatically by the memory layer
+ */
+
+import type { Trajectory } from '../types/index.js';
+import { createObservation } from '../types/knowledge.js';
+import type { MemorySystem } from '../memory/system.js';
+import type { PlaybookMatch } from '../memory/playbook.js';
+import type { CausalEdge } from '../memory/causal-store.js';
+import { ReflexionGenerator, type ReflexionGeneratorConfig } from './reflexion-generator.js';
+
+/**
+ * Result of a single instant-loop pass
+ */
+export interface InstantLoopResult {
+  /** ID of the stored experience */
+  experienceId: string;
+  /** Playbooks whose confidence was updated */
+  matchedPlaybooks: Array<{ id: string; confidenceDelta: number }>;
+  /** Number of knowledge notes extracted (0 if knowledge bank disabled) */
+  knowledgeNotesExtracted: number;
+  /** Number of causal edges extracted */
+  causalEdgesExtracted: number;
+  /** ID of the generated reflexion episode (if reflexion is enabled) */
+  reflexionEpisodeId?: string;
+  /** Wall-clock duration of the instant loop in ms */
+  durationMs: number;
+}
+
+/**
+ * InstantLoop configuration
+ */
+export interface InstantLoopConfig {
+  /** Max knowledge notes to extract per trajectory (default: 3) */
+  maxInstantKnowledgeNotes?: number;
+  /** Max playbooks to match per trajectory (default: 3) */
+  maxPlaybookMatches?: number;
+  /** Enable reflexion episode generation (default: true) */
+  enableReflexion?: boolean;
+  /** Enable causal edge extraction (default: true) */
+  enableCausalExtraction?: boolean;
+  /** Configuration for the reflexion generator */
+  reflexionConfig?: ReflexionGeneratorConfig;
+}
+
+/**
+ * InstantLoop — lightweight, per-trajectory learning
+ */
+export class InstantLoop {
+  private memory: MemorySystem;
+  private config: Required<Pick<InstantLoopConfig, 'maxInstantKnowledgeNotes' | 'maxPlaybookMatches' | 'enableReflexion' | 'enableCausalExtraction'>>;
+  private reflexionGenerator: ReflexionGenerator;
+
+  constructor(memory: MemorySystem, config?: InstantLoopConfig) {
+    this.memory = memory;
+    this.config = {
+      maxInstantKnowledgeNotes: config?.maxInstantKnowledgeNotes ?? 3,
+      maxPlaybookMatches: config?.maxPlaybookMatches ?? 3,
+      enableReflexion: config?.enableReflexion ?? true,
+      enableCausalExtraction: config?.enableCausalExtraction ?? true,
+    };
+    this.reflexionGenerator = new ReflexionGenerator(config?.reflexionConfig);
+  }
+
+  /**
+   * Process a single trajectory immediately after completion.
+   * Target: <200ms for typical trajectories.
+   */
+  async process(trajectory: Trajectory): Promise<InstantLoopResult> {
+    const start = Date.now();
+
+    // 1. Store experience
+    const experience = await this.memory.storeTrajectory(trajectory);
+
+    // 2. Find matching playbooks and bump confidence
+    const matchResult = await this.bumpPlaybooks(trajectory);
+
+    // 3. Extract lightweight knowledge (heuristic, no LLM)
+    const knowledgeNotesExtracted = await this.extractKnowledge(trajectory);
+
+    // 4. Extract lightweight causal edges (if enabled)
+    const causalEdgesExtracted = this.config.enableCausalExtraction
+      ? await this.extractCausalEdges(trajectory)
+      : 0;
+
+    // 5. Generate and store reflexion episode
+    let reflexionEpisodeId: string | undefined;
+    if (this.config.enableReflexion) {
+      try {
+        const episode = await this.reflexionGenerator.generate(
+          trajectory,
+          matchResult.playbookMatches
+        );
+        await this.memory.reflexion.add(episode);
+        reflexionEpisodeId = episode.id;
+      } catch {
+        // Non-critical — don't fail the instant loop for reflexion errors
+      }
+    }
+
+    return {
+      experienceId: experience.id,
+      matchedPlaybooks: matchResult.deltas,
+      knowledgeNotesExtracted,
+      causalEdgesExtracted,
+      reflexionEpisodeId,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  /**
+   * Find matching playbooks and update their confidence based on trajectory outcome.
+   * Returns both confidence deltas and the original PlaybookMatch objects for reflexion.
+   */
+  private async bumpPlaybooks(
+    trajectory: Trajectory
+  ): Promise<{
+    deltas: Array<{ id: string; confidenceDelta: number }>;
+    playbookMatches: PlaybookMatch[];
+  }> {
+    const deltas: Array<{ id: string; confidenceDelta: number }> = [];
+
+    // Find playbooks matching this trajectory's task description
+    let matches: PlaybookMatch[];
+    try {
+      matches = await this.memory.playbooks.findMatching(
+        trajectory.task.description,
+        {
+          k: this.config.maxPlaybookMatches,
+          domains: trajectory.task.domain ? [trajectory.task.domain] : undefined,
+          minScore: 0.3,
+        }
+      );
+    } catch {
+      return { deltas, playbookMatches: [] };
+    }
+
+    for (const match of matches) {
+      const before = match.playbook.confidence;
+
+      if (trajectory.outcome.success) {
+        await this.memory.playbooks.recordSuccess(
+          match.playbook.id,
+          trajectory.id,
+          trajectory.task.domain,
+        );
+      } else {
+        await this.memory.playbooks.recordFailure(
+          match.playbook.id,
+          trajectory.id,
+          trajectory.task.domain ?? 'unknown',
+          trajectory.outcome.errorInfo ?? 'Unknown failure',
+        );
+      }
+
+      // Read back the updated confidence
+      const updated = await this.memory.playbooks.get(match.playbook.id);
+      const after = updated?.confidence ?? before;
+
+      deltas.push({
+        id: match.playbook.id,
+        confidenceDelta: after - before,
+      });
+    }
+
+    return { deltas, playbookMatches: matches };
+  }
+
+  /**
+   * Extract lightweight knowledge from a trajectory (heuristic, no LLM).
+   *
+   * Parses error messages, tool names, and file paths from trajectory steps
+   * and stores them as KnowledgeNote observations.
+   */
+  private async extractKnowledge(trajectory: Trajectory): Promise<number> {
+    const kb = this.memory.knowledgeBank;
+    if (!kb) return 0;
+
+    const notes: Array<{ subject: string; content: string }> = [];
+
+    // Extract error patterns from failed steps
+    if (!trajectory.outcome.success && trajectory.outcome.errorInfo) {
+      notes.push({
+        subject: `error:${trajectory.task.domain ?? 'general'}`,
+        content: `Error encountered: ${trajectory.outcome.errorInfo.slice(0, 300)}`,
+      });
+    }
+
+    // Extract tool usage patterns from steps
+    const toolNames = new Set<string>();
+    const filePaths = new Set<string>();
+
+    for (const step of trajectory.steps) {
+      // Extract tool names from action strings
+      const toolMatch = step.action?.match(/^(\w+(?:[A-Z]\w*)*)\s/);
+      if (toolMatch) {
+        toolNames.add(toolMatch[1]);
+      }
+
+      // Extract file paths from observations
+      const pathMatches = step.observation?.match(
+        /(?:\/[\w.-]+)+(?:\.[\w]+)/g
+      );
+      if (pathMatches) {
+        for (const p of pathMatches.slice(0, 5)) {
+          filePaths.add(p);
+        }
+      }
+    }
+
+    // Create a tool-usage note if tools were used
+    if (toolNames.size > 0 && trajectory.outcome.success) {
+      notes.push({
+        subject: `tools:${trajectory.task.domain ?? 'general'}`,
+        content: `Successful approach used tools: ${[...toolNames].join(', ')}`,
+      });
+    }
+
+    // Create a file-paths note for context
+    if (filePaths.size > 0) {
+      notes.push({
+        subject: `files:${trajectory.task.domain ?? 'general'}`,
+        content: `Files involved: ${[...filePaths].slice(0, 10).join(', ')}`,
+      });
+    }
+
+    // Store up to maxInstantKnowledgeNotes
+    const domain = trajectory.task.domain ?? 'general';
+    let stored = 0;
+    for (const note of notes.slice(0, this.config.maxInstantKnowledgeNotes)) {
+      try {
+        const observation = createObservation({
+          title: note.subject,
+          body: note.content,
+          domain: [domain],
+          entities: [note.subject],
+          confidence: trajectory.outcome.success ? 0.7 : 0.4,
+          source: {
+            origin: 'extracted',
+            trajectories: [trajectory.id],
+          },
+        });
+        await kb.addObservation(observation);
+        stored++;
+      } catch {
+        // Non-critical — don't fail the instant loop for knowledge extraction errors
+      }
+    }
+
+    return stored;
+  }
+
+  /**
+   * Extract lightweight causal edges from a trajectory.
+   *
+   * From failed trajectories: error message → root cause (if identifiable)
+   * From successful trajectories: approach → outcome patterns
+   */
+  private async extractCausalEdges(trajectory: Trajectory): Promise<number> {
+    const causalStore = this.memory.causal;
+    let extracted = 0;
+    const domain = trajectory.task.domain ?? 'general';
+    const now = new Date();
+
+    try {
+      if (!trajectory.outcome.success && trajectory.outcome.errorInfo) {
+        // Failed trajectory: extract error → root cause pattern
+        const errorInfo = trajectory.outcome.errorInfo.slice(0, 300);
+        const taskDesc = trajectory.task.description.slice(0, 200);
+
+        const edge: CausalEdge = {
+          id: `ce-fail-${trajectory.id}`,
+          cause: `Task: ${taskDesc}`,
+          effect: `Error: ${errorInfo}`,
+          confidence: 0.4,
+          domain,
+          sourceTrajectoryIds: [trajectory.id],
+          observedCount: 1,
+          createdAt: now,
+          updatedAt: now,
+        };
+        await causalStore.add(edge);
+        extracted++;
+      }
+
+      if (trajectory.outcome.success) {
+        // Successful trajectory: approach → outcome
+        const taskDesc = trajectory.task.description.slice(0, 200);
+        const solutionSummary = trajectory.outcome.solution !== undefined
+          ? String(trajectory.outcome.solution).slice(0, 200)
+          : 'Task completed successfully';
+
+        const edge: CausalEdge = {
+          id: `ce-succ-${trajectory.id}`,
+          cause: `Approach: ${taskDesc}`,
+          effect: `Outcome: ${solutionSummary}`,
+          confidence: 0.7,
+          domain,
+          sourceTrajectoryIds: [trajectory.id],
+          observedCount: 1,
+          createdAt: now,
+          updatedAt: now,
+        };
+        await causalStore.add(edge);
+        extracted++;
+
+        // Extract tool → outcome edges from steps with high attribution
+        for (const step of trajectory.steps) {
+          if (
+            step.attributionScore !== undefined &&
+            step.attributionScore > 0.7 &&
+            step.action
+          ) {
+            const toolMatch = step.action.match(/^(\w+(?:[A-Z]\w*)*)\s/);
+            if (toolMatch) {
+              const toolEdge: CausalEdge = {
+                id: `ce-tool-${trajectory.id}-${toolMatch[1]}`,
+                cause: `Used tool ${toolMatch[1]} for ${domain} task`,
+                effect: `Contributed to successful outcome (attribution: ${step.attributionScore.toFixed(2)})`,
+                confidence: 0.5,
+                domain,
+                sourceTrajectoryIds: [trajectory.id],
+                observedCount: 1,
+                createdAt: now,
+                updatedAt: now,
+              };
+              await causalStore.add(toolEdge);
+              extracted++;
+            }
+          }
+        }
+      }
+    } catch {
+      // Non-critical — don't fail the instant loop for causal extraction errors
+    }
+
+    return extracted;
+  }
+}
+
+/**
+ * Create an InstantLoop
+ */
+export function createInstantLoop(
+  memory: MemorySystem,
+  config?: InstantLoopConfig
+): InstantLoop {
+  return new InstantLoop(memory, config);
+}

package/src/learning/maintenance-scheduler.ts

@@ -0,0 +1,271 @@
+/**
+ * MaintenanceScheduler — Circadian-style duty-gated maintenance scheduling.
+ *
+ * Inspired by ruvector's CircadianController (ruvector-nervous-system/routing/circadian.rs).
+ * Gates background maintenance work using configurable triggers:
+ *
+ *   - 'manual': Only runs when explicitly requested
+ *   - 'afterNBatches': Runs after N batch cycles complete
+ *   - 'periodic': Runs on a time interval
+ *
+ * Maintenance tasks are deferred during active batch processing to avoid
+ * contention. A duty-factor model ensures maintenance doesn't starve
+ * the primary learning pipeline.
+ */
+
+/**
+ * Maintenance trigger mode.
+ */
+export type MaintenanceMode = 'manual' | 'afterNBatches' | 'periodic';
+
+/**
+ * Configuration for the MaintenanceScheduler.
+ */
+export interface MaintenanceSchedulerConfig {
+  /** Trigger mode (default: 'afterNBatches') */
+  mode: MaintenanceMode;
+  /** For 'afterNBatches' mode: batches between maintenance runs (default: 5) */
+  batchInterval: number;
+  /** For 'periodic' mode: milliseconds between runs (default: 3600000 = 1h) */
+  intervalMs: number;
+  /** Skip maintenance if a batch is currently running (default: true) */
+  deferDuringBatch: boolean;
+  /** Maximum queued maintenance tasks before dropping oldest (default: 10) */
+  maxQueueSize: number;
+}
+
+const DEFAULT_CONFIG: MaintenanceSchedulerConfig = {
+  mode: 'afterNBatches',
+  batchInterval: 5,
+  intervalMs: 3_600_000,
+  deferDuringBatch: true,
+  maxQueueSize: 10,
+};
+
+/**
+ * A maintenance task that can be scheduled.
+ */
+export interface MaintenanceTask {
+  /** Unique name for this task (e.g., 'knowledge-defrag', 'temporal-compression') */
+  name: string;
+  /** Priority (higher = run first) */
+  priority: number;
+  /** The async work to perform */
+  execute: () => Promise<MaintenanceTaskResult>;
+}
+
+/**
+ * Result of a maintenance task execution.
+ */
+export interface MaintenanceTaskResult {
+  taskName: string;
+  success: boolean;
+  durationMs: number;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Result of a full maintenance cycle.
+ */
+export interface MaintenanceCycleResult {
+  /** Whether the cycle actually ran (false if deferred or not due) */
+  ran: boolean;
+  /** Reason the cycle was skipped, if applicable */
+  skipReason?: 'not_due' | 'batch_in_progress' | 'manual_mode' | 'queue_empty';
+  /** Results from each task that ran */
+  taskResults: MaintenanceTaskResult[];
+  /** Total duration of the cycle in ms */
+  totalDurationMs: number;
+  /** Timestamp of this cycle */
+  timestamp: Date;
+}
+
+/**
+ * MaintenanceScheduler — duty-gated background maintenance scheduling.
+ */
+export class MaintenanceScheduler {
+  private config: MaintenanceSchedulerConfig;
+  private registeredTasks: MaintenanceTask[] = [];
+  private batchesSinceLastMaintenance = 0;
+  private lastMaintenanceTime = 0;
+  private isBatchRunning = false;
+  private cycleHistory: MaintenanceCycleResult[] = [];
+
+  constructor(config?: Partial<MaintenanceSchedulerConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Register a maintenance task.
+   * Tasks are sorted by priority (descending) before execution.
+   */
+  registerTask(task: MaintenanceTask): void {
+    // Replace existing task with same name
+    this.registeredTasks = this.registeredTasks.filter(t => t.name !== task.name);
+    this.registeredTasks.push(task);
+    this.registeredTasks.sort((a, b) => b.priority - a.priority);
+  }
+
+  /**
+   * Unregister a maintenance task by name.
+   */
+  unregisterTask(name: string): void {
+    this.registeredTasks = this.registeredTasks.filter(t => t.name !== name);
+  }
+
+  /**
+   * Signal that a batch cycle has completed.
+   * For 'afterNBatches' mode, this increments the counter.
+   */
+  onBatchComplete(): void {
+    this.batchesSinceLastMaintenance++;
+  }
+
+  /**
+   * Signal that a batch is starting (for deferral logic).
+   */
+  onBatchStart(): void {
+    this.isBatchRunning = true;
+  }
+
+  /**
+   * Signal that a batch has finished running.
+   */
+  onBatchEnd(): void {
+    this.isBatchRunning = false;
+  }
+
+  /**
+   * Check whether maintenance should run now.
+   */
+  shouldRunMaintenance(): boolean {
+    if (this.config.mode === 'manual') return false;
+    if (this.config.deferDuringBatch && this.isBatchRunning) return false;
+    if (this.registeredTasks.length === 0) return false;
+
+    if (this.config.mode === 'afterNBatches') {
+      return this.batchesSinceLastMaintenance >= this.config.batchInterval;
+    }
+
+    if (this.config.mode === 'periodic') {
+      const now = Date.now();
+      return (now - this.lastMaintenanceTime) >= this.config.intervalMs;
+    }
+
+    return false;
+  }
+
+  /**
+   * Run a maintenance cycle.
+   * Executes all registered tasks in priority order.
+   *
+   * Can be called manually regardless of mode — bypasses trigger checks.
+   */
+  async runMaintenance(options?: { force?: boolean }): Promise<MaintenanceCycleResult> {
+    const start = Date.now();
+
+    // Check if we should run (unless forced)
+    if (!options?.force) {
+      if (this.config.deferDuringBatch && this.isBatchRunning) {
+        return this.skipResult('batch_in_progress', start);
+      }
+      if (this.registeredTasks.length === 0) {
+        return this.skipResult('queue_empty', start);
+      }
+    }
+
+    // Execute tasks in priority order
+    const taskResults: MaintenanceTaskResult[] = [];
+    for (const task of this.registeredTasks) {
+      const taskStart = Date.now();
+      try {
+        const result = await task.execute();
+        taskResults.push(result);
+      } catch (error) {
+        taskResults.push({
+          taskName: task.name,
+          success: false,
+          durationMs: Date.now() - taskStart,
+          details: {
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+      }
+    }
+
+    // Reset counters
+    this.batchesSinceLastMaintenance = 0;
+    this.lastMaintenanceTime = Date.now();
+
+    const result: MaintenanceCycleResult = {
+      ran: true,
+      taskResults,
+      totalDurationMs: Date.now() - start,
+      timestamp: new Date(),
+    };
+
+    this.cycleHistory.push(result);
+    if (this.cycleHistory.length > this.config.maxQueueSize) {
+      this.cycleHistory.shift();
+    }
+
+    return result;
+  }
+
+  /**
+   * Get the list of registered tasks.
+   */
+  getRegisteredTasks(): readonly MaintenanceTask[] {
+    return this.registeredTasks;
+  }
+
+  /**
+   * Get maintenance cycle history.
+   */
+  getCycleHistory(): readonly MaintenanceCycleResult[] {
+    return this.cycleHistory;
+  }
+
+  /**
+   * Get the number of batches since last maintenance.
+   */
+  getBatchesSinceLastMaintenance(): number {
+    return this.batchesSinceLastMaintenance;
+  }
+
+  /**
+   * Get current configuration.
+   */
+  getConfig(): Readonly<MaintenanceSchedulerConfig> {
+    return this.config;
+  }
+
+  /**
+   * Update configuration.
+   */
+  updateConfig(config: Partial<MaintenanceSchedulerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  private skipResult(
+    reason: MaintenanceCycleResult['skipReason'],
+    start: number,
+  ): MaintenanceCycleResult {
+    return {
+      ran: false,
+      skipReason: reason,
+      taskResults: [],
+      totalDurationMs: Date.now() - start,
+      timestamp: new Date(),
+    };
+  }
+}
+
+/**
+ * Create a MaintenanceScheduler.
+ */
+export function createMaintenanceScheduler(
+  config?: Partial<MaintenanceSchedulerConfig>,
+): MaintenanceScheduler {
+  return new MaintenanceScheduler(config);
+}

package/src/learning/meta-learner.ts

@@ -17,6 +17,7 @@ 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';
+import { detectRepeatedActions, extractToolNames } from '../utils/trajectory-helpers.js';
 
 /**
  * Routing decision from the router
@@ -375,31 +376,12 @@ export class MetaLearner {
     toolsUsed: string[];
   } {
     const steps = trajectory.steps;
-    const toolsUsed = new Set<string>();
-    let backtrackingOccurred = false;
-
-    // Collect tools used (extract from action)
-    for (const step of steps) {
-      // Try to extract tool name from action (e.g., "tool_use: Bash" or just "Bash")
-      const toolMatch = step.action.match(/^(?:tool_use:\s*)?(\w+)/);
-      if (toolMatch) {
-        toolsUsed.add(toolMatch[1]);
-      }
-    }
 
-    // Check for backtracking (similar actions repeated)
-    const actionCounts = new Map<string, number>();
-    for (const step of steps) {
-      const normalized = step.action.toLowerCase().slice(0, 50);
-      actionCounts.set(normalized, (actionCounts.get(normalized) ?? 0) + 1);
-    }
+    // Collect tools used
+    const toolsUsed = extractToolNames(steps);
 
-    for (const count of actionCounts.values()) {
-      if (count > 2) {
-        backtrackingOccurred = true;
-        break;
-      }
-    }
+    // Check for backtracking (similar actions repeated)
+    const backtrackingOccurred = detectRepeatedActions(steps, 3).length > 0;
 
     // Check for decomposition (multiple sub-tasks)
     const decompositionUsed =