@robthepcguy/rag-vault 1.7.2 → 1.9.0

package/dist/reranker/index.js

@@ -0,0 +1,199 @@
+// Cross-encoder reranker implementation with Transformers.js
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pipeline } from '@huggingface/transformers';
+const SUPPORTED_DEVICES = [
+    'auto',
+    'gpu',
+    'cpu',
+    'wasm',
+    'webgpu',
+    'cuda',
+    'dml',
+    'webnn',
+    'webnn-npu',
+    'webnn-gpu',
+    'webnn-cpu',
+];
+const SUPPORTED_DEVICE_SET = new Set(SUPPORTED_DEVICES);
+/** Default init timeout: 10 minutes */
+const DEFAULT_INIT_TIMEOUT_MS = 10 * 60 * 1000;
+function getInitTimeoutMs(configValue) {
+    if (configValue !== undefined && configValue > 0)
+        return configValue;
+    const envValue = process.env['RERANKER_INIT_TIMEOUT_MS'];
+    if (envValue) {
+        const parsed = Number.parseInt(envValue, 10);
+        if (!Number.isNaN(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_INIT_TIMEOUT_MS;
+}
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${Math.round(ms / 1000)}s`)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+// ============================================
+// Reranker Class
+// ============================================
+/**
+ * Cross-encoder reranker using Transformers.js
+ *
+ * Scores (query, passage) pairs for relevance using a cross-encoder model.
+ * Unlike bi-encoders, cross-encoders jointly encode both texts, producing
+ * more accurate relevance judgments at the cost of speed.
+ *
+ * Default model: Xenova/ms-marco-MiniLM-L-6-v2 (~23MB ONNX)
+ */
+export class Reranker {
+    // Using unknown to avoid TS2590 (union type too complex with @types/jsdom)
+    model = null;
+    initPromise = null;
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get the model name/path
+     */
+    getModelName() {
+        return this.config.modelPath;
+    }
+    /**
+     * Resolve the device to use for inference
+     */
+    resolveDevice() {
+        // Check config first
+        if (this.config.device && SUPPORTED_DEVICE_SET.has(this.config.device)) {
+            return this.config.device;
+        }
+        // Check environment variable
+        const envDevice = process.env['RAG_RERANKER_DEVICE'] || process.env['RAG_EMBEDDING_DEVICE'];
+        if (envDevice && SUPPORTED_DEVICE_SET.has(envDevice.toLowerCase())) {
+            return envDevice.toLowerCase();
+        }
+        return 'auto';
+    }
+    /**
+     * Get a recovery cache directory for corrupted model caches
+     */
+    getRecoveryCacheDir() {
+        return path.join(this.config.cacheDir, '.recovery-reranker');
+    }
+    /**
+     * Check if an error is recoverable by using a fresh cache
+     */
+    isRecoverableCacheError(error) {
+        if (!(error instanceof Error))
+            return false;
+        const msg = error.message.toLowerCase();
+        return msg.includes('protobuf') || msg.includes('parsing failed') || msg.includes('corrupt');
+    }
+    /**
+     * Initialize Transformers.js cross-encoder model
+     */
+    async initialize() {
+        if (this.model)
+            return;
+        try {
+            const device = this.resolveDevice();
+            const timeoutMs = getInitTimeoutMs(this.config.initTimeoutMs);
+            console.error(`Reranker: Using device preference "${device}"`);
+            console.error(`Reranker: Loading model "${this.config.modelPath}" (timeout: ${Math.round(timeoutMs / 1000)}s)...`);
+            this.model = await withTimeout(pipeline('text-classification', this.config.modelPath, {
+                device,
+                cache_dir: this.config.cacheDir,
+            }), timeoutMs, 'Reranker model initialization');
+            console.error('Reranker: Model loaded successfully');
+        }
+        catch (error) {
+            if (this.isRecoverableCacheError(error)) {
+                const recoveryCacheDir = this.getRecoveryCacheDir();
+                console.error(`Reranker: Detected corrupted cache. Retrying with isolated cache: "${recoveryCacheDir}"`);
+                try {
+                    await mkdir(recoveryCacheDir, { recursive: true });
+                    const device = this.resolveDevice();
+                    this.model = await withTimeout(pipeline('text-classification', this.config.modelPath, {
+                        device,
+                        cache_dir: recoveryCacheDir,
+                    }), getInitTimeoutMs(this.config.initTimeoutMs), 'Reranker model initialization (recovery)');
+                    console.error('Reranker: Model loaded successfully via recovery cache');
+                    return;
+                }
+                catch (recoveryError) {
+                    throw new Error(`Failed to initialize Reranker after cache recovery: ${recoveryError.message}`);
+                }
+            }
+            throw new Error(`Failed to initialize Reranker: ${error.message}`);
+        }
+    }
+    /**
+     * Ensure model is initialized (lazy initialization)
+     */
+    async ensureInitialized() {
+        if (this.model)
+            return;
+        if (this.initPromise) {
+            await this.initPromise;
+            return;
+        }
+        console.error('Reranker: First use detected. Initializing model (downloading ~23MB, may take a moment)...');
+        const initWork = this.initialize().catch((error) => {
+            this.initPromise = null;
+            throw new Error(`Failed to initialize reranker on first use: ${error.message}\n\nPossible causes:\n  • Network connectivity issues during model download\n  • Insufficient disk space\n  • Corrupted model cache\n\nRecommended actions:\n  1. Check your internet connection and try again\n  2. Delete cache: ${this.config.cacheDir}\n  3. Retry your query\n`);
+        });
+        this.initPromise = initWork;
+        await this.initPromise;
+    }
+    /**
+     * Rerank passages by relevance to a query using cross-encoder scoring.
+     *
+     * @param query - The search query
+     * @param passages - Array of passage texts to score
+     * @returns Array of {index, score} sorted by score descending (most relevant first)
+     */
+    async rerank(query, passages) {
+        if (passages.length === 0)
+            return [];
+        await this.ensureInitialized();
+        try {
+            // Runtime check: model must be a callable pipeline
+            if (typeof this.model !== 'function') {
+                throw new Error('Reranker model is not initialized or not callable');
+            }
+            // Cross-encoder expects pairs of (text_a, text_b)
+            // For ms-marco models, we use the text_pair approach
+            const modelCall = this.model;
+            // Prepare inputs: query repeated for each passage
+            const queries = passages.map(() => query);
+            const rawOutputs = await modelCall(queries, { text_pair: passages });
+            // Validate output shape at runtime
+            if (!Array.isArray(rawOutputs)) {
+                throw new Error(`Reranker returned non-array output: ${typeof rawOutputs}`);
+            }
+            // Map results back with original indices
+            const results = rawOutputs.map((output, index) => {
+                const outputObj = output;
+                const rawScore = outputObj && typeof outputObj === 'object' ? Number(outputObj['score']) : 0;
+                return { index, score: Number.isFinite(rawScore) ? rawScore : 0 };
+            });
+            // Sort by score descending (most relevant first)
+            results.sort((a, b) => b.score - a.score);
+            return results;
+        }
+        catch (error) {
+            console.error(`Reranker: Scoring failed: ${error.message}`);
+            // Return original order on failure (graceful degradation)
+            return passages.map((_, index) => ({ index, score: 0 }));
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/reranker/index.js.map

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

package/dist/server/index.d.ts

@@ -21,6 +21,28 @@ export interface RAGServerConfig {
     grouping?: GroupingMode;
     /** Hybrid search weight for BM25 (0.0 = vector only, 1.0 = BM25 only, default 0.6) */
     hybridWeight?: number;
+    /** Enable cross-encoder reranking */
+    rerankerEnabled?: boolean;
+    /** Cross-encoder model name (default: Xenova/ms-marco-MiniLM-L-6-v2) */
+    rerankerModel?: string;
+    /** Reranker candidate multiplier (default: 2) */
+    rerankerCandidateMultiplier?: number;
+    /** Enable HyDE query expansion */
+    hydeEnabled?: boolean;
+    /** HyDE backend: 'rule-based' or 'api' */
+    hydeBackend?: string;
+    /** Number of HyDE expansions (default: 2) */
+    hydeExpansions?: number;
+    /** API key for HyDE API backend (only used when hydeBackend='api') */
+    hydeApiKey?: string;
+    /** API base URL for HyDE API backend */
+    hydeApiBaseUrl?: string;
+    /** API model for HyDE API backend */
+    hydeApiModel?: string;
+    /** Search mode: 'rrf' or 'boost' */
+    searchMode?: string;
+    /** RRF K constant (smoothing factor, default: 60) */
+    rrfK?: number;
 }
 /**
  * RAG server compliant with MCP Protocol
@@ -35,6 +57,9 @@ export declare class RAGServer {
     private readonly server;
     private readonly vectorStore;
     private readonly embedder;
+    private readonly reranker;
+    private readonly rerankerCandidateMultiplier;
+    private readonly hydeExpander;
     private readonly chunker;
     private readonly parser;
     private readonly dbPath;

package/dist/server/index.d.ts.map

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

package/dist/server/index.js

@@ -6,6 +6,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { SemanticChunker } from '../chunker/index.js';
 import { Embedder } from '../embedder/index.js';
+import { HyDEExpander } from '../hyde/index.js';
+import { Reranker } from '../reranker/index.js';
 import { getErrorMessage } from '../errors/index.js';
 import { explainChunkSimilarity } from '../explainability/keywords.js';
 import { getFeedbackStore } from '../flywheel/feedback.js';
@@ -16,6 +18,28 @@ import { VectorStore } from '../vectordb/index.js';
 import { extractSourceFromPath, generateRawDataPath, isManagedRawDataPath, saveRawData, } from './raw-data-utils.js';
 import { DeleteFileSchema, } from './schemas.js';
 // ============================================
+// Constants
+// ============================================
+/** Timeout for VectorStore.initialize() (default: 10 seconds) */
+const VECTORSTORE_INIT_TIMEOUT_MS = Number.parseInt(process.env['VECTORSTORE_INIT_TIMEOUT_MS'] || '10000', 10);
+/** Timeout for MCP transport connect (default: 10 seconds) */
+const MCP_CONNECT_TIMEOUT_MS = Number.parseInt(process.env['MCP_CONNECT_TIMEOUT_MS'] || '10000', 10);
+/**
+ * Wrap a promise with a timeout
+ */
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${Math.round(ms / 1000)}s`)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+// ============================================
 // RAGServer Class
 // ============================================
 /**
@@ -31,6 +55,9 @@ export class RAGServer {
     server;
     vectorStore;
     embedder;
+    reranker;
+    rerankerCandidateMultiplier;
+    hydeExpander;
     chunker;
     parser;
     dbPath;
@@ -55,12 +82,53 @@ export class RAGServer {
         if (config.hybridWeight !== undefined) {
             vectorStoreConfig.hybridWeight = config.hybridWeight;
         }
+        if (config.searchMode !== undefined) {
+            vectorStoreConfig.searchMode = config.searchMode;
+        }
+        if (config.rrfK !== undefined) {
+            vectorStoreConfig.rrfK = config.rrfK;
+        }
         this.vectorStore = new VectorStore(vectorStoreConfig);
         this.embedder = new Embedder({
             modelPath: config.modelName,
             batchSize: 16,
             cacheDir: config.cacheDir,
         });
+        // Cross-encoder reranker (opt-in)
+        if (config.rerankerEnabled) {
+            this.reranker = new Reranker({
+                modelPath: config.rerankerModel || 'Xenova/ms-marco-MiniLM-L-6-v2',
+                cacheDir: config.cacheDir,
+            });
+        }
+        else {
+            this.reranker = null;
+        }
+        this.rerankerCandidateMultiplier = config.rerankerCandidateMultiplier ?? 2;
+        // HyDE query expansion (opt-in)
+        if (config.hydeEnabled) {
+            const hydeConfig = {
+                enabled: true,
+                backend: (config.hydeBackend === 'api' ? 'api' : 'rule-based'),
+                numExpansions: config.hydeExpansions ?? 2,
+            };
+            if (config.hydeApiKey)
+                hydeConfig.apiKey = config.hydeApiKey;
+            if (config.hydeApiBaseUrl)
+                hydeConfig.apiBaseUrl = config.hydeApiBaseUrl;
+            if (config.hydeApiModel)
+                hydeConfig.apiModel = config.hydeApiModel;
+            this.hydeExpander = new HyDEExpander(hydeConfig);
+            if (config.hydeBackend === 'api' && config.hydeApiKey) {
+                console.error('WARNING: HyDE API backend is enabled. Queries will be sent to an external LLM endpoint ' +
+                    `(${config.hydeApiBaseUrl || 'https://api.anthropic.com'}). ` +
+                    'This breaks the "Zero cloud" privacy guarantee. ' +
+                    'Set RAG_HYDE_BACKEND=rule-based to use local-only query expansion.');
+            }
+        }
+        else {
+            this.hydeExpander = null;
+        }
         this.chunker = new SemanticChunker();
         this.parser = new DocumentParser({
             baseDir: config.baseDir,
@@ -83,13 +151,13 @@ export class RAGServer {
      */
     setupHandlers(target = this.server) {
         // query_documents tool
-        target.tool('query_documents', `Search ingested documents using hybrid semantic + keyword search. Advanced syntax supported:
+        target.tool('query_documents', `Search your documents using both meaning and exact keyword matching. You can also use advanced syntax:
 - "exact phrase" → Match phrase exactly
 - field:value → Filter by custom metadata (e.g., domain:legal, author:john)
 - term1 AND term2 → Both terms required (default)
 - term1 OR term2 → Either term matches
 - -term → Exclude results containing term
-Results include score (0 = most relevant, higher = less relevant). Set explain=true to see why each result matched.`, {
+Results include a score (0 = best match, higher = less relevant). Set explain=true to see why each result matched.`, {
             query: z.string(),
             limit: z.number().optional(),
             explain: z.boolean().optional(),
@@ -100,9 +168,9 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
             };
         });
         // ingest_file tool
-        target.tool('ingest_file', 'Ingest a document file (PDF, DOCX, TXT, MD, JSON, JSONL) into the vector database for semantic search. File path must be an absolute path. Supports re-ingestion to update existing documents. Optional metadata can include author, domain, tags, etc.', {
+        target.tool('ingest_file', 'Add a document (PDF, DOCX, TXT, MD, JSON, JSONL) to your knowledge base so you can search it. Use the full file path. If you ingest the same file again, it replaces the old version. You can tag it with metadata like author, domain, or tags.', {
             filePath: z.string(),
-            metadata: z.record(z.string()).optional(),
+            metadata: z.record(z.string(), z.string()).optional(),
         }, async (args) => {
             const result = await this.executeIngestFile(args);
             return {
@@ -110,12 +178,12 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
             };
         });
         // ingest_data tool
-        target.tool('ingest_data', 'Ingest content as a string, not from a file. Use for: fetched web pages (format: html), copied text (format: text), or markdown strings (format: markdown). The source identifier enables re-ingestion to update existing content. Optional custom metadata can include author, domain, tags, etc. For files on disk, use ingest_file instead.', {
+        target.tool('ingest_data', 'Add text content directly instead of from a file. Good for: fetched web pages (format: html), copied text (format: text), or markdown strings (format: markdown). The source identifier lets you update the content later by re-ingesting with the same source. You can add custom metadata too. For files on disk, use ingest_file instead.', {
             content: z.string(),
             metadata: z.object({
                 source: z.string(),
                 format: z.enum(['text', 'html', 'markdown']),
-                custom: z.record(z.string()).optional(),
+                custom: z.record(z.string(), z.string()).optional(),
             }),
         }, async (args) => {
             const result = await this.executeIngestData(args);
@@ -124,7 +192,7 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
             };
         });
         // delete_file tool (uses .refine(), so handle validation in handler)
-        target.tool('delete_file', 'Delete a previously ingested file or data from the vector database. Use filePath for files ingested via ingest_file, or source for data ingested via ingest_data. Either filePath or source must be provided.', {
+        target.tool('delete_file', 'Remove a document from your knowledge base. Use filePath for files you added with ingest_file, or source for content you added with ingest_data. You need to provide one or the other.', {
             filePath: z.string().optional(),
             source: z.string().optional(),
         }, async (args) => {
@@ -139,21 +207,21 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
             };
         });
         // list_files tool
-        target.tool('list_files', 'List all ingested files in the vector database. Returns file paths and chunk counts for each document.', {}, async () => {
+        target.tool('list_files', 'Show all documents in your knowledge base, with file paths and how many chunks each one has.', {}, async () => {
             const files = await this.executeListFiles();
             return {
                 content: [{ type: 'text', text: JSON.stringify(files, null, 2) }],
             };
         });
         // status tool
-        target.tool('status', 'Get system status including total documents, total chunks, database size, and configuration information.', {}, async () => {
+        target.tool('status', 'Check how many documents and chunks you have, the database size, and current settings.', {}, async () => {
             const status = await this.executeStatus();
             return {
                 content: [{ type: 'text', text: JSON.stringify(status, null, 2) }],
             };
         });
         // feedback_pin tool
-        target.tool('feedback_pin', 'Pin a search result as relevant for a query. Pinned results will be boosted in future searches. Use when a result was particularly helpful.', {
+        target.tool('feedback_pin', 'Mark a search result as relevant for a query. Pinned results get boosted in future searches. Use this when a result was helpful.', {
             sourceQuery: z.string().describe('The query that returned this result'),
             targetFilePath: z.string().describe('File path of the result to pin'),
             targetChunkIndex: z.number().describe('Chunk index of the result to pin'),
@@ -181,7 +249,7 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
             }
         });
         // feedback_dismiss tool
-        target.tool('feedback_dismiss', 'Dismiss a search result as irrelevant for a query. Dismissed results will be penalized in future searches. Use when a result was unhelpful.', {
+        target.tool('feedback_dismiss', "Mark a search result as irrelevant for a query. Dismissed results get pushed down in future searches. Use this when a result wasn't helpful.", {
             sourceQuery: z.string().describe('The query that returned this result'),
             targetFilePath: z.string().describe('File path of the result to dismiss'),
             targetChunkIndex: z.number().describe('Chunk index of the result to dismiss'),
@@ -209,7 +277,7 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
             }
         });
         // feedback_stats tool
-        target.tool('feedback_stats', 'Get feedback statistics including total events, pinned pairs, and dismissed pairs.', {}, async () => {
+        target.tool('feedback_stats', "See your feedback stats: total events, how many results you've pinned, and how many you've dismissed.", {}, async () => {
             try {
                 const stats = this.executeFeedbackStats();
                 return {
@@ -233,7 +301,7 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
      * Initialization
      */
     async initialize() {
-        await this.vectorStore.initialize();
+        await withTimeout(this.vectorStore.initialize(), VECTORSTORE_INIT_TIMEOUT_MS, 'VectorStore initialization');
         console.error('RAGServer initialized');
     }
     /**
@@ -282,12 +350,55 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
         const semanticQuery = toSemanticQuery(parsed);
         // Generate query embedding from semantic terms
         const queryVector = await this.embedder.embed(semanticQuery || args.query);
+        // HyDE: expand query into hypothetical documents and embed them
+        let additionalVectors;
+        if (this.hydeExpander) {
+            try {
+                const expandedQueries = await this.hydeExpander.expandQuery(args.query);
+                // Skip first item (original query, already embedded above)
+                const expansions = expandedQueries.slice(1);
+                if (expansions.length > 0) {
+                    additionalVectors = [];
+                    for (const expansion of expansions) {
+                        const expansionVector = await this.embedder.embed(expansion.text);
+                        additionalVectors.push({ vector: expansionVector, weight: expansion.weight });
+                    }
+                }
+            }
+            catch (hydeError) {
+                console.error(`HyDE expansion failed, using original query only: ${hydeError.message}`);
+            }
+        }
         // Request extra results to account for post-filtering (capped at 20)
         const userLimit = args.limit || 10;
         const hasFilters = parsed.excludeTerms.length > 0 || parsed.filters.length > 0;
         const requestLimit = hasFilters ? Math.min(userLimit * 2, 20) : userLimit;
-        // Hybrid search (vector + BM25 keyword matching)
-        let searchResults = await this.vectorStore.search(queryVector, args.query, requestLimit);
+        // Expand request limit for reranking if enabled
+        const rerankerActive = this.reranker !== null;
+        const rerankerLimit = rerankerActive
+            ? Math.min(requestLimit * this.rerankerCandidateMultiplier, 20)
+            : requestLimit;
+        // Hybrid search (vector + BM25 keyword matching, with RRF fusion if enabled)
+        let searchResults = await this.vectorStore.search(queryVector, args.query, rerankerLimit, additionalVectors);
+        // Cross-encoder reranking: re-score top candidates for better relevance
+        if (rerankerActive && this.reranker && searchResults.length > 0) {
+            try {
+                const reranked = await this.reranker.rerank(args.query, searchResults.map((r) => r.text));
+                // Reorder results by cross-encoder score, convert to pseudo-distance
+                const reorderedResults = reranked.map(({ index, score }) => ({
+                    ...searchResults[index],
+                    // Convert cross-encoder score to distance-like metric (lower = better)
+                    // Cross-encoder scores can be negative, so we use: 1 / (1 + exp(score))
+                    // This produces values in (0, 1) where lower = more relevant
+                    score: 1 / (1 + Math.exp(score)),
+                }));
+                searchResults = reorderedResults.slice(0, requestLimit);
+            }
+            catch (rerankerError) {
+                console.error(`Reranker failed, using original ordering: ${rerankerError.message}`);
+                searchResults = searchResults.slice(0, requestLimit);
+            }
+        }
         // Apply flywheel reranking based on user feedback
         const feedbackStore = getFeedbackStore();
         const sourceRef = {
@@ -384,25 +495,6 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
         const chunks = await this.chunker.chunkText(text, this.embedder);
         // Generate embeddings for final chunks
         const embeddings = await this.embedder.embedBatch(chunks.map((chunk) => chunk.text));
-        // Note: Full backup with vectors is not implemented because search results don't include vectors.
-        // If rollback is needed, re-ingestion from the original file is required.
-        // Track if this is a re-ingestion for logging purposes.
-        let isReingestion = false;
-        try {
-            const existingFiles = await this.vectorStore.listFiles();
-            const existingFile = existingFiles.find((file) => file.filePath === args.filePath);
-            if (existingFile && existingFile.chunkCount > 0) {
-                isReingestion = true;
-                console.error(`Re-ingesting existing file: ${args.filePath} (${existingFile.chunkCount} existing chunks)`);
-            }
-        }
-        catch (error) {
-            // File check failure is warning only (for new files)
-            console.warn('Failed to check existing file (new file?):', error);
-        }
-        // Delete existing data
-        await this.vectorStore.deleteChunks(args.filePath);
-        console.error(`Deleted existing chunks for: ${args.filePath}`);
         // Validate embeddings and chunks match
         if (embeddings.length !== chunks.length) {
             throw new Error(`Embedding count (${embeddings.length}) doesn't match chunk count (${chunks.length})`);
@@ -429,20 +521,20 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
                 timestamp,
             };
         });
-        // Insert vectors (transaction processing)
+        // Insert-then-delete strategy: avoids data-loss window during re-ingestion.
+        // Insert new vectors first, then delete old ones. On crash between the two,
+        // the worst case is temporary duplicates rather than permanent data loss.
+        await this.vectorStore.insertChunks(vectorChunks);
+        console.error(`Inserted ${vectorChunks.length} chunks for: ${args.filePath}`);
+        // Delete old chunks that don't belong to this ingestion batch
         try {
-            await this.vectorStore.insertChunks(vectorChunks);
-            console.error(`Inserted ${vectorChunks.length} chunks for: ${args.filePath}`);
-        }
-        catch (insertError) {
-            // Note: Full rollback is not possible without stored vectors.
-            // If this was a re-ingestion and it failed, the old data has been deleted.
-            // User should re-ingest from the original file.
-            if (isReingestion) {
-                console.error('Ingestion failed during re-ingestion. Previous data was deleted. ' +
-                    'Please re-ingest from the original file to restore.', insertError);
-            }
-            throw insertError;
+            const newIds = new Set(vectorChunks.map((c) => c.id));
+            await this.vectorStore.deleteChunksExcluding(args.filePath, newIds);
+            console.error(`Cleaned up old chunks for: ${args.filePath}`);
+        }
+        catch (deleteError) {
+            // Non-fatal: duplicates are better than data loss
+            console.warn(`Failed to clean up old chunks for ${args.filePath}. Duplicates may exist until next re-ingestion.`, deleteError);
         }
         return {
             filePath: args.filePath,
@@ -822,7 +914,7 @@ Results include score (0 = most relevant, higher = less relevant). Set explain=t
      */
     async run() {
         const transport = new StdioServerTransport();
-        await this.server.connect(transport);
+        await withTimeout(this.server.connect(transport), MCP_CONNECT_TIMEOUT_MS, 'MCP transport connect');
         console.error('RAGServer running on stdio transport');
     }
 }