moflo 4.0.1 → 4.0.3

package/v3/@claude-flow/memory/dist/hnsw-lite.d.ts

@@ -0,0 +1,23 @@
+export interface HnswSearchResult {
+    id: string;
+    score: number;
+}
+export declare class HnswLite {
+    private vectors;
+    private neighbors;
+    private readonly dimensions;
+    private readonly maxNeighbors;
+    private readonly efConstruction;
+    private readonly metric;
+    constructor(dimensions: number, m: number, efConstruction: number, metric: string);
+    get size(): number;
+    add(id: string, vector: Float32Array): void;
+    remove(id: string): void;
+    search(query: Float32Array, k: number, threshold?: number): HnswSearchResult[];
+    private bruteForce;
+    private findNearest;
+    private pruneNeighbors;
+    private similarity;
+}
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+//# sourceMappingURL=hnsw-lite.d.ts.map

package/v3/@claude-flow/memory/dist/hnsw-lite.js

@@ -0,0 +1,168 @@
+export class HnswLite {
+    vectors = new Map();
+    neighbors = new Map();
+    dimensions;
+    maxNeighbors;
+    efConstruction;
+    metric;
+    constructor(dimensions, m, efConstruction, metric) {
+        this.dimensions = dimensions;
+        this.maxNeighbors = m;
+        this.efConstruction = efConstruction;
+        this.metric = metric;
+    }
+    get size() {
+        return this.vectors.size;
+    }
+    add(id, vector) {
+        this.vectors.set(id, vector);
+        if (this.vectors.size === 1) {
+            this.neighbors.set(id, new Set());
+            return;
+        }
+        const nearest = this.findNearest(vector, this.maxNeighbors);
+        const neighborSet = new Set();
+        for (const n of nearest) {
+            neighborSet.add(n.id);
+            const nNeighbors = this.neighbors.get(n.id);
+            if (nNeighbors) {
+                nNeighbors.add(id);
+                if (nNeighbors.size > this.maxNeighbors * 2) {
+                    this.pruneNeighbors(n.id);
+                }
+            }
+        }
+        this.neighbors.set(id, neighborSet);
+    }
+    remove(id) {
+        this.vectors.delete(id);
+        const myNeighbors = this.neighbors.get(id);
+        if (myNeighbors) {
+            for (const nId of myNeighbors) {
+                this.neighbors.get(nId)?.delete(id);
+            }
+        }
+        this.neighbors.delete(id);
+    }
+    search(query, k, threshold) {
+        if (this.vectors.size === 0)
+            return [];
+        if (this.vectors.size <= k * 2) {
+            return this.bruteForce(query, k, threshold);
+        }
+        const visited = new Set();
+        const candidates = [];
+        let entryId;
+        let bestScore = -1;
+        for (const [id] of this.vectors) {
+            const score = this.similarity(query, this.vectors.get(id));
+            if (score > bestScore) {
+                bestScore = score;
+                entryId = id;
+            }
+            if (visited.size >= Math.min(this.efConstruction, this.vectors.size))
+                break;
+            visited.add(id);
+            candidates.push({ id, score });
+        }
+        if (entryId) {
+            const queue = [entryId];
+            let idx = 0;
+            while (idx < queue.length && visited.size < this.efConstruction * 2) {
+                const currentId = queue[idx++];
+                const currentNeighbors = this.neighbors.get(currentId);
+                if (!currentNeighbors)
+                    continue;
+                for (const nId of currentNeighbors) {
+                    if (visited.has(nId))
+                        continue;
+                    visited.add(nId);
+                    const vec = this.vectors.get(nId);
+                    if (!vec)
+                        continue;
+                    const score = this.similarity(query, vec);
+                    candidates.push({ id: nId, score });
+                    queue.push(nId);
+                }
+            }
+        }
+        candidates.sort((a, b) => b.score - a.score);
+        let filtered = candidates;
+        if (threshold !== undefined) {
+            filtered = filtered.filter(c => c.score >= threshold);
+        }
+        return filtered.slice(0, k);
+    }
+    bruteForce(query, k, threshold) {
+        const results = [];
+        for (const [id, vec] of this.vectors) {
+            const score = this.similarity(query, vec);
+            if (threshold !== undefined && score < threshold)
+                continue;
+            results.push({ id, score });
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, k);
+    }
+    findNearest(query, k) {
+        return this.bruteForce(query, k);
+    }
+    pruneNeighbors(id) {
+        const myNeighbors = this.neighbors.get(id);
+        if (!myNeighbors)
+            return;
+        const vec = this.vectors.get(id);
+        if (!vec)
+            return;
+        const scored = [];
+        for (const nId of myNeighbors) {
+            const nVec = this.vectors.get(nId);
+            if (!nVec)
+                continue;
+            scored.push({ id: nId, score: this.similarity(vec, nVec) });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const keep = new Set(scored.slice(0, this.maxNeighbors).map(s => s.id));
+        for (const nId of myNeighbors) {
+            if (!keep.has(nId)) {
+                myNeighbors.delete(nId);
+            }
+        }
+    }
+    similarity(a, b) {
+        if (this.metric === 'dot')
+            return dotProduct(a, b);
+        if (this.metric === 'euclidean')
+            return 1 / (1 + euclideanDistance(a, b));
+        return cosineSimilarity(a, b);
+    }
+}
+export function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+function dotProduct(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        sum += a[i] * b[i];
+    }
+    return sum;
+}
+function euclideanDistance(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const d = a[i] - b[i];
+        sum += d * d;
+    }
+    return Math.sqrt(sum);
+}
+//# sourceMappingURL=hnsw-lite.js.map

