brainbank 0.1.3 → 0.1.4

package/src/providers/pruners/haiku-expander.ts

@@ -0,0 +1,178 @@
+/**
+ * BrainBank — Haiku Expander
+ *
+ * LLM-powered context expansion using Anthropic's Haiku 4.5 model.
+ * After search + pruning, reviews a manifest of available chunks
+ * and requests additional IDs to include.
+ *
+ * Flow:
+ *   1. Receives lightweight manifest (~20 chars per chunk)
+ *   2. Haiku selects additional chunk IDs (just numbers, fast)
+ *   3. Caller fetches those chunks from DB and splices into results
+ *
+ * Designed for minimal token usage:
+ *   - Input: ~2,000-3,000 tokens (manifest)
+ *   - Output: ~50-100 tokens (ID array)
+ *   - Cost: ~$0.001 per call
+ *   - Latency: ~300-600ms
+ *
+ * Fail-open: any error returns empty array (no expansion).
+ */
+
+import type { Expander, ExpanderManifestItem, ExpanderResult } from '@/types.ts';
+
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+const _debug = !!process.env.BRAINBANK_DEBUG;
+function dbg(msg: string): void { if (_debug) console.error(msg); }
+
+export interface HaikuExpanderOptions {
+    /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Default: claude-haiku-4-5-20251001 */
+    model?: string;
+}
+
+export class HaikuExpander implements Expander {
+    private readonly _apiKey: string;
+    private readonly _model: string;
+
+    constructor(options: HaikuExpanderOptions = {}) {
+        this._apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '';
+        this._model = options.model ?? DEFAULT_MODEL;
+
+        if (!this._apiKey) {
+            throw new Error(
+                'HaikuExpander: No API key provided. Set ANTHROPIC_API_KEY env var or pass apiKey option.',
+            );
+        }
+    }
+
+    async expand(
+        query: string,
+        currentIds: number[],
+        manifest: ExpanderManifestItem[],
+        context?: string,
+    ): Promise<ExpanderResult> {
+        if (manifest.length === 0) return { ids: [] };
+
+        // Filter out chunks already in results
+        const currentSet = new Set(currentIds);
+        const available = manifest.filter(m => !currentSet.has(m.id));
+        if (available.length === 0) return { ids: [] };
+
+        // Split manifest into priority (import-graph neighbors) and general
+        const priorityChunks = available.filter(m => m.priority);
+        const otherChunks = available.filter(m => !m.priority);
+
+        const currentSummary = manifest
+            .filter(m => currentSet.has(m.id))
+            .map(m => `#${m.id} ${m.filePath} | ${m.chunkType} ${m.name}`)
+            .join('\n');
+
+        // Build manifest sections
+        let manifestSection = '';
+        if (priorityChunks.length > 0) {
+            const prioLines = priorityChunks.map(m => {
+                const base = `#${m.id} ${m.filePath} | ${m.chunkType} ${m.name} ${m.lines}`;
+                return m.synopsis ? `${base} — ${m.synopsis}` : base;
+            }).join('\n');
+            manifestSection += `DEPENDENCY chunks (imported by or importing the search result files):\n${prioLines}\n\n`;
+            const synopsisCount = priorityChunks.filter(m => m.synopsis).length;
+            dbg(`[HaikuExpander] ${priorityChunks.length} priority chunks (${synopsisCount} with synopsis)`);
+        }
+        if (otherChunks.length > 0) {
+            const otherLines = otherChunks.map(m =>
+                `#${m.id} ${m.filePath} | ${m.chunkType} ${m.name} ${m.lines}`
+            ).join('\n');
+            manifestSection += `Other available chunks:\n${otherLines}`;
+        }
+
+        const contextSection = context
+            ? `\nTask Context:\n"""\n${context.slice(0, 2000)}\n"""\n\n`
+            : '';
+
+        const prompt =
+            `Task: "${query}"\n${contextSection}` +
+            `Already included chunks:\n${currentSummary}\n\n` +
+            `${manifestSection}\n\n` +
+            `You are a code context expander. The search already found the "included" chunks above.\n` +
+            `Review the available chunks and select any that would help an AI agent complete the task.\n\n` +
+            `Rules:\n` +
+            `- STRONGLY PREFER dependency chunks — they are structurally connected to the search results via imports\n` +
+            `- Select type definitions, interfaces, models, or configs needed to understand included code\n` +
+            `- Select initialization or setup code if the task involves debugging or modifying a feature\n` +
+            `- Do NOT select test files, documentation, or unrelated utilities\n` +
+            `- Be selective: only include chunks that fill clear gaps. Quality over quantity.\n` +
+            `- If nothing useful is available, return an empty ids array\n\n` +
+            `Respond with ONLY a JSON object:\n` +
+            `{ "ids": [42, 17, 89], "note": "Brief 1-2 sentence observation about the codebase relevant to the task" }\n\n` +
+            `The "note" is optional — use it to mention things like missing files, architectural patterns, ` +
+            `deprecated modules, or important relationships you noticed. If nothing notable, omit it.\n` +
+            `If nothing to add: { "ids": [] }`;
+
+        try {
+            const response = await fetch('https://api.anthropic.com/v1/messages', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this._apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify({
+                    model: this._model,
+                    max_tokens: 512,
+                    messages: [{
+                        role: 'user',
+                        content: prompt,
+                    }],
+                }),
+            });
+
+            if (!response.ok) {
+                return { ids: [] };
+            }
+
+            const data = await response.json() as {
+                content: { type: string; text: string }[];
+            };
+
+            const text = data.content?.[0]?.text ?? '';
+            dbg(`[HaikuExpander] Raw response: ${text.slice(0, 300)}${text.length > 300 ? '...' : ''}`);
+            return this._parseResponse(text, available);
+        } catch (err) {
+            dbg(`[HaikuExpander] Error: ${err instanceof Error ? err.message : String(err)}`);
+            return { ids: [] };
+        }
+    }
+
+    /** Parse Haiku response — handles both `{ ids, note }` and bare `[...]` formats. */
+    private _parseResponse(text: string, available: ExpanderManifestItem[]): ExpanderResult {
+        const validIds = new Set(available.map(m => m.id));
+
+        // Try JSON object first: { "ids": [...], "note": "..." }
+        const objMatch = text.match(/\{[\s\S]*"ids"\s*:\s*\[[\d\s,]*\][\s\S]*\}/);
+        if (objMatch) {
+            try {
+                const parsed = JSON.parse(objMatch[0]) as { ids: number[]; note?: string };
+                const ids = parsed.ids.filter(id => validIds.has(id));
+                const note = parsed.note?.trim() || undefined;
+                return { ids, note };
+            } catch {
+                // Fall through to array parsing
+            }
+        }
+
+        // Fallback: bare array [42, 17, 89]
+        const arrMatch = text.match(/\[[\d\s,]*\]/);
+        if (arrMatch) {
+            const ids = (JSON.parse(arrMatch[0]) as number[]).filter(id => validIds.has(id));
+            return { ids };
+        }
+
+        return { ids: [] };
+    }
+
+    async close(): Promise<void> {
+        // No resources to release (stateless HTTP)
+    }
+}

