@softerist/heuristic-mcp 3.0.17 → 3.1.0

package/config.jsonc

@@ -1,5 +1,6 @@
 {
   // Root directory to index (relative or absolute).
+  // Keep "." for dynamic workspace behavior so MCP roots / IDE workspace selection works.
   "searchDirectory": ".",
   // File extensions to include (without dot).
   "fileExtensions": [
@@ -627,7 +628,7 @@
     "**/.smart-coding-cache/**",
   ],
   // Indexing controls.
-  "indexing": {
+  "indexing": {
     // Enable project-type detection + smart ignore patterns.
     "smartIndexing": true,
     // Lines per chunk.
@@ -642,14 +643,27 @@
     "maxResults": 5,
     // Enable file watcher for incremental indexing.
     "watchFiles": true,
-  },
-  // Logging and diagnostics.
-  "logging": {
+    // Save incremental index checkpoints every 2s so interrupted runs can resume with minimal rework.
+    // Increase to 5000-10000 on slower disks if checkpoint writes feel too frequent.
+    "indexCheckpointIntervalMs": 2000,
+  },
+  // Server lifecycle controls.
+  // When true, a newly started server instance will terminate older heuristic-mcp server processes.
+  // This helps prevent stale workspace binding after IDE reloads/window switches.
+  "autoStopOtherServersOnStartup": true,
+  // Safety guard for IDE sessions:
+  // when true, semantic/index tools require a current trusted workspace signal
+  // (MCP roots or explicit workspace env), otherwise the call fails fast.
+  "requireTrustedWorkspaceSignalForTools": true,
+  // Logging and diagnostics.
+  "logging": {
     // Enable verbose logging.
     "verbose": true,
   },
   // Cache engine and serialization controls.
   "cache": {
+    // NOTE: leave top-level "cacheDirectory" unset to keep per-workspace global cache hashing.
+    // This preserves resume/incremental indexing across IDE restarts.
     // Persist embeddings between sessions.
     "enableCache": true,
     // Assume vectors are finite (skip validation).
@@ -680,7 +694,10 @@
   "worker": {
     // Number of embedding workers (0 disables).
     // Windows + heavy Jina models are more stable with child-process embedding than worker pools.
-    "workerThreads": 0,
+    "workerThreads": 1,
+    // Safety guard for heavy models on Windows.
+    // Keep true (recommended). Set false only to opt in to experimental heavy-model workers on Windows.
+    "workerDisableHeavyModelOnWindows": false,
     // Worker batch timeout in milliseconds.
     "workerBatchTimeoutMs": 120000,
     // Failures before worker circuit opens.
@@ -707,7 +724,7 @@
     // Override embedding batch size (null = auto).
     "embeddingBatchSize": null,
     // ONNX threads used by embedding child process.
-    // 6 is a practical balance on 24-thread desktop CPUs (high throughput, less contention than 8+).
+    // 8 is a practical balance on 24-thread desktop CPUs for this workspace size.
     "embeddingProcessNumThreads": 8,
     // Embedding-child adaptive GC RSS threshold in MB (higher = less frequent GC).
     "embeddingProcessGcRssThresholdMb": 2048,

package/features/ann-config.js

@@ -1,9 +1,4 @@
-/**
- * ANN Config Tool - Runtime tuning of ANN search parameters
- *
- * Allows adjusting efSearch on the fly for speed/accuracy tradeoff,
- * and querying current ANN index statistics.
- */
+
 
 export class AnnConfigTool {
   constructor(cache, config) {
@@ -11,9 +6,7 @@ export class AnnConfigTool {
     this.config = config;
   }
 
-  /**
-   * Adjust efSearch and optionally trigger index rebuild
-   */
+  
   async execute(args) {
     const action = args.action || 'stats';
 
@@ -33,7 +26,7 @@ export class AnnConfigTool {
     }
 
     if (action === 'rebuild') {
-      // Force invalidate and rebuild the ANN index
+      
       this.cache.invalidateAnnIndex();
       const index = await this.cache.ensureAnnIndex();
       return {
@@ -56,7 +49,7 @@ export class AnnConfigTool {
     }
 
     if (result.enabled !== undefined) {
-      // Stats response
+      
       let output = '## ANN Index Statistics\n\n';
       output += `- **Enabled**: ${result.enabled}\n`;
       output += `- **Index Loaded**: ${result.indexLoaded}\n`;
@@ -79,12 +72,12 @@ export class AnnConfigTool {
       return output;
     }
 
-    // Other responses (set_ef_search, rebuild)
+    
     return JSON.stringify(result, null, 2);
   }
 }
 
-// MCP Tool definition
+
 export function getToolDefinition() {
   return {
     name: 'd_ann_config',
@@ -119,7 +112,7 @@ export function getToolDefinition() {
   };
 }
 
-// Tool handler
+
 export async function handleToolCall(request, annConfigTool) {
   const args = request.params.arguments || {};
   const result = await annConfigTool.execute(args);

package/features/clear-cache.js

@@ -7,21 +7,21 @@ export class CacheClearer {
   }
 
   async execute() {
-    // Check if indexing is in progress
+    
     if (this.indexer && this.indexer.isIndexing) {
       throw new Error(
         'Cannot clear cache while indexing is in progress. Please wait for indexing to complete.'
       );
     }
 
-    // Check if cache is currently being saved (race condition prevention)
+    
     if (this.cache.isSaving) {
       throw new Error(
         'Cannot clear cache while cache is being saved. Please try again in a moment.'
       );
     }
 
-    // Check if a clear operation is already in progress (prevent concurrent clears)
+    
     if (this.isClearing) {
       throw new Error('Cache clear operation already in progress. Please wait for it to complete.');
     }

package/features/find-similar-code.js

@@ -1,10 +1,7 @@
 import path from 'path';
 import { dotSimilarity, smartChunk, estimateTokens, getModelTokenLimit } from '../lib/utils.js';
 
-/**
- * FindSimilarCode feature
- * Given a code snippet, finds similar patterns elsewhere in the codebase
- */
+
 export class FindSimilarCode {
   constructor(embedder, cache, config) {
     this.embedder = embedder;
@@ -62,15 +59,15 @@ export class FindSimilarCode {
       let codeToEmbed = code;
       let warningMessage = null;
 
-      // Check if input is too large and truncate intelligently
+      
       const estimatedTokens = estimateTokens(code);
       const limit = getModelTokenLimit(this.config.embeddingModel);
 
-      // If input is significantly larger than the model limit, we should chunk it
+      
       if (estimatedTokens > limit) {
-        // Use smartChunk to get a semantically valid first block
-        // We pass a dummy file name to trigger language detection if possible, or default to .txt
-        // Since we don't know the language, we'll try to guess or just use generic chunking
+        
+        
+        
         const chunks = smartChunk(code, 'input.txt', this.config);
         if (chunks.length > 0) {
           codeToEmbed = chunks[0].text;
@@ -78,14 +75,14 @@ export class FindSimilarCode {
         }
       }
 
-      // Generate embedding for the input code
+      
       const codeEmbed = await this.embedder(codeToEmbed, {
         pooling: 'mean',
         normalize: true,
       });
 
-      // CRITICAL: Deep copy Float32Array to avoid detachment issues with WASM/Workers
-      // accessing a detached buffer from a reusable ONNX tensor can crash the process.
+      
+      
       let codeVector;
       try {
         codeVector = new Float32Array(codeEmbed.data);
@@ -94,7 +91,7 @@ export class FindSimilarCode {
           try {
             codeEmbed.dispose();
           } catch {
-            /* ignore */
+            
           }
         }
       }
@@ -120,9 +117,7 @@ export class FindSimilarCode {
       const normalizeText = (text) => text.trim().replace(/\s+/g, ' ');
       const normalizedInput = normalizeText(codeToEmbed);
 
-      /**
-       * Batch scoring function to prevent blocking the event loop
-       */
+      
       const scoreAndFilter = async (chunks) => {
         const BATCH_SIZE = 500;
         const scored = [];
@@ -130,7 +125,7 @@ export class FindSimilarCode {
         for (let i = 0; i < chunks.length; i += BATCH_SIZE) {
           const batch = chunks.slice(i, i + BATCH_SIZE);
 
-          // Yield to event loop between batches
+          
           if (i > 0) {
             await new Promise((resolve) => setTimeout(resolve, 0));
           }
@@ -159,14 +154,14 @@ export class FindSimilarCode {
 
       let filteredResults = await scoreAndFilter(candidates);
 
-      // Fallback to full scan if ANN didn't provide enough results
-      // Optimization: Skip full scan on large codebases to avoid long pauses
+      
+      
       const MAX_FULL_SCAN_SIZE = 5000;
       if (usedAnn && filteredResults.length < safeMaxResults) {
         if (vectorStore.length <= MAX_FULL_SCAN_SIZE) {
           filteredResults = await scoreAndFilter(vectorStore);
         } else {
-          // Just return what we found via ANN
+          
         }
       }
       const results = [];
@@ -220,7 +215,7 @@ export class FindSimilarCode {
   }
 }
 
-// MCP Tool definition
+
 export function getToolDefinition(_config) {
   return {
     name: 'd_find_similar_code',
@@ -256,7 +251,7 @@ export function getToolDefinition(_config) {
   };
 }
 
-// Tool handler
+
 export async function handleToolCall(request, findSimilarCode) {
   const args = request.params?.arguments || {};
   const code = args.code;

package/features/hybrid-search.js

@@ -14,8 +14,8 @@ export class HybridSearch {
     this.embedder = embedder;
     this.cache = cache;
     this.config = config;
-    this.fileModTimes = new Map(); // Cache for file modification times
-    this._lastAccess = new Map(); // Track last access time for LRU eviction
+    this.fileModTimes = new Map(); 
+    this._lastAccess = new Map(); 
   }
 
   async getChunkContent(chunkOrIndex) {
@@ -41,16 +41,16 @@ export class HybridSearch {
 
     for (const file of uniqueFiles) {
       if (!this.fileModTimes.has(file)) {
-        // Try to get from cache metadata first (fast)
+        
         const meta = this.cache.getFileMeta(file);
         if (meta && typeof meta.mtimeMs === 'number') {
           this.fileModTimes.set(file, meta.mtimeMs);
-          this._lastAccess.set(file, Date.now()); // Track for LRU
+          this._lastAccess.set(file, Date.now()); 
         } else {
           missing.push(file);
         }
       } else {
-        this._lastAccess.set(file, Date.now()); // Track access for LRU
+        this._lastAccess.set(file, Date.now()); 
       }
     }
 
@@ -58,8 +58,8 @@ export class HybridSearch {
       return;
     }
 
-    // Concurrency-limited execution to avoid EMFILE
-    // Pre-distribute files to workers (no shared mutable state - avoids race condition)
+    
+    
     const workerCount = Math.min(STAT_CONCURRENCY_LIMIT, missing.length);
 
     const worker = async (startIdx) => {
@@ -77,16 +77,16 @@ export class HybridSearch {
 
     await Promise.all(Array.from({ length: workerCount }, (_, i) => worker(i)));
 
-    // Prevent unbounded growth (LRU-style eviction based on access time)
+    
     const lruMaxEntries = this.config.lruMaxEntries ?? 5000;
     const lruTargetEntries = this.config.lruTargetEntries ?? 4000;
     if (this.fileModTimes.size > lruMaxEntries) {
-      // Convert to array with last-access info, sort by oldest access
+      
       const entries = [...this.fileModTimes.keys()].map((k) => ({
         key: k,
         lastAccess: this._lastAccess?.get(k) ?? 0,
       }));
-      entries.sort((a, b) => a.lastAccess - b.lastAccess); // Oldest first
+      entries.sort((a, b) => a.lastAccess - b.lastAccess); 
       const toEvict = entries.slice(0, entries.length - lruTargetEntries);
       for (const { key } of toEvict) {
         this.fileModTimes.delete(key);
@@ -95,20 +95,12 @@ export class HybridSearch {
     }
   }
 
-  // Cache invalidation helper
+  
   clearFileModTime(file) {
     this.fileModTimes.delete(file);
   }
 
-  /**
-   * Search the indexed codebase for relevant code snippets.
-   * Uses a hybrid approach combining semantic similarity (via embeddings) with
-   * keyword matching for optimal results.
-   * @param {string} query - Natural language or keyword search query
-   * @param {number} maxResults - Maximum number of results to return (default: 15)
-   * @returns {Promise<{results: Array<{file: string, startLine: number, endLine: number, content: string, score: number}>, message?: string}>}
-   * @throws {Error} If embedder is not initialized
-   */
+  
   async search(query, maxResults) {
     try {
       if (typeof this.cache.ensureLoaded === 'function') {
@@ -125,19 +117,19 @@ export class HybridSearch {
         };
       }
 
-      // Generate query embedding
+      
       if (this.config.verbose) {
         console.info(`[Search] Query: "${query}"`);
       }
       
       let queryVector;
       
-      // Use child process for embedding when unloadModelAfterSearch is enabled
-      // This ensures the OS completely reclaims memory when the child exits
+      
+      
       if (this.config.unloadModelAfterSearch) {
         queryVector = await embedQueryInChildProcess(query, this.config);
       } else {
-        // Use main process embedder (faster for consecutive searches)
+        
         const queryEmbed = await this.embedder(query, {
           pooling: 'mean',
           normalize: true,
@@ -150,13 +142,13 @@ export class HybridSearch {
             try {
               queryEmbed.dispose();
             } catch {
-              /* ignore */
+              
             }
           }
         }
       }
 
-      let candidateIndices = null; // null implies full scan of all chunks
+      let candidateIndices = null; 
       let usedAnn = false;
 
       if (this.config.annEnabled) {
@@ -167,7 +159,7 @@ export class HybridSearch {
           if (this.config.verbose) {
             console.info(`[Search] Using ANN index (${annLabels.length} candidates)`);
           }
-          candidateIndices = Array.from(new Set(annLabels)); // dedupe
+          candidateIndices = Array.from(new Set(annLabels)); 
         }
       }
 
@@ -183,7 +175,7 @@ export class HybridSearch {
             `[Search] ANN returned fewer results (${candidateIndices.length}) than requested (${maxResults}), augmenting with full scan...`
           );
         }
-        candidateIndices = null; // Fallback to full scan to ensure we don't miss anything relevant
+        candidateIndices = null; 
         usedAnn = false;
       }
 
@@ -202,38 +194,38 @@ export class HybridSearch {
         }
 
         if (exactMatchCount < maxResults) {
-          // Fallback to full scan if keyword constraint isn't met in candidates
-          // Note: This is expensive as it iterates everything.
-          // Optimization: Only do this for small-ish codebases to avoid UI freeze
+          
+          
+          
           const MAX_FULL_SCAN_SIZE = this.config.fullScanThreshold ?? 2000;
 
           if (storeSize <= MAX_FULL_SCAN_SIZE) {
             const seen = new Set(candidateIndices);
 
-            // Full scan logic for keyword augmentation
-            // Batch content loading to reduce async overhead
+            
+            
             const FALLBACK_BATCH = 100;
             let additionalMatches = 0;
             const targetMatches = maxResults - exactMatchCount;
             
             outerLoop:
             for (let i = 0; i < storeSize; i += FALLBACK_BATCH) {
-              if (i > 0) await new Promise((r) => setTimeout(r, 0)); // Yield
+              if (i > 0) await new Promise((r) => setTimeout(r, 0)); 
 
               const limit = Math.min(storeSize, i + FALLBACK_BATCH);
               
-              // Build batch of indices to check (excluding already seen)
+              
               const batchIndices = [];
               for (let j = i; j < limit; j++) {
                 if (!seen.has(j)) batchIndices.push(j);
               }
               
-              // Batch load content in parallel
+              
               const contents = await Promise.all(
                 batchIndices.map(idx => this.getChunkContent(idx))
               );
               
-              // Check each loaded content
+              
               for (let k = 0; k < batchIndices.length; k++) {
                 const content = contents[k];
                 if (content && content.toLowerCase().includes(lowerQuery)) {
@@ -241,7 +233,7 @@ export class HybridSearch {
                   seen.add(idx);
                   candidateIndices.push(idx);
                   additionalMatches++;
-                  // Early exit once we have enough additional matches
+                  
                   if (additionalMatches >= targetMatches) break outerLoop;
                 }
               }
@@ -254,7 +246,7 @@ export class HybridSearch {
         }
       }
 
-      // Recency pre-processing
+      
       let recencyBoostEnabled = this.config.recencyBoost > 0;
       let now = Date.now();
       let recencyDecayMs = (this.config.recencyDecayDays || 30) * 24 * 60 * 60 * 1000;
@@ -266,13 +258,13 @@ export class HybridSearch {
         const candidates = candidateIndices
           ? candidateIndices.map((idx) => this.cache.getChunk(idx)).filter(Boolean)
           : Array.from({ length: storeSize }, (_, i) => this.cache.getChunk(i)).filter(Boolean);
-        // optimization: avoid IO storm during full scan fallbacks
-        // For large candidate sets, we strictly rely on cached metadata
-        // For small sets, we allow best-effort fs.stat
+        
+        
+        
         if (candidates.length <= 1000) {
           await this.populateFileModTimes(candidates.map((chunk) => chunk.file));
         } else {
-          // Bulk pre-populate from cache only (no syscalls)
+          
           for (const chunk of candidates) {
             if (!this.fileModTimes.has(chunk.file)) {
               const meta = this.cache.getFileMeta(chunk.file);
@@ -284,11 +276,11 @@ export class HybridSearch {
         }
       }
 
-      // Score all chunks (batched to prevent blocking event loop)
+      
       const scoredChunks = [];
 
-      // Process in batches
-      // Candidates is now implicitly range 0..storeSize OR candidateIndices
+      
+      
       const totalCandidates = candidateIndices ? candidateIndices.length : storeSize;
       const textMatchMaxCandidates = Number.isInteger(this.config.textMatchMaxCandidates)
         ? this.config.textMatchMaxCandidates
@@ -297,7 +289,7 @@ export class HybridSearch {
       const deferTextMatch = shouldApplyTextMatch && totalCandidates > textMatchMaxCandidates;
 
       for (let i = 0; i < totalCandidates; i += SEARCH_BATCH_SIZE) {
-        // Allow event loop to tick between batches
+        
         if (i > 0) {
           await new Promise((resolve) => setTimeout(resolve, 0));
         }
@@ -307,25 +299,25 @@ export class HybridSearch {
         for (let j = i; j < limit; j++) {
           const idx = candidateIndices ? candidateIndices[j] : j;
 
-          // CRITICAL: Fetch chunk info FIRST to ensure atomicity with index.
-          // If we fetch vector and chunk separately, the store could be modified
-          // between calls (e.g., by removeFileFromStore compacting the array).
+          
+          
+          
           const chunkInfo = this.cache.getChunk(idx);
           if (!chunkInfo) {
-            // Chunk was removed or index is stale - skip silently
+            
             continue;
           }
 
-          // Get vector from chunk or via index (now safe since we have valid chunkInfo)
+          
           const vector = this.cache.getChunkVector(chunkInfo, idx);
           if (!vector) continue;
 
-          // Ensure vector compatibility with try-catch for dimension mismatch
+          
           let score;
           try {
             score = dotSimilarity(queryVector, vector) * semanticWeight;
           } catch (err) {
-            // Dimension mismatch indicates config change - log and skip this chunk
+            
             if (this.config.verbose) {
               console.warn(`[Search] ${err.message} at index ${idx}`);
             }
@@ -340,7 +332,7 @@ export class HybridSearch {
             if (lowerContent && lowerContent.includes(lowerQuery)) {
               score += exactMatchBoost;
             } else if (lowerContent && queryWordCount > 0) {
-              // Partial word matching (optimized)
+              
               let matchedWords = 0;
               for (let k = 0; k < queryWordCount; k++) {
                 if (lowerContent.includes(queryWords[k])) matchedWords++;
@@ -349,7 +341,7 @@ export class HybridSearch {
             }
           }
 
-          // Recency boost
+          
           if (recencyBoostEnabled) {
             const mtime = this.fileModTimes.get(chunkInfo.file);
             if (typeof mtime === 'number') {
@@ -367,10 +359,10 @@ export class HybridSearch {
         }
       }
 
-      // Sort by initial score
+      
       scoredChunks.sort((a, b) => b.score - a.score);
 
-      // Defer expensive text matching for large candidate sets
+      
       if (deferTextMatch) {
         const textMatchCount = Math.min(textMatchMaxCandidates, scoredChunks.length);
         for (let i = 0; i < textMatchCount; i++) {
@@ -395,9 +387,9 @@ export class HybridSearch {
         scoredChunks.sort((a, b) => b.score - a.score);
       }
 
-      // Apply call graph proximity boost if enabled
+      
       if (this.config.callGraphEnabled && this.config.callGraphBoost > 0) {
-        // Extract symbols from top initial results
+        
         const topN = Math.min(5, scoredChunks.length);
         const symbolsFromTop = new Set();
         for (let i = 0; i < topN; i++) {
@@ -409,22 +401,22 @@ export class HybridSearch {
         }
 
         if (symbolsFromTop.size > 0) {
-          // Get related files from call graph
+          
           const relatedFiles = await this.cache.getRelatedFiles(Array.from(symbolsFromTop));
 
-          // Apply boost to chunks from related files
+          
           for (const chunk of scoredChunks) {
             const proximity = relatedFiles.get(chunk.file);
             if (proximity) {
               chunk.score += proximity * this.config.callGraphBoost;
             }
           }
-          // Re-sort after applying call graph boost
+          
           scoredChunks.sort((a, b) => b.score - a.score);
         }
       }
 
-      // Get top results
+      
       const results = await Promise.all(
         scoredChunks.slice(0, maxResults).map(async (chunk) => {
           if (chunk.content === undefined || chunk.content === null) {
@@ -478,7 +470,7 @@ export class HybridSearch {
   }
 }
 
-// MCP Tool definition for this feature
+
 export function getToolDefinition(config) {
   return {
     name: 'a_semantic_search',
@@ -510,12 +502,12 @@ export function getToolDefinition(config) {
   };
 }
 
-// Tool handler
+
 export async function handleToolCall(request, hybridSearch) {
   const args = request.params?.arguments || {};
   const query = args.query;
   
-  // Input validation
+  
   if (typeof query !== 'string' || query.trim().length === 0) {
     return {
       content: [{ type: 'text', text: 'Error: A non-empty query string is required.' }],