package/v3/@claude-flow/memory/dist/hybrid-backend.d.ts

@@ -0,0 +1,245 @@
+/**
+ * HybridBackend - Combines SQLite (structured queries) + AgentDB (vector search)
+ *
+ * Per ADR-009: "HybridBackend (SQLite + AgentDB) as default"
+ * - SQLite for: Structured queries, ACID transactions, exact matches
+ * - AgentDB for: Semantic search, vector similarity, RAG
+ *
+ * @module v3/memory/hybrid-backend
+ */
+import { EventEmitter } from 'node:events';
+import { IMemoryBackend, MemoryEntry, MemoryEntryUpdate, MemoryQuery, SearchOptions, SearchResult, BackendStats, HealthCheckResult, EmbeddingGenerator } from './types.js';
+import { SQLiteBackend, SQLiteBackendConfig } from './sqlite-backend.js';
+import { AgentDBBackend, AgentDBBackendConfig } from './agentdb-backend.js';
+/**
+ * Configuration for HybridBackend
+ */
+export interface HybridBackendConfig {
+    /** SQLite configuration */
+    sqlite?: Partial<SQLiteBackendConfig>;
+    /** AgentDB configuration */
+    agentdb?: Partial<AgentDBBackendConfig>;
+    /** Default namespace */
+    defaultNamespace?: string;
+    /** Embedding generator function */
+    embeddingGenerator?: EmbeddingGenerator;
+    /** Query routing strategy */
+    routingStrategy?: 'auto' | 'sqlite-first' | 'agentdb-first';
+    /** Enable dual-write (write to both backends) */
+    dualWrite?: boolean;
+    /** Semantic search threshold for hybrid queries */
+    semanticThreshold?: number;
+    /** Maximum results to fetch from each backend in hybrid queries */
+    hybridMaxResults?: number;
+}
+/**
+ * Structured Query Interface
+ * Optimized for SQLite's strengths
+ */
+export interface StructuredQuery {
+    /** Exact key match */
+    key?: string;
+    /** Key prefix match */
+    keyPrefix?: string;
+    /** Namespace filter */
+    namespace?: string;
+    /** Owner filter */
+    ownerId?: string;
+    /** Type filter */
+    type?: string;
+    /** Time range filters */
+    createdAfter?: number;
+    createdBefore?: number;
+    updatedAfter?: number;
+    updatedBefore?: number;
+    /** Pagination */
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Semantic Query Interface
+ * Optimized for AgentDB's vector search
+ */
+export interface SemanticQuery {
+    /** Content to search for (will be embedded) */
+    content?: string;
+    /** Pre-computed embedding */
+    embedding?: Float32Array;
+    /** Number of results */
+    k?: number;
+    /** Similarity threshold (0-1) */
+    threshold?: number;
+    /** Additional filters */
+    filters?: Partial<MemoryQuery>;
+}
+/**
+ * Hybrid Query Interface
+ * Combines structured + semantic search
+ */
+export interface HybridQuery {
+    /** Semantic component */
+    semantic: SemanticQuery;
+    /** Structured component */
+    structured?: StructuredQuery;
+    /** How to combine results */
+    combineStrategy?: 'union' | 'intersection' | 'semantic-first' | 'structured-first';
+    /** Weights for score combination */
+    weights?: {
+        semantic: number;
+        structured: number;
+    };
+}
+/**
+ * HybridBackend Implementation
+ *
+ * Intelligently routes queries between SQLite and AgentDB:
+ * - Exact matches, prefix queries → SQLite
+ * - Semantic search, similarity → AgentDB
+ * - Complex hybrid queries → Both backends with intelligent merging
+ */
+export declare class HybridBackend extends EventEmitter implements IMemoryBackend {
+    private sqlite;
+    private agentdb;
+    private config;
+    private initialized;
+    private stats;
+    constructor(config?: HybridBackendConfig);
+    /**
+     * Initialize both backends
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown both backends
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Store in both backends (dual-write for consistency)
+     */
+    store(entry: MemoryEntry): Promise<void>;
+    /**
+     * Get from AgentDB (has caching enabled)
+     */
+    get(id: string): Promise<MemoryEntry | null>;
+    /**
+     * Get by key (SQLite optimized for exact matches)
+     */
+    getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+    /**
+     * Update in both backends
+     */
+    update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+    /**
+     * Delete from both backends
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Query routing - semantic goes to AgentDB, structured to SQLite
+     */
+    query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /**
+     * Structured queries (SQL)
+     * Routes to SQLite for optimal performance
+     */
+    queryStructured(query: StructuredQuery): Promise<MemoryEntry[]>;
+    /**
+     * Semantic queries (vector)
+     * Routes to AgentDB for HNSW-based vector search
+     */
+    querySemantic(query: SemanticQuery): Promise<MemoryEntry[]>;
+    /**
+     * Hybrid queries (combine both)
+     * Intelligently merges results from both backends
+     */
+    queryHybrid(query: HybridQuery): Promise<MemoryEntry[]>;
+    /**
+     * Semantic vector search (routes to AgentDB)
+     */
+    search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Bulk insert to both backends
+     */
+    bulkInsert(entries: MemoryEntry[]): Promise<void>;
+    /**
+     * Bulk delete from both backends
+     */
+    bulkDelete(ids: string[]): Promise<number>;
+    /**
+     * Count entries (use SQLite for efficiency)
+     */
+    count(namespace?: string): Promise<number>;
+    /**
+     * List namespaces (use SQLite)
+     */
+    listNamespaces(): Promise<string[]>;
+    /**
+     * Clear namespace in both backends
+     */
+    clearNamespace(namespace: string): Promise<number>;
+    /**
+     * Get combined statistics from both backends
+     */
+    getStats(): Promise<BackendStats>;
+    /**
+     * Health check for both backends
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Auto-route queries based on properties
+     */
+    private autoRoute;
+    /**
+     * Internal hybrid query implementation
+     */
+    private queryHybridInternal;
+    /**
+     * Combine results using union (all unique results)
+     */
+    private combineUnion;
+    /**
+     * Combine results using intersection (only common results)
+     */
+    private combineIntersection;
+    /**
+     * Semantic-first: Prefer semantic results, add structured if not present
+     */
+    private combineSemanticFirst;
+    /**
+     * Structured-first: Prefer structured results, add semantic if not present
+     */
+    private combineStructuredFirst;
+    /**
+     * Record feedback for a memory entry.
+     * Delegates to AgentDB's recordFeedback when available.
+     * Gracefully degrades to a no-op when AgentDB is unavailable.
+     */
+    recordFeedback(entryId: string, feedback: {
+        score: number;
+        label?: string;
+        context?: Record<string, unknown>;
+    }): Promise<boolean>;
+    /**
+     * Verify a witness chain for a memory entry.
+     * Delegates to AgentDB's verifyWitnessChain when available.
+     */
+    verifyWitnessChain(entryId: string): Promise<{
+        valid: boolean;
+        chainLength: number;
+        errors: string[];
+    }>;
+    /**
+     * Get the witness chain for a memory entry.
+     * Delegates to AgentDB's getWitnessChain when available.
+     */
+    getWitnessChain(entryId: string): Promise<Array<{
+        hash: string;
+        timestamp: number;
+        operation: string;
+    }>>;
+    /**
+     * Get underlying backends for advanced operations
+     */
+    getSQLiteBackend(): SQLiteBackend;
+    getAgentDBBackend(): AgentDBBackend;
+}
+export default HybridBackend;
+//# sourceMappingURL=hybrid-backend.d.ts.map