@softerist/heuristic-mcp 3.0.12 → 3.0.14

package/README.md

@@ -99,31 +99,48 @@ Clears the cache for the current working directory (or `--workspace` if provided
 
 Configuration is loaded from your workspace root when the server runs with `--workspace` (this is how IDEs launch it). In server mode, it falls back to the package `config.jsonc` (or `config.json`) and then your current working directory.
 
-Example `config.jsonc`:
-
-```json
-{
-  "excludePatterns": ["**/legacy-code/**", "**/*.test.ts"],
-  "fileNames": ["Dockerfile", ".env.example", "Makefile"],
-  "smartIndexing": true,
-  "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
-  "workerThreads": 0,
-  "embeddingBatchSize": null,
-  "embeddingProcessNumThreads": 8,
-  "enableExplicitGc": false,
-  "recencyBoost": 0.1,
-  "recencyDecayDays": 30,
-  "callGraphEnabled": true,
-  "callGraphBoost": 0.15,
-  "annEnabled": true,
-  "vectorStoreFormat": "binary",
-  "vectorStoreContentMode": "external",
-  "vectorStoreLoadMode": "disk",
-  "contentCacheEntries": 256,
-  "vectorCacheEntries": 64,
-  "clearCacheAfterIndex": true
-}
-```
+Example `config.jsonc`:
+
+```json
+{
+  "excludePatterns": ["**/legacy-code/**", "**/*.test.ts"],
+  "fileNames": ["Dockerfile", ".env.example", "Makefile"],
+  "indexing": {
+    "smartIndexing": true
+  },
+  "worker": {
+    "workerThreads": 0
+  },
+  "embedding": {
+    "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
+    "embeddingBatchSize": null,
+    "embeddingProcessNumThreads": 8
+  },
+  "search": {
+    "recencyBoost": 0.1,
+    "recencyDecayDays": 30
+  },
+  "callGraph": {
+    "callGraphEnabled": true,
+    "callGraphBoost": 0.15
+  },
+  "ann": {
+    "annEnabled": true
+  },
+  "vectorStore": {
+    "vectorStoreFormat": "binary",
+    "vectorStoreContentMode": "external",
+    "vectorStoreLoadMode": "disk",
+    "contentCacheEntries": 256,
+    "vectorCacheEntries": 64
+  },
+  "memoryCleanup": {
+    "clearCacheAfterIndex": true
+  }
+}
+```
+
+Preferred style is namespaced keys (shown above). Legacy top-level keys are still supported for backward compatibility.
 
 ### Embedding Model & Dimension Options
 
@@ -133,12 +150,14 @@ Example `config.jsonc`:
 
 For faster search with smaller embeddings, switch to an MRL-compatible model:
 
-```json
-{
-  "embeddingModel": "nomic-ai/nomic-embed-text-v1.5",
-  "embeddingDimension": 128
-}
-```
+```json
+{
+  "embedding": {
+    "embeddingModel": "nomic-ai/nomic-embed-text-v1.5",
+    "embeddingDimension": 128
+  }
+}
+```
 
 **MRL-compatible models:**
 - `nomic-ai/nomic-embed-text-v1.5` — recommended for 128d/256d
@@ -153,7 +172,9 @@ Cache location:
 
 ### Environment Variables
 
-Selected overrides (prefix `SMART_CODING_`):
+Selected overrides (prefix `SMART_CODING_`):
+
+Environment overrides target runtime keys and are synced back into namespaces by `lib/config.js`.
 
 - `SMART_CODING_VERBOSE=true|false` — enable detailed logging.
 - `SMART_CODING_WORKER_THREADS=auto|N` — worker thread count.
@@ -179,35 +200,37 @@ Selected overrides (prefix `SMART_CODING_`):
 
 See `lib/config.js` for the full list.
 
-### Binary Vector Store
-
-Set `vectorStoreFormat` to `binary` to use the on-disk binary cache. This keeps vectors and content out of JS heap
-and reads on demand. Recommended for large repos.
-
-- `vectorStoreContentMode=external` keeps content in the binary file and only loads for top-N results.
-- `contentCacheEntries` controls the small in-memory LRU for decoded content strings.
-- `vectorStoreLoadMode=disk` streams vectors from disk to reduce memory usage.
-- `vectorCacheEntries` controls the small in-memory LRU for vectors when using disk mode.
-- `clearCacheAfterIndex=true` drops in-memory vectors after indexing and reloads lazily on next query.
-- `unloadModelAfterIndex=true` (default) unloads the embedding model after indexing to free ~500MB-1GB of RAM; the model will reload on the next search query.
-- Note: `annEnabled=true` with `vectorStoreLoadMode=disk` can increase disk reads during ANN rebuilds on large indexes.
+### Binary Vector Store
+
+Set `vectorStore.vectorStoreFormat` to `binary` to use the on-disk binary cache. This keeps vectors and content out of JS heap
+and reads on demand. Recommended for large repos.
+
+- `vectorStore.vectorStoreContentMode=external` keeps content in the binary file and only loads for top-N results.
+- `vectorStore.contentCacheEntries` controls the small in-memory LRU for decoded content strings.
+- `vectorStore.vectorStoreLoadMode=disk` streams vectors from disk to reduce memory usage.
+- `vectorStore.vectorCacheEntries` controls the small in-memory LRU for vectors when using disk mode.
+- `memoryCleanup.clearCacheAfterIndex=true` drops in-memory vectors after indexing and reloads lazily on next query.
+- `memoryCleanup.unloadModelAfterIndex=true` (default) unloads the embedding model after indexing to free ~500MB-1GB of RAM; the model will reload on the next search query.
+- Note: `ann.annEnabled=true` with `vectorStore.vectorStoreLoadMode=disk` can increase disk reads during ANN rebuilds on large indexes.
 
 ### SQLite Vector Store
 
-Set `vectorStoreFormat` to `sqlite` to use SQLite for persistence. This provides:
+Set `vectorStore.vectorStoreFormat` to `sqlite` to use SQLite for persistence. This provides:
 
 - ACID transactions for reliable writes
 - Simpler concurrent access
 - Standard database format for inspection
 
-```json
-{
-  "vectorStoreFormat": "sqlite"
-}
-```
-
-The vectors and content are stored in `vectors.sqlite` in your cache directory. You can inspect it with any SQLite browser.
-`vectorStoreContentMode` and `vectorStoreLoadMode` are respected for SQLite (use `vectorStoreLoadMode=disk` to avoid loading vectors into memory).
+```json
+{
+  "vectorStore": {
+    "vectorStoreFormat": "sqlite"
+  }
+}
+```
+
+The vectors and content are stored in `vectors.sqlite` in your cache directory. You can inspect it with any SQLite browser.
+`vectorStore.vectorStoreContentMode` and `vectorStore.vectorStoreLoadMode` are respected for SQLite (use `vectorStore.vectorStoreLoadMode=disk` to avoid loading vectors into memory).
 
 **Tradeoffs vs Binary:**
 - Slightly higher read overhead (SQL queries vs direct memory access)
@@ -230,7 +253,7 @@ SMART_CODING_VECTOR_STORE_LOAD_MODE=disk node tools/scripts/benchmark-search.js
 SMART_CODING_VECTOR_STORE_FORMAT=binary SMART_CODING_VECTOR_STORE_LOAD_MODE=disk node tools/scripts/benchmark-search.js --runs 10
 ```
 
-Note: On small repos, disk mode may be slightly slower and show noisy RSS deltas; benefits are clearer on large indexes with a small `vectorCacheEntries`.
+Note: On small repos, disk mode may be slightly slower and show noisy RSS deltas; benefits are clearer on large indexes with a small `vectorStore.vectorCacheEntries`.
 
 ---
 
@@ -293,8 +316,8 @@ Native ONNX backend unavailable: The operating system cannot run %1.
 ...onnxruntime_binding.node. Falling back to WASM.
 ```
 
-The server will automatically disable workers and force `embeddingProcessPerBatch` to reduce memory spikes, but you
-should fix the native binding to restore stable memory usage:
+The server will automatically disable workers and force `embedding.embeddingProcessPerBatch` to reduce memory spikes, but you
+should fix the native binding to restore stable memory usage:
 
 - Ensure you are running **64-bit Node.js** (`node -p "process.arch"` should be `x64`).
 - Install **Microsoft Visual C++ 2015–2022 Redistributable (x64)**.

package/config.jsonc

@@ -615,109 +615,180 @@
     "makefile.in",
   ],
   // Glob patterns to exclude from indexing.
