@softerist/heuristic-mcp 3.0.12 → 3.0.14

package/lib/config.js

@@ -5,8 +5,127 @@ import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import { ProjectDetector } from './project-detector.js';
 import { parseJsonc } from './settings-editor.js';
-
-const DEFAULT_CONFIG = {
+import {
+  EMBEDDING_PROCESS_DEFAULT_GC_MAX_REQUESTS_WITHOUT_COLLECTION,
+  EMBEDDING_PROCESS_DEFAULT_GC_MIN_INTERVAL_MS,
+  EMBEDDING_PROCESS_DEFAULT_GC_RSS_THRESHOLD_MB,
+} from './constants.js';
+
+const DEFAULT_MEMORY_CLEANUP_CONFIG = {
+  enableExplicitGc: true, // Require --expose-gc for more aggressive memory cleanup
+  clearCacheAfterIndex: true, // Drop in-memory vectors after indexing completes
+  unloadModelAfterIndex: true, // Unload embedding model from memory after indexing completes to free RAM
+  shutdownQueryEmbeddingPoolAfterIndex: true, // Force shutdown search embedding child pool after index operations
+  unloadModelAfterSearch: true, // Unload embedding model after search queries to keep memory low (trades speed for RAM)
+  embeddingPoolIdleTimeoutMs: 2000, // Idle timeout before killing persistent embedding child process (ms)
+  incrementalGcThresholdMb: 512, // RSS threshold for optional incremental GC
+  incrementalMemoryProfile: false, // Enable phase-level incremental indexing memory traces (diagnostics)
+  recycleServerOnHighRssAfterIncremental: false, // Recycle server process after incremental cleanup if RSS remains high
+  recycleServerOnHighRssThresholdMb: 4096, // RSS threshold (MB) that triggers incremental recycle
+  recycleServerOnHighRssCooldownMs: 300000, // Minimum interval between recycle attempts
+  recycleServerOnHighRssDelayMs: 2000, // Delay before recycle to allow logs/responses to flush
+};
+
+const DEFAULT_INDEXING_CONFIG = {
+  smartIndexing: true, // Enable automatic project type detection and smart ignore patterns
+  chunkSize: 16, // Lines per chunk (tuned for speed/memory balance)
+  chunkOverlap: 4, // Overlap between chunks for context continuity
+  batchSize: 50, // Number of files to process in a single indexing batch
+  maxFileSize: 1048576, // 1MB - skip files larger than this
+  prefilterContentMaxBytes: 512 * 1024, // 512KB - cache content during prefilter to avoid double reads
+  maxResults: 5, // Maximum number of semantic search results to return
+  watchFiles: true, // Enable file system watcher to re-index changed files in real-time
+};
+
+const DEFAULT_LOGGING_CONFIG = {
+  verbose: false, // Enable detailed logging for debugging and progress tracking
+  memoryLogIntervalMs: 5000, // Verbose memory log cadence during indexing (ms)
+};
+
+const DEFAULT_CACHE_CONFIG = {
+  enableCache: true, // Whether to persist and reload embeddings between sessions
+  saveReaderWaitTimeoutMs: 5000, // Max wait for active reads before saving binary cache
+  cacheVectorAssumeFinite: true, // Assume vectors are finite (skip validation)
+  cacheVectorFloatDigits: null, // Decimal precision for cached vectors (null = default)
+  cacheWriteHighWaterMark: 262144, // Write stream highWaterMark for cache files
+  cacheVectorFlushChars: 262144, // Flush threshold (chars) for JSON writer
+  cacheVectorCheckFinite: true, // Validate vectors contain only finite numbers
+  cacheVectorNoMutation: false, // Avoid mutating vectors during serialization
+  cacheVectorJoinThreshold: 8192, // Join threshold for JSON array chunks
+  cacheVectorJoinChunkSize: 2048, // Chunk size for JSON join optimization
+};
+
+const DEFAULT_WORKER_CONFIG = {
+  workerThreads: 'auto', // 0 = run in main thread (no workers), "auto" = CPU cores - 1, or set a number
+  workerBatchTimeoutMs: 120000, // Timeout per worker batch before fallback (ms)
+  workerFailureThreshold: 1, // Open circuit after N worker failures
+  workerFailureCooldownMs: 10 * 60 * 1000, // Cooldown before retrying workers
+  workerMaxChunksPerBatch: 100, // Cap chunks per worker batch to reduce hang risk
+  allowSingleThreadFallback: false, // Allow fallback to main-thread embeddings if workers fail
+  failFastEmbeddingErrors: false, // Abort worker embedding batch after repeated consecutive embed failures
+};
+
+const DEFAULT_EMBEDDING_CONFIG = {
+  embeddingModel: 'jinaai/jina-embeddings-v2-base-code', // AI model ID used for semantic search
+  embeddingDimension: null, // null = full dimensions, or 64/128/256/512/768 for MRL-trained models
+  preloadEmbeddingModel: true, // Preload the embedding model at startup (server mode)
+  embeddingProcessPerBatch: false, // Use child process per batch for memory isolation
+  autoEmbeddingProcessPerBatch: true, // Auto-enable child process embedding in single-threaded mode for heavy models
+  embeddingBatchSize: null, // Override embedding batch size (null = auto)
+  embeddingProcessNumThreads: 8, // ONNX threads used by embedding child process
+  embeddingProcessGcRssThresholdMb: EMBEDDING_PROCESS_DEFAULT_GC_RSS_THRESHOLD_MB, // RSS threshold for embedding-child adaptive GC
+  embeddingProcessGcMinIntervalMs: EMBEDDING_PROCESS_DEFAULT_GC_MIN_INTERVAL_MS, // Minimum interval between embedding-child GC runs
+  embeddingProcessGcMaxRequestsWithoutCollection:
+    EMBEDDING_PROCESS_DEFAULT_GC_MAX_REQUESTS_WITHOUT_COLLECTION, // Backstop GC cadence for embedding child
+};
+
+const DEFAULT_VECTOR_STORE_CONFIG = {
+  vectorStoreFormat: 'binary', // json | binary | sqlite (binary uses mmap-friendly on-disk store)
+  vectorStoreContentMode: 'external', // external = content loaded on-demand for binary store
+  contentCacheEntries: 256, // In-memory content cache entries for binary store
+  vectorStoreLoadMode: 'memory', // memory | disk (disk streams vectors from disk / memory is faster but requires more RAM)
+  vectorCacheEntries: 0, // In-memory vector cache entries for disk-backed loads
+};
+
+const DEFAULT_SEARCH_CONFIG = {
+  semanticWeight: 0.7, // Balance between semantic and keyword scores (0.0 to 1.0)
+  exactMatchBoost: 1.5, // Multiplier applied when an exact string match is found
+  recencyBoost: 0.1, // Boost for recently modified files (max 0.1 added to score)
+  recencyDecayDays: 30, // After this many days, recency boost is 0
+  textMatchMaxCandidates: 2000, // Max candidates for full text matching before deferring
+};
+
+const DEFAULT_CALL_GRAPH_CONFIG = {
+  callGraphEnabled: true, // Enable call graph extraction for proximity boosting
+  callGraphBoost: 0.15, // Boost for files related via call graph (0-1)
+  callGraphMaxHops: 1, // How many levels of calls to follow (1 = direct only)
+};
+
+const DEFAULT_ANN_CONFIG = {
+  annEnabled: true, // Enable Approximate Nearest Neighbor (ANN) index for large codebases
+  annMinChunks: 5000, // Minimum number of chunks required to trigger ANN indexing
+  annMinCandidates: 50, // Minimum initial candidates to pull from ANN before refinement
+  annMaxCandidates: 200, // Hard limit on the number of ANN candidates to process
+  annCandidateMultiplier: 20, // Scale initial search depth based on requested maxResults
+  annEfConstruction: 200, // HNSW index construction quality (higher = better index, slower build)
+  annEfSearch: 64, // HNSW search parameter (higher = more accurate, slower search)
+  annM: 16, // Number of connections per element in HNSW index
+  annIndexCache: true, // Whether to cache the built HNSW index on disk
+  annMetric: 'cosine', // Distance metric for similarity (currently locked to cosine)
+};
+
+const MEMORY_CLEANUP_KEYS = Object.freeze(Object.keys(DEFAULT_MEMORY_CLEANUP_CONFIG));
+const INDEXING_KEYS = Object.freeze(Object.keys(DEFAULT_INDEXING_CONFIG));
+const LOGGING_KEYS = Object.freeze(Object.keys(DEFAULT_LOGGING_CONFIG));
+const CACHE_KEYS = Object.freeze(Object.keys(DEFAULT_CACHE_CONFIG));
+const WORKER_KEYS = Object.freeze(Object.keys(DEFAULT_WORKER_CONFIG));
+const EMBEDDING_KEYS = Object.freeze(Object.keys(DEFAULT_EMBEDDING_CONFIG));
+const VECTOR_STORE_KEYS = Object.freeze(Object.keys(DEFAULT_VECTOR_STORE_CONFIG));
+const SEARCH_KEYS = Object.freeze(Object.keys(DEFAULT_SEARCH_CONFIG));
+const CALL_GRAPH_KEYS = Object.freeze(Object.keys(DEFAULT_CALL_GRAPH_CONFIG));
+const ANN_KEYS = Object.freeze(Object.keys(DEFAULT_ANN_CONFIG));
+
+const DEFAULT_CONFIG = {
   searchDirectory: '.',
   fileExtensions: [
     // JavaScript/TypeScript
@@ -242,16 +361,16 @@ const DEFAULT_CONFIG = {
     '**/scripts/**',
     '**/tools/**',
   ],
-  chunkSize: 16, // Lines per chunk (tuned for speed/memory balance)
-  chunkOverlap: 4, // Overlap between chunks for context continuity
-  batchSize: 50, // Number of files to process in a single indexing batch
-  maxFileSize: 1048576, // 1MB - skip files larger than this
-  prefilterContentMaxBytes: 512 * 1024, // 512KB - cache content during prefilter to avoid double reads
-  maxResults: 5, // Maximum number of semantic search results to return
-  enableCache: true, // Whether to persist and reload embeddings between sessions
-  cacheDirectory: null, // Will be set dynamically by loadConfig()
-  // Cache cleanup behavior (consolidated namespace)
-  cacheCleanup: {
+  chunkSize: DEFAULT_INDEXING_CONFIG.chunkSize,
+  chunkOverlap: DEFAULT_INDEXING_CONFIG.chunkOverlap,
+  batchSize: DEFAULT_INDEXING_CONFIG.batchSize,
+  maxFileSize: DEFAULT_INDEXING_CONFIG.maxFileSize,
+  prefilterContentMaxBytes: DEFAULT_INDEXING_CONFIG.prefilterContentMaxBytes,
+  maxResults: DEFAULT_INDEXING_CONFIG.maxResults,
+  enableCache: DEFAULT_CACHE_CONFIG.enableCache,
+  cacheDirectory: null, // Will be set dynamically by loadConfig()
+  // Cache cleanup behavior (consolidated namespace)
+  cacheCleanup: {
     autoCleanup: true, // Automatically remove stale caches on startup
     staleNoMetaHours: 6, // Hours before incomplete cache (no meta.json) is considered stale
     emptyThresholdHours: 24, // Hours before empty cache (0 files/chunks) is removed
@@ -259,56 +378,82 @@ const DEFAULT_CONFIG = {
     maxUnusedDays: 30, // Days before unused cache is removed
     tempThresholdHours: 24, // Hours before temp workspace cache is removed
     staleProgressHours: 6, // Hours before stuck indexing is considered stale
-    safetyWindowMinutes: 10, // Minutes of recent activity to never delete
-    removeDuplicates: true, // Remove duplicate workspace caches
-  },
-  watchFiles: true, // Enable file system watcher to re-index changed files in real-time
-  verbose: false, // Enable detailed logging for debugging and progress tracking
-  saveReaderWaitTimeoutMs: 5000, // Max wait for active reads before saving binary cache
-  workerThreads: 'auto', // 0 = run in main thread (no workers), "auto" = CPU cores - 1, or set a number
-  workerBatchTimeoutMs: 120000, // Timeout per worker batch before fallback (ms)
-  workerFailureThreshold: 1, // Open circuit after N worker failures
-  workerFailureCooldownMs: 10 * 60 * 1000, // Cooldown before retrying workers
-  workerMaxChunksPerBatch: 100, // Cap chunks per worker batch to reduce hang risk
-  allowSingleThreadFallback: false, // Allow fallback to main-thread embeddings if workers fail
-  embeddingProcessPerBatch: false, // Use child process per batch for memory isolation
-  autoEmbeddingProcessPerBatch: true, // Auto-enable child process embedding in single-threaded mode for heavy models
-  embeddingBatchSize: null, // Override embedding batch size (null = auto)
-  embeddingProcessNumThreads: 8, // ONNX threads used by embedding child process
-  enableExplicitGc: true, // Require --expose-gc for more aggressive memory cleanup
-  embeddingModel: 'jinaai/jina-embeddings-v2-base-code', // AI model ID used for semantic search - can be changed with a lighter model for speed
-  embeddingDimension: null, // null = full dimensions, or 64/128/256/512/768 for MRL-trained models (e.g. nomic-embed-text-v1.5)
-  preloadEmbeddingModel: true, // Preload the embedding model at startup (server mode)
-  vectorStoreFormat: 'binary', // json | binary | sqlite (binary uses mmap-friendly on-disk store)
-  vectorStoreContentMode: 'external', // external = content loaded on-demand for binary store
-  contentCacheEntries: 256, // In-memory content cache entries for binary store
-  vectorStoreLoadMode: 'memory', // memory | disk (disk streams vectors from disk / memory is faster but requires more RAM)
-  vectorCacheEntries: 0, // In-memory vector cache entries for disk-backed loads
-  clearCacheAfterIndex: true, // Drop in-memory vectors after indexing completes
-  unloadModelAfterIndex: true, // Unload embedding model from memory after indexing completes to free RAM
-  unloadModelAfterSearch: true, // Unload embedding model after search queries to keep memory low (trades speed for RAM)
-  embeddingPoolIdleTimeoutMs: 10000, // Idle timeout before killing persistent embedding child process (ms)
-  incrementalGcThresholdMb: 2048, // RSS threshold for optional incremental GC (requires enableExplicitGc)
-  semanticWeight: 0.7, // Balance between semantic and keyword scores (0.0 to 1.0)
-  exactMatchBoost: 1.5, // Multiplier applied when an exact string match is found
-  recencyBoost: 0.1, // Boost for recently modified files (max 0.1 added to score)
-  recencyDecayDays: 30, // After this many days, recency boost is 0
-  textMatchMaxCandidates: 2000, // Max candidates for full text matching before deferring
-  smartIndexing: true, // Enable automatic project type detection and smart ignore patterns
-  callGraphEnabled: true, // Enable call graph extraction for proximity boosting
-  callGraphBoost: 0.15, // Boost for files related via call graph (0-1)
-  callGraphMaxHops: 1, // How many levels of calls to follow (1 = direct only)
-  annEnabled: true, // Enable Approximate Nearest Neighbor (ANN) index for large codebases
-  annMinChunks: 5000, // Minimum number of chunks required to trigger ANN indexing
-  annMinCandidates: 50, // Minimum initial candidates to pull from ANN before refinement
-  annMaxCandidates: 200, // Hard limit on the number of ANN candidates to process
-  annCandidateMultiplier: 20, // Scale initial search depth based on requested maxResults
-  annEfConstruction: 200, // HNSW index construction quality (higher = better index, slower build)
-  annEfSearch: 64, // HNSW search parameter (higher = more accurate, slower search)
-  annM: 16, // Number of connections per element in HNSW index
-  annIndexCache: true, // Whether to cache the built HNSW index on disk
-  annMetric: 'cosine', // Distance metric for similarity (currently locked to cosine)
-};
+    safetyWindowMinutes: 10, // Minutes of recent activity to never delete
+    removeDuplicates: true, // Remove duplicate workspace caches
+  },
+  watchFiles: DEFAULT_INDEXING_CONFIG.watchFiles,
+  verbose: DEFAULT_LOGGING_CONFIG.verbose,
+  memoryLogIntervalMs: DEFAULT_LOGGING_CONFIG.memoryLogIntervalMs,
+  saveReaderWaitTimeoutMs: DEFAULT_CACHE_CONFIG.saveReaderWaitTimeoutMs,
+  workerThreads: DEFAULT_WORKER_CONFIG.workerThreads,
+  workerBatchTimeoutMs: DEFAULT_WORKER_CONFIG.workerBatchTimeoutMs,
+  workerFailureThreshold: DEFAULT_WORKER_CONFIG.workerFailureThreshold,
+  workerFailureCooldownMs: DEFAULT_WORKER_CONFIG.workerFailureCooldownMs,
+  workerMaxChunksPerBatch: DEFAULT_WORKER_CONFIG.workerMaxChunksPerBatch,
+  allowSingleThreadFallback: DEFAULT_WORKER_CONFIG.allowSingleThreadFallback,
+  failFastEmbeddingErrors: DEFAULT_WORKER_CONFIG.failFastEmbeddingErrors,
+  embeddingProcessPerBatch: DEFAULT_EMBEDDING_CONFIG.embeddingProcessPerBatch,
+  autoEmbeddingProcessPerBatch: DEFAULT_EMBEDDING_CONFIG.autoEmbeddingProcessPerBatch,
+  embeddingBatchSize: DEFAULT_EMBEDDING_CONFIG.embeddingBatchSize,
+  embeddingProcessNumThreads: DEFAULT_EMBEDDING_CONFIG.embeddingProcessNumThreads,
+  embeddingProcessGcRssThresholdMb: DEFAULT_EMBEDDING_CONFIG.embeddingProcessGcRssThresholdMb,
+  embeddingProcessGcMinIntervalMs: DEFAULT_EMBEDDING_CONFIG.embeddingProcessGcMinIntervalMs,
+  embeddingProcessGcMaxRequestsWithoutCollection:
+    DEFAULT_EMBEDDING_CONFIG.embeddingProcessGcMaxRequestsWithoutCollection,
+  enableExplicitGc: DEFAULT_MEMORY_CLEANUP_CONFIG.enableExplicitGc,
+  embeddingModel: DEFAULT_EMBEDDING_CONFIG.embeddingModel,
+  embeddingDimension: DEFAULT_EMBEDDING_CONFIG.embeddingDimension,
+  preloadEmbeddingModel: DEFAULT_EMBEDDING_CONFIG.preloadEmbeddingModel,
+  vectorStoreFormat: DEFAULT_VECTOR_STORE_CONFIG.vectorStoreFormat,
+  vectorStoreContentMode: DEFAULT_VECTOR_STORE_CONFIG.vectorStoreContentMode,
+  contentCacheEntries: DEFAULT_VECTOR_STORE_CONFIG.contentCacheEntries,
+  vectorStoreLoadMode: DEFAULT_VECTOR_STORE_CONFIG.vectorStoreLoadMode,
+  vectorCacheEntries: DEFAULT_VECTOR_STORE_CONFIG.vectorCacheEntries,
+  clearCacheAfterIndex: DEFAULT_MEMORY_CLEANUP_CONFIG.clearCacheAfterIndex,
+  unloadModelAfterIndex: DEFAULT_MEMORY_CLEANUP_CONFIG.unloadModelAfterIndex,
+  shutdownQueryEmbeddingPoolAfterIndex:
+    DEFAULT_MEMORY_CLEANUP_CONFIG.shutdownQueryEmbeddingPoolAfterIndex,
+  unloadModelAfterSearch: DEFAULT_MEMORY_CLEANUP_CONFIG.unloadModelAfterSearch,
+  embeddingPoolIdleTimeoutMs: DEFAULT_MEMORY_CLEANUP_CONFIG.embeddingPoolIdleTimeoutMs,
+  incrementalGcThresholdMb: DEFAULT_MEMORY_CLEANUP_CONFIG.incrementalGcThresholdMb,
+  incrementalMemoryProfile: DEFAULT_MEMORY_CLEANUP_CONFIG.incrementalMemoryProfile,
+  recycleServerOnHighRssAfterIncremental:
+    DEFAULT_MEMORY_CLEANUP_CONFIG.recycleServerOnHighRssAfterIncremental,
+  recycleServerOnHighRssThresholdMb:
+    DEFAULT_MEMORY_CLEANUP_CONFIG.recycleServerOnHighRssThresholdMb,
+  recycleServerOnHighRssCooldownMs:
+    DEFAULT_MEMORY_CLEANUP_CONFIG.recycleServerOnHighRssCooldownMs,
+  recycleServerOnHighRssDelayMs: DEFAULT_MEMORY_CLEANUP_CONFIG.recycleServerOnHighRssDelayMs,
+  memoryCleanup: { ...DEFAULT_MEMORY_CLEANUP_CONFIG },
+  semanticWeight: DEFAULT_SEARCH_CONFIG.semanticWeight,
+  exactMatchBoost: DEFAULT_SEARCH_CONFIG.exactMatchBoost,
+  recencyBoost: DEFAULT_SEARCH_CONFIG.recencyBoost,
+  recencyDecayDays: DEFAULT_SEARCH_CONFIG.recencyDecayDays,
+  textMatchMaxCandidates: DEFAULT_SEARCH_CONFIG.textMatchMaxCandidates,
+  smartIndexing: DEFAULT_INDEXING_CONFIG.smartIndexing,
+  callGraphEnabled: DEFAULT_CALL_GRAPH_CONFIG.callGraphEnabled,
+  callGraphBoost: DEFAULT_CALL_GRAPH_CONFIG.callGraphBoost,
+  callGraphMaxHops: DEFAULT_CALL_GRAPH_CONFIG.callGraphMaxHops,
+  annEnabled: DEFAULT_ANN_CONFIG.annEnabled,
+  annMinChunks: DEFAULT_ANN_CONFIG.annMinChunks,
+  annMinCandidates: DEFAULT_ANN_CONFIG.annMinCandidates,
+  annMaxCandidates: DEFAULT_ANN_CONFIG.annMaxCandidates,
+  annCandidateMultiplier: DEFAULT_ANN_CONFIG.annCandidateMultiplier,
+  annEfConstruction: DEFAULT_ANN_CONFIG.annEfConstruction,
+  annEfSearch: DEFAULT_ANN_CONFIG.annEfSearch,
+  annM: DEFAULT_ANN_CONFIG.annM,
+  annIndexCache: DEFAULT_ANN_CONFIG.annIndexCache,
+  annMetric: DEFAULT_ANN_CONFIG.annMetric,
+  indexing: { ...DEFAULT_INDEXING_CONFIG },
+  logging: { ...DEFAULT_LOGGING_CONFIG },
+  cache: { ...DEFAULT_CACHE_CONFIG },
+  worker: { ...DEFAULT_WORKER_CONFIG },
+  embedding: { ...DEFAULT_EMBEDDING_CONFIG },
+  vectorStore: { ...DEFAULT_VECTOR_STORE_CONFIG },
+  search: { ...DEFAULT_SEARCH_CONFIG },
+  callGraph: { ...DEFAULT_CALL_GRAPH_CONFIG },
+  ann: { ...DEFAULT_ANN_CONFIG },
+};
 
 let config = { ...DEFAULT_CONFIG };
 
@@ -323,7 +468,7 @@ const WORKSPACE_ENV_VARS = [
   'INIT_CWD',
 ];
 
-const WORKSPACE_MARKERS = [
+const WORKSPACE_MARKERS = [
   '.git',
   'package.json',
   'pyproject.toml',
@@ -335,8 +480,118 @@ const WORKSPACE_MARKERS = [
   'requirements.txt',
   'Gemfile',
   'Makefile',
-  'CMakeLists.txt',
-];
+  'CMakeLists.txt',
+];
+
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+const CONFIG_NAMESPACES = Object.freeze([
+  {
+    name: 'memoryCleanup',
+    keys: MEMORY_CLEANUP_KEYS,
+    defaults: DEFAULT_MEMORY_CLEANUP_CONFIG,
+  },
+  {
+    name: 'indexing',
+    keys: INDEXING_KEYS,
+    defaults: DEFAULT_INDEXING_CONFIG,
+  },
+  {
+    name: 'logging',
+    keys: LOGGING_KEYS,
+    defaults: DEFAULT_LOGGING_CONFIG,
+  },
+  {
+    name: 'cache',
+    keys: CACHE_KEYS,
+    defaults: DEFAULT_CACHE_CONFIG,
+  },
+  {
+    name: 'worker',
+    keys: WORKER_KEYS,
+    defaults: DEFAULT_WORKER_CONFIG,
+  },
+  {
+    name: 'embedding',
+    keys: EMBEDDING_KEYS,
+    defaults: DEFAULT_EMBEDDING_CONFIG,
+  },
+  {
+    name: 'vectorStore',
+    keys: VECTOR_STORE_KEYS,
+    defaults: DEFAULT_VECTOR_STORE_CONFIG,
+  },
+  {
+    name: 'search',
+    keys: SEARCH_KEYS,
+    defaults: DEFAULT_SEARCH_CONFIG,
+  },
+  {
+    name: 'callGraph',
+    keys: CALL_GRAPH_KEYS,
+    defaults: DEFAULT_CALL_GRAPH_CONFIG,
+  },
+  {
+    name: 'ann',
+    keys: ANN_KEYS,
+    defaults: DEFAULT_ANN_CONFIG,
+  },
+]);
+
+function applyNamespace(targetConfig, sourceConfig, namespaceName, keys, defaults) {
+  const sourceNamespace =
+    sourceConfig && typeof sourceConfig[namespaceName] === 'object'
+      ? sourceConfig[namespaceName]
+      : {};
+  const mergedNamespace = {
+    ...defaults,
+    ...(targetConfig[namespaceName] && typeof targetConfig[namespaceName] === 'object'
+      ? targetConfig[namespaceName]
+      : {}),
+  };
+
+  for (const key of keys) {
+    if (hasOwn(sourceNamespace, key)) {
+      targetConfig[key] = mergedNamespace[key];
+    } else {
+      mergedNamespace[key] = targetConfig[key];
+    }
+  }
+
+  targetConfig[namespaceName] = mergedNamespace;
+}
+
+function syncNamespace(targetConfig, namespaceName, keys, defaults) {
+  const currentNamespace =
+    targetConfig[namespaceName] && typeof targetConfig[namespaceName] === 'object'
+      ? targetConfig[namespaceName]
+      : {};
+  const mergedNamespace = { ...defaults, ...currentNamespace };
+  for (const key of keys) {
+    mergedNamespace[key] = targetConfig[key];
+  }
+  targetConfig[namespaceName] = mergedNamespace;
+}
+
+function applyAllNamespaces(targetConfig, sourceConfig) {
+  for (const namespace of CONFIG_NAMESPACES) {
+    applyNamespace(
+      targetConfig,
+      sourceConfig,
+      namespace.name,
+      namespace.keys,
+      namespace.defaults
+    );
+  }
+}
+
+function syncAllNamespaces(targetConfig) {
+  for (const namespace of CONFIG_NAMESPACES) {
+    syncNamespace(targetConfig, namespace.name, namespace.keys, namespace.defaults);
+  }
+}
 
 async function pathExists(filePath) {
   try {
@@ -444,7 +699,16 @@ export async function loadConfig(workspaceDir = null) {
       }
     }
 
-    config = { ...DEFAULT_CONFIG, ...userConfig };
+    config = { ...DEFAULT_CONFIG, ...userConfig };
+    applyAllNamespaces(config, userConfig);
+
+    // Backward compatibility for legacy top-level cache cleanup toggle.
+    if (
+      hasOwn(userConfig, 'autoCleanStaleCaches') &&
+      !(userConfig.cacheCleanup && hasOwn(userConfig.cacheCleanup, 'autoCleanup'))
+    ) {
+      config.cacheCleanup.autoCleanup = Boolean(userConfig.autoCleanStaleCaches);
+    }
 
     // Set search directory (respect user override when provided)
     if (userConfig.searchDirectory) {
@@ -479,7 +743,7 @@ export async function loadConfig(workspaceDir = null) {
         if (stats.isDirectory()) {
           config.cacheDirectory = legacyPath;
           if (config.verbose) {
-            console.error(`[Config] Using existing local cache: ${legacyPath}`);
+            console.info(`[Config] Using existing local cache: ${legacyPath}`);
           }
         }
       } catch {
@@ -524,6 +788,17 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
+  if (process.env.SMART_CODING_MEMORY_LOG_INTERVAL_MS !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_MEMORY_LOG_INTERVAL_MS, 10);
+    if (!isNaN(value) && value >= 0 && value <= 300000) {
+      config.memoryLogIntervalMs = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_MEMORY_LOG_INTERVAL_MS: ${process.env.SMART_CODING_MEMORY_LOG_INTERVAL_MS}, using default`
+      );
+    }
+  }
+
   if (process.env.SMART_CODING_BATCH_SIZE !== undefined) {
     const value = parseInt(process.env.SMART_CODING_BATCH_SIZE, 10);
     if (!isNaN(value) && value > 0 && value <= 1000) {
@@ -697,6 +972,17 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
+  if (process.env.SMART_CODING_SHUTDOWN_QUERY_POOL_AFTER_INDEX !== undefined) {
+    const value = process.env.SMART_CODING_SHUTDOWN_QUERY_POOL_AFTER_INDEX;
+    if (value === 'true' || value === 'false') {
+      config.shutdownQueryEmbeddingPoolAfterIndex = value === 'true';
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_SHUTDOWN_QUERY_POOL_AFTER_INDEX: ${value}, using default`
+      );
+    }
+  }
+
   if (process.env.SMART_CODING_UNLOAD_MODEL_AFTER_SEARCH !== undefined) {
     const value = process.env.SMART_CODING_UNLOAD_MODEL_AFTER_SEARCH;
     if (value === 'true' || value === 'false') {
@@ -704,19 +990,74 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
-  if (process.env.SMART_CODING_INCREMENTAL_GC_THRESHOLD_MB !== undefined) {
-    const value = parseInt(process.env.SMART_CODING_INCREMENTAL_GC_THRESHOLD_MB, 10);
-    if (!isNaN(value) && value >= 0) {
-      config.incrementalGcThresholdMb = value;
+  if (process.env.SMART_CODING_INCREMENTAL_GC_THRESHOLD_MB !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_INCREMENTAL_GC_THRESHOLD_MB, 10);
+    if (!isNaN(value) && value >= 0) {
+      config.incrementalGcThresholdMb = value;
     } else {
       console.warn(
         `[Config] Invalid SMART_CODING_INCREMENTAL_GC_THRESHOLD_MB: ${process.env.SMART_CODING_INCREMENTAL_GC_THRESHOLD_MB}, using default`
-      );
-    }
-  }
-
-  if (process.env.SMART_CODING_CONTENT_CACHE_ENTRIES !== undefined) {
-    const value = parseInt(process.env.SMART_CODING_CONTENT_CACHE_ENTRIES, 10);
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_INCREMENTAL_MEMORY_PROFILE !== undefined) {
+    const value = process.env.SMART_CODING_INCREMENTAL_MEMORY_PROFILE;
+    if (value === 'true' || value === 'false') {
+      config.incrementalMemoryProfile = value === 'true';
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_INCREMENTAL_MEMORY_PROFILE: ${value}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_RECYCLE_SERVER_ON_HIGH_RSS_AFTER_INCREMENTAL !== undefined) {
+    const value = process.env.SMART_CODING_RECYCLE_SERVER_ON_HIGH_RSS_AFTER_INCREMENTAL;
+    if (value === 'true' || value === 'false') {
+      config.recycleServerOnHighRssAfterIncremental = value === 'true';
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_RECYCLE_SERVER_ON_HIGH_RSS_AFTER_INCREMENTAL: ${value}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_RECYCLE_SERVER_RSS_THRESHOLD_MB !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_RECYCLE_SERVER_RSS_THRESHOLD_MB, 10);
+    if (!isNaN(value) && value > 0) {
+      config.recycleServerOnHighRssThresholdMb = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_RECYCLE_SERVER_RSS_THRESHOLD_MB: ${process.env.SMART_CODING_RECYCLE_SERVER_RSS_THRESHOLD_MB}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_RECYCLE_SERVER_COOLDOWN_MS !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_RECYCLE_SERVER_COOLDOWN_MS, 10);
+    if (!isNaN(value) && value >= 0) {
+      config.recycleServerOnHighRssCooldownMs = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_RECYCLE_SERVER_COOLDOWN_MS: ${process.env.SMART_CODING_RECYCLE_SERVER_COOLDOWN_MS}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_RECYCLE_SERVER_DELAY_MS !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_RECYCLE_SERVER_DELAY_MS, 10);
+    if (!isNaN(value) && value >= 0) {
+      config.recycleServerOnHighRssDelayMs = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_RECYCLE_SERVER_DELAY_MS: ${process.env.SMART_CODING_RECYCLE_SERVER_DELAY_MS}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_CONTENT_CACHE_ENTRIES !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_CONTENT_CACHE_ENTRIES, 10);
     if (!isNaN(value) && value >= 0 && value <= 10000) {
       config.contentCacheEntries = value;
     } else {
@@ -753,6 +1094,17 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
+  if (process.env.SMART_CODING_EMBEDDING_FAIL_FAST_BREAKER !== undefined) {
+    const value = process.env.SMART_CODING_EMBEDDING_FAIL_FAST_BREAKER;
+    if (value === 'true' || value === 'false') {
+      config.failFastEmbeddingErrors = value === 'true';
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_EMBEDDING_FAIL_FAST_BREAKER: ${value}, using default`
+      );
+    }
+  }
+
   if (process.env.SMART_CODING_EMBEDDING_BATCH_SIZE !== undefined) {
     const value = parseInt(process.env.SMART_CODING_EMBEDDING_BATCH_SIZE, 10);
     if (!isNaN(value) && value > 0 && value <= 256) {
@@ -775,6 +1127,42 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
+  if (process.env.SMART_CODING_EMBEDDING_PROCESS_GC_RSS_THRESHOLD_MB !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_EMBEDDING_PROCESS_GC_RSS_THRESHOLD_MB, 10);
+    if (!isNaN(value) && value > 0) {
+      config.embeddingProcessGcRssThresholdMb = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_EMBEDDING_PROCESS_GC_RSS_THRESHOLD_MB: ${process.env.SMART_CODING_EMBEDDING_PROCESS_GC_RSS_THRESHOLD_MB}, using default`
+      );
+    }
+  }
+
+  if (process.env.SMART_CODING_EMBEDDING_PROCESS_GC_MIN_INTERVAL_MS !== undefined) {
+    const value = parseInt(process.env.SMART_CODING_EMBEDDING_PROCESS_GC_MIN_INTERVAL_MS, 10);
+    if (!isNaN(value) && value >= 0) {
+      config.embeddingProcessGcMinIntervalMs = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_EMBEDDING_PROCESS_GC_MIN_INTERVAL_MS: ${process.env.SMART_CODING_EMBEDDING_PROCESS_GC_MIN_INTERVAL_MS}, using default`
+      );
+    }
+  }
+
+  const embeddingProcessGcMaxRequestsEnv =
+    process.env.SMART_CODING_EMBEDDING_PROCESS_GC_MAX_REQUESTS ??
+    process.env.SMART_CODING_EMBEDDING_PROCESS_GC_MAX_REQUESTS_WITHOUT_COLLECTION;
+  if (embeddingProcessGcMaxRequestsEnv !== undefined) {
+    const value = parseInt(embeddingProcessGcMaxRequestsEnv, 10);
+    if (!isNaN(value) && value > 0) {
+      config.embeddingProcessGcMaxRequestsWithoutCollection = value;
+    } else {
+      console.warn(
+        `[Config] Invalid SMART_CODING_EMBEDDING_PROCESS_GC_MAX_REQUESTS: ${embeddingProcessGcMaxRequestsEnv}, using default`
+      );
+    }
+  }
+
   if (process.env.SMART_CODING_ANN_ENABLED !== undefined) {
     const value = process.env.SMART_CODING_ANN_ENABLED;
     if (value === 'true' || value === 'false') {
@@ -922,8 +1310,69 @@ export async function loadConfig(workspaceDir = null) {
     }
   }
 
-  return config;
-}
+  if (config.memoryLogIntervalMs !== null && config.memoryLogIntervalMs !== undefined) {
+    const value = parseInt(config.memoryLogIntervalMs, 10);
+    if (!isNaN(value) && value >= 0 && value <= 300000) {
+      config.memoryLogIntervalMs = value;
+    } else {
+      console.warn(
+        `[Config] Invalid memoryLogIntervalMs: ${config.memoryLogIntervalMs}, using default`
+      );
+      config.memoryLogIntervalMs = DEFAULT_CONFIG.memoryLogIntervalMs;
+    }
+  }
+
+  if (
+    config.embeddingProcessGcRssThresholdMb !== null &&
+    config.embeddingProcessGcRssThresholdMb !== undefined
+  ) {
+    const value = parseInt(config.embeddingProcessGcRssThresholdMb, 10);
+    if (!isNaN(value) && value > 0) {
+      config.embeddingProcessGcRssThresholdMb = value;
+    } else {
+      console.warn(
+        `[Config] Invalid embeddingProcessGcRssThresholdMb: ${config.embeddingProcessGcRssThresholdMb}, using default`
+      );
+      config.embeddingProcessGcRssThresholdMb =
+        DEFAULT_CONFIG.embeddingProcessGcRssThresholdMb;
+    }
+  }
+
+  if (
+    config.embeddingProcessGcMinIntervalMs !== null &&
+    config.embeddingProcessGcMinIntervalMs !== undefined
+  ) {
+    const value = parseInt(config.embeddingProcessGcMinIntervalMs, 10);
+    if (!isNaN(value) && value >= 0) {
+      config.embeddingProcessGcMinIntervalMs = value;
+    } else {
+      console.warn(
+        `[Config] Invalid embeddingProcessGcMinIntervalMs: ${config.embeddingProcessGcMinIntervalMs}, using default`
+      );
+      config.embeddingProcessGcMinIntervalMs =
+        DEFAULT_CONFIG.embeddingProcessGcMinIntervalMs;
+    }
+  }
+
+  if (
+    config.embeddingProcessGcMaxRequestsWithoutCollection !== null &&
+    config.embeddingProcessGcMaxRequestsWithoutCollection !== undefined
+  ) {
+    const value = parseInt(config.embeddingProcessGcMaxRequestsWithoutCollection, 10);
+    if (!isNaN(value) && value > 0) {
+      config.embeddingProcessGcMaxRequestsWithoutCollection = value;
+    } else {
+      console.warn(
+        `[Config] Invalid embeddingProcessGcMaxRequestsWithoutCollection: ${config.embeddingProcessGcMaxRequestsWithoutCollection}, using default`
+      );
+      config.embeddingProcessGcMaxRequestsWithoutCollection =
+        DEFAULT_CONFIG.embeddingProcessGcMaxRequestsWithoutCollection;
+    }
+  }
+
+  syncAllNamespaces(config);
+  return config;
+}
 
 /**
  * Get platform-specific global cache directory