feat: implement always-adaptive caching with getCacheStats monitoring

Replaces lazy mode concept with always-adaptive caching strategy:

- Rename getLazyModeStats() → getCacheStats() with enhanced metrics
- Change lazyModeEnabled boolean → cachingStrategy enum ('preloaded' | 'on-demand')
- Update preloading threshold from 30% to 80% for better cache utilization
- Add comprehensive production monitoring and diagnostics
- Add memory detection for containers (Docker/K8s cgroups v1/v2)
- Add adaptive memory sizing from 2GB to 128GB+ systems

Breaking changes: None (backward compatible, deprecated lazy option ignored)

New APIs:
- getCacheStats(): Comprehensive cache performance statistics
- cachingStrategy field: Transparent strategy reporting
- Enhanced fairness metrics and memory pressure monitoring

Documentation:
- Add migration guide for v3.36.0
- Add operations/capacity-planning.md for enterprise deployments
- Update all examples and troubleshooting guides
- Rename monitor-lazy-mode.ts → monitor-cache-performance.ts
This commit is contained in:
David Snelling 2025-10-10 14:09:30 -07:00
parent 6037db3d85
commit 46c6af3f21
17 changed files with 2737 additions and 127 deletions

View file

@ -68,18 +68,6 @@ const brain = new Brainy({
- **Performance**: Near-native file system speed
- **Persistence**: Permanent in browser (with quota limits)
### Memory Storage
```typescript
const brain = new Brainy({
storage: {
type: 'memory'
}
})
```
- **Use case**: Testing, temporary processing
- **Performance**: Fastest possible
- **Persistence**: Volatile (lost on restart)
## Metadata Indexing System
### Field Discovery Index
@ -284,14 +272,15 @@ console.log(stats)
## Best Practices
### Choose the Right Adapter
1. **Development**: Memory or FileSystem
1. **Development**: FileSystem (local persistence)
2. **Production Server**: FileSystem or S3
3. **Browser Apps**: OPFS or Memory
3. **Browser Apps**: OPFS
4. **Distributed**: S3 with caching
### Optimize for Your Use Case
1. **Read-heavy**: Enable aggressive caching
3. **Real-time**: Memory with periodic persistence
2. **Write-heavy**: Batch operations
3. **Real-time**: FileSystem with periodic snapshots
4. **Archival**: S3 with compression
### Monitor and Maintain