-  "excludePatterns": [
-    "**/node_modules/**",
-    "**/dist/**",
-    "**/build/**",
+  "excludePatterns": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
     "**/.git/**",
     "**/coverage/**",
     "**/.next/**",
     "**/target/**",
-    "**/vendor/**",
-    "**/.smart-coding-cache/**",
-  ],
-  // Enable project-type detection + smart ignore patterns.
-  "smartIndexing": true,
-  // Lines per chunk.
-  "chunkSize": 16,
-  // Overlapping lines between chunks.
-  "chunkOverlap": 4,
-  // Files per indexing batch.
-  "batchSize": 50,
-  // Skip files larger than this many bytes.
-  "maxFileSize": 1048576,
-  // Maximum number of search results.
-  "maxResults": 5,
-  // Persist embeddings between sessions.
-  "enableCache": true,
-  // Remove stale caches automatically.
-  "autoCleanStaleCaches": true,
-  // Assume vectors are finite (skip validation).
-  "cacheVectorAssumeFinite": true,
-  // Decimal precision for cached vectors (null = default).
-  "cacheVectorFloatDigits": null,
-  // Write stream highWaterMark for cache files.
-  "cacheWriteHighWaterMark": 262144,
-  // Flush threshold (chars) for JSON writer.
-  "cacheVectorFlushChars": 262144,
-  // Validate vectors contain only finite numbers.
-  "cacheVectorCheckFinite": true,
-  // Avoid mutating vectors during serialization.
-  "cacheVectorNoMutation": false,
-  // Join threshold for JSON array chunks.
-  "cacheVectorJoinThreshold": 8192,
-  // Chunk size for JSON join optimization.
-  "cacheVectorJoinChunkSize": 2048,
-  // Enable file watcher for incremental indexing.
-  "watchFiles": true,
-  // Enable verbose logging.
-  "verbose": true,
-  // Embedding model identifier.
-  "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
-  // Preload the embedding model on startup. Set to false when using child processes for memory savings.
-  "preloadEmbeddingModel": false,
-  // Vector store format: json, binary, or sqlite.
-  "vectorStoreFormat": "binary",
-  // Content storage: external or inline.
-  "vectorStoreContentMode": "external",
-  // In-memory content cache entries (binary store).
-  "contentCacheEntries": 256,
-  // Weight for semantic similarity scoring.
-  "semanticWeight": 0.7,
-  // Score boost for exact text matches.
-  "exactMatchBoost": 1.5,
-  // Number of embedding workers (0 disables).
-  "workerThreads": "auto",
-  // Worker batch timeout in milliseconds.
-  "workerBatchTimeoutMs": 120000,
-  // Failures before worker circuit opens.
-  "workerFailureThreshold": 1,
-  // Cooldown before re-enabling workers (ms).
-  "workerFailureCooldownMs": 600000,
-  // Max chunks per worker batch.
-  "workerMaxChunksPerBatch": 20,
-  // Allow fallback to main-thread embeddings.
-  "allowSingleThreadFallback": false,
-  // Enable explicit GC (requires --expose-gc).
-  "enableExplicitGc": true,
-  // Use child process per batch for memory isolation.
-  "embeddingProcessPerBatch": false,
-  // Auto-enable child process when no workers + heavy model.
-  "autoEmbeddingProcessPerBatch": true,
-  // Override embedding batch size (null = auto).
-  "embeddingBatchSize": null,
-  // ONNX threads used by embedding child process.
-  "embeddingProcessNumThreads": 8,
-  // Wait time for active readers before saving cache (ms).
-  "saveReaderWaitTimeoutMs": 5000,
-  // Enable ANN index for large codebases.
-  "annEnabled": true,
-  // Minimum chunks required to build ANN.
-  "annMinChunks": 5000,
-  // Minimum ANN candidates to retrieve.
-  "annMinCandidates": 50,
-  // Maximum ANN candidates to retrieve.
-  "annMaxCandidates": 200,
-  // Scale ANN candidates by this multiplier.
-  "annCandidateMultiplier": 20,
-  // HNSW efConstruction value.
-  "annEfConstruction": 200,
-  // HNSW efSearch value.
-  "annEfSearch": 64,
-  // HNSW M parameter (graph degree).
-  "annM": 16,
-  // Persist ANN index to disk.
-  "annIndexCache": true,
-  // ANN distance metric.
-  "annMetric": "cosine",
-}
+    "**/vendor/**",
+    "**/.smart-coding-cache/**",
+  ],
+  // Indexing controls.
+  "indexing": {
+    // Enable project-type detection + smart ignore patterns.
+    "smartIndexing": true,
+    // Lines per chunk.
+    "chunkSize": 16,
+    // Overlapping lines between chunks.
+    "chunkOverlap": 4,
+    // Files per indexing batch.
+    "batchSize": 50,
+    // Skip files larger than this many bytes.
+    "maxFileSize": 1048576,
+    // Maximum number of search results.
+    "maxResults": 5,
+    // Enable file watcher for incremental indexing.
+    "watchFiles": true,
+  },
+  // Logging and diagnostics.
+  "logging": {
+    // Enable verbose logging.
+    "verbose": true,
+  },
+  // Cache engine and serialization controls.
+  "cache": {
+    // Persist embeddings between sessions.
+    "enableCache": true,
+    // Assume vectors are finite (skip validation).
+    "cacheVectorAssumeFinite": true,
+    // Decimal precision for cached vectors (null = default).
+    "cacheVectorFloatDigits": null,
+    // Write stream highWaterMark for cache files.
+    "cacheWriteHighWaterMark": 262144,
+    // Flush threshold (chars) for JSON writer.
+    "cacheVectorFlushChars": 262144,
+    // Validate vectors contain only finite numbers.
+    "cacheVectorCheckFinite": true,
+    // Avoid mutating vectors during serialization.
+    "cacheVectorNoMutation": false,
+    // Join threshold for JSON array chunks.
+    "cacheVectorJoinThreshold": 8192,
+    // Chunk size for JSON join optimization.
+    "cacheVectorJoinChunkSize": 2048,
+    // Wait time for active readers before saving cache (ms).
+    "saveReaderWaitTimeoutMs": 5000,
+  },
+  // Stale cache cleanup policy.
+  "cacheCleanup": {
+    // Remove stale caches automatically.
+    "autoCleanup": true,
+  },
+  // Worker-thread controls.
+  "worker": {
+    // Number of embedding workers (0 disables).
+    // Windows + heavy Jina models are more stable with child-process embedding than worker pools.
+    "workerThreads": 0,
+    // Worker batch timeout in milliseconds.
+    "workerBatchTimeoutMs": 120000,
+    // Failures before worker circuit opens.
+    "workerFailureThreshold": 1,
+    // Cooldown before re-enabling workers (ms).
+    "workerFailureCooldownMs": 600000,
+    // Max chunks per worker batch.
+    "workerMaxChunksPerBatch": 20,
+    // Allow fallback to main-thread embeddings.
+    "allowSingleThreadFallback": false,
+    // Abort worker embedding batches after repeated consecutive embedding failures.
+    "failFastEmbeddingErrors": false,
+  },
+  // Embedding/runtime controls.
+  "embedding": {
+    // Embedding model identifier.
+    "embeddingModel": "jinaai/jina-embeddings-v2-base-code",
+    // Preload the embedding model on startup. Set to false when using child processes for memory savings.
+    "preloadEmbeddingModel": false,
+    // Use child process per batch for memory isolation.
+    "embeddingProcessPerBatch": true,
+    // Auto-enable child process when no workers + heavy model.
+    "autoEmbeddingProcessPerBatch": false,
+    // 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+).
+    "embeddingProcessNumThreads": 8,
+    // Embedding-child adaptive GC RSS threshold in MB (higher = less frequent GC).
+    "embeddingProcessGcRssThresholdMb": 2048,
+    // Minimum interval between embedding-child GC runs.
+    "embeddingProcessGcMinIntervalMs": 15000,
+    // Backstop GC cadence if threshold is not crossed.
+    "embeddingProcessGcMaxRequestsWithoutCollection": 8,
+  },
+  // Vector store backend controls.
+  "vectorStore": {
+    // Vector store format: json, binary, or sqlite.
+    "vectorStoreFormat": "binary",
+    // Content storage: external or inline.
+    "vectorStoreContentMode": "external",
+    // In-memory content cache entries (binary store).
+    "contentCacheEntries": 256,
+    // Vector loading mode: "disk" keeps RAM lower by streaming vectors as needed.
+    "vectorStoreLoadMode": "disk",
+  },
+  // Search scoring controls.
+  "search": {
+    // Weight for semantic similarity scoring.
+    "semanticWeight": 0.7,
+    // Score boost for exact text matches.
+    "exactMatchBoost": 1.5,
+  },
+  // Memory cleanup and memory-footprint controls.
+  "memoryCleanup": {
+    // Enable explicit GC (requires --expose-gc).
+    "enableExplicitGc": true,
+    // Drop in-memory vectors after indexing completes.
+    "clearCacheAfterIndex": true,
+    // Unload embedding model after indexing.
+    "unloadModelAfterIndex": true,
+    // Shutdown persistent query embedding child pool after indexing.
+    "shutdownQueryEmbeddingPoolAfterIndex": true,
+    // Unload embedding model after searches.
+    "unloadModelAfterSearch": true,
+    // Idle timeout before query embedding child process exits (ms).
+    "embeddingPoolIdleTimeoutMs": 2000,
+    // RSS threshold for optional incremental GC.
+    "incrementalGcThresholdMb": 512,
+    // Optional: print detailed phase memory traces for incremental indexing/update paths.
+    "incrementalMemoryProfile": false,
+    // Optional: recycle server process when RSS stays too high after incremental cleanup.
+    // Safe default is disabled.
+    "recycleServerOnHighRssAfterIncremental": false,
+    // RSS threshold (MB) for incremental recycle trigger.
+    "recycleServerOnHighRssThresholdMb": 4096,
+    // Minimum interval between recycle attempts (ms).
+    "recycleServerOnHighRssCooldownMs": 300000,
+    // Delay before recycle to let logs/responses flush (ms).
+    "recycleServerOnHighRssDelayMs": 2000,
+  },
+  // Call graph proximity boosting controls.
+  "callGraph": {
+    "callGraphEnabled": true,
+    "callGraphBoost": 0.15,
+    "callGraphMaxHops": 1,
+  },
+  // ANN index controls.
+  "ann": {
+    // Enable ANN index for large codebases.
+    "annEnabled": true,
+    // Minimum chunks required to build ANN.
+    "annMinChunks": 5000,
+    // Minimum ANN candidates to retrieve.
+    "annMinCandidates": 50,
+    // Maximum ANN candidates to retrieve.
+    "annMaxCandidates": 200,
+    // Scale ANN candidates by this multiplier.
+    "annCandidateMultiplier": 20,
+    // HNSW efConstruction value.
+    "annEfConstruction": 200,
+    // HNSW efSearch value.
+    "annEfSearch": 64,
+    // HNSW M parameter (graph degree).
+    "annM": 16,
+    // Persist ANN index to disk.
+    "annIndexCache": true,
+    // ANN distance metric.
+    "annMetric": "cosine",
+  },
+}

