Storage Intelligence - Quick Reference Card

One-page reference for storage-system's intelligent adapter selection

⚡ Storage Intelligence - Quick Reference

One-page guide to the storage-system's autonomous intelligence.

🎯 The Golden Rule

// ✅ YOUR JOB: Tell the system WHAT to store
await storage.put(key, value);

// ✅ SYSTEM'S JOB: Decide HOW to store it
// - Analyzes size, key pattern, strategy, capabilities
// - Selects optimal adapter(s)
// - Applies redundancy if needed
// - Learns and optimizes over time

Never manually specify adapters - the system is smarter than manual code!

📊 Automatic Adapter Selection

By Data Size

Size	Adapter	Why
< 8KB	IndexedDB	Fast structured storage
8KB - 64KB	IndexedDB	Optimal for medium data
64KB - 512KB	OPFS + IndexedDB index	File-system performance
> 512KB	OPFS + CAS	Deduplication for huge files

By Key Pattern

Pattern	Type	Storage	Redundancy
`auth/*`	Critical	IndexedDB	✅ + localStorage
`session/*`	Critical	IndexedDB	✅ + localStorage
`user/*`	User Pref	IndexedDB	✅ + localStorage (if small)
`cache/*`	Cache	IndexedDB	❌ None
`temp/*`	Temporary	localStorage	❌ None
Other	Data	Intelligent	Size-based

By Strategy

Strategy	Behavior
`speed`	Micro-cache for small data, queued OPFS writes
`balanced`	Optimal balance (default)
`durable`	Redundant storage, immediate writes

✅ DO This

// ✅ Trust the intelligence
await storage.put('user/profile', userData);
await storage.put('universe_123', universe);
await storage.put('cache/api/response', apiData);

// ✅ Use semantic key names (helps classifier)
await storage.put('auth/session/token', token);     // Critical
await storage.put('user/preferences', prefs);        // User pref
await storage.put('temp/upload', data);              // Temporary

// ✅ Configure strategy, not adapters
provideIntelligentStorage({
  strategy: 'balanced',  // Let system decide adapters
  performance: {
    adaptiveStrategy: true  // Enable AI learning
  }
})

❌ DON'T Do This

// ❌ NEVER manually specify adapter
const event: StorageEventData = {
  adapter: 'opfs'  // Defeats intelligence!
};

// ❌ NEVER manually route to adapters
if (size > threshold) {
  await opfsAdapter.write(key, value);
}

// ❌ NEVER bypass the system
await indexedDB.put(key, value);

🧠 How Intelligence Works

Decision Pipeline

Your Code
   ↓
storage.put(key, value)
   ↓
estimateSize(value)  ← Calculates size
   ↓
classifyKey(key)     ← Analyzes pattern
   ↓
Policy Engine        ← Makes decision
   ↓
Adaptive Learning    ← Improves over time
   ↓
Storage Operation    ← Executes intelligently
   ↓
Event Emission       ← Notifies with adapter info

Key Classification

// Automatic classification based on key patterns
'auth/*'      → 'critical'       → Redundant storage
'user/*'      → 'user-preference' → IndexedDB + localStorage
'cache/*'     → 'cache'           → IndexedDB only
'temp/*'      → 'temp'            → localStorage only
'universe_*'  → 'data'            → Size-based decision

Size Analysis

Small:  < 8KB      → IndexedDB
Medium: 8-64KB     → IndexedDB
Large:  64-512KB   → OPFS + IndexedDB index
Huge:   > 512KB    → OPFS + CAS

🎯 Real-World Examples

Example 1: Universe (3KB)

await storage.put('universe_123', universe);
// Intelligence: data + 3KB → IndexedDB

Example 2: Auth Token (200 bytes)

await storage.put('auth/session/token', token);
// Intelligence: critical + 200B → IndexedDB + localStorage

Example 3: Large PDF (2MB)

await storage.put('documents/pdf', pdfData);
// Intelligence: data + 2MB → OPFS + IndexedDB index

Example 4: API Cache (5KB)

await storage.put('cache/api/users', response);
// Intelligence: cache + 5KB → IndexedDB only

📈 Adaptive Learning

The system gets smarter over time:

// First 10 accesses
storage.get('user/settings') // 15ms (IndexedDB)

// System learns: "This is hot data!"
// Auto-promotes to RAM cache

// Next 100 accesses
storage.get('user/settings') // 0.3ms (RAM cache)

// All automatic - no code changes!

🚨 Common Mistakes

Mistake 1: Manual Adapter Override

❌ event.adapter = 'opfs'
✅ Let storage-system populate adapter automatically

Mistake 2: Assuming Adapter

❌ "Small data always goes to localStorage"
✅ System decides based on key pattern + size + strategy

Mistake 3: Manual Routing

❌ if (large) use OPFS else use IndexedDB
✅ storage.put(key, value) // System decides

💡 Key Insights

Adapter is OUTPUT, not INPUT - Read it from events, don't set it
Intelligence happens during operations - Not during event handling
System learns your patterns - Gets faster over time
Semantic keys help classification - Use auth/*, user/*, cache/*
Configure behavior, not implementation - Use strategy, not adapters

🎓 Remember

The storage-system is a Ferrari 🏎️ - you don't tell it how to shift gears!

// Just drive (tell it what to store)
await storage.put(key, value);

// Ferrari handles the rest (decides how to store it)
// - Optimal adapter selection
// - Redundancy if critical
// - Caching strategy
// - Performance optimization
// - Adaptive learning

📚 Learn More

Overview - Architecture and adapter selection details
API Reference - Complete API documentation
Getting Started - 5-minute setup

Created: November 19, 2025 - 12:15 PM
Session ID: 11.25.1.2
Status: ✅ Complete
Print this! Keep it next to your monitor! 📌