@soulcraft/brainy 3.35.0 → 3.36.0

package/dist/utils/unifiedCache.js

@@ -1,8 +1,15 @@
 /**
  * UnifiedCache - Single cache for both HNSW and MetadataIndex
  * Prevents resource competition with cost-aware eviction
+ *
+ * Features (v3.36.0+):
+ * - Adaptive sizing: Automatically scales from 2GB to 128GB+ based on available memory
+ * - Container-aware: Detects Docker/K8s limits (cgroups v1/v2)
+ * - Environment detection: Production vs development allocation strategies
+ * - Memory pressure monitoring: Warns when approaching limits
  */
 import { prodLog } from './logger.js';
+import { getRecommendedCacheConfig, formatBytes, checkMemoryPressure } from './memoryDetection.js';
 export class UnifiedCache {
     constructor(config = {}) {
         this.cache = new Map();
@@ -11,17 +18,51 @@ export class UnifiedCache {
         this.typeAccessCounts = { hnsw: 0, metadata: 0, embedding: 0, other: 0 };
         this.totalAccessCount = 0;
         this.currentSize = 0;
-        this.maxSize = config.maxSize || 2 * 1024 * 1024 * 1024; // 2GB default
+        this.memoryPressureCheckTimer = null;
+        this.lastMemoryWarning = 0;
+        // Adaptive cache sizing (v3.36.0+)
+        const recommendation = getRecommendedCacheConfig({
+            manualSize: config.maxSize,
+            minSize: config.minSize,
+            developmentMode: config.developmentMode
+        });
+        this.memoryInfo = recommendation.memoryInfo;
+        this.allocationStrategy = recommendation.allocation;
+        this.maxSize = recommendation.allocation.cacheSize;
+        // Log allocation decision (v3.36.0+: includes model memory)
+        prodLog.info(`UnifiedCache initialized: ${formatBytes(this.maxSize)} ` +
+            `(${this.allocationStrategy.environment} mode, ` +
+            `${(this.allocationStrategy.ratio * 100).toFixed(0)}% of ${formatBytes(this.allocationStrategy.availableForCache)} ` +
+            `after ${formatBytes(this.allocationStrategy.modelMemory)} ${this.allocationStrategy.modelPrecision.toUpperCase()} model)`);
+        // Log memory detection details
+        prodLog.debug(`Memory detection: source=${this.memoryInfo.source}, ` +
+            `container=${this.memoryInfo.isContainer}, ` +
+            `system=${formatBytes(this.memoryInfo.systemTotal)}, ` +
+            `free=${formatBytes(this.memoryInfo.free)}, ` +
+            `totalAvailable=${formatBytes(this.memoryInfo.available)}, ` +
+            `modelReserved=${formatBytes(this.allocationStrategy.modelMemory)}, ` +
+            `availableForCache=${formatBytes(this.allocationStrategy.availableForCache)}`);
+        // Log warnings if any
+        for (const warning of recommendation.warnings) {
+            prodLog.warn(`UnifiedCache: ${warning}`);
+        }
+        // Finalize configuration
         this.config = {
             enableRequestCoalescing: true,
             enableFairnessCheck: true,
             fairnessCheckInterval: 60000, // Check fairness every minute
             persistPatterns: true,
+            enableMemoryMonitoring: true,
+            memoryCheckInterval: 30000, // Check memory every 30s
             ...config
         };
+        // Start monitoring
         if (this.config.enableFairnessCheck) {
             this.startFairnessMonitor();
         }
+        if (this.config.enableMemoryMonitoring) {
+            this.startMemoryPressureMonitor();
+        }
     }
     /**
      * Get item from cache with request coalescing
@@ -62,6 +103,25 @@ export class UnifiedCache {
             }
         }
     }
+    /**
+     * Synchronous cache lookup (v3.36.0+)
+     * Returns cached data immediately or undefined if not cached
+     * Use for sync fast path optimization - zero async overhead
+     */
+    getSync(key) {
+        // Check if in cache
+        const item = this.cache.get(key);
+        if (item) {
+            // Update access tracking synchronously
+            this.access.set(key, (this.access.get(key) || 0) + 1);
+            this.totalAccessCount++;
+            item.lastAccess = Date.now();
+            item.accessCount++;
+            this.typeAccessCounts[item.type]++;
+            return item.data;
+        }
+        return undefined;
+    }
     /**
      * Set item in cache with cost-aware eviction
      */
@@ -234,7 +294,45 @@ export class UnifiedCache {
         }
     }
     /**
-     * Get cache statistics
+     * Start memory pressure monitoring
+     * Periodically checks if we're approaching memory limits
+     */
+    startMemoryPressureMonitor() {
+        const checkInterval = this.config.memoryCheckInterval || 30000;
+        this.memoryPressureCheckTimer = setInterval(() => {
+            this.checkMemoryPressure();
+        }, checkInterval);
+        // Unref so it doesn't keep process alive
+        if (this.memoryPressureCheckTimer.unref) {
+            this.memoryPressureCheckTimer.unref();
+        }
+    }
+    /**
+     * Check current memory pressure and warn if needed
+     */
+    checkMemoryPressure() {
+        const pressure = checkMemoryPressure(this.currentSize, this.memoryInfo);
+        // Only log warnings every 5 minutes to avoid spam
+        const now = Date.now();
+        const fiveMinutes = 5 * 60 * 1000;
+        if (pressure.warnings.length > 0 && now - this.lastMemoryWarning > fiveMinutes) {
+            for (const warning of pressure.warnings) {
+                prodLog.warn(`UnifiedCache: ${warning}`);
+            }
+            this.lastMemoryWarning = now;
+        }
+        // If critical, force aggressive eviction
+        if (pressure.pressure === 'critical') {
+            const targetSize = Math.floor(this.maxSize * 0.7); // Evict to 70%
+            const bytesToFree = this.currentSize - targetSize;
+            if (bytesToFree > 0) {
+                prodLog.warn(`UnifiedCache: Critical memory pressure - forcing eviction of ${formatBytes(bytesToFree)}`);
+                this.evictForSize(bytesToFree);
+            }
+        }
+    }
+    /**
+     * Get cache statistics with memory information
      */
     getStats() {
         const typeSizes = { hnsw: 0, metadata: 0, embedding: 0, other: 0 };
@@ -243,7 +341,10 @@ export class UnifiedCache {
             typeSizes[item.type] += item.size;
             typeCounts[item.type]++;
         }
+        const hitRate = this.cache.size > 0 ?
+            Array.from(this.cache.values()).reduce((sum, item) => sum + item.accessCount, 0) / this.totalAccessCount : 0;
         return {
+            // Cache statistics
             totalSize: this.currentSize,
             maxSize: this.maxSize,
             utilization: this.currentSize / this.maxSize,
@@ -252,8 +353,26 @@ export class UnifiedCache {
             typeCounts,
             typeAccessCounts: this.typeAccessCounts,
             totalAccessCount: this.totalAccessCount,
-            hitRate: this.cache.size > 0 ?
-                Array.from(this.cache.values()).reduce((sum, item) => sum + item.accessCount, 0) / this.totalAccessCount : 0
+            hitRate,
+            // Memory management (v3.36.0+)
+            memory: {
+                available: this.memoryInfo.available,
+                source: this.memoryInfo.source,
+                isContainer: this.memoryInfo.isContainer,
+                systemTotal: this.memoryInfo.systemTotal,
+                allocationRatio: this.allocationStrategy.ratio,
+                environment: this.allocationStrategy.environment
+            }
+        };
+    }
+    /**
+     * Get detailed memory information
+     */
+    getMemoryInfo() {
+        return {
+            memoryInfo: { ...this.memoryInfo },
+            allocationStrategy: { ...this.allocationStrategy },
+            currentPressure: checkMemoryPressure(this.currentSize, this.memoryInfo)
         };
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.35.0",
+  "version": "3.36.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",