package/index.js

@@ -53,7 +53,11 @@ import * as PackageVersionFeature from './features/package-version.js';
 import * as SetWorkspaceFeature from './features/set-workspace.js';
 import { handleListResources, handleReadResource } from './features/resources.js';
 
-import { MEMORY_LOG_INTERVAL_MS, ONNX_THREAD_LIMIT } from './lib/constants.js';
+import {
+  MEMORY_LOG_INTERVAL_MS,
+  ONNX_THREAD_LIMIT,
+  BACKGROUND_INDEX_DELAY_MS,
+} from './lib/constants.js';
 const PID_FILE_NAME = '.heuristic-mcp.pid';
 
 async function readLogTail(logPath, maxLines = 2000) {
@@ -177,41 +181,46 @@ async function initialize(workspaceDir) {
     }
   }
   
-  // Skip gc check during tests (VITEST env is set)
-  const isTest = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
-  if (config.enableExplicitGc && typeof global.gc !== 'function' && !isTest) {
-    console.error(
-      '[Server] FATAL: enableExplicitGc=true but this process was not started with --expose-gc.'
-    );
-    console.error(
-      '[Server] Please start the server using "npm start" or add --expose-gc to your node command.'
-    );
-    process.exit(1);
-  }
+  // Skip gc check during tests (VITEST env is set)
+  const isTest = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
+  if (config.enableExplicitGc && typeof global.gc !== 'function' && !isTest) {
+    console.warn(
+      '[Server] enableExplicitGc=true but this process was not started with --expose-gc; continuing with explicit GC disabled.'
+    );
+    console.warn(
+      '[Server] Tip: start with "npm start" or add --expose-gc to enable explicit GC again.'
+    );
+    config.enableExplicitGc = false;
+  }
 
   let mainBackendConfigured = false;
   let nativeOnnxAvailable = null;
