agentic-flow 2.0.0-alpha → 2.0.1-alpha.2

package/dist/reasoningbank/AdvancedMemory.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Advanced Memory System - Full Implementation for v1.7.1
+ *
+ * Provides high-level memory operations on top of HybridReasoningBank:
+ * - Auto-consolidation (patterns → skills) using NightlyLearner
+ * - Episodic replay (learn from failures)
+ * - Causal reasoning (what-if analysis)
+ * - Skill composition (combine learned skills)
+ *
+ * @example
+ * ```typescript
+ * import { AdvancedMemorySystem } from 'agentic-flow/reasoningbank';
+ *
+ * const memory = new AdvancedMemorySystem();
+ *
+ * // Auto-consolidate patterns into skills
+ * const result = await memory.autoConsolidate({ minUses: 3, minSuccessRate: 0.7 });
+ *
+ * // Learn from failures
+ * const failures = await memory.replayFailures('authentication', 5);
+ *
+ * // Causal what-if analysis
+ * const insight = await memory.whatIfAnalysis('add caching');
+ * ```
+ */
+export interface FailureAnalysis {
+    critique: string;
+    whatWentWrong: string[];
+    howToFix: string[];
+    similarFailures: number;
+}
+export interface SkillComposition {
+    availableSkills: any[];
+    compositionPlan: string;
+    expectedSuccessRate: number;
+}
+export interface ConsolidationResult {
+    skillsCreated: number;
+    causalEdgesCreated: number;
+    patternsAnalyzed: number;
+    executionTimeMs: number;
+    recommendations: string[];
+}
+export declare class AdvancedMemorySystem {
+    private reasoning;
+    private learner;
+    private pool;
+    constructor(options?: {
+        preferWasm?: boolean;
+    });
+    /**
+     * Auto-consolidate successful patterns into skills
+     *
+     * Uses NightlyLearner to:
+     * 1. Discover causal edges from episode patterns
+     * 2. Complete A/B experiments
+     * 3. Calculate uplift for experiments
+     * 4. Prune low-confidence edges
+     * 5. Consolidate high-performing patterns into skills
+     */
+    autoConsolidate(options?: {
+        minUses?: number;
+        minSuccessRate?: number;
+        lookbackDays?: number;
+        dryRun?: boolean;
+    }): Promise<ConsolidationResult>;
+    /**
+     * Learn from past failures with episodic replay
+     *
+     * Retrieves failed attempts, extracts lessons, and provides recommendations
+     */
+    replayFailures(task: string, k?: number): Promise<FailureAnalysis[]>;
+    /**
+     * Extract critique from failure pattern
+     */
+    private extractCritique;
+    /**
+     * Analyze what went wrong in a failure
+     */
+    private analyzeFailure;
+    /**
+     * Generate fix recommendations
+     */
+    private generateFixes;
+    /**
+     * What-if causal analysis
+     *
+     * Analyzes potential outcomes of taking an action based on causal evidence
+     */
+    whatIfAnalysis(action: string): Promise<{
+        action: string;
+        avgReward: number;
+        avgUplift: number;
+        confidence: number;
+        evidenceCount: number;
+        recommendation: 'DO_IT' | 'AVOID' | 'NEUTRAL';
+        expectedImpact: string;
+    }>;
+    /**
+     * Compose multiple skills for a complex task
+     *
+     * Finds relevant skills and creates an execution plan
+     */
+    composeSkills(task: string, k?: number): Promise<SkillComposition>;
+    /**
+     * Run automated learning cycle
+     *
+     * Discovers causal edges, consolidates skills, and optimizes performance
+     */
+    runLearningCycle(): Promise<ConsolidationResult>;
+    /**
+     * Get comprehensive memory statistics
+     */
+    getStats(): {
+        reasoningBank: any;
+        learner: string;
+        memoryPool: any;
+    };
+}
+//# sourceMappingURL=AdvancedMemory.d.ts.map

