cognitive-core 0.1.2 → 0.2.0

package/src/atlas.ts

@@ -10,11 +10,11 @@ import type { KnowledgeMatch } from './types/knowledge.js';
 import { createDefaultConfig } from './types/index.js';
 import { MemorySystem, createMemorySystem, type TeamExperience } from './memory/index.js';
 import {
-  LearningPipeline,
-  createLearningPipeline,
-  type ProcessResult,
-  type BatchResult,
-} from './learning/index.js';
+  UnifiedLearningPipeline,
+  createUnifiedPipeline,
+  type ImmediateResult,
+  type UnifiedBatchResult,
+} from './learning/unified-pipeline.js';
 import {
   TeamLearningPipeline,
   createTeamLearningPipeline,
@@ -40,14 +40,8 @@ import {
   PlaybookUsageInference,
   createUsageInference,
 } from './learning/usage-inference.js';
-import {
-  MetaLearner,
-  createMetaLearner,
-} from './learning/meta-learner.js';
-import {
-  LearningEffectivenessTracker,
-  createEffectivenessTracker,
-} from './learning/effectiveness.js';
+import type { MetaLearner } from './learning/meta-learner.js';
+import type { LearningEffectivenessTracker } from './learning/effectiveness.js';
 import { TaskRouter, createRouter, type RoutingDecision } from './search/router.js';
 import { DirectSolver, createSolver } from './search/solver.js';
 import {
@@ -64,6 +58,7 @@ import {
 } from './surfacing/skill-library.js';
 import { SqliteStorageAdapter } from './surfacing/sqlite-storage-adapter.js';
 import { join } from 'node:path';
+import { SqlitePersistence, createSqlitePersistence } from './persistence/index.js';
 import {
   PlaybookMCPServer,
   createPlaybookMCPServer,
@@ -160,7 +155,7 @@ export interface SolveResult {
  */
 export class Atlas {
   private memory: MemorySystem;
-  private learning: LearningPipeline;
+  private unifiedPipeline: UnifiedLearningPipeline;
   private router: TaskRouter;
   private solver: DirectSolver | null = null;
   private agentManager: AgentManager | null = null;
@@ -176,10 +171,6 @@ export class Atlas {
   private usageInference: PlaybookUsageInference | null = null;
   private mcpServer: PlaybookMCPServer | null = null;
 
-  // Meta-learning and effectiveness
-  private metaLearner: MetaLearner | null = null;
-  private effectivenessTracker: LearningEffectivenessTracker | null = null;
-
   // Agentic workspace components
   private taskRunner: AgenticTaskRunner | null = null;
   private workspaceManager: WorkspaceManager | null = null;
@@ -190,21 +181,50 @@ export class Atlas {
   private teamMetaLearner: TeamMetaLearner | null = null;
   private teamSkillLibrary: TeamSkillLibrary | null = null;
 
+  // Unified SQLite persistence
+  private persistence: SqlitePersistence;
+
   constructor(config?: Partial<AtlasConfig>) {
     this.config = createDefaultConfig(config);
 
+    // Create unified SQLite persistence
+    this.persistence = createSqlitePersistence({
+      baseDir: this.config.storage.baseDir,
+      dbName: this.config.storage.dbName,
+    });
+
     // Initialize memory system (with optional knowledge bank)
     this.memory = createMemorySystem(
+      this.persistence,
       this.config.storage.baseDir,
       this.config.memory,
-      this.config.knowledgeBank.enabled ? this.config.knowledgeBank : undefined
+      this.config.knowledgeBank.enabled
+        ? { ...this.config.knowledgeBank, coherenceChecking: this.config.features.coherenceChecking }
+        : undefined
     );
 
-    // Initialize learning pipeline
-    this.learning = createLearningPipeline(this.memory, this.config.learning);
+    // Initialize unified learning pipeline (replaces LearningPipeline + InstantLoop + LoopCoordinator)
+    this.unifiedPipeline = createUnifiedPipeline(this.memory, {
+      instant: {
+        enableReflexion: this.config.features.reflexion,
+        enableCausalExtraction: this.config.features.causalExtraction,
+      },
+      batch: {
+        learning: this.config.learning,
+        energy: {
+          countThreshold: this.config.learning.minTrajectories ?? 10,
+        },
+      },
+      features: {
+        temporalCompression: this.config.features.temporalCompression,
+        reasoningBank: this.config.features.reasoningBank,
+        reflexion: this.config.features.reflexion,
+        causalExtraction: this.config.features.causalExtraction,
+      },
+    }, this.persistence);
 
-    // Initialize router
-    this.router = createRouter(this.memory, this.config.router);
+    // Initialize router (with persistence for MoEGate)
+    this.router = createRouter(this.memory, this.config.router, undefined, this.persistence);
 
     // Initialize team learning pipeline and router if enabled
     if (this.config.teamLearning.enabled) {
@@ -232,8 +252,23 @@ export class Atlas {
    * Initialize Atlas (load persisted data)
    */
   async init(): Promise<void> {
+    await this.persistence.init();
+
+    // Load persisted state for components created before persistence.init()
+    this.router.loadPersistedState();
+    this.unifiedPipeline.loadPersistedState();
+
     await this.memory.init();
 
+    // Initialize unified pipeline async components (meta-learner, effectiveness tracker, energy seed)
+    await this.unifiedPipeline.init();
+
+    // Connect meta-learner to router
+    const metaLearner = this.unifiedPipeline.getMetaLearner();
+    if (metaLearner) {
+      this.router.setMetaLearner(metaLearner);
+    }
+
     // Initialize playbook-based components if playbooks are available
     if (this.memory.playbooks) {
       this.skillLibrary = createSkillLibrary(
@@ -253,18 +288,6 @@ export class Atlas {
       // Refresh skill tiers on init
       await this.skillLibrary.refreshTiers();
     }
-
-    // Initialize meta-learner and connect to router
-    if (this.memory.meta) {
-      this.metaLearner = createMetaLearner(this.memory.meta);
-      this.router.setMetaLearner(this.metaLearner);
-    }
-
-    // Initialize effectiveness tracker
-    this.effectivenessTracker = createEffectivenessTracker(
-      this.config.storage.baseDir
-    );
-    await this.effectivenessTracker.init();
   }
 
   /**
@@ -303,12 +326,12 @@ export class Atlas {
       this.workspaceManager,
       this.agentManager,
       this.memory,
-      this.learning,
+      this.unifiedPipeline,
       this.config.agenticTasks
     );
 
-    // Connect task runner to learning pipeline for workspace-based analysis
-    this.learning.setTaskRunner(this.taskRunner);
+    // Connect task runner to unified pipeline for workspace-based analysis
+    this.unifiedPipeline.setTaskRunner(this.taskRunner);
 
     // Connect task runner to team learning pipeline
     if (this.teamLearning) {
@@ -481,12 +504,14 @@ export class Atlas {
     }
 
     // Generate meta-reflection (records observation + periodically generates strategies)
-    if (this.metaLearner) {
+    const metaLearner = this.unifiedPipeline.getMetaLearner();
+    if (metaLearner) {
       await this.reflectOnExecution(result.trajectory, routing);
     }
 
     // Annotate trajectory for effectiveness tracking
-    if (this.effectivenessTracker) {
+    const effectivenessTracker = this.unifiedPipeline.getEffectivenessTracker();
+    if (effectivenessTracker) {
       const appliedPlaybookIds = (result.playbookUsage ?? [])
         .filter(u => u.wasUsed)
         .map(u => u.playbookId);
@@ -495,7 +520,7 @@ export class Atlas {
         e => e.experience.id
       );
 
-      await this.effectivenessTracker.annotate(
+      await effectivenessTracker.annotate(
         result.trajectory,
         routing.memoryContext.playbooks,
         surfacedExperienceIds,
@@ -503,15 +528,10 @@ export class Atlas {
       );
     }
 
-    // Process the trajectory for learning
-    await this.learning.processTrajectory(result.trajectory);
+    // Process the trajectory through unified pipeline (immediate + batch if energy triggers)
+    await this.unifiedPipeline.processTrajectory(result.trajectory);
     this.trajectoriesProcessed++;
 
-    // Run batch learning if ready
-    if (this.learning.shouldRunBatch()) {
-      await this.runBatchLearning();
-    }
-
     return result;
   }
 
@@ -588,10 +608,12 @@ export class Atlas {
   }
 
   /**
-   * Process an external trajectory (from another agent)
+   * Process an external trajectory (from another agent).
+   * Runs the instant loop first (hot path), then feeds into the batch pipeline.
    */
-  async processTrajectory(trajectory: Trajectory): Promise<ProcessResult> {
-    const result = await this.learning.processTrajectory(trajectory);
+  async processTrajectory(trajectory: Trajectory): Promise<ImmediateResult> {
+    // Unified pipeline handles immediate + batch (if energy triggers)
+    const result = await this.unifiedPipeline.processTrajectory(trajectory);
     this.trajectoriesProcessed++;
     return result;
   }
@@ -763,8 +785,8 @@ export class Atlas {
   /**
    * Run batch learning explicitly
    */
-  async runBatchLearning(): Promise<BatchResult> {
-    return this.learning.runBatchLearning();
+  async runBatchLearning(): Promise<UnifiedBatchResult> {
+    return this.unifiedPipeline.runBatch();
   }
 
   /**
@@ -790,7 +812,7 @@ export class Atlas {
       memory: memoryStats,
       learning: {
         trajectoriesProcessed: this.trajectoriesProcessed,
-        pendingTrajectories: this.learning.getAccumulatedCount(),
+        pendingTrajectories: this.unifiedPipeline.getAccumulatedCount(),
         teamTrajectoriesProcessed: this.teamTrajectoriesProcessed,
       },
     };
@@ -845,8 +867,8 @@ export class Atlas {
   /**
    * Get the learning pipeline for direct access
    */
-  getLearning(): LearningPipeline {
-    return this.learning;
+  getLearning(): UnifiedLearningPipeline {
+    return this.unifiedPipeline;
   }
 
   /**
@@ -903,7 +925,7 @@ export class Atlas {
    */
   updateConfig(config: Partial<AtlasConfig>): void {
     if (config.learning) {
-      this.learning.updateConfig(config.learning);
+      this.unifiedPipeline.updateConfig(config.learning);
     }
     if (config.router) {
       this.router.updateConfig(config.router);
@@ -949,7 +971,8 @@ export class Atlas {
     trajectory: Trajectory,
     routing: RoutingDecision,
   ): Promise<void> {
-    if (!this.metaLearner) return;
+    const metaLearnerRef = this.unifiedPipeline.getMetaLearner();
+    if (!metaLearnerRef) return;
 
     const routingInfo = {
       strategy: routing.strategy,
@@ -970,7 +993,7 @@ export class Atlas {
         // Bridge template output into MetaLearner storage
         const playbookIds = playbookMatches.map(p => p.playbook.id);
         const actualEffort = trajectory.llmCalls ?? trajectory.steps.length;
-        await this.metaLearner.recordFromReflection(
+        await metaLearnerRef.recordFromReflection(
           result.output,
           trajectory.id,
           routingInfo,
@@ -987,7 +1010,7 @@ export class Atlas {
     }
 
     // Heuristic fallback
-    await this.metaLearner.generateReflection(
+    await metaLearnerRef.generateReflection(
       trajectory,
       routingInfo,
       playbookMatches,
@@ -998,23 +1021,23 @@ export class Atlas {
    * Get the meta learner for direct access
    */
   getMetaLearner(): MetaLearner | null {
-    return this.metaLearner;
+    return this.unifiedPipeline.getMetaLearner();
   }
 
   /**
    * Get the effectiveness tracker for direct access
    */
   getEffectivenessTracker(): LearningEffectivenessTracker | null {
-    return this.effectivenessTracker;
+    return this.unifiedPipeline.getEffectivenessTracker();
   }
 
   async close(): Promise<void> {
     // Stop MCP server if running
     await this.stopMCPServer();
 
-    // Flush learning pipeline
-    if (this.learning.getAccumulatedCount() > 0) {
-      await this.learning.runBatchLearning();
+    // Flush unified pipeline
+    if (this.unifiedPipeline.getAccumulatedCount() > 0) {
+      await this.unifiedPipeline.runBatch();
     }
 
     // Flush team learning pipeline
@@ -1022,9 +1045,13 @@ export class Atlas {
       await this.teamLearning.runBatchLearning();
     }
 
+    // Flush MoE gate state before closing persistence
+    this.router.persistGateState();
+
     // Close effectiveness tracker
-    if (this.effectivenessTracker) {
-      await this.effectivenessTracker.close();
+    const tracker = this.unifiedPipeline.getEffectivenessTracker();
+    if (tracker) {
+      await tracker.close();
     }
 
     // Close skill-tree storage
@@ -1034,6 +1061,9 @@ export class Atlas {
 
     // Close memory system
     await this.memory.close();
+
+    // Close SQLite persistence
+    this.persistence.close();
   }
 }
 

package/src/bin/cli-utils.ts

@@ -0,0 +1,220 @@
+/**
+ * CLI shared utilities — types, arg parser, Atlas lifecycle, output helpers.
+ */
+
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { Atlas, createAtlas } from '../atlas.js';
+import type { KnowledgeBank } from '../memory/knowledge-bank.js';
+import type { SkillLibrary } from '../surfacing/skill-library.js';
+import type { Playbook, AtlasConfig } from '../types/index.js';
+
+// ─── Types ───────────────────────────────────────────────────────────
+
+export interface CLIOptions {
+  dir?: string;
+  domain?: string;
+  limit?: number;
+  format?: 'json' | 'text';
+  type?: string;
+  tier?: string;
+  agent?: string;
+  since?: string;
+  before?: string;
+  branch?: string;
+  interval?: number;
+  repo?: string;
+  once?: boolean;
+}
+
+export interface ParsedArgs {
+  group: string;
+  command: string;
+  positional: string[];
+  options: CLIOptions;
+}
+
+const COMMAND_GROUPS = new Set(['kb', 'sessions', 'learn', 'skills', 'run']);
+
+// ─── Arg Parser ──────────────────────────────────────────────────────
+
+export function parseArgs(args: string[]): ParsedArgs {
+  const options: CLIOptions = {};
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--dir' && args[i + 1]) {
+      options.dir = args[++i];
+    } else if (arg === '--domain' && args[i + 1]) {
+      options.domain = args[++i];
+    } else if (arg === '--limit' && args[i + 1]) {
+      options.limit = parseInt(args[++i], 10);
+    } else if (arg === '--format' && args[i + 1]) {
+      options.format = args[++i] as 'json' | 'text';
+    } else if (arg === '--json') {
+      options.format = 'json';
+    } else if (arg === '--type' && args[i + 1]) {
+      options.type = args[++i];
+    } else if (arg === '--tier' && args[i + 1]) {
+      options.tier = args[++i];
+    } else if (arg === '--agent' && args[i + 1]) {
+      options.agent = args[++i];
+    } else if (arg === '--since' && args[i + 1]) {
+      options.since = args[++i];
+    } else if (arg === '--before' && args[i + 1]) {
+      options.before = args[++i];
+    } else if (arg === '--branch' && args[i + 1]) {
+      options.branch = args[++i];
+    } else if (arg === '--interval' && args[i + 1]) {
+      options.interval = parseInt(args[++i], 10);
+    } else if (arg === '--repo' && args[i + 1]) {
+      options.repo = args[++i];
+    } else if (arg === '--once') {
+      options.once = true;
+    } else if (!arg.startsWith('-')) {
+      positional.push(arg);
+    }
+  }
+
+  // Two-level routing: first positional may be a command group
+  const first = positional[0] ?? '';
+
+  if (COMMAND_GROUPS.has(first)) {
+    return {
+      group: first,
+      command: positional[1] ?? '',
+      positional: positional.slice(2),
+      options,
+    };
+  }
+
+  // Legacy commands — group is empty, first positional is the command
+  return {
+    group: '',
+    command: first,
+    positional: positional.slice(1),
+    options,
+  };
+}
+
+// ─── Storage Dir ─────────────────────────────────────────────────────
+
+export function resolveStorageDir(): string {
+  if (process.env.COGNITIVE_CORE_HOME) return process.env.COGNITIVE_CORE_HOME;
+  const swarmDir = path.join(process.cwd(), '.swarm', 'cognitive-core');
+  if (existsSync(swarmDir)) return swarmDir;
+  return path.join(process.cwd(), '.cognitive-core');
+}
+
+// ─── Atlas Lifecycle ─────────────────────────────────────────────────
+
+export async function withAtlas<T>(
+  options: CLIOptions,
+  fn: (atlas: Atlas) => Promise<T>,
+): Promise<T> {
+  const atlas = createAtlas({
+    storage: { baseDir: options.dir || resolveStorageDir() },
+    knowledgeBank: { enabled: true },
+  } as Partial<AtlasConfig>);
+  try {
+    await atlas.init();
+    return await fn(atlas);
+  } finally {
+    await atlas.close();
+  }
+}
+
+// ─── Subsystem Guards ────────────────────────────────────────────────
+
+export function requireKnowledgeBank(atlas: Atlas): KnowledgeBank {
+  const kb = atlas.getKnowledgeBank();
+  if (!kb) {
+    throw new Error(
+      'Knowledge bank is not enabled. Ensure knowledgeBank.enabled is true in config.',
+    );
+  }
+  return kb;
+}
+
+export function requireSkillLibrary(atlas: Atlas): SkillLibrary {
+  const lib = atlas.getSkillLibrary();
+  if (!lib) {
+    throw new Error(
+      'Skill library is not available. Initialize Atlas first.',
+    );
+  }
+  return lib;
+}
+
+// ─── Output Helpers ──────────────────────────────────────────────────
+
+export function outputJson(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function outputError(error: unknown, options: CLIOptions): void {
+  const message = error instanceof Error ? error.message : String(error);
+  if (options.format === 'json') {
+    console.log(JSON.stringify({ error: message }));
+  } else {
+    console.error(`Error: ${message}`);
+  }
+}
+
+// ─── Playbook Formatting ─────────────────────────────────────────────
+
+export function formatPlaybook(playbook: Playbook, verbose = false): string {
+  const lines: string[] = [];
+  const { successCount, failureCount } = playbook.evolution;
+  const totalUses = successCount + failureCount;
+  const successRate = totalUses > 0 ? Math.round((successCount / totalUses) * 100) : 0;
+
+  lines.push(`## ${playbook.name}`);
+  lines.push(`ID: ${playbook.id}`);
+  lines.push(`Confidence: ${Math.round(playbook.confidence * 100)}%`);
+  lines.push(`Success Rate: ${successRate}% (${totalUses} uses)`);
+  lines.push(`Domains: ${playbook.applicability.domains.join(', ')}`);
+  lines.push('');
+  lines.push(`**Strategy**: ${playbook.guidance.strategy}`);
+
+  if (playbook.guidance.tactics.length > 0) {
+    lines.push('**Tactics**:');
+    for (const tactic of playbook.guidance.tactics) {
+      lines.push(`  - ${tactic}`);
+    }
+  }
+
+  if (verbose) {
+    if (playbook.guidance.steps && playbook.guidance.steps.length > 0) {
+      lines.push('**Steps**:');
+      for (let i = 0; i < playbook.guidance.steps.length; i++) {
+        lines.push(`  ${i + 1}. ${playbook.guidance.steps[i]}`);
+      }
+    }
+
+    if (playbook.applicability.situations.length > 0) {
+      lines.push('**When to use**:');
+      for (const sit of playbook.applicability.situations) {
+        lines.push(`  - ${sit}`);
+      }
+    }
+
+    if (playbook.applicability.antiPatterns.length > 0) {
+      lines.push('**Avoid when**:');
+      for (const anti of playbook.applicability.antiPatterns) {
+        lines.push(`  - ${anti}`);
+      }
+    }
+
+    if (playbook.verification.successIndicators.length > 0) {
+      lines.push('**Success indicators**:');
+      for (const ind of playbook.verification.successIndicators) {
+        lines.push(`  - ${ind}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}