agentic-flow 2.0.6 → 3.0.0-alpha.1

package/dist/packages/agentdb/src/controllers/CausalRecall.d.ts

@@ -0,0 +1,135 @@
+/**
+ * CausalRecall - Utility-Based Reranking + Certificate Issuer
+ *
+ * Combines:
+ * 1. Vector similarity search
+ * 2. Causal uplift from CausalMemoryGraph
+ * 3. Utility-based reranking: U = α*similarity + β*uplift − γ*latencyCost
+ * 4. Automatic certificate issuance via ExplainableRecall
+ *
+ * This is the main entry point for production retrieval with:
+ * - Causal-aware ranking
+ * - Explainable provenance
+ * - Policy compliance
+ */
+type Database = any;
+import { RecallCertificate } from './ExplainableRecall.js';
+import { EmbeddingService } from './EmbeddingService.js';
+import type { VectorBackend } from '../backends/VectorBackend.js';
+export interface RerankConfig {
+    alpha: number;
+    beta: number;
+    gamma: number;
+    minConfidence?: number;
+}
+export interface RerankCandidate {
+    id: string;
+    type: 'episode' | 'skill' | 'note' | 'fact';
+    content: string;
+    similarity: number;
+    uplift?: number;
+    causalConfidence?: number;
+    latencyMs?: number;
+    utilityScore: number;
+    rank: number;
+}
+export interface CausalRecallResult {
+    candidates: RerankCandidate[];
+    certificate: RecallCertificate;
+    queryId: string;
+    totalLatencyMs: number;
+    metrics: {
+        vectorSearchMs: number;
+        causalLookupMs: number;
+        rerankMs: number;
+        certificateMs: number;
+    };
+}
+export declare class CausalRecall {
+    private config;
+    private db;
+    private causalGraph;
+    private explainableRecall;
+    private embedder;
+    private vectorBackend?;
+    constructor(db: Database, embedder: EmbeddingService, vectorBackend?: VectorBackend, config?: RerankConfig);
+    /**
+     * Main recall function with utility-based reranking and certificate issuance
+     *
+     * @param queryId Unique query identifier
+     * @param queryText Natural language query
+     * @param k Number of results to return (default: 12)
+     * @param requirements Optional list of requirements for completeness checking
+     * @param accessLevel Security access level for certificate
+     * @returns Reranked results with certificate
+     */
+    recall(queryId: string, queryText: string, k?: number, requirements?: string[], accessLevel?: 'public' | 'internal' | 'confidential' | 'restricted'): Promise<CausalRecallResult>;
+    /**
+     * Vector similarity search using cosine similarity
+     */
+    private vectorSearch;
+    /**
+     * Load causal edges for candidates
+     */
+    private loadCausalEdges;
+    /**
+     * Rerank by utility: U = α*similarity + β*uplift − γ*latencyCost
+     */
+    private rerankByUtility;
+    /**
+     * Issue certificate for the retrieval
+     */
+    private issueCertificate;
+    /**
+     * Extract requirements from query text (simple keyword extraction)
+     */
+    private extractRequirements;
+    /**
+     * Deserialize embedding from Buffer
+     */
+    private deserializeEmbedding;
+    /**
+     * Batch recall for multiple queries
+     */
+    batchRecall(queries: Array<{
+        queryId: string;
+        queryText: string;
+        k?: number;
+    }>, requirements?: string[], accessLevel?: 'public' | 'internal' | 'confidential' | 'restricted'): Promise<CausalRecallResult[]>;
+    /**
+     * Get recall statistics
+     */
+    getStats(): {
+        totalCausalEdges: number;
+        totalCertificates: number;
+        avgRedundancyRatio: number;
+        avgCompletenessScore: number;
+    };
+    /**
+     * Update rerank configuration
+     */
+    updateConfig(config: Partial<RerankConfig>): void;
+    /**
+     * Search for memories with semantic similarity and causal utility ranking
+     *
+     * @param params Search parameters
+     * @returns Array of ranked search results with similarity and causal uplift scores
+     */
+    search(params: {
+        query: string;
+        k?: number;
+        includeEvidence?: boolean;
+        alpha?: number;
+        beta?: number;
+        gamma?: number;
+    }): Promise<Array<{
+        id: number;
+        type: string;
+        content: string;
+        similarity: number;
+        causalUplift: number;
+        utilityScore: number;
+    }>>;
+}
+export {};
+//# sourceMappingURL=CausalRecall.d.ts.map

