@psiclawops/hypermem 0.5.0 → 0.5.1

package/dist/vector-store.js

@@ -0,0 +1,677 @@
+/**
+ * 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 { createHash } from 'node:crypto';
+const DEFAULT_EMBEDDING_CONFIG = {
+    provider: 'ollama',
+    ollamaUrl: 'http://localhost:11434',
+    openaiBaseUrl: 'https://api.openai.com/v1',
+    model: 'nomic-embed-text',
+    dimensions: 768,
+    timeout: 10000,
+    batchSize: 32,
+    cacheSize: 128,
+};
+/** Provider-specific defaults applied when provider is 'openai' and fields are not set. */
+const OPENAI_DEFAULTS = {
+    model: 'text-embedding-3-small',
+    dimensions: 1536,
+    batchSize: 128,
+};
+const _embeddingCache = new Map();
+/**
+ * Insert an entry into the LRU cache, evicting the oldest if over capacity.
+ */
+function cachePut(key, embedding, maxSize) {
+    if (_embeddingCache.has(key)) {
+        // Update existing entry (refresh timestamp)
+        _embeddingCache.delete(key);
+    }
+    else if (_embeddingCache.size >= maxSize) {
+        // Evict oldest entry by timestamp
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [k, v] of _embeddingCache) {
+            if (v.timestamp < oldestTime) {
+                oldestTime = v.timestamp;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey !== undefined) {
+            _embeddingCache.delete(oldestKey);
+        }
+    }
+    _embeddingCache.set(key, { embedding, timestamp: Date.now() });
+}
+/**
+ * Clear the embedding cache. Primarily for testing.
+ */
+export function clearEmbeddingCache() {
+    _embeddingCache.clear();
+}
+/**
+ * Generate embeddings via OpenAI Embeddings API.
+ * Batches up to batchSize inputs per request.
+ */
+async function generateOpenAIEmbeddings(texts, config) {
+    // Resolve API key: config > environment
+    const apiKey = config.openaiApiKey
+        ?? process.env.OPENROUTER_API_KEY
+        ?? process.env.OPENAI_API_KEY
+        ?? null;
+    if (!apiKey) {
+        throw new Error('[hypermem] OpenAI embedding provider requires an API key. ' +
+            'Set openaiApiKey in hypermem config, or set OPENROUTER_API_KEY / OPENAI_API_KEY env var.');
+    }
+    const baseUrl = config.openaiBaseUrl ?? 'https://api.openai.com/v1';
+    const model = config.model;
+    const results = [];
+    for (let i = 0; i < texts.length; i += config.batchSize) {
+        const batch = texts.slice(i, i + config.batchSize);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeout);
+        try {
+            const response = await fetch(`${baseUrl}/embeddings`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({ model, input: batch }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => '');
+                throw new Error(`OpenAI embedding failed: ${response.status} ${response.statusText} — ${body}`);
+            }
+            const data = await response.json();
+            // OpenAI returns results in order by default but may not guarantee it — sort by index.
+            const sorted = data.data.sort((a, b) => a.index - b.index);
+            for (const item of sorted) {
+                if (item.embedding.length !== config.dimensions) {
+                    throw new Error(`OpenAI embedding dimension mismatch: expected ${config.dimensions}, got ${item.embedding.length}. ` +
+                        'If you changed models, re-index via hypermem reindex.');
+                }
+                results.push(new Float32Array(item.embedding));
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return results;
+}
+/**
+ * Generate embeddings via Ollama API.
+ * Supports single and batch embedding.
+ * Results are cached per text hash — cache hits skip the Ollama call entirely.
+ */
+export async function generateEmbeddings(texts, config = DEFAULT_EMBEDDING_CONFIG) {
+    // Apply provider-specific defaults when provider is 'openai' and fields are at Ollama defaults
+    if (config.provider === 'openai') {
+        // Merge: OpenAI defaults fill in any unset fields, user-supplied values always win
+        config = {
+            ...DEFAULT_EMBEDDING_CONFIG,
+            ...config,
+            model: config.model !== DEFAULT_EMBEDDING_CONFIG.model ? config.model : OPENAI_DEFAULTS.model,
+            dimensions: config.dimensions !== DEFAULT_EMBEDDING_CONFIG.dimensions ? config.dimensions : OPENAI_DEFAULTS.dimensions,
+            batchSize: config.batchSize !== DEFAULT_EMBEDDING_CONFIG.batchSize ? config.batchSize : OPENAI_DEFAULTS.batchSize,
+        };
+        // OpenAI path — no LRU cache (responses are billed; caching at this layer
+        // adds complexity without proportional benefit given async background use).
+        return generateOpenAIEmbeddings(texts, config);
+    }
+    if (texts.length === 0)
+        return [];
+    const maxSize = Math.min(config.cacheSize ?? DEFAULT_EMBEDDING_CONFIG.cacheSize ?? 128, 10_000 // Hard cap: prevent unbounded memory growth from operator misconfiguration
+    );
+    const results = new Array(texts.length).fill(null);
+    // Check cache first — build list of texts that need Ollama calls
+    const uncachedIndices = [];
+    for (let i = 0; i < texts.length; i++) {
+        const key = simpleHash(texts[i]);
+        const cached = _embeddingCache.get(key);
+        if (cached) {
+            results[i] = cached.embedding;
+        }
+        else {
+            uncachedIndices.push(i);
+        }
+    }
+    if (uncachedIndices.length === 0) {
+        return results;
+    }
+    // Fetch uncached texts from Ollama in batches
+    const uncachedTexts = uncachedIndices.map(i => texts[i]);
+    const ollamaResults = [];
+    // Ollama /api/embed supports batch via `input` array
+    for (let i = 0; i < uncachedTexts.length; i += config.batchSize) {
+        const batch = uncachedTexts.slice(i, i + config.batchSize);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), config.timeout);
+        try {
+            const response = await fetch(`${config.ollamaUrl}/api/embed`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: config.model,
+                    input: batch,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Ollama embedding failed: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            for (const embedding of data.embeddings) {
+                if (embedding.length !== config.dimensions) {
+                    throw new Error(`Embedding dimension mismatch: expected ${config.dimensions}, got ${embedding.length}`);
+                }
+                ollamaResults.push(new Float32Array(embedding));
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // Populate cache and fill results array
+    for (let j = 0; j < uncachedIndices.length; j++) {
+        const origIdx = uncachedIndices[j];
+        const embedding = ollamaResults[j];
+        results[origIdx] = embedding;
+        cachePut(simpleHash(texts[origIdx]), embedding, maxSize);
+    }
+    return results;
+}
+/**
+ * Serialize a Float32Array to Uint8Array for sqlite-vec binding.
+ */
+function vecToBytes(vec) {
+    return new Uint8Array(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+/**
+ * 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 class VectorStore {
+    db; // vectors.db
+    libraryDb; // library.db for source content
+    config;
+    constructor(db, config, libraryDb) {
+        this.db = db;
+        this.libraryDb = libraryDb || null;
+        this.config = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
+    }
+    /**
+     * Create vector index tables if they don't exist.
+     * Safe to call multiple times (idempotent).
+     */
+    ensureTables() {
+        const dim = this.config.dimensions;
+        // Vector index for facts
+        this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS vec_facts
+      USING vec0(embedding float[${dim}])
+    `);
+        // Vector index for knowledge
+        this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS vec_knowledge
+      USING vec0(embedding float[${dim}])
+    `);
+        // Vector index for episodes
+        this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS vec_episodes
+      USING vec0(embedding float[${dim}])
+    `);
+        // Vector index for session registry (library DB)
+        // This is created separately via ensureSessionRegistryTable()
+        // Mapping table: links vec rowids to source table rows
+        // Using a single mapping table for all vec tables
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS vec_index_map (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        source_table TEXT NOT NULL,
+        source_id INTEGER NOT NULL,
+        vec_table TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        indexed_at TEXT NOT NULL,
+        UNIQUE(source_table, source_id)
+      )
+    `);
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_vec_map_source ON vec_index_map(source_table, source_id)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_vec_map_vec ON vec_index_map(vec_table, id)');
+    }
+    /**
+     * 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. */
+    static ALLOWED_SOURCE_TABLES = new Set(['facts', 'knowledge', 'episodes', 'sessions']);
+    validateSourceTable(sourceTable) {
+        if (!VectorStore.ALLOWED_SOURCE_TABLES.has(sourceTable)) {
+            throw new Error(`Invalid sourceTable: "${sourceTable}". Must be one of: ${[...VectorStore.ALLOWED_SOURCE_TABLES].join(', ')}`);
+        }
+    }
+    async indexItem(sourceTable, sourceId, content, domain) {
+        this.validateSourceTable(sourceTable);
+        const vecTable = `vec_${sourceTable}`;
+        const contentHash = simpleHash(content);
+        // Check if already indexed with same content
+        const existing = this.db
+            .prepare('SELECT id, content_hash FROM vec_index_map WHERE source_table = ? AND source_id = ?')
+            .get(sourceTable, sourceId);
+        if (existing && existing.content_hash === contentHash) {
+            return false; // Already indexed, content unchanged
+        }
+        // Generate embedding
+        const [embedding] = await generateEmbeddings([content], this.config);
+        const bytes = vecToBytes(embedding);
+        if (existing) {
+            // Update: delete old vector, insert new
+            this.db.prepare(`DELETE FROM ${vecTable} WHERE rowid = CAST(? AS INTEGER)`).run(existing.id);
+            this.db.prepare(`INSERT INTO ${vecTable}(rowid, embedding) VALUES (CAST(? AS INTEGER), ?)`).run(existing.id, bytes);
+            this.db
+                .prepare('UPDATE vec_index_map SET content_hash = ?, indexed_at = ? WHERE id = ?')
+                .run(contentHash, new Date().toISOString(), existing.id);
+        }
+        else {
+            // Insert new mapping row first to get the rowid
+            const mapResult = this.db
+                .prepare('INSERT INTO vec_index_map (source_table, source_id, vec_table, content_hash, indexed_at) VALUES (?, ?, ?, ?, ?)')
+                .run(sourceTable, sourceId, vecTable, contentHash, new Date().toISOString());
+            const mapRowId = Number(mapResult.lastInsertRowid);
+            // Insert vector with matching rowid
+            this.db.prepare(`INSERT INTO ${vecTable}(rowid, embedding) VALUES (CAST(? AS INTEGER), ?)`).run(mapRowId, bytes);
+        }
+        return true;
+    }
+    /**
+     * Batch index multiple items. More efficient than individual calls.
+     */
+    async indexBatch(items) {
+        let indexed = 0;
+        let skipped = 0;
+        // Validate all source tables before processing any items
+        for (const item of items) {
+            this.validateSourceTable(item.sourceTable);
+        }
+        // Filter out already-indexed items
+        const toIndex = [];
+        for (const item of items) {
+            const contentHash = simpleHash(item.content);
+            const existing = this.db
+                .prepare('SELECT content_hash FROM vec_index_map WHERE source_table = ? AND source_id = ?')
+                .get(item.sourceTable, item.sourceId);
+            if (existing && existing.content_hash === contentHash) {
+                skipped++;
+            }
+            else {
+                toIndex.push(item);
+            }
+        }
+        if (toIndex.length === 0)
+            return { indexed, skipped };
+        // Batch generate embeddings
+        const texts = toIndex.map(item => item.content);
+        const embeddings = await generateEmbeddings(texts, this.config);
+        // Insert in a transaction
+        this.db.exec('BEGIN');
+        try {
+            for (let i = 0; i < toIndex.length; i++) {
+                const item = toIndex[i];
+                const embedding = embeddings[i];
+                const vecTable = `vec_${item.sourceTable}`;
+                const contentHash = simpleHash(item.content);
+                const bytes = vecToBytes(embedding);
+                // Check for existing mapping (might need update vs insert)
+                const existing = this.db
+                    .prepare('SELECT id FROM vec_index_map WHERE source_table = ? AND source_id = ?')
+                    .get(item.sourceTable, item.sourceId);
+                if (existing) {
+                    this.db.prepare(`DELETE FROM ${vecTable} WHERE rowid = CAST(? AS INTEGER)`).run(existing.id);
+                    this.db.prepare(`INSERT INTO ${vecTable}(rowid, embedding) VALUES (CAST(? AS INTEGER), ?)`).run(existing.id, bytes);
+                    this.db
+                        .prepare('UPDATE vec_index_map SET content_hash = ?, indexed_at = ? WHERE id = ?')
+                        .run(contentHash, new Date().toISOString(), existing.id);
+                }
+                else {
+                    const mapResult = this.db
+                        .prepare('INSERT INTO vec_index_map (source_table, source_id, vec_table, content_hash, indexed_at) VALUES (?, ?, ?, ?, ?)')
+                        .run(item.sourceTable, item.sourceId, vecTable, contentHash, new Date().toISOString());
+                    const mapRowId = Number(mapResult.lastInsertRowid);
+                    this.db.prepare(`INSERT INTO ${vecTable}(rowid, embedding) VALUES (CAST(? AS INTEGER), ?)`).run(mapRowId, bytes);
+                }
+                indexed++;
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+        return { indexed, skipped };
+    }
+    /**
+     * 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.
+     */
+    async search(query, opts) {
+        const limit = opts?.limit || 10;
+        const tables = opts?.tables || ['facts', 'knowledge', 'episodes'];
+        // Validate all table names before any SQL construction
+        for (const table of tables) {
+            this.validateSourceTable(table);
+        }
+        // Use precomputed embedding if provided, otherwise call Ollama
+        let queryEmbedding;
+        if (opts?.precomputedEmbedding) {
+            queryEmbedding = opts.precomputedEmbedding;
+            // Populate LRU cache so subsequent queries for the same text hit
+            const maxSize = this.config.cacheSize ?? 128;
+            cachePut(simpleHash(query), queryEmbedding, maxSize);
+        }
+        else {
+            [queryEmbedding] = await generateEmbeddings([query], this.config);
+        }
+        const queryBytes = vecToBytes(queryEmbedding);
+        const results = [];
+        for (const table of tables) {
+            const vecTable = `vec_${table}`;
+            // Check if the vec table exists
+            const tableExists = this.db
+                .prepare("SELECT count(*) as cnt FROM sqlite_master WHERE type='table' AND name=?")
+                .get(vecTable);
+            if (!tableExists || tableExists.cnt === 0)
+                continue;
+            // KNN query
+            const rows = this.db
+                .prepare(`SELECT rowid, distance 
+           FROM ${vecTable} 
+           WHERE embedding MATCH ? 
+           ORDER BY distance 
+           LIMIT ?`)
+                .all(queryBytes, limit);
+            for (const row of rows) {
+                if (opts?.maxDistance !== undefined && row.distance > opts.maxDistance)
+                    continue;
+                // Look up source from mapping table
+                const mapping = this.db
+                    .prepare('SELECT source_table, source_id FROM vec_index_map WHERE id = ?')
+                    .get(row.rowid);
+                if (!mapping)
+                    continue;
+                // Fetch actual content from source table
+                const sourceContent = this.getSourceContent(mapping.source_table, mapping.source_id);
+                if (!sourceContent)
+                    continue;
+                results.push({
+                    rowid: row.rowid,
+                    distance: row.distance,
+                    sourceTable: mapping.source_table,
+                    sourceId: mapping.source_id,
+                    content: sourceContent.content,
+                    domain: sourceContent.domain,
+                    agentId: sourceContent.agentId,
+                    metadata: sourceContent.metadata,
+                });
+            }
+        }
+        // Sort all results by distance (cross-table)
+        results.sort((a, b) => a.distance - b.distance);
+        return results.slice(0, limit);
+    }
+    /**
+     * Get content from a source table by id.
+     */
+    getSourceContent(table, id) {
+        // Source content lives in the library DB (facts, knowledge, episodes)
+        // or in the vector DB itself (if old schema). Try library first.
+        const sourceDb = this.libraryDb || this.db;
+        switch (table) {
+            case 'facts': {
+                const row = sourceDb
+                    .prepare('SELECT content, domain, agent_id FROM facts WHERE id = ? AND superseded_by IS NULL')
+                    .get(id);
+                return row ? { content: row.content, domain: row.domain, agentId: row.agent_id } : null;
+            }
+            case 'knowledge': {
+                const row = sourceDb
+                    .prepare('SELECT content, domain, agent_id, key FROM knowledge WHERE id = ? AND superseded_by IS NULL')
+                    .get(id);
+                return row
+                    ? { content: row.content, domain: row.domain, agentId: row.agent_id, metadata: row.key }
+                    : null;
+            }
+            case 'episodes': {
+                const row = sourceDb
+                    .prepare('SELECT summary, event_type, agent_id, participants FROM episodes WHERE id = ?')
+                    .get(id);
+                return row
+                    ? {
+                        content: row.summary,
+                        domain: row.event_type,
+                        agentId: row.agent_id,
+                        metadata: row.participants,
+                    }
+                    : null;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Index all un-indexed content in the agent's database.
+     * Called by the background indexer.
+     */
+    async indexAll(agentId) {
+        const items = [];
+        const sourceDb = this.libraryDb || this.db;
+        // Count already-indexed items for accurate skip reporting
+        const alreadyIndexed = this.db
+            .prepare('SELECT COUNT(*) as cnt FROM vec_index_map')
+            .get().cnt;
+        // Get IDs already indexed (in vector DB)
+        const indexedFacts = new Set(this.db.prepare("SELECT source_id FROM vec_index_map WHERE source_table = 'facts'")
+            .all().map(r => r.source_id));
+        const indexedKnowledge = new Set(this.db.prepare("SELECT source_id FROM vec_index_map WHERE source_table = 'knowledge'")
+            .all().map(r => r.source_id));
+        const indexedEpisodes = new Set(this.db.prepare("SELECT source_id FROM vec_index_map WHERE source_table = 'episodes'")
+            .all().map(r => r.source_id));
+        // Collect un-indexed facts from library DB
+        const facts = sourceDb
+            .prepare('SELECT id, content, domain FROM facts WHERE agent_id = ? AND superseded_by IS NULL')
+            .all(agentId);
+        for (const f of facts) {
+            if (!indexedFacts.has(f.id)) {
+                items.push({ sourceTable: 'facts', sourceId: f.id, content: f.content });
+            }
+        }
+        // Collect un-indexed knowledge from library DB
+        const knowledge = sourceDb
+            .prepare('SELECT id, content, domain, key FROM knowledge WHERE agent_id = ? AND superseded_by IS NULL')
+            .all(agentId);
+        for (const k of knowledge) {
+            if (!indexedKnowledge.has(k.id)) {
+                items.push({
+                    sourceTable: 'knowledge',
+                    sourceId: k.id,
+                    content: `${k.key}: ${k.content}`,
+                });
+            }
+        }
+        // Collect un-indexed episodes from library DB
+        const episodes = sourceDb
+            .prepare('SELECT id, summary, event_type FROM episodes WHERE agent_id = ?')
+            .all(agentId);
+        for (const e of episodes) {
+            if (!indexedEpisodes.has(e.id)) {
+                items.push({ sourceTable: 'episodes', sourceId: e.id, content: e.summary });
+            }
+        }
+        if (items.length === 0) {
+            return { indexed: 0, skipped: alreadyIndexed };
+        }
+        const result = await this.indexBatch(items);
+        return { indexed: result.indexed, skipped: result.skipped + alreadyIndexed };
+    }
+    /**
+     * Remove vector index entries for deleted source rows.
+     */
+    pruneOrphans() {
+        let pruned = 0;
+        const sourceDb = this.libraryDb || this.db;
+        for (const table of ['facts', 'knowledge', 'episodes']) {
+            // Get all indexed IDs for this table
+            const indexed = this.db
+                .prepare('SELECT id, vec_table, source_id FROM vec_index_map WHERE source_table = ?')
+                .all(table);
+            for (const entry of indexed) {
+                // Check if source still exists in library DB
+                const exists = sourceDb
+                    .prepare(`SELECT 1 FROM ${table} WHERE id = ?`)
+                    .get(entry.source_id);
+                if (!exists) {
+                    this.db.prepare(`DELETE FROM ${entry.vec_table} WHERE rowid = CAST(? AS INTEGER)`).run(entry.id);
+                    this.db.prepare('DELETE FROM vec_index_map WHERE id = ?').run(entry.id);
+                    pruned++;
+                }
+            }
+        }
+        return pruned;
+    }
+    /**
+     * 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, sourceId) {
+        this.validateSourceTable(sourceTable);
+        const entry = this.db
+            .prepare('SELECT id, vec_table FROM vec_index_map WHERE source_table = ? AND source_id = ?')
+            .get(sourceTable, sourceId);
+        if (!entry)
+            return false;
+        this.db.prepare(`DELETE FROM ${entry.vec_table} WHERE rowid = CAST(? AS INTEGER)`).run(entry.id);
+        this.db.prepare('DELETE FROM vec_index_map WHERE id = ?').run(entry.id);
+        return true;
+    }
+    /**
+     * Check whether a source item already has a vector in the index.
+     * Used by the episode backfill to skip already-vectorized entries.
+     */
+    hasItem(sourceTable, sourceId) {
+        this.validateSourceTable(sourceTable);
+        const row = this.db
+            .prepare('SELECT 1 FROM vec_index_map WHERE source_table = ? AND source_id = ? LIMIT 1')
+            .get(sourceTable, sourceId);
+        return row !== undefined;
+    }
+    /**
+     * 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() {
+        const sourceDb = this.libraryDb || this.db;
+        let tombstoned = 0;
+        for (const table of ['facts', 'knowledge']) {
+            // Find all indexed entries whose source row has been superseded
+            const indexed = this.db
+                .prepare('SELECT vim.id, vim.vec_table, vim.source_id FROM vec_index_map vim WHERE vim.source_table = ?')
+                .all(table);
+            for (const entry of indexed) {
+                const row = sourceDb
+                    .prepare(`SELECT superseded_by FROM ${table} WHERE id = ?`)
+                    .get(entry.source_id);
+                if (row?.superseded_by != null) {
+                    // Remove from vector table
+                    this.db.prepare(`DELETE FROM ${entry.vec_table} WHERE rowid = CAST(? AS INTEGER)`).run(entry.id);
+                    // Remove from index map
+                    this.db.prepare('DELETE FROM vec_index_map WHERE id = ?').run(entry.id);
+                    tombstoned++;
+                }
+            }
+        }
+        if (tombstoned > 0) {
+            console.log(`[hypermem-vector] tombstoneSuperseded: removed ${tombstoned} stale vector entries`);
+        }
+        return tombstoned;
+    }
+    /**
+     * Get index statistics.
+     */
+    getStats() {
+        const breakdown = {};
+        let total = 0;
+        for (const table of ['facts', 'knowledge', 'episodes']) {
+            const count = this.db
+                .prepare('SELECT COUNT(*) as cnt FROM vec_index_map WHERE source_table = ?')
+                .get(table);
+            breakdown[table] = count.cnt;
+            total += count.cnt;
+        }
+        const lastIndexed = this.db
+            .prepare('SELECT MAX(indexed_at) as last_at FROM vec_index_map')
+            .get();
+        return {
+            totalVectors: total,
+            tableBreakdown: breakdown,
+            lastIndexedAt: lastIndexed.last_at,
+        };
+    }
+}
+/**
+ * SHA-256 content hash for change detection and deduplication.
+ * Replaces the prior 32-bit rolling hash which had collision risk on large corpora.
+ */
+function simpleHash(str) {
+    return createHash('sha256').update(str).digest('hex').slice(0, 16);
+}
+/**
+ * Create vector tables in a library database for session registry search.
+ */
+export function ensureSessionVecTable(db, dimensions = 768) {
+    db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS vec_sessions
+    USING vec0(embedding float[${dimensions}])
+  `);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS vec_session_map (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL UNIQUE,
+      content_hash TEXT NOT NULL,
+      indexed_at TEXT NOT NULL
+    )
+  `);
+}
+//# sourceMappingURL=vector-store.js.map