@arcanea/guardian-evolution 0.1.0

package/dist/reasoning-bank.d.ts

@@ -0,0 +1,259 @@
+/**
+ * ReasoningBank Integration with AgentDB
+ *
+ * Implements the 4-step learning pipeline with real vector storage:
+ * 1. RETRIEVE - Top-k memory injection with MMR diversity (using AgentDB HNSW)
+ * 2. JUDGE - LLM-as-judge trajectory evaluation
+ * 3. DISTILL - Extract strategy memories from trajectories
+ * 4. CONSOLIDATE - Dedup, detect contradictions, prune old patterns
+ *
+ * Performance Targets:
+ * - Retrieval: <10ms with AgentDB HNSW (150x faster than brute-force)
+ * - Learning step: <10ms
+ * - Consolidation: <100ms
+ *
+ * @module reasoning-bank
+ */
+import type { Trajectory, TrajectoryVerdict, DistilledMemory, Pattern, NeuralEventListener } from './types.js';
+/**
+ * Configuration for ReasoningBank
+ */
+export interface ReasoningBankConfig {
+    /** Maximum number of trajectories to store */
+    maxTrajectories: number;
+    /** Minimum quality threshold for distillation */
+    distillationThreshold: number;
+    /** Number of similar memories to retrieve */
+    retrievalK: number;
+    /** Diversity factor for MMR (0-1) */
+    mmrLambda: number;
+    /** Maximum age of patterns in days */
+    maxPatternAgeDays: number;
+    /** Similarity threshold for deduplication */
+    dedupThreshold: number;
+    /** Enable contradiction detection */
+    enableContradictionDetection: boolean;
+    /** Database path for persistent storage */
+    dbPath?: string;
+    /** Vector dimension for embeddings */
+    vectorDimension: number;
+    /** Namespace for AgentDB storage */
+    namespace: string;
+    /** Enable AgentDB vector storage */
+    enableAgentDB: boolean;
+}
+/**
+ * Retrieval result with diversity scoring
+ */
+export interface RetrievalResult {
+    memory: DistilledMemory;
+    relevanceScore: number;
+    diversityScore: number;
+    combinedScore: number;
+}
+/**
+ * Consolidation result
+ */
+export interface ConsolidationResult {
+    removedDuplicates: number;
+    contradictionsDetected: number;
+    prunedPatterns: number;
+    mergedPatterns: number;
+}
+/**
+ * ReasoningBank - Trajectory storage and learning pipeline with AgentDB
+ *
+ * This class implements a complete learning pipeline for AI agents:
+ * - Store and retrieve trajectories using vector similarity
+ * - Judge trajectory quality using rule-based evaluation
+ * - Distill successful trajectories into reusable patterns
+ * - Consolidate patterns to remove duplicates and contradictions
+ */
+export declare class ReasoningBank {
+    private config;
+    private trajectories;
+    private memories;
+    private patterns;
+    private eventListeners;
+    private agentdb;
+    private agentdbAvailable;
+    private initialized;
+    private retrievalCount;
+    private totalRetrievalTime;
+    private distillationCount;
+    private totalDistillationTime;
+    private judgeCount;
+    private totalJudgeTime;
+    private consolidationCount;
+    private totalConsolidationTime;
+    constructor(config?: Partial<ReasoningBankConfig>);
+    /**
+     * Initialize ReasoningBank with AgentDB
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown and cleanup resources
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Retrieve relevant memories using Maximal Marginal Relevance (MMR)
+     *
+     * Uses AgentDB HNSW index for 150x faster retrieval when available.
+     *
+     * @param queryEmbedding - Query vector for similarity search
+     * @param k - Number of results to return (default: config.retrievalK)
+     * @returns Retrieval results with relevance and diversity scores
+     */
+    retrieve(queryEmbedding: Float32Array, k?: number): Promise<RetrievalResult[]>;
+    /**
+     * Search for similar memories by content string
+     *
+     * @param content - Text content to search for
+     * @param k - Number of results
+     * @returns Retrieval results
+     */
+    retrieveByContent(content: string, k?: number): Promise<RetrievalResult[]>;
+    /**
+     * Judge a trajectory and produce a verdict
+     *
+     * Uses rule-based evaluation to assess trajectory quality.
+     * In production, this could be enhanced with LLM-as-judge.
+     *
+     * @param trajectory - Completed trajectory to judge
+     * @returns Verdict with success status and analysis
+     */
+    judge(trajectory: Trajectory): Promise<TrajectoryVerdict>;
+    /**
+     * Distill a trajectory into a reusable memory
+     *
+     * @param trajectory - Trajectory to distill
+     * @returns Distilled memory or null if quality too low
+     */
+    distill(trajectory: Trajectory): Promise<DistilledMemory | null>;
+    /**
+     * Batch distill multiple trajectories
+     *
+     * @param trajectories - Array of trajectories to distill
+     * @returns Array of distilled memories (excludes nulls)
+     */
+    distillBatch(trajectories: Trajectory[]): Promise<DistilledMemory[]>;
+    /**
+     * Consolidate memories: deduplicate, detect contradictions, prune old
+     *
+     * @returns Consolidation statistics
+     */
+    consolidate(): Promise<ConsolidationResult>;
+    /**
+     * Convert a distilled memory to a pattern
+     */
+    memoryToPattern(memory: DistilledMemory): Pattern;
+    /**
+     * Evolve a pattern based on new experience
+     */
+    evolvePattern(patternId: string, newExperience: Trajectory): void;
+    /**
+     * Get all patterns
+     */
+    getPatterns(): Pattern[];
+    /**
+     * Find patterns matching a query
+     */
+    findPatterns(queryEmbedding: Float32Array, k?: number): Promise<Pattern[]>;
+    /**
+     * Store a trajectory
+     */
+    storeTrajectory(trajectory: Trajectory): void;
+    /**
+     * Get trajectory by ID
+     */
+    getTrajectory(trajectoryId: string): Trajectory | undefined;
+    /**
+     * Get all trajectories
+     */
+    getTrajectories(): Trajectory[];
+    /**
+     * Get successful trajectories
+     */
+    getSuccessfulTrajectories(): Trajectory[];
+    /**
+     * Get failed trajectories
+     */
+    getFailedTrajectories(): Trajectory[];
+    /**
+     * Get ReasoningBank statistics
+     */
+    getStats(): Record<string, number>;
+    /**
+     * Get detailed metrics for hooks
+     */
+    getDetailedMetrics(): {
+        routing: {
+            totalRoutes: number;
+            avgConfidence: number;
+            topAgents: Array<{
+                agent: string;
+                count: number;
+                successRate: number;
+            }>;
+        };
+        edits: {
+            totalEdits: number;
+            successRate: number;
+            commonPatterns: string[];
+        };
+        commands: {
+            totalCommands: number;
+            successRate: number;
+            avgExecutionTime: number;
+            commonCommands: string[];
+        };
+    };
+    addEventListener(listener: NeuralEventListener): void;
+    removeEventListener(listener: NeuralEventListener): void;
+    private emitEvent;
+    /**
+     * Store memory in AgentDB for vector search
+     */
+    private storeInAgentDB;
+    /**
+     * Search using AgentDB HNSW index
+     */
+    private searchWithAgentDB;
+    /**
+     * Delete from AgentDB
+     */
+    private deleteFromAgentDB;
+    private cosineSimilarity;
+    private computeContentSimilarity;
+    private computeMaxSimilarity;
+    private analyzeSteps;
+    private identifyStrengths;
+    private identifyWeaknesses;
+    private generateImprovements;
+    private computeRelevanceScore;
+    private computeConfidence;
+    private extractStrategy;
+    private extractKeyLearnings;
+    private computeAggregateEmbedding;
+    private deduplicateMemories;
+    private detectContradictions;
+    private pruneOldPatterns;
+    private mergePatterns;
+    private pruneTrajectories;
+    private generatePatternName;
+    private inferDomain;
+    private determineEvolutionType;
+    /**
+     * Check if AgentDB is available and initialized
+     */
+    isAgentDBAvailable(): boolean;
+}
+/**
+ * Factory function for creating ReasoningBank
+ */
+export declare function createReasoningBank(config?: Partial<ReasoningBankConfig>): ReasoningBank;
+/**
+ * Create and initialize a ReasoningBank instance
+ */
+export declare function createInitializedReasoningBank(config?: Partial<ReasoningBankConfig>): Promise<ReasoningBank>;
+//# sourceMappingURL=reasoning-bank.d.ts.map

package/dist/reasoning-bank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-bank.d.ts","sourceRoot":"","sources":["../src/reasoning-bank.ts"],"names":[],"mappings":"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"}