package/dist/reasoningbank/HybridBackend.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Hybrid ReasoningBank Backend - Full Implementation for v1.7.1
+ *
+ * Combines Rust WASM (compute) + AgentDB TypeScript (storage) for optimal performance:
+ * - WASM: 10x faster similarity computation
+ * - AgentDB: Persistent SQLite storage with frontier memory
+ * - CausalRecall: Utility-based reranking with causal uplift
+ * - Automatic backend selection based on task requirements
+ *
+ * @example
+ * ```typescript
+ * import { HybridReasoningBank } from 'agentic-flow/reasoningbank';
+ *
+ * const rb = new HybridReasoningBank({ preferWasm: true });
+ * await rb.storePattern({ task: '...', success: true, reward: 0.95 });
+ * const patterns = await rb.retrievePatterns('similar task', { k: 5 });
+ * const strategy = await rb.learnStrategy('API optimization');
+ * ```
+ */
+export interface PatternData {
+    sessionId: string;
+    task: string;
+    input?: string;
+    output?: string;
+    critique?: string;
+    success: boolean;
+    reward: number;
+    latencyMs?: number;
+    tokensUsed?: number;
+}
+export interface RetrievalOptions {
+    k?: number;
+    minReward?: number;
+    onlySuccesses?: boolean;
+    onlyFailures?: boolean;
+}
+export interface CausalInsight {
+    action: string;
+    avgReward: number;
+    avgUplift: number;
+    confidence: number;
+    evidenceCount: number;
+    recommendation: 'DO_IT' | 'AVOID' | 'NEUTRAL';
+}
+export declare class HybridReasoningBank {
+    private memory;
+    private reflexion;
+    private skills;
+    private causalRecall;
+    private causalGraph;
+    private useWasm;
+    private wasmModule;
+    constructor(options?: {
+        preferWasm?: boolean;
+    });
+    private loadWasmModule;
+    /**
+     * Store a reasoning pattern
+     */
+    storePattern(pattern: PatternData): Promise<number>;
+    /**
+     * Retrieve similar patterns with optional WASM acceleration
+     */
+    retrievePatterns(query: string, options?: RetrievalOptions): Promise<any[]>;
+    /**
+     * Learn optimal strategy for a task
+     *
+     * Combines pattern retrieval with causal analysis to provide evidence-based recommendations
+     */
+    learnStrategy(task: string): Promise<{
+        patterns: any[];
+        causality: CausalInsight;
+        confidence: number;
+        recommendation: string;
+    }>;
+    /**
+     * Auto-consolidate patterns into skills
+     */
+    autoConsolidate(minUses?: number, minSuccessRate?: number, lookbackDays?: number): Promise<{
+        skillsCreated: number;
+    }>;
+    /**
+     * What-if causal analysis
+     */
+    whatIfAnalysis(action: string): Promise<CausalInsight>;
+    /**
+     * Search for relevant skills
+     */
+    searchSkills(taskType: string, k?: number): Promise<any[]>;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        causalRecall: any;
+        reflexion: any;
+        skills: number;
+    };
+}
+//# sourceMappingURL=HybridBackend.d.ts.map