package/dist/packages/agentdb/src/controllers/CausalRecall.d.ts.map

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

package/dist/packages/agentdb/src/controllers/CausalRecall.js

@@ -0,0 +1,339 @@
+/**
+ * CausalRecall - Utility-Based Reranking + Certificate Issuer
+ *
+ * Combines:
+ * 1. Vector similarity search
+ * 2. Causal uplift from CausalMemoryGraph
+ * 3. Utility-based reranking: U = α*similarity + β*uplift − γ*latencyCost
+ * 4. Automatic certificate issuance via ExplainableRecall
+ *
+ * This is the main entry point for production retrieval with:
+ * - Causal-aware ranking
+ * - Explainable provenance
+ * - Policy compliance
+ */
+import { CausalMemoryGraph } from './CausalMemoryGraph.js';
+import { ExplainableRecall } from './ExplainableRecall.js';
+import { cosineSimilarity } from '../utils/vector-math.js';
+export class CausalRecall {
+    config;
+    db;
+    causalGraph;
+    explainableRecall;
+    embedder;
+    vectorBackend;
+    constructor(db, embedder, vectorBackend, config = {
+        alpha: 0.7,
+        beta: 0.2,
+        gamma: 0.1,
+        minConfidence: 0.6
+    }) {
+        this.config = config;
+        this.db = db;
+        this.embedder = embedder;
+        this.vectorBackend = vectorBackend;
+        this.causalGraph = new CausalMemoryGraph(db);
+        this.explainableRecall = new ExplainableRecall(db);
+    }
+    /**
+     * Main recall function with utility-based reranking and certificate issuance
+     *
+     * @param queryId Unique query identifier
+     * @param queryText Natural language query
+     * @param k Number of results to return (default: 12)
+     * @param requirements Optional list of requirements for completeness checking
+     * @param accessLevel Security access level for certificate
+     * @returns Reranked results with certificate
+     */
+    async recall(queryId, queryText, k = 12, requirements, accessLevel = 'internal') {
+        const startTime = Date.now();
+        const metrics = {
+            vectorSearchMs: 0,
+            causalLookupMs: 0,
+            rerankMs: 0,
+            certificateMs: 0
+        };
+        // Step 1: Vector similarity search
+        const vectorStart = Date.now();
+        const queryEmbedding = await this.embedder.embed(queryText);
+        const candidates = await this.vectorSearch(queryEmbedding, k * 2); // Fetch 2k for reranking
+        metrics.vectorSearchMs = Date.now() - vectorStart;
+        // Step 2: Load causal edges for candidates
+        const causalStart = Date.now();
+        const causalEdges = await this.loadCausalEdges(candidates.map(c => c.id));
+        metrics.causalLookupMs = Date.now() - causalStart;
+        // Step 3: Rerank by utility
+        const rerankStart = Date.now();
+        const reranked = this.rerankByUtility(candidates, causalEdges);
+        const topK = reranked.slice(0, k);
+        metrics.rerankMs = Date.now() - rerankStart;
+        // Step 4: Issue certificate
+        const certStart = Date.now();
+        const certificate = await this.issueCertificate({
+            queryId,
+            queryText,
+            candidates: topK,
+            requirements: requirements || this.extractRequirements(queryText),
+            accessLevel
+        });
+        metrics.certificateMs = Date.now() - certStart;
+        const totalLatencyMs = Date.now() - startTime;
+        return {
+            candidates: topK,
+            certificate,
+            queryId,
+            totalLatencyMs,
+            metrics
+        };
+    }
+    /**
+     * Vector similarity search using cosine similarity
+     */
+    async vectorSearch(queryEmbedding, k) {
+        // Use optimized vector backend if available (100x faster)
+        if (this.vectorBackend && typeof this.vectorBackend.search === 'function') {
+            const searchResults = this.vectorBackend.search(queryEmbedding, k, {
+                threshold: 0.0
+            });
+            // Fetch episode content from DB
+            if (searchResults.length === 0) {
+                return [];
+            }
+            const episodeIds = searchResults.map(r => r.id);
+            const placeholders = episodeIds.map(() => '?').join(',');
+            const episodes = this.db.prepare(`
+        SELECT
+          id,
+          task || ' ' || COALESCE(output, '') as content,
+          latency_ms
+        FROM episodes
+        WHERE id IN (${placeholders})
+      `).all(...episodeIds);
+            const episodeMap = new Map(episodes.map((e) => [e.id, e]));
+            return searchResults.map(result => {
+                const ep = episodeMap.get(result.id);
+                return {
+                    id: result.id.toString(),
+                    type: 'episode',
+                    content: ep?.content || '',
+                    similarity: result.similarity,
+                    latencyMs: ep?.latency_ms || 0
+                };
+            });
+        }
+        // Fallback to SQL-based similarity search
+        const results = [];
+        const episodes = this.db.prepare(`
+      SELECT
+        e.id,
+        'episode' as type,
+        e.task || ' ' || COALESCE(e.output, '') as content,
+        ee.embedding,
+        e.latency_ms
+      FROM episodes e
+      JOIN episode_embeddings ee ON e.id = ee.episode_id
+      ORDER BY e.ts DESC
+      LIMIT ?
+    `).all(k * 2);
+        for (const ep of episodes) {
+            const episodeRow = ep;
+            const embedding = this.deserializeEmbedding(episodeRow.embedding);
+            const similarity = cosineSimilarity(queryEmbedding, embedding);
+            results.push({
+                id: episodeRow.id.toString(),
+                type: episodeRow.type,
+                content: episodeRow.content,
+                similarity,
+                latencyMs: episodeRow.latency_ms || 0
+            });
+        }
+        return results
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, k);
+    }
+    /**
+     * Load causal edges for candidates
+     */
+    async loadCausalEdges(candidateIds) {
+        const edgeMap = new Map();
+        if (candidateIds.length === 0) {
+            return edgeMap;
+        }
+        const placeholders = candidateIds.map(() => '?').join(',');
+        const edges = this.db.prepare(`
+      SELECT * FROM causal_edges
+      WHERE from_memory_id IN (${placeholders})
+        AND confidence >= ?
+    `).all(...candidateIds.map(id => parseInt(id)), this.config.minConfidence || 0.6);
+        for (const edge of edges) {
+            const fromId = edge.from_memory_id.toString();
+            if (!edgeMap.has(fromId)) {
+                edgeMap.set(fromId, []);
+            }
+            edgeMap.get(fromId).push({
+                id: edge.id,
+                fromMemoryId: edge.from_memory_id,
+                fromMemoryType: edge.from_memory_type,
+                toMemoryId: edge.to_memory_id,
+                toMemoryType: edge.to_memory_type,
+                similarity: edge.similarity,
+                uplift: edge.uplift,
+                confidence: edge.confidence,
+                sampleSize: edge.sample_size,
+                evidenceIds: edge.evidence_ids ? JSON.parse(edge.evidence_ids) : undefined,
+                mechanism: edge.mechanism
+            });
+        }
+        return edgeMap;
+    }
+    /**
+     * Rerank by utility: U = α*similarity + β*uplift − γ*latencyCost
+     */
+    rerankByUtility(candidates, causalEdges) {
+        const { alpha, beta, gamma } = this.config;
+        const reranked = candidates.map(candidate => {
+            // Get causal uplift (average if multiple edges)
+            const edges = causalEdges.get(candidate.id) || [];
+            const avgUplift = edges.length > 0
+                ? edges.reduce((sum, e) => sum + (e.uplift || 0), 0) / edges.length
+                : 0;
+            const avgConfidence = edges.length > 0
+                ? edges.reduce((sum, e) => sum + e.confidence, 0) / edges.length
+                : 0;
+            // Normalize latency (assume max 1000ms)
+            const latencyCost = Math.min(candidate.latencyMs / 1000, 1.0);
+            // Calculate utility
+            const utilityScore = alpha * candidate.similarity + beta * avgUplift - gamma * latencyCost;
+            return {
+                id: candidate.id,
+                type: candidate.type,
+                content: candidate.content,
+                similarity: candidate.similarity,
+                uplift: avgUplift,
+                causalConfidence: avgConfidence,
+                latencyMs: candidate.latencyMs,
+                utilityScore,
+                rank: 0 // Will be set after sorting
+            };
+        });
+        // Sort by utility score descending
+        reranked.sort((a, b) => b.utilityScore - a.utilityScore);
+        // Assign ranks
+        reranked.forEach((candidate, idx) => {
+            candidate.rank = idx + 1;
+        });
+        return reranked;
+    }
+    /**
+     * Issue certificate for the retrieval
+     */
+    async issueCertificate(params) {
+        const { queryId, queryText, candidates, requirements, accessLevel } = params;
+        const chunks = candidates.map(c => ({
+            id: c.id,
+            type: c.type,
+            content: c.content,
+            relevance: c.similarity
+        }));
+        return await this.explainableRecall.createCertificate({
+            queryId,
+            queryText,
+            chunks,
+            requirements,
+            accessLevel
+        });
+    }
+    /**
+     * Extract requirements from query text (simple keyword extraction)
+     */
+    extractRequirements(queryText) {
+        // Simple extraction: split on common words and filter
+        const stopWords = new Set(['a', 'an', 'the', 'is', 'are', 'was', 'were', 'to', 'from', 'for', 'with', 'how', 'what', 'where', 'when', 'why', 'who']);
+        const words = queryText
+            .toLowerCase()
+            .replace(/[^a-z0-9\s]/g, '')
+            .split(/\s+/)
+            .filter(w => w.length > 3 && !stopWords.has(w));
+        // Return unique words
+        return [...new Set(words)];
+    }
+    /**
+     * Deserialize embedding from Buffer
+     */
+    deserializeEmbedding(buffer) {
+        return new Float32Array(buffer.buffer, buffer.byteOffset, buffer.length / 4);
+    }
+    /**
+     * Batch recall for multiple queries
+     */
+    async batchRecall(queries, requirements, accessLevel = 'internal') {
+        const results = [];
+        for (const query of queries) {
+            const result = await this.recall(query.queryId, query.queryText, query.k || 12, requirements, accessLevel);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Get recall statistics
+     */
+    getStats() {
+        const causalEdges = this.db.prepare('SELECT COUNT(*) as count FROM causal_edges').get();
+        const certificates = this.db.prepare('SELECT COUNT(*) as count FROM recall_certificates').get();
+        const avgStats = this.db.prepare(`
+      SELECT
+        AVG(redundancy_ratio) as avg_redundancy,
+        AVG(completeness_score) as avg_completeness
+      FROM recall_certificates
+    `).get();
+        return {
+            totalCausalEdges: causalEdges.count,
+            totalCertificates: certificates.count,
+            avgRedundancyRatio: avgStats?.avg_redundancy || 0,
+            avgCompletenessScore: avgStats?.avg_completeness || 0
+        };
+    }
+    /**
+     * Update rerank configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Search for memories with semantic similarity and causal utility ranking
+     *
+     * @param params Search parameters
+     * @returns Array of ranked search results with similarity and causal uplift scores
+     */
+    async search(params) {
+        const { query, k = 12, includeEvidence = false, alpha = this.config.alpha, beta = this.config.beta, gamma = this.config.gamma } = params;
+        // Temporarily override config for this search
+        const originalConfig = { ...this.config };
+        this.config = { ...this.config, alpha, beta, gamma };
+        try {
+            // Step 1: Generate query embedding
+            const queryEmbedding = await this.embedder.embed(query);
+            // Step 2: Vector similarity search
+            const candidates = await this.vectorSearch(queryEmbedding, k * 2);
+            // Step 3: Load causal edges for uplift scoring
+            const causalEdges = await this.loadCausalEdges(candidates.map(c => c.id));
+            // Step 4: Rerank by utility
+            const reranked = this.rerankByUtility(candidates, causalEdges);
+            // Step 5: Format results for search interface
+            const results = reranked.slice(0, k).map(candidate => ({
+                id: parseInt(candidate.id),
+                type: candidate.type,
+                content: candidate.content,
+                similarity: candidate.similarity,
+                causalUplift: candidate.uplift || 0,
+                utilityScore: candidate.utilityScore
+            }));
+            return results;
+        }
+        finally {
+            // Restore original config
+            this.config = originalConfig;
+        }
+    }
+}
+//# sourceMappingURL=CausalRecall.js.map

package/dist/packages/agentdb/src/controllers/CausalRecall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CausalRecall.js","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/controllers/CausalRecall.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * CausalRecall - Utility-Based Reranking + Certificate Issuer\n *\n * Combines:\n * 1. Vector similarity search\n * 2. Causal uplift from CausalMemoryGraph\n * 3. Utility-based reranking: U = α*similarity + β*uplift − γ*latencyCost\n * 4. Automatic certificate issuance via ExplainableRecall\n *\n * This is the main entry point for production retrieval with:\n * - Causal-aware ranking\n * - Explainable provenance\n * - Policy compliance\n */\n\n// Database type from db-fallback\ntype Database = any;\nimport { CausalMemoryGraph, CausalEdge } from './CausalMemoryGraph.js';\nimport { ExplainableRecall, RecallCertificate } from './ExplainableRecall.js';\nimport { EmbeddingService } from './EmbeddingService.js';\nimport type { VectorBackend } from '../backends/VectorBackend.js';\nimport { cosineSimilarity } from '../utils/vector-math.js';\n\nexport interface RerankConfig {\n  alpha: number; // Similarity weight (default: 0.7)\n  beta: number;  // Uplift weight (default: 0.2)\n  gamma: number; // Latency penalty (default: 0.1)\n  minConfidence?: number; // Min causal confidence (default: 0.6)\n}\n\nexport interface RerankCandidate {\n  id: string;\n  type: 'episode' | 'skill' | 'note' | 'fact';\n  content: string;\n  similarity: number;\n  uplift?: number;\n  causalConfidence?: number;\n  latencyMs?: number;\n  utilityScore: number;\n  rank: number;\n}\n\nexport interface CausalRecallResult {\n  candidates: RerankCandidate[];\n  certificate: RecallCertificate;\n  queryId: string;\n  totalLatencyMs: number;\n  metrics: {\n    vectorSearchMs: number;\n    causalLookupMs: number;\n    rerankMs: number;\n    certificateMs: number;\n  };\n}\n\nexport class CausalRecall {\n  private db: Database;\n  private causalGraph: CausalMemoryGraph;\n  private explainableRecall: ExplainableRecall;\n  private embedder: EmbeddingService;\n  private vectorBackend?: VectorBackend;\n\n  constructor(\n    db: Database,\n    embedder: EmbeddingService,\n    vectorBackend?: VectorBackend,\n    private config: RerankConfig = {\n      alpha: 0.7,\n      beta: 0.2,\n      gamma: 0.1,\n      minConfidence: 0.6\n    }\n  ) {\n    this.db = db;\n    this.embedder = embedder;\n    this.vectorBackend = vectorBackend;\n    this.causalGraph = new CausalMemoryGraph(db);\n    this.explainableRecall = new ExplainableRecall(db);\n  }\n\n  /**\n   * Main recall function with utility-based reranking and certificate issuance\n   *\n   * @param queryId Unique query identifier\n   * @param queryText Natural language query\n   * @param k Number of results to return (default: 12)\n   * @param requirements Optional list of requirements for completeness checking\n   * @param accessLevel Security access level for certificate\n   * @returns Reranked results with certificate\n   */\n  async recall(\n    queryId: string,\n    queryText: string,\n    k: number = 12,\n    requirements?: string[],\n    accessLevel: 'public' | 'internal' | 'confidential' | 'restricted' = 'internal'\n  ): Promise<CausalRecallResult> {\n    const startTime = Date.now();\n    const metrics = {\n      vectorSearchMs: 0,\n      causalLookupMs: 0,\n      rerankMs: 0,\n      certificateMs: 0\n    };\n\n    // Step 1: Vector similarity search\n    const vectorStart = Date.now();\n    const queryEmbedding = await this.embedder.embed(queryText);\n    const candidates = await this.vectorSearch(queryEmbedding, k * 2); // Fetch 2k for reranking\n    metrics.vectorSearchMs = Date.now() - vectorStart;\n\n    // Step 2: Load causal edges for candidates\n    const causalStart = Date.now();\n    const causalEdges = await this.loadCausalEdges(candidates.map(c => c.id));\n    metrics.causalLookupMs = Date.now() - causalStart;\n\n    // Step 3: Rerank by utility\n    const rerankStart = Date.now();\n    const reranked = this.rerankByUtility(candidates, causalEdges);\n    const topK = reranked.slice(0, k);\n    metrics.rerankMs = Date.now() - rerankStart;\n\n    // Step 4: Issue certificate\n    const certStart = Date.now();\n    const certificate = await this.issueCertificate({\n      queryId,\n      queryText,\n      candidates: topK,\n      requirements: requirements || this.extractRequirements(queryText),\n      accessLevel\n    });\n    metrics.certificateMs = Date.now() - certStart;\n\n    const totalLatencyMs = Date.now() - startTime;\n\n    return {\n      candidates: topK,\n      certificate,\n      queryId,\n      totalLatencyMs,\n      metrics\n    };\n  }\n\n  /**\n   * Vector similarity search using cosine similarity\n   */\n  private async vectorSearch(\n    queryEmbedding: Float32Array,\n    k: number\n  ): Promise<Array<{ id: string; type: string; content: string; similarity: number; latencyMs: number }>> {\n    // Use optimized vector backend if available (100x faster)\n    if (this.vectorBackend && typeof this.vectorBackend.search === 'function') {\n      const searchResults = this.vectorBackend.search(queryEmbedding, k, {\n        threshold: 0.0\n      });\n\n      // Fetch episode content from DB\n      if (searchResults.length === 0) {\n        return [];\n      }\n\n      const episodeIds = searchResults.map(r => r.id);\n      const placeholders = episodeIds.map(() => '?').join(',');\n      const episodes = this.db.prepare(`\n        SELECT\n          id,\n          task || ' ' || COALESCE(output, '') as content,\n          latency_ms\n        FROM episodes\n        WHERE id IN (${placeholders})\n      `).all(...episodeIds) as any[];\n\n      const episodeMap = new Map(episodes.map((e: any) => [e.id, e]));\n\n      return searchResults.map(result => {\n        const ep = episodeMap.get(result.id);\n        return {\n          id: result.id.toString(),\n          type: 'episode',\n          content: ep?.content || '',\n          similarity: result.similarity,\n          latencyMs: ep?.latency_ms || 0\n        };\n      });\n    }\n\n    // Fallback to SQL-based similarity search\n    const results: any[] = [];\n    const episodes = this.db.prepare(`\n      SELECT\n        e.id,\n        'episode' as type,\n        e.task || ' ' || COALESCE(e.output, '') as content,\n        ee.embedding,\n        e.latency_ms\n      FROM episodes e\n      JOIN episode_embeddings ee ON e.id = ee.episode_id\n      ORDER BY e.ts DESC\n      LIMIT ?\n    `).all(k * 2);\n\n    for (const ep of episodes) {\n      const episodeRow = ep as any;\n      const embedding = this.deserializeEmbedding(episodeRow.embedding);\n      const similarity = cosineSimilarity(queryEmbedding, embedding);\n      results.push({\n        id: episodeRow.id.toString(),\n        type: episodeRow.type,\n        content: episodeRow.content,\n        similarity,\n        latencyMs: episodeRow.latency_ms || 0\n      });\n    }\n\n    return results\n      .sort((a, b) => b.similarity - a.similarity)\n      .slice(0, k);\n  }\n\n  /**\n   * Load causal edges for candidates\n   */\n  private async loadCausalEdges(candidateIds: string[]): Promise<Map<string, CausalEdge[]>> {\n    const edgeMap = new Map<string, CausalEdge[]>();\n\n    if (candidateIds.length === 0) {\n      return edgeMap;\n    }\n\n    const placeholders = candidateIds.map(() => '?').join(',');\n    const edges = this.db.prepare(`\n      SELECT * FROM causal_edges\n      WHERE from_memory_id IN (${placeholders})\n        AND confidence >= ?\n    `).all(...candidateIds.map(id => parseInt(id)), this.config.minConfidence || 0.6) as any[];\n\n    for (const edge of edges) {\n      const fromId = edge.from_memory_id.toString();\n      if (!edgeMap.has(fromId)) {\n        edgeMap.set(fromId, []);\n      }\n      edgeMap.get(fromId)!.push({\n        id: edge.id,\n        fromMemoryId: edge.from_memory_id,\n        fromMemoryType: edge.from_memory_type,\n        toMemoryId: edge.to_memory_id,\n        toMemoryType: edge.to_memory_type,\n        similarity: edge.similarity,\n        uplift: edge.uplift,\n        confidence: edge.confidence,\n        sampleSize: edge.sample_size,\n        evidenceIds: edge.evidence_ids ? JSON.parse(edge.evidence_ids) : undefined,\n        mechanism: edge.mechanism\n      });\n    }\n\n    return edgeMap;\n  }\n\n  /**\n   * Rerank by utility: U = α*similarity + β*uplift − γ*latencyCost\n   */\n  private rerankByUtility(\n    candidates: Array<{ id: string; type: string; content: string; similarity: number; latencyMs: number }>,\n    causalEdges: Map<string, CausalEdge[]>\n  ): RerankCandidate[] {\n    const { alpha, beta, gamma } = this.config;\n\n    const reranked = candidates.map(candidate => {\n      // Get causal uplift (average if multiple edges)\n      const edges = causalEdges.get(candidate.id) || [];\n      const avgUplift = edges.length > 0\n        ? edges.reduce((sum, e) => sum + (e.uplift || 0), 0) / edges.length\n        : 0;\n\n      const avgConfidence = edges.length > 0\n        ? edges.reduce((sum, e) => sum + e.confidence, 0) / edges.length\n        : 0;\n\n      // Normalize latency (assume max 1000ms)\n      const latencyCost = Math.min(candidate.latencyMs / 1000, 1.0);\n\n      // Calculate utility\n      const utilityScore = alpha * candidate.similarity + beta * avgUplift - gamma * latencyCost;\n\n      return {\n        id: candidate.id,\n        type: candidate.type as any,\n        content: candidate.content,\n        similarity: candidate.similarity,\n        uplift: avgUplift,\n        causalConfidence: avgConfidence,\n        latencyMs: candidate.latencyMs,\n        utilityScore,\n        rank: 0 // Will be set after sorting\n      };\n    });\n\n    // Sort by utility score descending\n    reranked.sort((a, b) => b.utilityScore - a.utilityScore);\n\n    // Assign ranks\n    reranked.forEach((candidate, idx) => {\n      candidate.rank = idx + 1;\n    });\n\n    return reranked;\n  }\n\n  /**\n   * Issue certificate for the retrieval\n   */\n  private async issueCertificate(params: {\n    queryId: string;\n    queryText: string;\n    candidates: RerankCandidate[];\n    requirements: string[];\n    accessLevel: 'public' | 'internal' | 'confidential' | 'restricted';\n  }): Promise<RecallCertificate> {\n    const { queryId, queryText, candidates, requirements, accessLevel } = params;\n\n    const chunks = candidates.map(c => ({\n      id: c.id,\n      type: c.type,\n      content: c.content,\n      relevance: c.similarity\n    }));\n\n    return await this.explainableRecall.createCertificate({\n      queryId,\n      queryText,\n      chunks,\n      requirements,\n      accessLevel\n    });\n  }\n\n  /**\n   * Extract requirements from query text (simple keyword extraction)\n   */\n  private extractRequirements(queryText: string): string[] {\n    // Simple extraction: split on common words and filter\n    const stopWords = new Set(['a', 'an', 'the', 'is', 'are', 'was', 'were', 'to', 'from', 'for', 'with', 'how', 'what', 'where', 'when', 'why', 'who']);\n\n    const words = queryText\n      .toLowerCase()\n      .replace(/[^a-z0-9\\s]/g, '')\n      .split(/\\s+/)\n      .filter(w => w.length > 3 && !stopWords.has(w));\n\n    // Return unique words\n    return [...new Set(words)];\n  }\n\n  /**\n   * Deserialize embedding from Buffer\n   */\n  private deserializeEmbedding(buffer: Buffer): Float32Array {\n    return new Float32Array(buffer.buffer, buffer.byteOffset, buffer.length / 4);\n  }\n\n  /**\n   * Batch recall for multiple queries\n   */\n  async batchRecall(\n    queries: Array<{ queryId: string; queryText: string; k?: number }>,\n    requirements?: string[],\n    accessLevel: 'public' | 'internal' | 'confidential' | 'restricted' = 'internal'\n  ): Promise<CausalRecallResult[]> {\n    const results: CausalRecallResult[] = [];\n\n    for (const query of queries) {\n      const result = await this.recall(\n        query.queryId,\n        query.queryText,\n        query.k || 12,\n        requirements,\n        accessLevel\n      );\n      results.push(result);\n    }\n\n    return results;\n  }\n\n  /**\n   * Get recall statistics\n   */\n  getStats(): {\n    totalCausalEdges: number;\n    totalCertificates: number;\n    avgRedundancyRatio: number;\n    avgCompletenessScore: number;\n  } {\n    const causalEdges = this.db.prepare('SELECT COUNT(*) as count FROM causal_edges').get() as any;\n    const certificates = this.db.prepare('SELECT COUNT(*) as count FROM recall_certificates').get() as any;\n\n    const avgStats = this.db.prepare(`\n      SELECT\n        AVG(redundancy_ratio) as avg_redundancy,\n        AVG(completeness_score) as avg_completeness\n      FROM recall_certificates\n    `).get() as any;\n\n    return {\n      totalCausalEdges: causalEdges.count,\n      totalCertificates: certificates.count,\n      avgRedundancyRatio: avgStats?.avg_redundancy || 0,\n      avgCompletenessScore: avgStats?.avg_completeness || 0\n    };\n  }\n\n  /**\n   * Update rerank configuration\n   */\n  updateConfig(config: Partial<RerankConfig>): void {\n    this.config = { ...this.config, ...config };\n  }\n\n  /**\n   * Search for memories with semantic similarity and causal utility ranking\n   *\n   * @param params Search parameters\n   * @returns Array of ranked search results with similarity and causal uplift scores\n   */\n  async search(params: {\n    query: string;\n    k?: number;\n    includeEvidence?: boolean;\n    alpha?: number;\n    beta?: number;\n    gamma?: number;\n  }): Promise<Array<{\n    id: number;\n    type: string;\n    content: string;\n    similarity: number;\n    causalUplift: number;\n    utilityScore: number;\n  }>> {\n    const {\n      query,\n      k = 12,\n      includeEvidence = false,\n      alpha = this.config.alpha,\n      beta = this.config.beta,\n      gamma = this.config.gamma\n    } = params;\n\n    // Temporarily override config for this search\n    const originalConfig = { ...this.config };\n    this.config = { ...this.config, alpha, beta, gamma };\n\n    try {\n      // Step 1: Generate query embedding\n      const queryEmbedding = await this.embedder.embed(query);\n\n      // Step 2: Vector similarity search\n      const candidates = await this.vectorSearch(queryEmbedding, k * 2);\n\n      // Step 3: Load causal edges for uplift scoring\n      const causalEdges = await this.loadCausalEdges(candidates.map(c => c.id));\n\n      // Step 4: Rerank by utility\n      const reranked = this.rerankByUtility(candidates, causalEdges);\n\n      // Step 5: Format results for search interface\n      const results = reranked.slice(0, k).map(candidate => ({\n        id: parseInt(candidate.id),\n        type: candidate.type,\n        content: candidate.content,\n        similarity: candidate.similarity,\n        causalUplift: candidate.uplift || 0,\n        utilityScore: candidate.utilityScore\n      }));\n\n      return results;\n    } finally {\n      // Restore original config\n      this.config = originalConfig;\n    }\n  }\n}\n"]}

package/dist/packages/agentdb/src/controllers/ContextSynthesizer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Context Synthesis - Generate coherent narratives from multiple memories
+ *
+ * Takes a collection of retrieved episodes/patterns and synthesizes
+ * a coherent context summary with extracted patterns, success rates,
+ * and actionable insights.
+ */
+export interface MemoryPattern {
+    task: string;
+    reward: number;
+    success: boolean;
+    critique?: string;
+    input?: string;
+    output?: string;
+    similarity?: number;
+    [key: string]: any;
+}
+export interface SynthesizedContext {
+    summary: string;
+    patterns: string[];
+    successRate: number;
+    averageReward: number;
+    recommendations: string[];
+    keyInsights: string[];
+    totalMemories: number;
+}
+export declare class ContextSynthesizer {
+    /**
+     * Synthesize context from multiple memories
+     *
+     * @param memories - Retrieved episodes/patterns
+     * @param options - Synthesis options
+     * @returns Synthesized context with insights
+     */
+    static synthesize(memories: MemoryPattern[], options?: {
+        minPatternFrequency?: number;
+        includeRecommendations?: boolean;
+        maxSummaryLength?: number;
+    }): SynthesizedContext;
+    /**
+     * Extract common patterns from memory critiques
+     */
+    private static extractPatterns;
+    /**
+     * Extract meaningful phrases from text
+     */
+    private static extractPhrases;
+    /**
+     * Generate key insights from memories
+     */
+    private static generateKeyInsights;
+    /**
+     * Generate actionable recommendations
+     */
+    private static generateRecommendations;
+    /**
+     * Generate narrative summary
+     */
+    private static generateSummary;
+    /**
+     * Extract actionable steps from successful memories
+     */
+    static extractActionableSteps(memories: MemoryPattern[]): string[];
+}
+//# sourceMappingURL=ContextSynthesizer.d.ts.map

package/dist/packages/agentdb/src/controllers/ContextSynthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextSynthesizer.d.ts","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/controllers/ContextSynthesizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,kBAAkB;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CACf,QAAQ,EAAE,aAAa,EAAE,EACzB,OAAO,GAAE;QACP,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,sBAAsB,CAAC,EAAE,OAAO,CAAC;QACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;KACtB,GACL,kBAAkB;IA8CrB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAwB9B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAoB7B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAuClC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAoCtC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAwC9B;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE;CAiBnE"}