-  const ensureMainOnnxBackend = () => {
-    if (mainBackendConfigured) return;
-    nativeOnnxAvailable = configureNativeOnnxBackend({
-      log: config.verbose ? console.info : null,
-      label: '[Server]',
-      threads: {
+  const ensureMainOnnxBackend = () => {
+    if (mainBackendConfigured) return;
+    nativeOnnxAvailable = configureNativeOnnxBackend({
+      log: config.verbose ? console.info : null,
+      label: '[Server]',
+      threads: {
         intraOpNumThreads: ONNX_THREAD_LIMIT,
         interOpNumThreads: 1,
       },
     });
-    if (!nativeOnnxAvailable && env?.backends?.onnx?.wasm) {
-      env.backends.onnx.wasm.numThreads = ONNX_THREAD_LIMIT;
-    }
-    mainBackendConfigured = true;
-  };
-
-  ensureMainOnnxBackend();
-  if (nativeOnnxAvailable === false) {
-    const status = getNativeOnnxStatus();
-    const reason = status?.message || 'onnxruntime-node not available';
-    console.warn(`[Server] Native ONNX backend unavailable (${reason}); using WASM backend.`);
+    mainBackendConfigured = true;
+  };
+
+  ensureMainOnnxBackend();
+  if (nativeOnnxAvailable === false) {
+    try {
+      const { env } = await getTransformers();
+      if (env?.backends?.onnx?.wasm) {
+        env.backends.onnx.wasm.numThreads = ONNX_THREAD_LIMIT;
+      }
+    } catch {
+      // ignore: fallback tuning is best effort
+    }
+    const status = getNativeOnnxStatus();
+    const reason = status?.message || 'onnxruntime-node not available';
+    console.warn(`[Server] Native ONNX backend unavailable (${reason}); using WASM backend.`);
     console.warn(
       '[Server] Auto-safety: disabling workers and forcing embeddingProcessPerBatch for memory isolation.'
     );
@@ -243,9 +252,12 @@ async function initialize(workspaceDir) {
   }
 
   // Log effective configuration for debugging
-  console.info(
-    `[Server] Config: workerThreads=${config.workerThreads}, embeddingProcessPerBatch=${config.embeddingProcessPerBatch}`
-  );
+  console.info(
+    `[Server] Config: workerThreads=${config.workerThreads}, embeddingProcessPerBatch=${config.embeddingProcessPerBatch}`
+  );
+  console.info(
+    `[Server] Config: vectorStoreLoadMode=${config.vectorStoreLoadMode}, vectorCacheEntries=${config.vectorCacheEntries}`
+  );
 
   if (pidPath) {
     console.info(`[Server] PID file: ${pidPath}`);
@@ -330,25 +342,22 @@ async function initialize(workspaceDir) {
       cachedEmbedderPromise = null;
       return false;
     }
-  };
-  
-  embedder = lazyEmbedder;
-  unloadMainEmbedder = unloader; // Store in module scope for tool handler access
-  let embedderPreloaded = false;
-
-  // Preload the embedding model to ensure deterministic startup logs
-  if (config.preloadEmbeddingModel !== false) {
-    try {
-      console.info('[Server] Preloading embedding model...');
-      await embedder(' ');
-      embedderPreloaded = true;
-    } catch (err) {
-      console.warn(`[Server] Embedding model preload failed: ${err.message}`);
-    }
-  }
-
-  // NOTE: We no longer auto-load in verbose mode when preloadEmbeddingModel=false.
-  // The model will be loaded lazily on first search or by child processes during indexing.
+  };
+  
+  embedder = lazyEmbedder;
+  unloadMainEmbedder = unloader; // Store in module scope for tool handler access
+  const preloadEmbeddingModel = async () => {
+    if (config.preloadEmbeddingModel === false) return;
+    try {
+      console.info('[Server] Preloading embedding model (background)...');
+      await embedder(' ');
+    } catch (err) {
+      console.warn(`[Server] Embedding model preload failed: ${err.message}`);
+    }
+  };
+
+  // NOTE: We no longer auto-load in verbose mode when preloadEmbeddingModel=false.
+  // The model will be loaded lazily on first search or by child processes during indexing.
 
   // Initialize cache (load deferred until after server is ready)
   cache = new EmbeddingsCache(config);
@@ -382,10 +391,13 @@ async function initialize(workspaceDir) {
   // Attach hybridSearch to server for cross-feature access (e.g. cache invalidation)
   server.hybridSearch = hybridSearch;
 
-  const startBackgroundTasks = async () => {
-    try {
-      console.info('[Server] Loading cache (deferred)...');
-      await cache.load();
+  const startBackgroundTasks = async () => {
+    // Keep startup responsive: do not block server readiness on model preload.
+    void preloadEmbeddingModel();
+
+    try {
+      console.info('[Server] Loading cache (deferred)...');
+      await cache.load();
       if (config.verbose) {
         logMemory('[Server] Memory (after cache load)');
       }
@@ -411,8 +423,8 @@ async function initialize(workspaceDir) {
         .catch((err) => {
           console.error('[Server] Background indexing error:', err.message);
         });
-    }, 3000);
-  };
+    }, BACKGROUND_INDEX_DELAY_MS);
+  };
 
   return { startBackgroundTasks, config };
 }