package/dist/reasoningbank/backend-selector.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Backend Selection Helper for ReasoningBank
+ *
+ * Automatically selects the optimal ReasoningBank backend based on runtime environment.
+ *
+ * Usage:
+ * ```typescript
+ * import { createOptimalReasoningBank, getRecommendedBackend } from 'agentic-flow/reasoningbank/backend-selector';
+ *
+ * // Automatic backend selection
+ * const rb = await createOptimalReasoningBank('my-db');
+ *
+ * // Manual check
+ * const backend = getRecommendedBackend();
+ * console.log(`Using ${backend} backend`);
+ * ```
+ */
+/**
+ * Detect runtime environment and recommend optimal backend
+ *
+ * @returns 'nodejs' for Node.js/Deno environments, 'wasm' for browsers
+ */
+export declare function getRecommendedBackend(): 'nodejs' | 'wasm';
+/**
+ * Check if IndexedDB is available (browser environment)
+ */
+export declare function hasIndexedDB(): boolean;
+/**
+ * Check if SQLite native module is available (Node.js)
+ */
+export declare function hasSQLite(): boolean;
+/**
+ * Create ReasoningBank instance with optimal backend for current environment
+ *
+ * @param dbName - Database name (used differently by each backend)
+ * @param options - Additional configuration options
+ * @returns ReasoningBank instance using optimal backend
+ *
+ * @example
+ * ```typescript
+ * // Node.js: Creates SQLite database at .swarm/my-app.db
+ * const rb = await createOptimalReasoningBank('my-app');
+ *
+ * // Browser: Creates IndexedDB database named 'my-app'
+ * const rb = await createOptimalReasoningBank('my-app');
+ * ```
+ */
+export declare function createOptimalReasoningBank(dbName?: string, options?: {
+    /** Force specific backend (overrides auto-detection) */
+    forceBackend?: 'nodejs' | 'wasm';
+    /** Custom database path (Node.js only) */
+    dbPath?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}): Promise<any>;
+/**
+ * Get backend information and capabilities
+ */
+export declare function getBackendInfo(): {
+    backend: "wasm" | "nodejs";
+    environment: string;
+    features: {
+        persistent: boolean;
+        sqlite: boolean;
+        indexeddb: boolean;
+        wasm: boolean;
+    };
+    storage: string;
+};
+/**
+ * Validate environment and warn about limitations
+ */
+export declare function validateEnvironment(): {
+    valid: boolean;
+    warnings: string[];
+    backend: 'nodejs' | 'wasm';
+};
+export { validateEnvironment as checkEnvironment };
+//# sourceMappingURL=backend-selector.d.ts.map

package/dist/reasoningbank/benchmark.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * ReasoningBank Performance Benchmark Suite
+ *
+ * Benchmarks:
+ * 1. Database Operations (CRUD, queries)
+ * 2. Retrieval Algorithm (top-k, MMR, scoring)
+ * 3. Embedding Operations (storage, similarity)
+ * 4. Scalability (10, 100, 1000, 10000 memories)
+ * 5. Configuration Loading
+ * 6. View Queries
+ */
+export {};
+//# sourceMappingURL=benchmark.d.ts.map

package/dist/reasoningbank/config/reasoningbank-types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * TypeScript configuration types for ReasoningBank
+ */
+export interface ReasoningBankConfig {
+    retrieve: {
+        k: number;
+        alpha: number;
+        beta: number;
+        gamma: number;
+        delta: number;
+        recency_half_life_days: number;
+        min_score: number;
+    };
+    judge: {
+        model: string;
+        max_tokens: number;
+        confidence_threshold: number;
+    };
+    distill: {
+        model: string;
+        max_tokens: number;
+        temperature: number;
+    };
+    consolidate: {
+        duplicate_threshold: number;
+        contradiction_threshold: number;
+        trigger_threshold: number;
+        prune_age_days: number;
+        prune_min_confidence: number;
+        min_confidence_keep: number;
+    };
+    matts: {
+        parallel_k: number;
+        sequential_k: number;
+        sequential_r: number;
+        sequential_stop_on_success: boolean;
+        confidence_boost: number;
+    };
+    embeddings: {
+        provider: 'claude' | 'openai';
+        model: string;
+        dims: number;
+        dimensions: number;
+        cache_ttl_seconds: number;
+    };
+    governance: {
+        scrub_pii: boolean;
+        pii_scrubber: boolean;
+        tenant_scoped: boolean;
+    };
+    features?: {
+        enable_pre_task_hook?: boolean;
+        enable_post_task_hook?: boolean;
+        enable_matts_parallel?: boolean;
+    };
+}
+//# sourceMappingURL=reasoningbank-types.d.ts.map

package/dist/reasoningbank/config/reasoningbank-types.ts

