@monoes/memory 1.0.1 → 1.0.3

package/dist/hybrid-backend.d.ts

@@ -1,297 +0,0 @@
-/**
- * HybridBackend - Combines SQLite (structured queries) + LanceDB (vector search)
- *
- * Per ADR-009: "HybridBackend (SQLite + LanceDB) as default"
- * - SQLite for: Structured queries, ACID transactions, exact matches
- * - LanceDB for: Semantic search, vector similarity, RAG
- *
- * @module v1/memory/hybrid-backend
- */
-import { EventEmitter } from 'node:events';
-import { IMemoryBackend, MemoryEntry, MemoryEntryUpdate, MemoryQuery, SearchOptions, SearchResult, BackendStats, HealthCheckResult, EmbeddingGenerator } from './types.js';
-import { SQLiteBackendConfig } from './sqlite-backend.js';
-import { LanceDBBackendConfig } from './lancedb-backend.js';
-/**
- * Configuration for HybridBackend
- */
-export interface HybridBackendConfig {
-    /** SQLite configuration */
-    sqlite?: Partial<SQLiteBackendConfig>;
-    /** LanceDB configuration override */
-    /**
-     * LanceDB configuration (used when semanticBackend is 'lancedb').
-     * Requires: npm install @lancedb/lancedb apache-arrow
-     */
-    lancedb?: LanceDBBackendConfig;
-    /** Which backend handles semantic (vector) search. Always 'lancedb'. */
-    semanticBackend?: 'lancedb';
-    /** Default namespace */
-    defaultNamespace?: string;
-    /** Embedding generator function */
-    embeddingGenerator?: EmbeddingGenerator;
-    /** Query routing strategy */
-    routingStrategy?: 'auto' | 'sqlite-first' | 'semantic-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;
-    /**
-     * Filter semantic search results for prompt-injection patterns.
-     * When true, entries whose content matches known injection signatures are
-     * removed from results and an `injection:blocked` event is emitted.
-     * Source: newinnovation.md §5 — Semantic injection detection
-     */
-    filterInjection?: boolean;
-    /**
-     * MemoRAG query rewriter — generates 2-3 reformulated sub-queries before HNSW.
-     *
-     * When provided, `querySemantic()` calls this function on the original query text
-     * to produce alternative formulations (e.g. more specific, paraphrased, or
-     * keyword-expanded variants). Each sub-query is embedded and searched independently;
-     * results are fused using Reciprocal Rank Fusion (RRF).
-     *
-     * Use a cheap LLM call (Haiku) or a deterministic paraphrase function.
-     * Source: arXiv:2409.05591 — MemoRAG (TheWebConf 2025)
-     */
-    memoragRewriter?: (query: string) => Promise<string[]>;
-}
-/**
- * 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 LanceDB'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 LanceDB:
- * - Exact matches, prefix queries → SQLite
- * - Semantic search, similarity → LanceDB
- * - Complex hybrid queries → Both backends with intelligent merging
- */
-export declare class HybridBackend extends EventEmitter implements IMemoryBackend {
-    private sqlite;
-    private semantic;
-    private config;
-    private initialized;
-    /** Lazy MemoryGraph for HippoRAG PPR re-ranking */
-    private memoryGraph;
-    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).
-     *
-     * A-MEM auto-linking: after writing, HNSW-searches for the top-3 most similar
-     * existing entries and adds bidirectional `references` edges between them and
-     * the new entry.  Only runs when an `embeddingGenerator` is configured.
-     * Source: arXiv:2409.11987 (A-MEM — Zettelkasten-style agent memory)
-     */
-    store(entry: MemoryEntry): Promise<void>;
-    /**
-     * A-MEM bidirectional reference linking.
-     * Finds the top-3 semantically similar existing entries and creates
-     * `references` edges in both directions.
-     */
-    private aMemAutoLink;
-    /**
-     * Get from semantic backend.
-     *
-     * Collaborative memory promotion: when `agentId` is supplied, also notifies
-     * the SQLite backend so it can track the read and promote the entry's
-     * AccessLevel to 'team' once 3+ distinct agents have accessed it.
-     * Source: newinnovation.md §2.7 — memory access-level promotion.
-     */
-    get(id: string, agentId?: 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 LanceDB, structured to SQLite
-     */
-    query(query: MemoryQuery): Promise<MemoryEntry[]>;
-    /**
-     * Structured queries (SQL)
-     * Routes to SQLite for optimal performance
-     */
-    queryStructured(query: StructuredQuery): Promise<MemoryEntry[]>;
-    /**
-     * Apply injection filtering and structured field filters to a set of entries.
-     * Used by the MemoRAG path (RRF-fused results) and as a shared post-processing step.
-     */
-    private postProcessSemanticResults;
-    /**
-     * Reciprocal Rank Fusion — merge multiple ranked result lists.
-     * Score for entry i in list j: 1 / (k + rank_j(i))  where k=60 (standard).
-     * Source: Cormack et al., "Reciprocal Rank Fusion outperforms Condorcet and individual
-     * Rank Learning Methods" (SIGIR 2009). Used by MemoRAG sub-query fusion.
-     */
-    private rrfFuse;
-    /**
-     * Semantic queries (vector)
-     * Routes to semantic backend for ANN vector search.
-     *
-     * MemoRAG query rewriting (arXiv:2409.05591): when `memoragRewriter` is configured
-     * and `query.content` is present, generates 2-3 reformulated sub-queries, embeds
-     * each, searches HNSW independently, then fuses with Reciprocal Rank Fusion (RRF)
-     * before HippoRAG PPR re-ranking.
-     */
-    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 LanceDB)
-     */
-    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 semantic backend's recordFeedback when available.
-     * Gracefully degrades to no-op when unavailable.
-     */
-    recordFeedback(_entryId: string, _feedback: {
-        score: number;
-        label?: string;
-        context?: Record<string, unknown>;
-    }): Promise<boolean>;
-    verifyWitnessChain(_entryId: string): Promise<{
-        valid: boolean;
-        chainLength: number;
-        errors: string[];
-    }>;
-    getWitnessChain(_entryId: string): Promise<Array<{
-        hash: string;
-        timestamp: number;
-        operation: string;
-    }>>;
-    /**
-     * Get underlying backends for advanced operations
-     */
-    getSQLiteBackend(): IMemoryBackend;
-    getSemanticBackend(): IMemoryBackend;
-}
-export default HybridBackend;
-//# sourceMappingURL=hybrid-backend.d.ts.map

package/dist/hybrid-backend.d.ts.map

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