package/src/providers/pruners/haiku-pruner.ts

@@ -0,0 +1,263 @@
+/**
+ * BrainBank — LLM Pruner
+ *
+ * LLM-based noise filter using Anthropic models (Haiku 4.5 or Sonnet 4.6).
+ * Binary classification: for each search result, the model decides
+ * "relevant" or "noise" based on filePath, metadata, and full
+ * file content (capped at ~8K chars per item by prune.ts).
+ *
+ * Latency: ~300-600ms (Haiku), ~500-1200ms (Sonnet).
+ */
+
+import type { Pruner, PrunerItem } from '@/types.ts';
+import * as fs from 'node:fs';
+
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+
+/** Budget map keyed by model prefix. Sonnet 4.6 has a larger context window. */
+const MODEL_BUDGETS: Record<string, number> = {
+    'claude-haiku': 700_000,   // ~180K tokens ≈ ~720K chars
+    'claude-sonnet': 900_000,  // ~200K tokens ≈ ~900K chars (Sonnet 4.6)
+};
+
+function _getBudget(model: string): number {
+    for (const [prefix, budget] of Object.entries(MODEL_BUDGETS)) {
+        if (model.startsWith(prefix)) return budget;
+    }
+    return 700_000; // Default: conservative budget
+}
+
+const _debug = !!process.env.BRAINBANK_DEBUG;
+function dbg(msg: string): void { if (_debug) console.error(msg); }
+
+export interface HaikuPrunerOptions {
+    /** Anthropic API key. Falls back to ANTHROPIC_API_KEY env var. */
+    apiKey?: string;
+    /** Model to use. Default: claude-haiku-4-5-20251001 */
+    model?: string;
+}
+
+export class HaikuPruner implements Pruner {
+    private readonly _apiKey: string;
+    private readonly _model: string;
+
+    constructor(options: HaikuPrunerOptions = {}) {
+        this._apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '';
+        this._model = options.model ?? DEFAULT_MODEL;
+
+        if (!this._apiKey) {
+            throw new Error(
+                'HaikuPruner: No API key provided. Set ANTHROPIC_API_KEY env var or pass apiKey option.',
+            );
+        }
+    }
+
+    async prune(query: string, items: PrunerItem[], context?: string): Promise<number[]> {
+        if (items.length === 0) return [];
+        if (items.length === 1) return [items[0].id];
+
+        // ── Adaptive preview truncation ──
+        // Estimate total chars and truncate previews if we'd exceed token budget
+        const budget = _getBudget(this._model);
+        let totalChars = _estimatePromptChars(query, items);
+        if (totalChars > budget && items.length > 1) {
+            // Calculate max preview chars per item to fit budget
+            const overheadPerItem = 200; // filePath + metadata + separators
+            const promptOverhead = 1500 + (context ? context.length : 0); // system prompt + rules + context
+            const availableForPreviews = budget - promptOverhead - (items.length * overheadPerItem);
+            const maxPreviewPerItem = Math.max(1000, Math.floor(availableForPreviews / items.length));
+
+            dbg(`[Pruner:${this._model}] Budget overflow: ${totalChars} chars for ${items.length} items (budget: ${budget}). Truncating previews to ${maxPreviewPerItem} chars each.`);
+
+            for (const item of items) {
+                if (item.preview.length > maxPreviewPerItem) {
+                    item.preview = _truncatePreview(item.preview, maxPreviewPerItem);
+                }
+            }
+
+            totalChars = _estimatePromptChars(query, items);
+            dbg(`[Pruner:${this._model}] After truncation: ${totalChars} chars`);
+        }
+
+        const itemLines = items.map(item => {
+            // Only show useful metadata fields (skip raw scores, IDs, large arrays)
+            const SKIP_KEYS = new Set(['id', 'chunkIds', 'rrfScore', 'filePath']);
+            const meta = Object.entries(item.metadata)
+                .filter(([k, v]) => v !== undefined && v !== null && !SKIP_KEYS.has(k))
+                .map(([k, v]) => `${k}=${v}`)
+                .join(' | ');
+            return `#${item.id} ${item.filePath} | ${meta}\n${item.preview}`;
+        }).join('\n---\n');
+
+        // Build context section if provided
+        const contextSection = context
+            ? `\nTask Context:\n"""\n${context.slice(0, 2000)}\n"""\n\n`
+            : '';
+
+        const prompt =
+            `Query: "${query}"\n${contextSection}Search results (full file content):\n${itemLines}\n\n` +
+            `You are a precision search filter. Remove noise but NEVER drop core implementation files.\n` +
+            `Return a JSON array of #IDs to KEEP, ordered by relevance (most relevant FIRST).\n` +
+            `${context ? 'Use the Task Context to understand EXACTLY what the user needs — keep files that would be needed to implement the described change.\n' : ''}` +
+            `\nKEEP (any ONE of these is enough):\n` +
+            `- File contains the method/handler/function that performs the queried action.\n` +
+            `- File defines the entity, types, or state machine for the queried system.\n` +
+            `- File is the controller/route that exposes the queried feature.\n` +
+            `- File orchestrates or composes the queried workflow (even if it also handles other workflows).\n` +
+            `- Service files that handle the queried action alongside other actions → KEEP (they contain the implementation).\n\n` +
+            `DROP (any ONE of these triggers a drop):\n` +
+            `- File is from a DIFFERENT domain that shares vocabulary with the query.\n` +
+            `  Example: query "job encounter time" → DROP priority.entity.ts, notification.worker.ts\n` +
+            `- Database seeders, migrations, test fixtures — unless query asks about seeding/migration.\n` +
+            `- Generic infrastructure: loggers, config factories, decorators — unless query targets that infra.\n` +
+            `- File where the queried concept appears only as an import, foreign key, or one-line reference.\n` +
+            `- Permission configs — unless query is about permissions/auth.\n` +
+            `- DTOs that only mirror entity fields without adding logic.\n\n` +
+            `Target: 25-50% keep rate. Drop infrastructure/boilerplate aggressively, but NEVER drop a service that implements the queried action.\n` +
+            `Order: core implementation → entity/types → controller/service → peripheral.\n\n` +
+            `Respond with ONLY the JSON array. Example: [3, 0, 5]`;
+
+        try {
+            const response = await fetch('https://api.anthropic.com/v1/messages', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this._apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify({
+                    model: this._model,
+                    max_tokens: 512,
+                    messages: [{
+                        role: 'user',
+                        content: prompt,
+                    }],
+                }),
+            });
+
+            if (!response.ok) {
+                const body = await response.text().catch(() => '');
+                // API error → fail-open, return all — but LOG IT
+                console.error(`[Pruner:${this._model}] API error: ${response.status} ${response.statusText} (${items.length} items, ~${Math.round(totalChars / 1000)}K chars) — keeping all. ${body.slice(0, 200)}`);
+                return items.map(i => i.id);
+            }
+
+            const data = await response.json() as {
+                content: { type: string; text: string }[];
+                usage?: {
+                    input_tokens: number;
+                    output_tokens: number;
+                    cache_creation_input_tokens?: number;
+                    cache_read_input_tokens?: number;
+                };
+            };
+
+            // ── Cost tracking (authoritative: these are Anthropic's exact billing counts) ──
+            const usage = data.usage;
+            if (usage) {
+                const cost = _estimateCost(this._model, usage);
+                const parts = [
+                    `${usage.input_tokens} in`,
+                    `${usage.output_tokens} out`,
+                ];
+                if (usage.cache_creation_input_tokens) parts.push(`${usage.cache_creation_input_tokens} cache_write`);
+                if (usage.cache_read_input_tokens) parts.push(`${usage.cache_read_input_tokens} cache_read`);
+                const costLine = `[Pruner] ${this._model} — ${parts.join(' + ')} = $${cost.toFixed(4)}`;
+                dbg(costLine);
+                // Append to brainbank.log (daemon stdio is 'ignore' so console.error is lost)
+                try { fs.appendFileSync('/tmp/brainbank.log', costLine + '\n'); } catch { /* best effort */ }
+            }
+
+            const text = data.content?.[0]?.text ?? '';
+            dbg(`[Pruner:${this._model}] Raw response: ${text}`);
+            // Haiku may wrap in ```json ... ``` — extract any JSON array
+            const match = text.match(/\[[\d\s,]+\]/);
+            if (!match) {
+                console.error(`[Pruner:${this._model}] No JSON array found in response — keeping all ${items.length} items. Raw: ${text.slice(0, 200)}`);
+                return items.map(i => i.id);
+            }
+
+            const keepIds = JSON.parse(match[0]) as number[];
+            const validIds = new Set(items.map(i => i.id));
+            const filtered = keepIds.filter(id => validIds.has(id));
+            dbg(`[HaikuPruner] Keep IDs: [${filtered.join(', ')}] (${items.length - filtered.length} dropped)`);
+            return filtered;
+        } catch (err) {
+            // Network error → fail-open, return all — but LOG IT
+            console.error(`[Pruner:${this._model}] Error: ${err instanceof Error ? err.message : String(err)} (${items.length} items) — keeping all`);
+            return items.map(i => i.id);
+        }
+    }
+
+    async close(): Promise<void> {
+        // No resources to release (stateless HTTP)
+    }
+}
+
+// ── Helpers ──────────────────────────────────────────
+
+/** Per-million-token pricing for supported models (May 2026). */
+const MODEL_PRICING: Record<string, { input: number; output: number }> = {
+    'claude-haiku':  { input: 1.00, output: 5.00 },   // Haiku 4.5
+    'claude-sonnet': { input: 3.00, output: 15.00 },   // Sonnet 4.6
+};
+
+interface UsageInfo {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+
+/**
+ * Calculate USD cost from the API's authoritative usage counts.
+ * Cache pricing: writes cost 1.25x input, reads cost 0.1x input.
+ */
+function _estimateCost(model: string, usage: UsageInfo): number {
+    let pricing = { input: 3.00, output: 15.00 }; // Default to Sonnet
+    for (const [prefix, p] of Object.entries(MODEL_PRICING)) {
+        if (model.startsWith(prefix)) { pricing = p; break; }
+    }
+    const inputCost = usage.input_tokens * pricing.input;
+    const outputCost = usage.output_tokens * pricing.output;
+    const cacheWriteCost = (usage.cache_creation_input_tokens ?? 0) * pricing.input * 1.25;
+    const cacheReadCost = (usage.cache_read_input_tokens ?? 0) * pricing.input * 0.1;
+    return (inputCost + outputCost + cacheWriteCost + cacheReadCost) / 1_000_000;
+}
+
+/** Estimate total prompt chars for budget checking. */
+function _estimatePromptChars(query: string, items: PrunerItem[]): number {
+    const promptOverhead = 1500;
+    let total = promptOverhead + query.length;
+    for (const item of items) {
+        total += item.filePath.length + item.preview.length + 200; // 200 for metadata + separators
+    }
+    return total;
+}
+
+/**
+ * Truncate a preview to fit within a character budget.
+ * Keeps top 60% + bottom 25% of lines (same strategy as prune.ts _buildPreview).
+ */
+function _truncatePreview(content: string, maxChars: number): string {
+    if (content.length <= maxChars) return content;
+
+    const lines = content.split('\n');
+    const totalLines = lines.length;
+
+    // Keep ~60% from top, ~25% from bottom
+    const topCount = Math.floor(totalLines * 0.6);
+    const bottomCount = Math.floor(totalLines * 0.25);
+    const omitted = totalLines - topCount - bottomCount;
+
+    let result = lines.slice(0, topCount).join('\n') +
+        `\n\n// [... ${omitted} lines omitted ...]\n\n` +
+        lines.slice(totalLines - bottomCount).join('\n');
+
+    // If still too long, hard-truncate
+    if (result.length > maxChars) {
+        result = result.slice(0, maxChars) + '\n// [truncated]';
+    }
+
+    return result;
+}

package/src/providers/vector/hnsw-index.ts

@@ -0,0 +1,174 @@
+/**
+ * BrainBank — HNSW Vector Index
+ * 
+ * Wraps hnswlib-node for O(log n) approximate nearest neighbor search.
+ * M=16 connections, ef=200 construction, ef=50 search by default.
+ * 150x faster than brute force at 1M vectors.
+ *
+ * Supports disk persistence: save(path) / tryLoad(path, count)
+ * to skip costly vector-by-vector rebuild on startup.
+ */
+
+import type { VectorIndex, SearchHit } from '@/types.ts';
+
+import { existsSync } from 'node:fs';
+
+/** Shape of the HNSW index from hnswlib-node. */
+interface HnswlibIndex {
+    initIndex(maxElements: number, M: number, efConstruction: number): void;
+    setEf(ef: number): void;
+    addPoint(vector: number[], id: number): void;
+    markDelete(id: number): void;
+    searchKnn(vector: number[], k: number): { neighbors: number[]; distances: number[] };
+    writeIndexSync(path: string): void;
+    readIndexSync(path: string): void;
+    getCurrentCount(): number;
+    getIdsList(): number[];
+}
+
+/** Shape of the hnswlib-node module (supports default + named exports). */
+interface HnswlibModule {
+    default?: { HierarchicalNSW: new (space: 'cosine' | 'l2' | 'ip', dims: number) => HnswlibIndex };
+    HierarchicalNSW?: new (space: 'cosine' | 'l2' | 'ip', dims: number) => HnswlibIndex;
+}
+
+export class HNSWIndex implements VectorIndex {
+    private _index: HnswlibIndex | null = null;
+    private _lib: HnswlibModule | null = null;
+    private _ids = new Set<number>();
+
+    constructor(
+        private _dims: number,
+        private _maxElements: number = 2_000_000,
+        private _M: number = 16,
+        private _efConstruction: number = 200,
+        private _efSearch: number = 50,
+    ) {}
+
+    /**
+     * Initialize the HNSW index.
+     * Must be called before add/search.
+     */
+    async init(): Promise<this> {
+        this._lib = await import('hnswlib-node');
+        this._createIndex();
+        return this;
+    }
+
+    /**
+     * Reinitialize the index in-place, clearing all vectors.
+     * Required after reembed or full re-index to avoid duplicate IDs.
+     * init() must have been called first.
+     */
+    reinit(): void {
+        if (!this._lib) throw new Error('HNSW not initialized — call init() first');
+        this._createIndex();
+    }
+
+    private _createIndex(): void {
+        if (!this._lib) throw new Error('HNSW lib not loaded');
+        const HNSW = this._lib.default?.HierarchicalNSW ?? this._lib.HierarchicalNSW;
+        if (!HNSW) throw new Error('HierarchicalNSW not found in hnswlib-node module');
+        this._index = new HNSW('cosine', this._dims);
+        this._index.initIndex(this._maxElements, this._M, this._efConstruction);
+        this._index.setEf(this._efSearch);
+        this._ids = new Set();
+    }
+
+    /** Maximum capacity of this index. */
+    get maxElements(): number { return this._maxElements; }
+
+    /**
+     * Add a vector with an integer ID.
+     * The vector should be pre-normalized for cosine distance.
+     */
+    add(vector: Float32Array, id: number): void {
+        if (!this._index) throw new Error('HNSW index not initialized — call init() first');
+        if (this._ids.has(id)) return; // idempotent: skip duplicates
+        if (this._ids.size >= this._maxElements) {
+            throw new Error(
+                `HNSW index full (${this._maxElements} elements). ` +
+                `Increase maxElements in config or prune old data.`
+            );
+        }
+        this._index.addPoint(Array.from(vector), id);
+        this._ids.add(id);
+    }
+
+    /**
+     * Mark a vector as deleted so it no longer appears in searches.
+     * Uses hnswlib-node markDelete under the hood.
+     * Safe to call with an ID that doesn't exist.
+     */
+    remove(id: number): void {
+        if (!this._index || this._ids.size === 0) return;
+        if (!this._ids.has(id)) return;
+        try {
+            this._index.markDelete(id);
+            this._ids.delete(id);
+        } catch {
+            // ID not found — ignore silently
+        }
+    }
+
+    /**
+     * Search for the k nearest neighbors.
+     * Returns results sorted by score (highest first).
+     * Score is 1 - cosine_distance (1.0 = identical).
+     */
+    search(query: Float32Array, k: number): SearchHit[] {
+        if (!this._index || this._ids.size === 0) return [];
+
+        const actualK = Math.min(k, this._ids.size);
+        const result = this._index.searchKnn(Array.from(query), actualK);
+
+        return result.neighbors.map((id: number, i: number) => ({
+            id,
+            score: 1 - result.distances[i],
+        }));
+    }
+
+    /** Number of vectors in the index. */
+    get size(): number {
+        return this._ids.size;
+    }
+
+    /**
+     * Save the HNSW graph to disk.
+     * The file can be loaded later with tryLoad() to skip vector-by-vector insertion.
+     */
+    save(path: string): void {
+        if (!this._index || this._ids.size === 0) return;
+        this._index.writeIndexSync(path);
+    }
+
+    /**
+     * Try to load a previously saved HNSW index from disk.
+     * Returns true if loaded successfully, false if stale or missing.
+     * @param path File path to the saved index
+     * @param expectedCount Expected number of vectors (from SQLite) — used to detect staleness
+     */
+    tryLoad(path: string, expectedCount: number): boolean {
+        if (!this._index || !existsSync(path)) return false;
+
+        try {
+            this._index.readIndexSync(path);
+            const loadedCount = this._index.getCurrentCount();
+
+            // Stale: vector count in DB differs from saved index
+            if (loadedCount !== expectedCount) {
+                this.reinit();
+                return false;
+            }
+
+            // Rebuild _ids set from the loaded index
+            const ids = this._index.getIdsList();
+            this._ids = new Set(ids);
+            this._index.setEf(this._efSearch);
+            return true;
+        } catch {
+            this.reinit();
+            return false;
+        }
+    }
+}