@@ -0,0 +1,57 @@
+/**
+ * TypeScript configuration types for ReasoningBank
+ */
+
+export interface ReasoningBankConfig {
+  retrieve: {
+    k: number;
+    alpha: number;
+    beta: number;
+    gamma: number;
+    delta: number;
+    recency_half_life_days: number;
+    min_score: number;
+  };
+  judge: {
+    model: string;
+    max_tokens: number;
+    confidence_threshold: number;
+  };
+  distill: {
+    model: string;
+    max_tokens: number;
+    temperature: number;
+  };
+  consolidate: {
+    duplicate_threshold: number;
+    contradiction_threshold: number;
+    trigger_threshold: number;
+    prune_age_days: number;
+    prune_min_confidence: number;
+    min_confidence_keep: number;
+  };
+  matts: {
+    parallel_k: number;
+    sequential_k: number;
+    sequential_r: number;
+    sequential_stop_on_success: boolean;
+    confidence_boost: number;
+  };
+  embeddings: {
+    provider: 'claude' | 'openai';
+    model: string;
+    dims: number;
+    dimensions: number;
+    cache_ttl_seconds: number;
+  };
+  governance: {
+    scrub_pii: boolean;
+    pii_scrubber: boolean;
+    tenant_scoped: boolean;
+  };
+  features?: {
+    enable_pre_task_hook?: boolean;
+    enable_post_task_hook?: boolean;
+    enable_matts_parallel?: boolean;
+  };
+}

package/dist/reasoningbank/core/consolidate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Memory Consolidation
+ * Algorithm 4 from ReasoningBank paper: Dedup, Contradict, Prune
+ */
+export interface ConsolidationResult {
+    itemsProcessed: number;
+    duplicatesFound: number;
+    contradictionsFound: number;
+    itemsPruned: number;
+    durationMs: number;
+}
+/**
+ * Run consolidation: deduplicate, detect contradictions, prune old memories
+ */
+export declare function consolidate(): Promise<ConsolidationResult>;
+/**
+ * Check if consolidation should run
+ * Returns true if threshold of new memories is reached
+ */
+export declare function shouldConsolidate(): boolean;
+//# sourceMappingURL=consolidate.d.ts.map

package/dist/reasoningbank/core/distill.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Memory Distillation from trajectories
+ * Algorithm 3 from ReasoningBank paper
+ */
+import type { Trajectory } from '../db/schema.js';
+import type { Verdict } from './judge.js';
+export interface DistilledMemory {
+    title: string;
+    description: string;
+    content: string;
+    tags: string[];
+    domain?: string;
+}
+/**
+ * Distill memories from a trajectory
+ */
+export declare function distillMemories(trajectory: Trajectory, verdict: Verdict, query: string, options?: {
+    taskId?: string;
+    agentId?: string;
+    domain?: string;
+}): Promise<string[]>;
+//# sourceMappingURL=distill.d.ts.map

package/dist/reasoningbank/core/judge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * LLM-as-Judge for trajectory evaluation
+ * Algorithm 2 from ReasoningBank paper
+ */
+import type { Trajectory } from '../db/schema.js';
+export interface Verdict {
+    label: 'Success' | 'Failure';
+    confidence: number;
+    reasons: string[];
+}
+/**
+ * Judge a task trajectory using LLM evaluation
+ */
+export declare function judgeTrajectory(trajectory: Trajectory, query: string, options?: {
+    useCache?: boolean;
+}): Promise<Verdict>;
+//# sourceMappingURL=judge.d.ts.map

package/dist/reasoningbank/core/matts.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MaTTS: Memory-aware Test-Time Scaling
+ * Algorithm 5 from ReasoningBank paper
+ *
+ * Two modes:
+ * - Parallel: k independent rollouts with self-contrast aggregation
+ * - Sequential: r iterative refinements with check-and-correct
+ */
+import type { Trajectory } from '../db/schema.js';
+export interface MattsResult {
+    runId: string;
+    mode: 'parallel' | 'sequential';
+    k: number;
+    trajectories: Array<{
+        id: string;
+        verdict: {
+            label: string;
+            confidence: number;
+        };
+        trajectory: Trajectory;
+    }>;
+    aggregatedMemories: string[];
+    successRate: number;
+    duration: number;
+}
+/**
+ * Run MaTTS in parallel mode
+ * Execute k independent rollouts and aggregate via self-contrast
+ */
+export declare function mattsParallel(taskFn: () => Promise<Trajectory>, query: string, options?: {
+    k?: number;
+    taskId?: string;
+    agentId?: string;
+    domain?: string;
+}): Promise<MattsResult>;
+/**
+ * Run MaTTS in sequential mode
+ * Iterative refinement with check-and-correct
+ */
+export declare function mattsSequential(taskFn: (memories: any[]) => Promise<Trajectory>, query: string, options?: {
+    r?: number;
+    taskId?: string;
+    agentId?: string;
+    domain?: string;
+}): Promise<MattsResult>;
+//# sourceMappingURL=matts.d.ts.map

