@psiclawops/hypermem 0.5.0 → 0.5.1

package/dist/vector-store.d.ts

@@ -0,0 +1,170 @@
+/**
+ * hypermem Vector Store — Semantic Search via sqlite-vec
+ *
+ * Provides embedding-backed KNN search over facts, knowledge, episodes,
+ * and session registry entries. Uses Ollama (local) for embeddings,
+ * sqlite-vec for vector indexing, and coexists with existing FTS5.
+ *
+ * Architecture:
+ *   - One vec0 virtual table per indexed content type
+ *   - Embeddings generated via local Ollama (nomic-embed-text, 768d)
+ *   - Vectors stored alongside content in the same agent DB
+ *   - LRU embedding cache (module-level, per-process) to avoid redundant Ollama calls
+ *   - Precomputed embedding passthrough: callers can supply an embedding to skip Ollama
+ *   - Batch embedding support for bulk indexing
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface EmbeddingConfig {
+    /**
+     * Embedding provider. Default: 'ollama'.
+     * - 'ollama': local Ollama instance (nomic-embed-text or any pull'd model)
+     * - 'openai': OpenAI Embeddings API (text-embedding-3-small / 3-large)
+     */
+    provider?: 'ollama' | 'openai';
+    /** Ollama base URL. Default: http://localhost:11434 */
+    ollamaUrl: string;
+    /** OpenAI API key. Required when provider is 'openai'. */
+    openaiApiKey?: string;
+    /** OpenAI base URL. Default: https://api.openai.com/v1 */
+    openaiBaseUrl?: string;
+    /** Embedding model name. Default: nomic-embed-text (ollama) or text-embedding-3-small (openai) */
+    model: string;
+    /** Embedding dimensions. Default: 768 (ollama/nomic) or 1536 (openai/3-small) */
+    dimensions: number;
+    /** Request timeout ms. Default: 10000 */
+    timeout: number;
+    /** Max texts per batch request. Default: 32 (ollama) or 128 (openai) */
+    batchSize: number;
+    /** LRU cache max entries. Default: 128 */
+    cacheSize?: number;
+}
+export interface VectorSearchResult {
+    rowid: number;
+    distance: number;
+    sourceTable: string;
+    sourceId: number;
+    content: string;
+    domain?: string;
+    agentId?: string;
+    metadata?: string;
+}
+export interface VectorIndexStats {
+    totalVectors: number;
+    tableBreakdown: Record<string, number>;
+    lastIndexedAt: string | null;
+}
+/**
+ * Clear the embedding cache. Primarily for testing.
+ */
+export declare function clearEmbeddingCache(): void;
+/**
+ * Generate embeddings via Ollama API.
+ * Supports single and batch embedding.
+ * Results are cached per text hash — cache hits skip the Ollama call entirely.
+ */
+export declare function generateEmbeddings(texts: string[], config?: EmbeddingConfig): Promise<Float32Array[]>;
+/**
+ * VectorStore — manages vector indexes in an agent's vector database.
+ *
+ * The vector DB (vectors.db) stores vec0 virtual tables and the index map.
+ * Source content (facts, knowledge, episodes) lives in the library DB.
+ * The VectorStore needs both: vectorDb for indexes, libraryDb for content.
+ */
+export declare class VectorStore {
+    private readonly db;
+    private readonly libraryDb;
+    private readonly config;
+    constructor(db: DatabaseSync, config?: Partial<EmbeddingConfig>, libraryDb?: DatabaseSync);
+    /**
+     * Create vector index tables if they don't exist.
+     * Safe to call multiple times (idempotent).
+     */
+    ensureTables(): void;
+    /**
+     * Index a single content item. Generates embedding and stores in vec table.
+     * Skips if content hasn't changed (based on hash).
+     */
+    /** Allowlisted source tables for vector indexing. Prevents SQL injection via table name interpolation. */
+    private static readonly ALLOWED_SOURCE_TABLES;
+    private validateSourceTable;
+    indexItem(sourceTable: string, sourceId: number, content: string, domain?: string): Promise<boolean>;
+    /**
+     * Batch index multiple items. More efficient than individual calls.
+     */
+    indexBatch(items: Array<{
+        sourceTable: string;
+        sourceId: number;
+        content: string;
+        domain?: string;
+    }>): Promise<{
+        indexed: number;
+        skipped: number;
+    }>;
+    /**
+     * Semantic KNN search across one or all vector tables.
+     *
+     * @param precomputedEmbedding — optional pre-computed embedding for the query.
+     *   When provided, skips the Ollama call entirely. The precomputed embedding
+     *   is still inserted into the LRU cache so subsequent identical queries hit.
+     */
+    search(query: string, opts?: {
+        tables?: string[];
+        limit?: number;
+        maxDistance?: number;
+        precomputedEmbedding?: Float32Array;
+    }): Promise<VectorSearchResult[]>;
+    /**
+     * Get content from a source table by id.
+     */
+    private getSourceContent;
+    /**
+     * Index all un-indexed content in the agent's database.
+     * Called by the background indexer.
+     */
+    indexAll(agentId: string): Promise<{
+        indexed: number;
+        skipped: number;
+    }>;
+    /**
+     * Remove vector index entries for deleted source rows.
+     */
+    pruneOrphans(): number;
+    /**
+     * Remove the vector index entry for a single source item.
+     *
+     * Deletes both the vec table row and the vec_index_map entry for the given
+     * (sourceTable, sourceId) pair. Used by the background indexer for immediate
+     * point-in-time removal when a supersedes relationship is detected.
+     *
+     * @returns true if an entry was found and removed, false if nothing was indexed.
+     */
+    removeItem(sourceTable: string, sourceId: number): boolean;
+    /**
+     * Check whether a source item already has a vector in the index.
+     * Used by the episode backfill to skip already-vectorized entries.
+     */
+    hasItem(sourceTable: string, sourceId: number): boolean;
+    /**
+     * Tombstone vector entries for superseded facts and knowledge.
+     *
+     * When fact A is superseded by fact B (facts.superseded_by = B.id), the old
+     * vector for A should not surface in semantic recall. Without this, recalled
+     * context can include contradicted/outdated facts alongside their replacements.
+     *
+     * Strategy: find all indexed facts/knowledge with superseded_by IS NOT NULL
+     * and delete their vec_index_map entries + vec table rows. The source row
+     * stays in library.db (audit trail) but disappears from recall.
+     *
+     * @returns Number of vector entries tombstoned.
+     */
+    tombstoneSuperseded(): number;
+    /**
+     * Get index statistics.
+     */
+    getStats(): VectorIndexStats;
+}
+/**
+ * Create vector tables in a library database for session registry search.
+ */
+export declare function ensureSessionVecTable(db: DatabaseSync, dimensions?: number): void;
+//# sourceMappingURL=vector-store.d.ts.map

