**feat(docs): add comprehensive cache configuration guide and enhance adaptive tuning**

- Added `cache-configuration.md` under `docs/guides`:
  - Detailed multi-level cache system (hot, warm, cold) overview.
  - Explained new adaptive tuning capabilities:
    - Memory-based adjustments across Node.js, Browser, and Worker environments.
    - Dynamic sizing for read-heavy/write-heavy workloads.
    - Environment-specific configurations for optimal caching.
  - Included best practices for large datasets, memory-constrained and read-only environments.
  - Added monitoring and advanced manual tuning instructions.
- Modified `cacheManager.ts`:
  - Introduced `environmentConfig` for tailored per-environment cache settings.
  - Enhanced auto-tuning with support for dynamic memory detection and cache hit/miss ratio.
  - Added fine-grained tuning for eviction thresholds, TTLs, and batch sizes based on workload characteristics.
  - Improved adaptive tuning with async memory detection and detailed cache statistics tracking.

**Purpose**: Provide developers with detailed guidance and dynamic tools for optimizing Brainy's cache system, ensuring better performance across diverse environments and workloads.

docs/guides/cache-configuration.md

@@ -0,0 +1,234 @@
+# Brainy Cache Configuration Guide
+
+This guide explains how to configure and optimize Brainy's cache system for different environments and use cases.
+
+## Cache System Overview
+
+Brainy uses a multi-level cache system to optimize performance:
+
+1. **Hot Cache**: In-memory cache for frequently accessed items
+2. **Warm Cache**: Secondary cache with longer retention but slower access
+3. **Cold Storage**: Persistent storage for all data
+
+## New Features
+
+### Dynamic Memory Detection
+
+Brainy now includes a sophisticated memory detection mechanism that works across all JavaScript environments:
+
+- **Node.js**: Uses dynamic import of the `os` module to get actual system memory
+- **Browser**: Uses `performance.memory` or `navigator.deviceMemory` APIs
+- **Worker**: Uses available memory APIs or conservative defaults
+
+```javascript
+// The cache will automatically detect available memory
+const brainy = new BrainyData();
+```
+
+### Environment-Specific Configuration
+
+You can now specify different cache configurations for each environment:
+
+```javascript
+const brainy = new BrainyData({
+  cacheOptions: {
+    environmentConfig: {
+      // Node.js specific settings
+      node: {
+        hotCacheMaxSize: 10000,
+        hotCacheEvictionThreshold: 0.85,
+        warmCacheTTL: 48 * 60 * 60 * 1000, // 48 hours
+        batchSize: 50
+      },
+      // Browser specific settings
+      browser: {
+        hotCacheMaxSize: 5000,
+        hotCacheEvictionThreshold: 0.8,
+        warmCacheTTL: 24 * 60 * 60 * 1000, // 24 hours
+        batchSize: 20
+      },
+      // Worker specific settings
+      worker: {
+        hotCacheMaxSize: 3000,
+        hotCacheEvictionThreshold: 0.75,
+        warmCacheTTL: 12 * 60 * 60 * 1000, // 12 hours
+        batchSize: 15
+      }
+    }
+  }
+});
+```
+
+### Adaptive Cache Tuning
+
+The cache system now includes improved adaptive tuning that automatically adjusts based on:
+
+1. Available memory in the current environment
+2. Cache hit/miss ratios
+3. Access patterns (read-heavy vs. write-heavy)
+4. Dataset size and characteristics
+5. Storage type (S3, filesystem, memory)
+
+The adaptive tuning system will:
+
+- Increase cache sizes for read-only workloads
+- Optimize batch sizes based on network conditions
+- Adjust eviction thresholds based on memory pressure
+- Tune warm cache TTL based on update frequency
+
+```javascript
+// Enable auto-tuning (on by default)
+const brainy = new BrainyData({
+  cacheOptions: {
+    autoTune: true
+  }
+});
+
+// Disable auto-tuning if needed
+const brainy = new BrainyData({
+  cacheOptions: {
+    autoTune: false
+  }
+});
+```
+
+## Best Practices
+
+### For Large Datasets
+
+When working with large datasets (>100K items):
+
+```javascript
+const brainy = new BrainyData({
+  cacheOptions: {
+    // For Node.js environments with large datasets
+    environmentConfig: {
+      node: {
+        hotCacheMaxSize: 50000,
+        batchSize: 100
+      }
+    }
+  }
+});
+```
+
+### For Memory-Constrained Environments
+
+For environments with limited memory:
+
+```javascript
+const brainy = new BrainyData({
+  cacheOptions: {
+    // Conservative settings for memory-constrained environments
+    hotCacheMaxSize: 1000,
+    hotCacheEvictionThreshold: 0.7, // Evict earlier
+    warmCacheTTL: 6 * 60 * 60 * 1000, // 6 hours
+    batchSize: 5
+  }
+});
+```
+
+### For Read-Only Applications
+
+For read-only applications where data doesn't change:
+
+```javascript
+const brainy = new BrainyData({
+  readOnly: true,
+  cacheOptions: {
+    // More aggressive caching for read-only data
+    hotCacheEvictionThreshold: 0.9,
+    warmCacheTTL: 72 * 60 * 60 * 1000 // 72 hours
+  }
+});
+```
+
+## Advanced Configuration
+
+### Manual Cache Size Calculation
+
+If you want to manually calculate the optimal cache size:
+
+```javascript
+// Get memory information
+async function getMemoryInfo() {
+  if (typeof window === 'undefined') {
+    // Node.js
+    const os = await import('os');
+    return {
+      totalMemory: os.totalmem(),
+      freeMemory: os.freemem()
+    };
+  } else if (navigator.deviceMemory) {
+    // Browser with deviceMemory API
+    const totalMemory = navigator.deviceMemory * 1024 * 1024 * 1024;
+    return {
+      totalMemory,
+      freeMemory: totalMemory * 0.5 // Estimate
+    };
+  }
+  // Default fallback
+  return {
+    totalMemory: 8 * 1024 * 1024 * 1024, // 8GB
+    freeMemory: 4 * 1024 * 1024 * 1024   // 4GB
+  };
+}
+
+// Calculate optimal cache size
+async function calculateOptimalCacheSize() {
+  const memoryInfo = await getMemoryInfo();
+  const BYTES_PER_ENTRY = 1024; // Estimate 1KB per entry
+  const memoryPercentage = 0.1; // Use 10% of free memory
+  
+  return Math.max(
+    Math.floor(memoryInfo.freeMemory * memoryPercentage / BYTES_PER_ENTRY),
+    1000 // Minimum size
+  );
+}
+
+// Use the calculated size
+async function initializeBrainy() {
+  const optimalSize = await calculateOptimalCacheSize();
+  
+  const brainy = new BrainyData({
+    cacheOptions: {
+      hotCacheMaxSize: optimalSize
+    }
+  });
+  
+  return brainy;
+}
+```
+
+## Monitoring Cache Performance
+
+You can monitor cache performance to fine-tune your settings:
+
+```javascript
+// Get cache statistics
+const stats = brainy.getCacheStats();
+
+console.log('Cache Statistics:', {
+  hotCacheSize: stats.hotCacheSize,
+  hotCacheHits: stats.hotCacheHits,
+  hotCacheMisses: stats.hotCacheMisses,
+  warmCacheSize: stats.warmCacheSize,
+  warmCacheHits: stats.warmCacheHits,
+  warmCacheMisses: stats.warmCacheMisses
+});
+
+// Calculate hit ratios
+const hotHitRatio = stats.hotCacheHits / (stats.hotCacheHits + stats.hotCacheMisses || 1);
+const warmHitRatio = stats.warmCacheHits / (stats.warmCacheHits + stats.warmCacheMisses || 1);
+
+console.log('Hit Ratios:', {
+  hotHitRatio: hotHitRatio.toFixed(2),
+  warmHitRatio: warmHitRatio.toFixed(2)
+});
+```
+
+## Conclusion
+
+Brainy's enhanced cache system now provides better performance across all JavaScript environments with minimal configuration. The adaptive tuning system will automatically optimize cache parameters based on your specific workload and environment.
+
+For most applications, the default settings with auto-tuning enabled will provide excellent performance. For specialized use cases, use the environment-specific configuration options to fine-tune the cache behavior.