cognitive-core 0.0.2 → 0.1.2

package/src/atlas.ts

@@ -0,0 +1,1072 @@
+import type {
+  Task,
+  Trajectory,
+  TeamTrajectory,
+  TeamPlaybook,
+  AtlasConfig,
+  Playbook,
+} from './types/index.js';
+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';
+import {
+  TeamLearningPipeline,
+  createTeamLearningPipeline,
+  type TeamBatchResult,
+  type TeamProcessResult,
+} from './learning/team-pipeline.js';
+import {
+  TeamMetaLearner,
+  createTeamMetaLearner,
+} from './learning/team-meta-learner.js';
+import {
+  TeamRouter,
+  createTeamRouter,
+  type TeamRecommendation,
+  type TeamRecommendationInput,
+} from './search/team-router.js';
+import {
+  TeamSkillLibrary,
+  createTeamSkillLibrary,
+  type TeamOutcomeFeedback,
+} from './surfacing/team-skill-library.js';
+import {
+  PlaybookUsageInference,
+  createUsageInference,
+} from './learning/usage-inference.js';
+import {
+  MetaLearner,
+  createMetaLearner,
+} from './learning/meta-learner.js';
+import {
+  LearningEffectivenessTracker,
+  createEffectivenessTracker,
+} from './learning/effectiveness.js';
+import { TaskRouter, createRouter, type RoutingDecision } from './search/router.js';
+import { DirectSolver, createSolver } from './search/solver.js';
+import {
+  RefinementLoop,
+  createRefinementLoop,
+} from './search/refinement-loop.js';
+import type { RefinementResult } from './search/refinement-types.js';
+import type { LLMProvider } from './agents/types.js';
+import { AgentManager, createAgentManager } from './runtime/manager.js';
+import type { AgentBackend, AgentSpawnConfig, AgentDelegate } from './runtime/types.js';
+import {
+  SkillLibrary,
+  createSkillLibrary,
+} from './surfacing/skill-library.js';
+import { SqliteStorageAdapter } from './surfacing/sqlite-storage-adapter.js';
+import { join } from 'node:path';
+import {
+  PlaybookMCPServer,
+  createPlaybookMCPServer,
+} from './mcp/playbook-server.js';
+import {
+  AgenticTaskRunner,
+  createAgenticTaskRunner,
+} from './workspace/runner.js';
+import { usageInferenceTemplate } from './workspace/templates/usage-inference.js';
+import { metaReflectionTemplate } from './workspace/templates/meta-reflection.js';
+import { WorkspaceManager } from 'agent-workspace';
+
+/**
+ * Result from processing a team trajectory.
+ * Re-exports the pipeline's TeamProcessResult type.
+ */
+export type { TeamProcessResult } from './learning/team-pipeline.js';
+
+/**
+ * Atlas statistics
+ */
+export interface AtlasStats {
+  memory: {
+    experienceCount: number;
+    playbookCount: number;
+    metaObservationCount: number;
+  };
+  teamMemory?: {
+    teamExperienceCount: number;
+    teamPlaybookCount: number;
+    rolePlaybookCount: number;
+    teamMetaObservationCount: number;
+  };
+  learning: {
+    trajectoriesProcessed: number;
+    pendingTrajectories: number;
+    teamTrajectoriesProcessed: number;
+  };
+  execution?: {
+    agentManagerEnabled: boolean;
+    refinementEnabled: boolean;
+    backends: string[];
+  };
+  skillLibrary?: {
+    coreSkillCount: number;
+    domainSkillCounts: Record<string, number>;
+    mcpServerEnabled: boolean;
+  };
+}
+
+/**
+ * Playbook usage tracking
+ */
+export interface PlaybookUsage {
+  playbookId: string;
+  playbookName: string;
+  wasUsed: boolean;
+  usageConfidence: number;
+  wasSuccessful: boolean;
+}
+
+/**
+ * Extended solve result with refinement info
+ */
+export interface SolveResult {
+  /** The execution trajectory */
+  trajectory: Trajectory;
+  /** Whether memory was used */
+  usedMemory?: boolean;
+  /** Strategy used (from legacy solver) */
+  strategy?: string;
+  /** Routing decision (when using AgentManager) */
+  routing?: RoutingDecision;
+  /** Whether the result came from agent execution (vs direct solver) */
+  usedAgentManager: boolean;
+  /** Refinement result if refinement was performed */
+  refinement?: RefinementResult;
+  /** Playbooks that were injected for this task */
+  injectedPlaybooks?: Playbook[];
+  /** Playbook usage inference results */
+  playbookUsage?: PlaybookUsage[];
+  /** Knowledge notes that were surfaced for this task */
+  surfacedKnowledge?: KnowledgeMatch[];
+}
+
+/**
+ * Atlas - Adaptive Trajectory Learning and Abstraction System
+ *
+ * Main orchestrator that combines:
+ * - Memory systems (experiences, playbooks, meta-observations)
+ * - Learning engine (trajectory analysis, playbook extraction)
+ * - Task routing (deciding how to solve tasks)
+ * - Skill surfacing (providing playbooks to agents)
+ */
+export class Atlas {
+  private memory: MemorySystem;
+  private learning: LearningPipeline;
+  private router: TaskRouter;
+  private solver: DirectSolver | null = null;
+  private agentManager: AgentManager | null = null;
+  private refinementLoop: RefinementLoop | null = null;
+  private config: AtlasConfig;
+  private provider: LLMProvider | null = null;
+  private trajectoriesProcessed = 0;
+  private teamTrajectoriesProcessed = 0;
+
+  // Playbook-based components
+  private skillLibrary: SkillLibrary | null = null;
+  private skillTreeStorage: SqliteStorageAdapter | null = null;
+  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;
+
+  // Team-aware learning, recommendation, and surfacing
+  private teamLearning: TeamLearningPipeline | null = null;
+  private teamRouter: TeamRouter | null = null;
+  private teamMetaLearner: TeamMetaLearner | null = null;
+  private teamSkillLibrary: TeamSkillLibrary | null = null;
+
+  constructor(config?: Partial<AtlasConfig>) {
+    this.config = createDefaultConfig(config);
+
+    // Initialize memory system (with optional knowledge bank)
+    this.memory = createMemorySystem(
+      this.config.storage.baseDir,
+      this.config.memory,
+      this.config.knowledgeBank.enabled ? this.config.knowledgeBank : undefined
+    );
+
+    // Initialize learning pipeline
+    this.learning = createLearningPipeline(this.memory, this.config.learning);
+
+    // Initialize router
+    this.router = createRouter(this.memory, this.config.router);
+
+    // Initialize team learning pipeline and router if enabled
+    if (this.config.teamLearning.enabled) {
+      this.teamLearning = createTeamLearningPipeline(
+        this.memory.teamExperiences,
+        this.config.teamLearning
+      );
+
+      // Initialize team meta-learner and team router
+      this.teamMetaLearner = createTeamMetaLearner(
+        this.memory.teamExperiences
+      );
+      this.teamRouter = createTeamRouter(
+        this.memory.teamExperiences,
+        undefined,
+        this.teamMetaLearner
+      );
+      this.teamSkillLibrary = createTeamSkillLibrary(
+        this.memory.teamExperiences
+      );
+    }
+  }
+
+  /**
+   * Initialize Atlas (load persisted data)
+   */
+  async init(): Promise<void> {
+    await this.memory.init();
+
+    // Initialize playbook-based components if playbooks are available
+    if (this.memory.playbooks) {
+      this.skillLibrary = createSkillLibrary(
+        this.memory.playbooks,
+        this.config.skillLibrary
+      );
+      this.usageInference = createUsageInference();
+
+      // Wire skill-tree publisher if enabled (default: true)
+      if (this.config.skillTree.enabled) {
+        const dbPath = join(this.config.storage.baseDir, this.config.skillTree.dbPath);
+        this.skillTreeStorage = new SqliteStorageAdapter(dbPath);
+        await this.skillTreeStorage.initialize();
+        this.skillLibrary.setPublisher(this.skillTreeStorage);
+      }
+
+      // 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();
+  }
+
+  /**
+   * Set the LLM provider for solving (deprecated)
+   * @deprecated Use setAgentManager() with backends for real execution
+   */
+  setProvider(provider: LLMProvider): void {
+    this.provider = provider;
+    this.solver = createSolver(this.memory, provider);
+  }
+
+  /**
+   * Set up the AgentManager with backends for real action execution
+   * This is the recommended way to configure Atlas for execution
+   */
+  setAgentManager(
+    backends: AgentBackend[],
+    options?: { delegate?: AgentDelegate }
+  ): void {
+    // Create AgentManager with memory system
+    this.agentManager = createAgentManager(this.memory, {
+      delegate: options?.delegate,
+    });
+
+    // Register all backends
+    for (const backend of backends) {
+      this.agentManager.registerBackend(backend);
+    }
+
+    // Create workspace infrastructure (using agent-workspace package)
+    this.workspaceManager = new WorkspaceManager({
+      baseDir: this.config.agenticTasks.workspaceBaseDir,
+      prefix: 'atlas-workspaces',
+    });
+    this.taskRunner = createAgenticTaskRunner(
+      this.workspaceManager,
+      this.agentManager,
+      this.memory,
+      this.learning,
+      this.config.agenticTasks
+    );
+
+    // Connect task runner to learning pipeline for workspace-based analysis
+    this.learning.setTaskRunner(this.taskRunner);
+
+    // Connect task runner to team learning pipeline
+    if (this.teamLearning) {
+      this.teamLearning.setTaskRunner(this.taskRunner);
+    }
+
+    // Create refinement loop with config
+    this.refinementLoop = createRefinementLoop(
+      this.agentManager,
+      this.memory,
+      {
+        maxIterations: this.config.refinement.maxIterations,
+        minAcceptableScore: this.config.refinement.acceptableScore,
+        evaluatorConfig: {
+          evaluatorAgentType: this.config.refinement.evaluatorAgentType,
+        },
+        triggerOnStrategies: this.config.refinement.triggerOnStrategies,
+        confidenceThreshold: this.config.refinement.confidenceThreshold,
+      }
+    );
+
+    // Connect task runner to refinement loop for workspace-based evaluation and analysis
+    this.refinementLoop.setTaskRunner(this.taskRunner);
+  }
+
+  /**
+   * Get the AgentManager for direct access
+   */
+  getAgentManager(): AgentManager | null {
+    return this.agentManager;
+  }
+
+  /**
+   * Set a delegate for caller-provided agent execution.
+   * Requires AgentManager to be initialized first (via setAgentManager).
+   */
+  setDelegate(delegate: AgentDelegate): void {
+    if (!this.agentManager) {
+      throw new Error('AgentManager not initialized. Call setAgentManager() first.');
+    }
+    this.agentManager.setDelegate(delegate);
+  }
+
+  /**
+   * Get the current delegate, if any.
+   */
+  getDelegate(): AgentDelegate | undefined {
+    return this.agentManager?.getDelegate();
+  }
+
+  /**
+   * Get the RefinementLoop for registering domain verifiers
+   */
+  getRefinementLoop(): RefinementLoop | null {
+    return this.refinementLoop;
+  }
+
+  /**
+   * Get the AgenticTaskRunner for running analysis tasks
+   */
+  getTaskRunner(): AgenticTaskRunner | null {
+    return this.taskRunner;
+  }
+
+  /**
+   * Check if agent execution is available
+   */
+  hasAgentExecution(): boolean {
+    return this.agentManager !== null;
+  }
+
+  /**
+   * Solve a task using the best available method
+   * Prefers AgentManager with refinement when available
+   */
+  async solve(task: Task): Promise<SolveResult> {
+    // Route the task first
+    const routing = await this.router.route(task);
+
+    // Get skills for the agent if skill library is available
+    let injectedPlaybooks: Playbook[] = [];
+    let skillContext = '';
+    if (this.skillLibrary) {
+      const skills = await this.skillLibrary.getSkillsForAgent(task);
+      injectedPlaybooks = [...skills.core, ...skills.domain, ...skills.contextual];
+      skillContext = this.skillLibrary.formatForSystemPrompt(skills);
+    }
+
+    // Merge playbooks from router's memory context (deduplicating by ID)
+    // This ensures we track ALL playbooks that will be injected into the agent
+    const injectedIds = new Set(injectedPlaybooks.map(p => p.id));
+    for (const { playbook } of routing.memoryContext.playbooks) {
+      if (!injectedIds.has(playbook.id)) {
+        injectedPlaybooks.push(playbook);
+        injectedIds.add(playbook.id);
+      }
+    }
+
+    // Surface knowledge from knowledge bank (independent from skill surfacing)
+    let knowledgeContext = '';
+    let surfacedKnowledge: KnowledgeMatch[] | undefined;
+    if (this.memory.knowledgeBank) {
+      surfacedKnowledge = await this.memory.knowledgeBank.getRelevantKnowledge(
+        { description: task.description, domain: task.domain },
+      );
+      if (surfacedKnowledge.length > 0) {
+        knowledgeContext = this.memory.knowledgeBank.formatKnowledgeForPrompt(
+          surfacedKnowledge,
+        );
+      }
+    }
+
+    // Combine skill context + knowledge context
+    const combinedContext = [skillContext, knowledgeContext]
+      .filter(Boolean)
+      .join('\n\n');
+
+    let result: SolveResult;
+
+    // Prefer AgentManager if available
+    if (this.agentManager) {
+      result = await this.solveWithAgent(task, routing, combinedContext || undefined);
+    } else if (this.solver && this.provider) {
+      // Fall back to DirectSolver (deprecated)
+      const solverResult = await this.solver.solve(task, routing);
+      result = {
+        trajectory: solverResult.trajectory,
+        usedMemory: solverResult.usedMemory,
+        strategy: solverResult.strategy,
+        usedAgentManager: false,
+      };
+    } else {
+      throw new Error(
+        'No execution method available. Call setAgentManager() or setProvider().'
+      );
+    }
+
+    // Add injected playbooks to result
+    result.injectedPlaybooks = injectedPlaybooks;
+    result.surfacedKnowledge = surfacedKnowledge;
+
+    // Infer playbook usage from trajectory
+    if (this.skillLibrary && injectedPlaybooks.length > 0) {
+      const usageResults = await this.inferPlaybookUsage(
+        result.trajectory,
+        injectedPlaybooks,
+      );
+
+      // Convert to PlaybookUsage format and record outcomes
+      result.playbookUsage = [];
+      for (const usage of usageResults) {
+        result.playbookUsage.push({
+          playbookId: usage.playbookId,
+          playbookName: usage.playbookName,
+          wasUsed: usage.wasUsed,
+          usageConfidence: usage.usageConfidence,
+          wasSuccessful: usage.wasSuccessful,
+        });
+
+        // Record outcome for tier management
+        if (usage.wasUsed) {
+          await this.skillLibrary.recordOutcome(
+            usage.playbookId,
+            result.trajectory.id,
+            usage.wasSuccessful,
+            usage.context
+          );
+        }
+      }
+    }
+
+    // Generate meta-reflection (records observation + periodically generates strategies)
+    if (this.metaLearner) {
+      await this.reflectOnExecution(result.trajectory, routing);
+    }
+
+    // Annotate trajectory for effectiveness tracking
+    if (this.effectivenessTracker) {
+      const appliedPlaybookIds = (result.playbookUsage ?? [])
+        .filter(u => u.wasUsed)
+        .map(u => u.playbookId);
+
+      const surfacedExperienceIds = routing.memoryContext.experiences.map(
+        e => e.experience.id
+      );
+
+      await this.effectivenessTracker.annotate(
+        result.trajectory,
+        routing.memoryContext.playbooks,
+        surfacedExperienceIds,
+        appliedPlaybookIds,
+      );
+    }
+
+    // Process the trajectory for learning
+    await this.learning.processTrajectory(result.trajectory);
+    this.trajectoriesProcessed++;
+
+    // Run batch learning if ready
+    if (this.learning.shouldRunBatch()) {
+      await this.runBatchLearning();
+    }
+
+    return result;
+  }
+
+  /**
+   * Solve using AgentManager with optional refinement
+   */
+  private async solveWithAgent(
+    task: Task,
+    routing: RoutingDecision,
+    skillContext?: string
+  ): Promise<SolveResult> {
+    if (!this.agentManager) {
+      throw new Error('AgentManager not available');
+    }
+
+    // Build spawn configuration
+    const spawnConfig: AgentSpawnConfig = {
+      agentType: this.config.execution.defaultAgentType,
+      task,
+      timeout: this.config.execution.maxExecutionTime * 1000,
+      captureToolCalls: this.config.execution.captureToolCalls,
+      // Inject skill context if available
+      systemPromptAdditions: skillContext || undefined,
+      // Pass router's memory context to avoid duplicate memory queries
+      injectedKnowledge: routing.memoryContext,
+    };
+
+    // Run initial execution
+    const agentResult = await this.agentManager.spawn(spawnConfig);
+
+    // Check if refinement should be triggered
+    const shouldRefine =
+      this.refinementLoop &&
+      this.config.refinement.useAgentEvaluation &&
+      this.refinementLoop.shouldTriggerRefinement(
+        routing.strategy,
+        routing.confidence
+      );
+
+    let refinementResult: RefinementResult | undefined;
+
+    if (shouldRefine && !agentResult.success) {
+      // Run refinement loop on failed trajectory
+      refinementResult = await this.refinementLoop!.refine(
+        agentResult.trajectory,
+        spawnConfig
+      );
+
+      return {
+        trajectory: refinementResult.trajectory,
+        routing,
+        usedAgentManager: true,
+        refinement: refinementResult,
+      };
+    }
+
+    return {
+      trajectory: agentResult.trajectory,
+      routing,
+      usedAgentManager: true,
+    };
+  }
+
+  /**
+   * Solve multiple tasks
+   */
+  async solveBatch(tasks: Task[]): Promise<SolveResult[]> {
+    const results: SolveResult[] = [];
+    for (const task of tasks) {
+      const result = await this.solve(task);
+      results.push(result);
+    }
+    return results;
+  }
+
+  /**
+   * Process an external trajectory (from another agent)
+   */
+  async processTrajectory(trajectory: Trajectory): Promise<ProcessResult> {
+    const result = await this.learning.processTrajectory(trajectory);
+    this.trajectoriesProcessed++;
+    return result;
+  }
+
+  /**
+   * Process a team trajectory through the full team learning pipeline.
+   * Ingests, analyzes (heuristic or agentic), stores, and accumulates
+   * for batch team playbook extraction.
+   */
+  async processTeamTrajectory(
+    trajectory: TeamTrajectory
+  ): Promise<TeamProcessResult> {
+    if (!this.config.teamLearning.enabled || !this.teamLearning) {
+      return { teamTrajectoryId: trajectory.id, stored: false, analyzed: false };
+    }
+
+    const result = await this.teamLearning.processTeamTrajectory(trajectory);
+    this.teamTrajectoriesProcessed++;
+
+    // Generate team meta-reflection for the meta-learner
+    if (this.teamMetaLearner) {
+      try {
+        await this.teamMetaLearner.generateReflection(trajectory);
+      } catch (error) {
+        console.error(
+          '[Atlas] Team meta-reflection failed:',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+
+    // Run batch team learning if ready
+    if (this.teamLearning.shouldRunBatch()) {
+      await this.runTeamBatchLearning();
+    }
+
+    return result;
+  }
+
+  /**
+   * Run batch team playbook extraction explicitly.
+   */
+  async runTeamBatchLearning(): Promise<TeamBatchResult | null> {
+    if (!this.teamLearning) return null;
+    return this.teamLearning.runBatchLearning();
+  }
+
+  /**
+   * Get the team learning pipeline for direct access.
+   */
+  getTeamLearning(): TeamLearningPipeline | null {
+    return this.teamLearning;
+  }
+
+  /**
+   * Recommend a team composition for a given task.
+   * Uses team playbooks and meta-strategies to produce a recommendation
+   * with optional OpenTeams YAML export.
+   */
+  async recommendTeam(input: TeamRecommendationInput): Promise<TeamRecommendation> {
+    if (!this.teamRouter) {
+      throw new Error(
+        'Team learning is not enabled. Set teamLearning.enabled = true in config.'
+      );
+    }
+    return this.teamRouter.recommend(input);
+  }
+
+  /**
+   * Get the team router for direct access.
+   */
+  getTeamRouter(): TeamRouter | null {
+    return this.teamRouter;
+  }
+
+  /**
+   * Get the team meta-learner for direct access.
+   */
+  getTeamMetaLearner(): TeamMetaLearner | null {
+    return this.teamMetaLearner;
+  }
+
+  /**
+   * Get the team skill library for direct access.
+   */
+  getTeamSkillLibrary(): TeamSkillLibrary | null {
+    return this.teamSkillLibrary;
+  }
+
+  /**
+   * Record team outcome feedback to update playbook evolution.
+   * Updates success/failure counts, recalculates confidence, and
+   * accumulates average metrics for the team playbook.
+   */
+  async recordTeamOutcome(feedback: TeamOutcomeFeedback): Promise<void> {
+    if (!this.teamSkillLibrary) {
+      throw new Error(
+        'Team learning is not enabled. Set teamLearning.enabled = true in config.'
+      );
+    }
+    await this.teamSkillLibrary.recordTeamOutcome(feedback);
+  }
+
+  /**
+   * Format role guidance for injection into an agent's system prompt.
+   * Returns markdown-formatted role playbook content for the given role.
+   */
+  async formatRoleGuidance(
+    role: string,
+    context?: { topology?: string; domain?: string; taskType?: string }
+  ): Promise<string> {
+    if (!this.teamSkillLibrary) return '';
+
+    const ranked = await this.teamSkillLibrary.findRolePlaybooks(role, {
+      topology: context?.topology,
+      domain: context?.domain,
+      taskType: context?.taskType,
+    });
+
+    return this.teamSkillLibrary.formatRoleGuidance(
+      role,
+      ranked.map((r) => r.playbook)
+    );
+  }
+
+  /**
+   * Query team memory for coordination patterns.
+   */
+  async queryTeamMemory(
+    query: string,
+    options?: {
+      domain?: string;
+      topology?: string;
+      includeExperiences?: boolean;
+      includePlaybooks?: boolean;
+    }
+  ) {
+    const results: {
+      experiences: Array<{ experience: TeamExperience; score: number }>;
+      playbooks: Array<{ playbook: TeamPlaybook; score: number }>;
+    } = {
+      experiences: [],
+      playbooks: [],
+    };
+
+    const shouldIncludeAll = !options || (
+      options.includeExperiences === undefined &&
+      options.includePlaybooks === undefined
+    );
+
+    if (shouldIncludeAll || options?.includeExperiences) {
+      results.experiences = await this.memory.teamExperiences.findSimilarTeamExperiences(
+        query,
+        { domain: options?.domain, topology: options?.topology }
+      );
+    }
+
+    if (shouldIncludeAll || options?.includePlaybooks) {
+      results.playbooks = await this.memory.teamExperiences.findMatchingTeamPlaybooks({
+        taskType: query,
+        domain: options?.domain,
+        topology: options?.topology,
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * Run batch learning explicitly
+   */
+  async runBatchLearning(): Promise<BatchResult> {
+    return this.learning.runBatchLearning();
+  }
+
+  /**
+   * Query memory for relevant context
+   */
+  async queryMemory(
+    query: string,
+    options?: {
+      domains?: string[];
+      includeExperiences?: boolean;
+      includePlaybooks?: boolean;
+    }
+  ) {
+    return this.memory.queryV2(query, options);
+  }
+
+  /**
+   * Get Atlas statistics
+   */
+  async getStats(): Promise<AtlasStats> {
+    const memoryStats = await this.memory.getStats();
+    const stats: AtlasStats = {
+      memory: memoryStats,
+      learning: {
+        trajectoriesProcessed: this.trajectoriesProcessed,
+        pendingTrajectories: this.learning.getAccumulatedCount(),
+        teamTrajectoriesProcessed: this.teamTrajectoriesProcessed,
+      },
+    };
+
+    // Add team memory stats if team learning is enabled
+    if (this.config.teamLearning.enabled) {
+      const teamStats = await this.memory.teamExperiences.getStats();
+      stats.teamMemory = {
+        teamExperienceCount: teamStats.teamExperienceCount,
+        teamPlaybookCount: teamStats.teamPlaybookCount,
+        rolePlaybookCount: teamStats.rolePlaybookCount,
+        teamMetaObservationCount: teamStats.metaObservationCount,
+      };
+    }
+
+    // Add execution stats if AgentManager is available
+    if (this.agentManager) {
+      stats.execution = {
+        agentManagerEnabled: true,
+        refinementEnabled: this.refinementLoop !== null,
+        backends: this.agentManager.listBackends(),
+      };
+    }
+
+    // Add skill library stats if available
+    if (this.skillLibrary) {
+      const libStats = this.skillLibrary.getStats();
+      stats.skillLibrary = {
+        coreSkillCount: libStats.coreSkillCount,
+        domainSkillCounts: libStats.domainSkillCounts,
+        mcpServerEnabled: this.mcpServer !== null,
+      };
+    }
+
+    return stats;
+  }
+
+  /**
+   * Get the memory system for direct access
+   */
+  getMemory(): MemorySystem {
+    return this.memory;
+  }
+
+  /**
+   * Get the knowledge bank for direct access (null if not enabled)
+   */
+  getKnowledgeBank(): import('./memory/knowledge-bank.js').KnowledgeBank | null {
+    return this.memory.knowledgeBank;
+  }
+
+  /**
+   * Get the learning pipeline for direct access
+   */
+  getLearning(): LearningPipeline {
+    return this.learning;
+  }
+
+  /**
+   * Get the skill library for direct access
+   */
+  getSkillLibrary(): SkillLibrary | null {
+    return this.skillLibrary;
+  }
+
+  /**
+   * Get the skill-tree storage adapter (null if not enabled)
+   */
+  getSkillTreeStorage(): SqliteStorageAdapter | null {
+    return this.skillTreeStorage;
+  }
+
+  /**
+   * Get the MCP server for direct access
+   */
+  getMCPServer(): PlaybookMCPServer | null {
+    return this.mcpServer;
+  }
+
+  /**
+   * Start the MCP server for playbook access
+   */
+  async startMCPServer(): Promise<void> {
+    if (!this.memory.playbooks) {
+      throw new Error('Playbook library not available. Initialize Atlas first.');
+    }
+
+    if (this.mcpServer) {
+      return; // Already started
+    }
+
+    this.mcpServer = createPlaybookMCPServer(
+      this.memory.playbooks,
+      this.skillLibrary ?? undefined,
+      this.config.mcp
+    );
+  }
+
+  /**
+   * Stop the MCP server
+   */
+  async stopMCPServer(): Promise<void> {
+    if (this.mcpServer) {
+      this.mcpServer = null;
+    }
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(config: Partial<AtlasConfig>): void {
+    if (config.learning) {
+      this.learning.updateConfig(config.learning);
+    }
+    if (config.router) {
+      this.router.updateConfig(config.router);
+    }
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Infer playbook usage via workspace template when taskRunner available,
+   * otherwise fall back to heuristic.
+   */
+  private async inferPlaybookUsage(
+    trajectory: Trajectory,
+    injectedPlaybooks: Playbook[],
+  ): Promise<import('./learning/usage-inference.js').PlaybookUsageResult[]> {
+    if (this.taskRunner && injectedPlaybooks.length > 0) {
+      try {
+        const result = await this.taskRunner.run(usageInferenceTemplate, {
+          trajectory,
+          injectedPlaybooks,
+        });
+        return result.output;
+      } catch (error) {
+        console.error(
+          'Workspace-based usage inference failed, falling back to heuristic:',
+          error instanceof Error ? error.message : error
+        );
+      }
+    }
+
+    // Heuristic fallback
+    if (this.usageInference) {
+      return this.usageInference.inferUsage(trajectory, injectedPlaybooks);
+    }
+    return [];
+  }
+
+  /**
+   * Reflect on execution via workspace template when taskRunner available,
+   * otherwise fall back to MetaLearner's built-in heuristic reflection.
+   */
+  private async reflectOnExecution(
+    trajectory: Trajectory,
+    routing: RoutingDecision,
+  ): Promise<void> {
+    if (!this.metaLearner) return;
+
+    const routingInfo = {
+      strategy: routing.strategy,
+      confidence: routing.confidence,
+      estimatedBudget: routing.estimatedBudget,
+      reasoning: routing.reasoning,
+    };
+    const playbookMatches = routing.memoryContext.playbooks;
+
+    if (this.taskRunner) {
+      try {
+        const result = await this.taskRunner.run(metaReflectionTemplate, {
+          trajectory,
+          routingDecision: routingInfo,
+          playbooksUsed: playbookMatches,
+        });
+
+        // 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(
+          result.output,
+          trajectory.id,
+          routingInfo,
+          playbookIds,
+          actualEffort,
+        );
+        return;
+      } catch (error) {
+        console.error(
+          'Workspace-based meta-reflection failed, falling back to heuristic:',
+          error instanceof Error ? error.message : error
+        );
+      }
+    }
+
+    // Heuristic fallback
+    await this.metaLearner.generateReflection(
+      trajectory,
+      routingInfo,
+      playbookMatches,
+    );
+  }
+
+  /**
+   * Get the meta learner for direct access
+   */
+  getMetaLearner(): MetaLearner | null {
+    return this.metaLearner;
+  }
+
+  /**
+   * Get the effectiveness tracker for direct access
+   */
+  getEffectivenessTracker(): LearningEffectivenessTracker | null {
+    return this.effectivenessTracker;
+  }
+
+  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 team learning pipeline
+    if (this.teamLearning && this.teamLearning.getAccumulatedCount() > 0) {
+      await this.teamLearning.runBatchLearning();
+    }
+
+    // Close effectiveness tracker
+    if (this.effectivenessTracker) {
+      await this.effectivenessTracker.close();
+    }
+
+    // Close skill-tree storage
+    if (this.skillTreeStorage) {
+      this.skillTreeStorage.close();
+    }
+
+    // Close memory system
+    await this.memory.close();
+  }
+}
+
+/**
+ * Create an Atlas instance
+ */
+export function createAtlas(config?: Partial<AtlasConfig>): Atlas {
+  return new Atlas(config);
+}
+
+/**
+ * Create an Atlas instance with an LLM provider
+ * @deprecated Use createAtlasWithAgents() for real action execution
+ */
+export function createAtlasWithProvider(
+  provider: LLMProvider,
+  config?: Partial<AtlasConfig>
+): Atlas {
+  const atlas = new Atlas(config);
+  atlas.setProvider(provider);
+  return atlas;
+}
+
+/**
+ * Create an Atlas instance with AgentManager backends
+ * This is the recommended way to create Atlas for production use
+ */
+export function createAtlasWithAgents(
+  backends: AgentBackend[],
+  config?: Partial<AtlasConfig>,
+  options?: { delegate?: AgentDelegate }
+): Atlas {
+  const atlas = new Atlas(config);
+  atlas.setAgentManager(backends, options);
+  return atlas;
+}