package/dist/vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../src/vector-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,aAAa,CAAC;AAG/D,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kGAAkG;IAClG,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAuDD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAqED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,GAAE,eAA0C,GACjD,OAAO,CAAC,YAAY,EAAE,CAAC,CAyFzB;AASD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC,EAAE,YAAY;IAMzF;;;OAGG;IACH,YAAY,IAAI,IAAI;IA6CpB;;;OAGG;IACH,0GAA0G;IAC1G,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAA2D;IAExG,OAAO,CAAC,mBAAmB;IAMrB,SAAS,CACb,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC;IA2CnB;;OAEG;IACG,UAAU,CACd,KAAK,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACxF,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAyEhD;;;;;;OAMG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,oBAAoB,CAAC,EAAE,YAAY,CAAC;KACrC,GACA,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2EhC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA8CxB;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAiE9E;;OAEG;IACH,YAAY,IAAI,MAAM;IA2BtB;;;;;;;;OAQG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAc1D;;;OAGG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAQvD;;;;;;;;;;;;OAYG;IACH,mBAAmB,IAAI,MAAM;IA+B7B;;OAEG;IACH,QAAQ,IAAI,gBAAgB;CAsB7B;AAUD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,YAAY,EAAE,UAAU,GAAE,MAAY,GAAG,IAAI,CActF"}