package/dist/reasoningbank/core/retrieve.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Memory Retrieval with MMR diversity
+ * Algorithm 1 from ReasoningBank paper
+ */
+export interface RetrievedMemory {
+    id: string;
+    title: string;
+    description: string;
+    content: string;
+    score: number;
+    components: {
+        similarity: number;
+        recency: number;
+        reliability: number;
+    };
+}
+/**
+ * Retrieve top-k memories with MMR diversity
+ *
+ * Scoring formula: score = α·sim + β·recency + γ·reliability
+ * Where:
+ * - sim: cosine similarity to query
+ * - recency: exp(-age_days / half_life)
+ * - reliability: min(confidence, 1.0)
+ */
+export declare function retrieveMemories(query: string, options?: {
+    k?: number;
+    domain?: string;
+    agent?: string;
+}): Promise<RetrievedMemory[]>;
+/**
+ * Format memories for injection into system prompt
+ */
+export declare function formatMemoriesForPrompt(memories: RetrievedMemory[]): string;
+//# sourceMappingURL=retrieve.d.ts.map

package/dist/reasoningbank/db/queries.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Database queries for ReasoningBank
+ * Operates on Claude Flow's memory.db at .swarm/memory.db
+ */
+import Database from 'better-sqlite3';
+import type { ReasoningMemory, PatternEmbedding, TaskTrajectory, MattsRun } from './schema.js';
+/**
+ * Run database migrations (create tables)
+ */
+export declare function runMigrations(): Promise<void>;
+/**
+ * Get database connection (singleton)
+ */
+export declare function getDb(): Database.Database;
+/**
+ * Fetch reasoning memory candidates for retrieval
+ */
+export declare function fetchMemoryCandidates(options: {
+    domain?: string;
+    agent?: string;
+    minConfidence?: number;
+}): Array<ReasoningMemory & {
+    embedding: Float32Array;
+    age_days: number;
+}>;
+/**
+ * Store a new reasoning memory
+ */
+export declare function upsertMemory(memory: Omit<ReasoningMemory, 'created_at' | 'last_used'>): string;
+/**
+ * Store embedding for a memory
+ */
+export declare function upsertEmbedding(embedding: PatternEmbedding): void;
+/**
+ * Increment usage count for a memory
+ */
+export declare function incrementUsage(memoryId: string): void;
+/**
+ * Store task trajectory
+ */
+export declare function storeTrajectory(trajectory: Omit<TaskTrajectory, 'created_at'>): void;
+/**
+ * Store MaTTS run
+ */
+export declare function storeMattsRun(run: Omit<MattsRun, 'created_at'>): void;
+/**
+ * Log performance metric
+ */
+export declare function logMetric(name: string, value: number): void;
+/**
+ * Count new memories since last consolidation
+ */
+export declare function countNewMemoriesSinceConsolidation(): number;
+/**
+ * Get all active reasoning memories
+ */
+export declare function getAllActiveMemories(): ReasoningMemory[];
+/**
+ * Store memory link (relationship)
+ */
+export declare function storeLink(srcId: string, dstId: string, relation: 'entails' | 'contradicts' | 'refines' | 'duplicate_of', weight: number): void;
+/**
+ * Get contradictions for a memory
+ */
+export declare function getContradictions(memoryId: string): string[];
+/**
+ * Store consolidation run
+ */
+export declare function storeConsolidationRun(run: {
+    run_id: string;
+    items_processed: number;
+    duplicates_found: number;
+    contradictions_found: number;
+    items_pruned: number;
+    duration_ms: number;
+}): void;
+/**
+ * Prune old, unused memories
+ */
+export declare function pruneOldMemories(options: {
+    maxAgeDays: number;
+    minConfidence: number;
+}): number;
+/**
+ * Close database connection
+ */
+export declare function closeDb(): void;
+//# sourceMappingURL=queries.d.ts.map