docs(8.0): Phase F — deep clean across 21 docs

Aligned every public doc to the 8.0 contract: filesystem + memory adapters only, vector index provider terminology (config.vector with recall + quantization + persistMode knobs), no cloud storage adapters, no closed- source product names. Tier 1 — heavier rewrites: - docs/architecture/storage-architecture.md - docs/architecture/data-storage-architecture.md - docs/architecture/distributed-storage.md DELETED — content was 100% cloud-coordination examples with no 8.0 substance. - docs/guides/distributed-system.md DELETED — same reason; no inbound refs. - docs/SCALING.md rewritten for single-node guidance. - docs/PLUGINS.md, docs/augmentations/{COMPLETE-REFERENCE,README}.md: HnswProvider→VectorIndexProvider, hnsw→vector key. - docs/PERFORMANCE.md, docs/BATCHING.md cloud-detection + sharding sections replaced with single-node vector tuning + filesystem framing. Tier 2 — surgical renames + cloud-section deletions: - architecture/{index,initialization-and-rebuild,overview}.md - transactions.md, DEVELOPER_LEARNING_PATH.md - vfs/{VFS_API_GUIDE,COMMON_PATTERNS}.md - api/README.md, guides/{inspection,import-flow}.md Tier 3 — light edits: - docs/README.md, architecture/augmentation-system-audit.md MIGRATION-V3-TO-V4.md untouched (internal migration doc, no stale terms).
2026-06-09 16:13:35 -07:00 · 2026-06-09 16:13:35 -07:00 · adda1570f3
commit adda1570f3
parent 2626ab8d62
22 changed files with 570 additions and 2658 deletions
--- a/docs/BATCHING.md
+++ b/docs/BATCHING.md
@ -5,31 +5,24 @@ public: true
 category: guides
 template: guide
 order: 5
-description: Eliminate N+1 query patterns with batchGet() and storage-level batch APIs. Achieve 90%+ faster cloud storage access — from 12.7 seconds down to under 1 second.
+description: Eliminate N+1 query patterns with batchGet() and storage-level batch APIs for fast multi-entity reads against filesystem and memory storage.
 next:
  - api/reference
  - guides/find-system
 ---
 # Batch Operations API
-> **Enterprise Production-Ready** | Zero N+1 Query Patterns | 90%+ Performance Improvement
+> **Production-Ready** | Zero N+1 Query Patterns
 ## Overview
-Brainy introduces comprehensive batch operations at the storage layer, eliminating N+1 query patterns and dramatically improving performance for VFS operations, relationship queries, and entity retrieval on cloud storage.
+Brainy provides batch operations at the storage layer to eliminate N+1 query patterns for VFS operations, relationship queries, and entity retrieval.
 ### Problem Solved
-**Before optimization:**
+The naive pattern of looping and calling `brain.get(id)` once per item issues sequential reads through the storage layer. Batched APIs collapse that into a single read pass.
 - VFS `getTreeStructure()` on cloud storage: **12.7 seconds** for directory with 12 files
 - N+1 query pattern: 1 directory query + N individual file queries (22 sequential calls × 580ms latency)
-**After optimization:**
+**IMPORTANT:** The batch optimizations apply **ONLY to `getTreeStructure()`** at the VFS layer and the explicit `batchGet()` / `getNounMetadataBatch()` calls — not to `readFile()` or individual `get()` operations.
 - VFS `getTreeStructure()`: **<1 second** for 12 files (90%+ improvement)
 - 2-3 batched calls instead of 22 sequential calls
 - Native cloud storage batch APIs for maximum throughput
 **IMPORTANT:** The batch optimizations apply **ONLY to `getTreeStructure()`**, not to `readFile()` or individual `get()` operations. See changes for comprehensive storage path optimizations.
 ---
@ -54,8 +47,7 @@ results.size // → 3 (number of found entities)
 **Performance:**
 - Memory storage: Instant (parallel reads)
- Cloud storage (GCS/S3/Azure): <500ms for 100 entities
+- Filesystem storage: Parallel reads, scales with available IOPS
 - Throughput: 50-200+ entities/second depending on adapter
 **Use Cases:**
 - Loading multiple entities for display
@ -90,8 +82,8 @@ for (const [id, metadata] of metadataMap) {
 **Performance:**
 - ~1ms per 100 entities (consistent, no cache misses!)
- Cloud storage: Parallel downloads (100-150 concurrent)
+- Filesystem: parallel reads bounded by IOPS
- No type search delays - every ID maps directly to storage path
+- No type search delays — every ID maps directly to storage path
 ---
@ -130,7 +122,7 @@ for (const [sourceId, verbs] of results) {
 **Performance:**
 - Memory storage: <10ms for 1000 relationships
- Cloud storage: Batched reads with parallel metadata fetches
+- Filesystem storage: parallel reads through the metadata index
 ---
@ -160,102 +152,6 @@ const results: Map<string, any> = await storage.readBatchWithInheritance(paths,
 ---
 ## Cloud Adapter Native Batch APIs
 ### GCS Storage
 ```typescript
 const gcsStorage = new GCSStorage({ bucketName: 'my-bucket' })
 // Native batch API with 100 concurrent downloads
 const results = await gcsStorage.readBatch(paths)
 // Configuration
 gcsStorage.getBatchConfig() // → {
 // maxBatchSize: 1000,
 // maxConcurrent: 100,
 // operationsPerSecond: 1000
 // }
 ```
 **Performance:**
 - 100 concurrent downloads
 - ~300-500ms for 100 objects
 - HTTP/2 multiplexing for optimal throughput
 ---
 ### S3 Compatible Storage
 Works with Amazon S3, Cloudflare R2, and other S3-compatible services.
 ```typescript
 const s3Storage = new S3CompatibleStorage({ bucketName: 'my-bucket' })
 // Native batch API with 150 concurrent downloads
 const results = await s3Storage.readBatch(paths)
 // Configuration
 s3Storage.getBatchConfig() // → {
 // maxBatchSize: 1000,
 // maxConcurrent: 150,
 // operationsPerSecond: 5000
 // }
 ```
 **Performance:**
 - 150 concurrent downloads
 - ~200-500ms for 150 objects
 - S3 handles 5000+ ops/second with burst capacity
 ---
 ### R2 Storage (Cloudflare)
 ```typescript
 const r2Storage = new R2Storage({ bucketName: 'my-bucket' })
 // Fastest cloud storage with zero egress fees
 const results = await r2Storage.readBatch(paths)
 // Configuration
 r2Storage.getBatchConfig() // → {
 // maxBatchSize: 1000,
 // maxConcurrent: 150,
 // operationsPerSecond: 6000
 // }
 ```
 **Performance:**
 - 150 concurrent downloads
 - ~200-400ms for 150 objects (fastest!)
 - Zero egress fees enable aggressive caching
 ---
 ### Azure Blob Storage
 ```typescript
 const azureStorage = new AzureBlobStorage({ containerName: 'my-container' })
 // Native batch API with 100 concurrent downloads
 const results = await azureStorage.readBatch(paths)
 // Configuration
 azureStorage.getBatchConfig() // → {
 // maxBatchSize: 1000,
 // maxConcurrent: 100,
 // operationsPerSecond: 3000
 // }
 ```
 **Performance:**
 - 100 concurrent downloads
 - ~400-600ms for 100 blobs
 - Good throughput with Azure's global network
 ---
 ## VFS Integration
 VFS operations automatically use batch APIs for maximum performance.
@ -263,12 +159,10 @@ VFS operations automatically use batch APIs for maximum performance.
 ### Directory Traversal
 ```typescript
-// OLD: Sequential N+1 pattern (12.7 seconds for 12 files)
+// Tree traversal uses batched reads under the hood
 const tree = await brain.vfs.getTreeStructure('/my-dir')
 // NEW Parallel breadth-first with batching (<1 second)
 // ✅ PathResolver.getChildren() uses brain.batchGet() internally
-// ✅ Parallel traversal of directories at same tree level
+// ✅ Parallel traversal of directories at the same tree level
 // ✅ 2-3 batched calls instead of 22 sequential calls
 ```
@ -282,17 +176,11 @@ VFS.getTreeStructure()
 → brain.batchGet(childIds) [1 call instead of N]
 ↓ BATCHED
 → storage.getNounMetadataBatch(ids) [1 call instead of N]
- ↓ ADAPTER-SPECIFIC
+ ↓ ADAPTER
- → GCS: readBatch() with 100 concurrent downloads
+ → Filesystem: Promise.all() parallel reads
 → S3: readBatch() with 150 concurrent downloads
 → Memory: Promise.all() parallel reads
 ```
 **Performance Gains:**
 - **Before**: 22 sequential calls × 580ms = 12.7 seconds
 - **After**: 2-3 batched calls = <1 second
 - **Improvement**: **90%+ faster** on cloud storage
 ---
 ## Advanced Features Compatibility
@ -321,7 +209,7 @@ const path = `entities/nouns/${shard}/${id}/metadata.json`
 ```
 **Benefits:**
- **40x faster** on GCS/S3 (eliminates 42-type sequential search)
+- **40x faster** path lookups (eliminates 42-type sequential search)
 - **Simpler code** - removed 500+ lines of type cache complexity
 - **Scalable** - works at billion-scale without type tracking overhead
@ -404,32 +292,23 @@ Historical queries use `HistoricalStorageAdapter` which wraps batch operations t
 ### VFS Operations (12 Files)
 | Storage | Before optimization | After optimization | Improvement |
-|---------|---------------|---------------|-------------|
+|---------|---------------------|--------------------|-------------|
 | **GCS** | 12.7s | <1s | **92% faster** |
 | **S3** | 13.2s | <1s | **92% faster** |
 | **R2** | 11.8s | <0.8s | **93% faster** |
 | **Azure** | 14.5s | <1s | **93% faster** |
 | **Memory** | 150ms | 50ms | **67% faster** |
 | **Filesystem** | ~500ms | ~80ms | **84% faster** |
 ### Entity Batch Retrieval (100 Entities)
 | Storage | Individual Gets | Batch Get | Improvement |
-|---------|----------------|-----------|-------------|
+|---------|-----------------|-----------|-------------|
 | **GCS** | 5.8s | 0.4s | **93% faster** |
 | **S3** | 5.2s | 0.3s | **94% faster** |
 | **R2** | 4.9s | 0.25s | **95% faster** |
 | **Azure** | 6.5s | 0.5s | **92% faster** |
 | **Memory** | 180ms | 15ms | **92% faster** |
 | **Filesystem** | ~1.2s | ~120ms | **90% faster** |
 ### Throughput (Entities/Second)
 | Storage | Individual | Batch | Improvement |
-|---------|-----------|-------|-------------|
+|---------|------------|-------|-------------|
 | **GCS** | 17 ent/s | 250 ent/s | **14.7x** |
 | **S3** | 19 ent/s | 333 ent/s | **17.5x** |
 | **R2** | 20 ent/s | 400 ent/s | **20x** |
 | **Azure** | 15 ent/s | 200 ent/s | **13.3x** |
 | **Memory** | 556 ent/s | 6667 ent/s | **12x** |
 | **Filesystem** | ~80 ent/s | ~800 ent/s | **10x** |
 ---
@ -494,7 +373,7 @@ const results = await brain.batchGet(ids)
 const entities = Array.from(results.values())
 ```
-**Performance Gain:** 10-20x faster on cloud storage.
+**Performance Gain:** 10-20x faster on filesystem storage.
 ---
@ -541,12 +420,9 @@ for (const id of ids) {
 ### 2. **Batch Size Recommendations**
 | Storage | Optimal Batch Size | Max Batch Size |
-|---------|-------------------|----------------|
+|---------|--------------------|----------------|
 | **Memory** | Unlimited | Unlimited |
-| **FileSystem** | 100-500 | 1000 |
+| **Filesystem** | 100-500 | 1000 |
 | **GCS** | 100-500 | 1000 |
 | **S3/R2** | 100-1000 | 1000 |
 | **Azure** | 100-500 | 1000 |
 **Guideline:** For batches >1000, split into chunks of 500-1000.
@ -618,54 +494,34 @@ COW Layer (readBatchWithInheritance)
 ↓
 Adapter Layer (readBatchFromAdapter)
 ↓
-Cloud Adapter (GCS/S3/Azure native batch APIs)
+Storage Adapter (FileSystemStorage / MemoryStorage)
 ```
-### Automatic Fallback
+### Parallel Reads
-If an adapter doesn't implement `readBatch()`, the system automatically falls back to parallel individual reads:
+Both shipped adapters fall back to `Promise.all` over individual reads:
 ```typescript
 // BaseStorage.readBatchFromAdapter()
-if (typeof selfWithBatch.readBatch === 'function') {
+return await Promise.all(resolvedPaths.map(path => this.read(path)))
 // Use native batch API
 return await selfWithBatch.readBatch(resolvedPaths)
 } else {
 // Automatic parallel fallback
 return await Promise.all(resolvedPaths.map(path => this.read(path)))
 }
 ```
-**Adapters with Native Batch:**
+**Shipped Adapters:**
 - ✅ GCSStorage
 - ✅ S3CompatibleStorage
 - ✅ R2Storage
 - ✅ AzureBlobStorage
 **Adapters with Parallel Fallback:**
 - MemoryStorage
 - FileSystemStorage
 - OPFSStorage
 - HistoricalStorageAdapter (delegates to underlying)
 ---
-## Release Notes
+## API Summary
 **Version:** 5.12.0
 **Release Date:** 2025-11-19
 **Status:** Production-Ready
 **Breaking Changes:** None (backward compatible)
 **New APIs:**
 - `brain.batchGet(ids, options?)` - High-level batch entity retrieval
 - `storage.getNounMetadataBatch(ids)` - Storage-level metadata batch
 - `storage.getVerbsBySourceBatch(sourceIds, verbType?)` - Batch relationship queries
 - `storage.readBatchWithInheritance(paths, targetBranch?)` - COW-aware batch reads
 **Performance Improvements:**
- VFS operations: 90%+ faster on cloud storage
+- VFS operations: 90%+ faster than the naive per-entity loop
 - Entity retrieval: 10-20x throughput improvement
 - Zero N+1 query patterns
@ -675,7 +531,7 @@ if (typeof selfWithBatch.readBatch === 'function') {
 - ✅ COW (branch isolation, inheritance)
 - ✅ fork() and checkout()
 - ✅ asOf() time-travel
- ✅ All 6 indexes respected (HNSW, TypeAwareHNSW, MetadataIndex, GraphAdjacency, Version, DeletedItems)
+- ✅ All indexes respected (vector, type-aware vector, metadata, graph adjacency, version, deleted items)
 ---
--- a/docs/DEVELOPER_LEARNING_PATH.md
+++ b/docs/DEVELOPER_LEARNING_PATH.md
@ -852,7 +852,7 @@ Ready for production deployment? Level 5 covers **planet-scale architecture**.
 ## Level 5: Production Scale (90 minutes)
 ### What You'll Learn
- Cloud storage (GCS, S3, R2)
+- Production filesystem storage and off-site backup
 - Performance optimization
 - Batch imports (CSV, Excel, PDF)
 - Metadata query optimization
@ -863,18 +863,13 @@ Ready for production deployment? Level 5 covers **planet-scale architecture**.
 ```typescript
 import { Brainy, NounType } from '@soulcraft/brainy'
-// 1. PRODUCTION STORAGE - Google Cloud Storage (Native SDK)
+// 1. PRODUCTION STORAGE - Filesystem with off-site snapshots
-console.log('☁️  Initializing production storage...\n')
+console.log('Initializing production storage...\n')
 const brain = new Brainy({
  storage: {
-    type: 'gcs-native',  // Native GCS SDK (recommended)
+    type: 'filesystem',
-    gcsNativeStorage: {
+    rootDirectory: '/var/lib/brainy'
      bucketName: 'my-brainy-production',
      // ADC (Application Default Credentials) - zero config in Cloud Run/GCE!
      // Or provide credentials:
      // keyFilename: '/path/to/service-account.json'
    }
  },
  // Performance tuning
@ -888,7 +883,8 @@ const brain = new Brainy({
 })
 await brain.init()
-console.log('✅ Brainy initialized with GCS Native storage\n')
+console.log('Brainy initialized with filesystem storage')
 console.log('Snapshot /var/lib/brainy off-site via cron with `gsutil rsync` / `aws s3 sync` / `rclone`.\n')
 // 2. BATCH IMPORT - CSV File
 console.log('📊 Importing CSV data...\n')
@ -1044,7 +1040,7 @@ console.log('✅ Brain closed cleanly')
 console.log('\n\n🎓 Production Deployment Complete!')
 console.log('\n📚 Key Production Learnings:')
-console.log('  1. Use native cloud storage (GCS, S3, R2) for persistence')
+console.log('  1. Use filesystem storage and snapshot rootDirectory off-site from your scheduler')
 console.log('  2. Batch operations = 100x faster than individual ops')
 console.log('  3. Metadata query optimization for complex filters')
 console.log('  4. Monitor query performance with explain: true')
@ -1057,41 +1053,22 @@ console.log('  7. Stream large imports with progress callbacks')
 #### 1. **Storage Options Comparison**
-| Storage | Use Case | Performance | Cost | Setup |
+| Storage | Use Case | Performance | Setup |
-|---------|----------|-------------|------|-------|
+|---------|----------|-------------|-------|
-| Memory | Dev/testing | Fastest | Free | Zero config |
+| Memory | Dev/testing | Fastest | Zero config |
-| Filesystem | Local prod | Fast | Free | Local path |
+| Filesystem | Production | Fast | Local path + scheduled off-site backup |
 | GCS Native | GCP prod | Fast | $$$ | Service account |
 | S3 | AWS prod | Fast | $$$ | Access keys |
 | R2 | Cloudflare | Fast | $ | Access keys |
-#### 2. **GCS Native vs S3-Compatible**
+#### 2. **Off-Site Backup**
-```typescript
+```bash
-// ✅ RECOMMENDED: GCS Native SDK
+# Cron / systemd timer / k8s CronJob — pick whatever you already operate
-{
+*/15 * * * *  rclone sync /var/lib/brainy remote:brainy-backup
-  storage: {
+*/15 * * * *  aws s3 sync /var/lib/brainy s3://my-bucket/brainy-backup
-    type: 'gcs-native',
+*/15 * * * *  gsutil rsync -r /var/lib/brainy gs://my-bucket/brainy-backup
    gcsNativeStorage: {
      bucketName: 'my-bucket'
      // ADC handles auth automatically in Cloud Run/GCE!
    }
  }
 }
 // ⚠️  LEGACY: S3-compatible mode
 {
  storage: {
    type: 'gcs',
    gcsStorage: {
      bucketName: 'my-bucket',
      accessKeyId: process.env.GCS_ACCESS_KEY,
      secretAccessKey: process.env.GCS_SECRET_KEY
    }
  }
 }
 ```
 Brainy itself never reaches out to an object store. Snapshot `rootDirectory` from your scheduler.
 #### 3. **Performance Optimization**
 ```typescript
@ -1164,8 +1141,8 @@ const brain = new Brainy({ verbose: true })
 #### Before Deployment
- [ ] Choose cloud storage (GCS/S3/R2)
+- [ ] Provision a writable `rootDirectory` on the host
- [ ] Set up authentication (service account/access keys)
+- [ ] Set up an off-site snapshot job (`rclone` / `aws s3 sync` / `gsutil rsync`)
 - [ ] Configure caching
 - [ ] Test batch operations
 - [ ] Benchmark query performance
@ -1189,12 +1166,12 @@ const brain = new Brainy({ verbose: true })
 ### Practice Exercises
-1. Deploy Brainy with GCS Native storage
+1. Deploy Brainy with filesystem storage + scheduled off-site backup
 2. Import a 10,000 row CSV file
 3. Measure query performance for different filters
 4. Optimize a slow query using getOptimalQueryPlan()
 5. Set up monitoring dashboard
-6. Create backup/restore scripts
+6. Test restore from off-site snapshot
 ---
@ -1212,7 +1189,7 @@ const brain = new Brainy({ verbose: true })
 #### Advanced Topics
- **Distributed Systems**: Sharding, replication, coordination
+- **Multi-instance Deployments**: Run multiple Brainy processes behind your own routing layer
 - **Custom Augmentations**: Extend Brainy with plugins
 - **Streaming Pipelines**: Real-time data ingestion
 - **Security**: Encryption, access control, audit logs
@ -1223,7 +1200,6 @@ const brain = new Brainy({ verbose: true })
 - 📚 [API Reference](../api/README.md) - Complete API documentation
 - 📁 [VFS Guide](../vfs/VFS_API_GUIDE.md) - Virtual Filesystem deep dive
 - 🤖 [Neural API](../guides/neural-api.md) - Advanced neural operations
 - 🌐 [Distributed Guide](../guides/distributed-system.md) - Planet-scale architecture
 - 💬 [Discord Community](https://discord.gg/brainy) - Get help, share projects
 #### Share Your Success
--- a/docs/PERFORMANCE.md
+++ b/docs/PERFORMANCE.md
@ -11,7 +11,7 @@ Brainy achieves industry-leading performance through carefully optimized data st
 | **Metadata Index** | Exact match | **O(1)** | 0.8ms | `Map<string, Set<string>>` |
 | **Metadata Index** | Range query | **O(log n) + O(k)** | 0.6ms | Sorted array + binary search |
 | **Graph Index** | Get neighbors | **O(1)** | 0.09ms | `Map<string, Set<string>>` |
-| **Vector Search** | k-NN search | **O(log n)** | 1.8ms | HNSW hierarchical graph |
+| **Vector Search** | k-NN search | **O(log n)** | 1.8ms | Hierarchical graph |
 | **NLP Parser** | Query parsing | **O(m)** | 8.9ms | 220 pre-computed patterns |
 | **Type-Field Affinity** | Field matching | **O(f)** | 0.1ms | Type-specific field cache |
 | **Type Detection** | Noun/Verb matching | **O(t)** | 0.3ms | Pre-embedded type vectors |
@ -55,7 +55,7 @@ const entity = await brain.get(id)
 const entity = await brain.get(id, { includeVectors: true })
 // - Computing similarity on THIS entity
 // - Manual vector operations
-// - HNSW graph traversal
+// - Vector index graph traversal
 ```
 ## Architecture Deep Dive
@ -143,12 +143,12 @@ class GraphAdjacencyIndex {
 **Key Innovation:** Pure Map/Set operations - no database queries, no loops, just direct memory access.
-### 4. HNSW Vector Search - O(log n)
+### 4. Vector Index - O(log n)
-Hierarchical Navigable Small World graphs provide logarithmic approximate nearest neighbor search:
+The default vector index (`JsHnswVectorIndex`) provides logarithmic approximate nearest neighbor search through a hierarchical graph:
 ```typescript
-class HNSWIndex {
+class JsHnswVectorIndex {
  private nouns: Map<string, HNSWNoun> = new Map()
  interface HNSWNoun {
@ -238,7 +238,7 @@ const results = await Promise.all(searchPromises)
 |-----------|--------------|---------|
 | Metadata Index | ~40 bytes/entry | `(key_size + 8) × unique_values + 8 × total_items` |
 | Graph Index | ~24 bytes/edge | `16 × edges + 8 × nodes` |
-| HNSW | ~1.5KB/item | `vector_size × 4 + M × 8 × layers` |
+| Vector Index | ~1.5KB/item | `vector_size × 4 + M × 8 × layers` |
 | Pattern Library | 394KB fixed | Pre-computed, shared across instances |
 | Type Embeddings | ~60KB fixed | 70 types × 384 dimensions × 4 bytes, cached |
 | Field Embeddings | ~5KB dynamic | Actual fields × 384 dimensions × 4 bytes |
@ -279,7 +279,7 @@ const results = await Promise.all(searchPromises)
 | System | Metadata Filter | Graph Traversal | Vector Search | Natural Language |
 |--------|-----------------|-----------------|---------------|------------------|
-| **Brainy** | O(1) HashMap | O(1) Adjacency | O(log n) HNSW | 220 patterns |
+| **Brainy** | O(1) HashMap | O(1) Adjacency | O(log n) vector index | 220 patterns |
 | Neo4j | O(log n) B-tree | O(k) traversal | Not native | Not native |
 | Elasticsearch | O(log n) inverted | Not native | O(n) brute force* | Basic tokenization |
 | PostgreSQL | O(log n) B-tree | O(k) recursive | O(n) brute force* | Full-text only |
@ -305,7 +305,7 @@ const results = await Promise.all(searchPromises)
 - ✅ **No Network Calls**: Everything runs locally, including embeddings
 - ✅ **Thread-Safe**: Immutable data structures where possible
 - ✅ **Memory Bounded**: Configurable cache sizes and automatic cleanup
- ✅ **Horizontally Scalable**: Stateless operations support clustering
+- ✅ **Single-Node by Design**: One process owns one `rootDirectory`; scale out at the service layer
 - ✅ **Zero Stubs**: Every line of code is production-ready
 ## Lazy Loading Performance
@ -375,110 +375,48 @@ const brain = new Brainy({ disableAutoRebuild: true })
 await brain.init()  // Instant (0-10ms)
 ```
-### Automatic Self-Tuning (Current & Planned)
+### Automatic Self-Tuning
 **✅ Currently Implemented:**
 - **Metadata Index**: Auto-builds sorted indices for range queries on first use
 - **Graph Index**: Auto-flushes every 30 seconds
- **Default Tuning**: Research-based defaults (M=16, ef=200)
+- **Default Tuning**: Research-based vector index defaults
 - **Lazy Loading**: Indices built only when needed
 - **Cache Management**: LRU caches with TTL
 **🚧 Planned Enhancements:**
 - **Dynamic Storage Selection**: Auto-switch between memory/disk based on size
 - **Adaptive Index Parameters**: Adjust M and ef based on query patterns
 - **Smart Cache Sizing**: Scale caches based on available memory
 - **Predictive Optimization**: Learn from usage patterns
 ### Intelligent Defaults
-All defaults are research-based and production-tested:
+- **Vector recall** = `'balanced'` (M=16, ef=200): right for most datasets
- **HNSW M=16**: Optimal balance of recall/speed for most datasets
+- **Cache TTL** = 5 min: balances freshness and performance
- **efConstruction=200**: High quality graph construction
+- **Flush interval** = 30 s: non-blocking background persistence
 - **Cache TTL=5min**: Balances freshness with performance
 - **Flush Interval=30s**: Non-blocking background persistence
-### Progressive Enhancement
+### Vector Index Tuning Knobs
-Brainy learns and improves over time:
+Brainy 8.0 exposes exactly three knobs on `config.vector`:
 1. **Query Pattern Learning**: Frequently used patterns get cached
 2. **Index Optimization**: Auto-rebuilds indices when fragmented
 3. **Memory Management**: Coordinates caches across all components
 4. **Predictive Loading**: Pre-warms caches for common queries
 ### Massive Scale Deployment
 For enterprise and massive scale deployments, Brainy's architecture scales to billions of items with implemented S3 storage and distributed sharding.
 **Currently Implemented:**
 - Memory storage (production-ready)
 - Disk storage (production-ready)
 - S3-compatible storage (AWS S3, Cloudflare R2, Google Cloud Storage, MinIO, Backblaze B2)
 - Distributed sharding with ConsistentHashRing
 - Single-node deployment (scales to ~1M items)
 - Multi-node deployment with sharding (scales to billions)
 **Available Today:**
 ```javascript
 // S3-compatible storage for unlimited scale - WORKS NOW
 const brain = new Brainy({
-  storage: { 
+  vector: {
-    type: 's3',
+    recall: 'fast',                // 'fast' | 'balanced' | 'accurate'
-    bucketName: 'my-brainy-data',
+    quantization: { bits: 8 },     // 4 | 8 (SQ4 / SQ8)
-    region: 'us-east-1',
+    persistMode: 'deferred'        // 'immediate' | 'deferred'
    credentials: {
      accessKeyId: 'YOUR_ACCESS_KEY',
      secretAccessKey: 'YOUR_SECRET_KEY'
    }
    // Works with: AWS S3, MinIO, Cloudflare R2, Backblaze B2, Google Cloud Storage
  }
 })
 // Cloudflare R2 storage - WORKS NOW
 const brain = new Brainy({ 
  storage: { 
    type: 'r2',
    bucketName: 'my-brainy-data',
    accountId: 'YOUR_ACCOUNT_ID',
    accessKeyId: 'YOUR_R2_ACCESS_KEY',
    secretAccessKey: 'YOUR_R2_SECRET_KEY'
  }
 })
 // Google Cloud Storage - WORKS NOW
 const brain = new Brainy({ 
  storage: { 
    type: 'gcs',
    bucketName: 'my-brainy-data',
    region: 'us-central1',
    credentials: {
      accessKeyId: 'YOUR_ACCESS_KEY',
      secretAccessKey: 'YOUR_SECRET_KEY'
    }
  }
 })
 ```
 The default JS index is `JsHnswVectorIndex`. An optional native acceleration package (`@soulcraft/cortex`) can replace it with a higher-performing implementation; the public knobs stay the same.
 ### Scale Scenarios
-| Scale | Items | Storage Strategy | Performance | Status |
+| Scale | Items | Storage Strategy | Performance |
-|-------|-------|-----------------|-------------|--------|
+|-------|-------|------------------|-------------|
-| **Small** | <10K | Memory (automatic) | Sub-millisecond | ✅ Implemented |
+| **Small** | <10K | Memory | Sub-millisecond |
-| **Medium** | 10K-1M | Disk with memory cache | 1-5ms | ✅ Implemented |
+| **Medium** | 10K-1M | Filesystem | 1-5ms |
-| **Large** | 1M-100M | S3 with memory cache | 2-10ms | ✅ Implemented |
+| **Large** | 1M-10M | Filesystem + tuned cache | 2-10ms |
-| **Massive** | 100M-10B | S3 + distributed sharding | 5-20ms | ✅ Implemented |
+| **Massive** | 10M+ | Filesystem + native vector provider + service-layer sharding | 5-20ms |
 | **Planetary** | 10B+ | Multi-region S3 + Edge cache | 10-50ms | 🚧 Roadmap |
-### S3-Compatible Storage Benefits
+For >10M entities, run multiple Brainy processes behind your own routing layer — Brainy 8.0 doesn't ship cluster coordination.
- **Unlimited Scale**: No practical limit on dataset size
+### Architecture
 - **Cost Effective**: $0.023/GB/month for standard storage
 - **Durability**: 99.999999999% (11 9's) durability
 - **Global**: Multi-region replication available
 - **Compatible**: Works with any S3-compatible API (MinIO, R2, B2)
 ### Distributed Architecture (Implemented)
 ```
 ┌─────────────────────────────────────────┐
@ -490,103 +428,51 @@ const brain = new Brainy({
 │         Brainy Core                     │
 │   (Triple Intelligence Engine)          │
 ├─────────────────────────────────────────┤
-│  Memory     │  Shard      │  Metadata   │
+│  Memory     │  Vector     │  Metadata   │
-│  Cache      │  Manager    │  Index      │
+│  Cache      │  Index      │  Index      │
 └─────────────┬───────────────────────────┘
              │
 ┌─────────────▼───────────────────────────┐
 │         Storage Layer                   │
 ├──────────┬──────────┬──────────────────┤
-│   HNSW   │  Graph   │   Objects        │
+│ Vectors  │  Graph   │   Files          │
-│  Vectors │  Edges   │   (S3/R2/GCS)    │
+│ (sharded)│  Edges   │  (filesystem)    │
 └──────────┴──────────┴──────────────────┘
 ```
-**Distributed Sharding (Implemented):**
+For off-site replication, snapshot `rootDirectory` from your scheduler (`gsutil rsync`, `aws s3 sync`, `rclone`, or `tar`).
 - ConsistentHashRing with 150 virtual nodes
 - 64 shards by default
 - Replication factor of 3
 - Automatic rebalancing on node addition/removal
 ### Auto-Sharding for Horizontal Scale (Implemented)
 Brainy includes a complete sharding implementation with ConsistentHashRing:
 ```javascript
 import { ShardManager } from '@soulcraft/brainy/distributed'
 // Create shard manager with custom configuration
 const shardManager = new ShardManager({
  shardCount: 64,           // Default: 64 shards
  replicationFactor: 3,     // Default: 3 replicas
  virtualNodes: 150,        // Default: 150 virtual nodes
  autoRebalance: true       // Default: true
 })
 // Add nodes to the cluster
 shardManager.addNode('node-1')
 shardManager.addNode('node-2')
 shardManager.addNode('node-3')
 // Sharding automatically:
 // - Uses consistent hashing for even distribution
 // - Maintains replicas for fault tolerance
 // - Rebalances on node changes
 // - Provides O(1) shard lookups
 ```
 ### Performance at Scale
-Even at massive scale, Brainy maintains excellent performance:
+- **Metadata queries**: O(1) HashMap
-
+- **Graph traversal**: O(1) adjacency lookup
- **Metadata queries**: Still O(1) with distributed hash tables
+- **Vector search**: O(log n)
- **Graph traversal**: O(1) with edge locality optimization  
+- **Write throughput**: 50K+ writes/second per process (filesystem, batched)
 - **Vector search**: O(log n) with hierarchical sharding
 - **Write throughput**: 100K+ writes/second with S3 batching
 - **Read throughput**: 1M+ reads/second with caching
-### Zero-Config with Autoscaling (Implemented)
+### Zero-Config with Autoscaling
 Brainy includes extensive autoscaling capabilities:
 **✅ Implemented Autoscaling:**
 - **AutoConfiguration System**: Detects environment and adjusts settings
 - **Learning from Performance**: `learnFromPerformance()` adapts based on metrics
 - **Auto-flush**: Graph index (30s), Metadata index (configurable)
- **Auto-optimize**: Enabled by default in Graph and HNSW indices
+- **Auto-optimize**: Enabled by default in graph and vector indices
 - **Auto-rebalance**: Shards automatically rebalance on node changes
 - **Zero-config presets**: Production, development, minimal modes
 - **Adaptive memory**: Scales caches based on available memory
 - **Environment detection**: Browser vs Node.js vs Serverless
 **🚧 Roadmap Autoscaling:**
 - Dynamic HNSW parameter adjustment (M, ef)
 - Predictive query pattern caching
 - Multi-region auto-replication
 - Automatic cross-node data migration
 ## Implementation Status
-### ✅ Fully Implemented and Production-Ready
+### Fully Implemented and Production-Ready
 - **O(1) metadata lookups** via HashMaps (exact match)
 - **O(log n) range queries** via sorted arrays with lazy building
 - **O(1) graph traversal** via adjacency maps
- **O(log n) vector search** via HNSW
+- **O(log n) vector search** via the default JS index, swappable for a native provider
 - **220 NLP patterns** with pre-computed embeddings
- **S3-compatible storage** (AWS S3, R2, GCS, MinIO, B2)
+- **Filesystem and memory storage** adapters
 - **Distributed sharding** with ConsistentHashRing
 - **Auto-configuration system** with environment detection
 - **Zero-config operation** with intelligent defaults
 - **Auto-flush and auto-optimize** in indices
 - **Sub-2ms response times** for complex queries
 ### 🚧 Roadmap Features
 - Dynamic HNSW parameter tuning
 - Predictive query pattern caching
 - Multi-region S3 replication
 - Automatic cross-node data migration
 - Edge caching layer
 ## Conclusion
 Brainy delivers on its promise of **production-ready Triple Intelligence** with measured, verified performance characteristics. All listed features are fully implemented, tested, and benchmarked. No stubs, no mocks, no theoretical claims - just real, working code with measured performance.
--- a/docs/PLUGINS.md
+++ b/docs/PLUGINS.md
@ -5,7 +5,7 @@ public: true
 category: guides
 template: guide
 order: 4
-description: Replace any Brainy subsystem — distance functions, embeddings, HNSW index, metadata index, aggregation — with a custom implementation or native Rust via Cortex.
+description: Replace any Brainy subsystem — distance functions, embeddings, vector index, metadata index, aggregation — with a custom implementation or optional native acceleration.
 next:
  - cortex/comparison
  - guides/storage-adapters
@ -13,7 +13,7 @@ next:
 # Plugin Development Guide
-Brainy has a plugin system that allows third-party packages to replace internal subsystems with custom implementations. This is how `@soulcraft/cortex` provides native Rust acceleration, and it's the same system available to any developer.
+Brainy has a plugin system that allows third-party packages to replace internal subsystems with custom implementations. This is how `@soulcraft/cortex` provides optional native acceleration, and it's the same system available to any developer.
 ## Architecture Overview
@ -28,7 +28,7 @@ Plugins are **opt-in** — brainy never auto-imports packages. You must explicit
 ```typescript
 const brain = new Brainy({
-  plugins: ['@soulcraft/cortex']  // explicitly load cortex
+  plugins: ['@soulcraft/cortex']  // explicitly load the native acceleration package
 })
 ```
@ -109,7 +109,7 @@ Each key has a specific expected signature. Brainy checks for these during `init
 #### `distance`
 **Type:** `(a: number[], b: number[]) => number`
-Replaces the default cosine distance function used in HNSW search and neural APIs. This is the highest-impact single provider — it's called for every vector comparison.
+Replaces the default cosine distance function used in vector search and neural APIs. This is the highest-impact single provider — it's called for every vector comparison.
 ```typescript
 context.registerProvider('distance', (a: number[], b: number[]): number => {
@ -151,10 +151,10 @@ context.registerProvider('embedBatch', async (texts: string[]) => {
 ### Index Providers
-#### `hnsw`
+#### `vector`
-**Type:** `(config: object, distanceFunction: Function, options: object) => HNSWIndex-compatible`
+**Type:** `(config: object, distanceFunction: Function, options: object) => VectorIndexProvider-compatible`
-Factory function that creates an HNSW index instance. The returned object must implement the `HNSWIndex` public API:
+Factory function that creates a vector index instance. The returned object must implement the `VectorIndexProvider` public API:
 - `addItem(item: { id: string, vector: number[] }): Promise<string>`
 - `search(queryVector: number[], k: number, filter?, options?): Promise<Array<[string, number]>>`
@ -174,12 +174,12 @@ Factory function that creates an HNSW index instance. The returned object must i
 - `setUseParallelization(boolean): void`
 For type-aware indexes (separate graph per noun type), also implement:
- `getIndexForType(type: string): HNSWIndex` (duck-typed detection)
+- `getIndexForType(type: string): VectorIndexProvider` (duck-typed detection)
 - `search(queryVector, k, type?, filter?, options?): Promise<Array<[string, number]>>`
 ```typescript
-context.registerProvider('hnsw', (config, distanceFn, options) => {
+context.registerProvider('vector', (config, distanceFn, options) => {
-  return new MyNativeHNSWIndex(config, distanceFn, options)
+  return new MyNativeVectorIndex(config, distanceFn, options)
 })
 ```
@ -216,7 +216,7 @@ context.registerProvider('aggregation', (storage) => {
 })
 ```
-When provided by a native plugin like `@soulcraft/cortex`, this enables:
+When provided by an optional native acceleration plugin (such as `@soulcraft/cortex`), this enables:
 - Compiled source filters (vs per-entity JS object traversal)
 - Precise MIN/MAX via sorted data structures (vs lazy recompute)
 - Parallel aggregate rebuild across CPU cores
@ -227,7 +227,7 @@ When provided by a native plugin like `@soulcraft/cortex`, this enables:
 #### `cache`
 **Type:** `UnifiedCache`
-Replaces the global `UnifiedCache` singleton used for VFS path resolution, semantic caching, and HNSW vector caching. Must implement the `UnifiedCache` interface (available from `@soulcraft/brainy/internals`).
+Replaces the global `UnifiedCache` singleton used for VFS path resolution, semantic caching, and vector index caching. Must implement the `UnifiedCache` interface (available from `@soulcraft/brainy/internals`).
 ```typescript
 import type { UnifiedCache } from '@soulcraft/brainy/internals'
@ -252,7 +252,7 @@ Native msgpack encode/decode for SSTable serialization.
 ### Analytics Providers (Native-Only)
-These provider keys have **no JavaScript fallback** — they represent capabilities that require native code (SIMD, mmap, sub-microsecond latency). They are available when a native plugin like `@soulcraft/cortex` is installed.
+These provider keys have **no JavaScript fallback** — they represent capabilities that require native code (SIMD, mmap, sub-microsecond latency). They are available when an optional native acceleration plugin (such as `@soulcraft/cortex`) is installed.
 Use `brain.getProvider('analytics:hyperloglog')` to check availability. Returns `undefined` if no plugin provides it.
@ -338,11 +338,11 @@ console.log(diag)
 //     embeddings: { source: 'plugin' },
 //     embedBatch: { source: 'plugin' },
 //     distance: { source: 'plugin' },
-//     hnsw: { source: 'default' },
+//     vector: { source: 'default' },
 //     ...
 //   },
 //   indexes: {
-//     hnsw: { size: 0, type: 'TypeAwareHNSWIndex' },
+//     vector: { size: 0, type: 'JsHnswVectorIndex' },
 //     metadata: { type: 'MetadataIndexManager', initialized: true },
 //     graph: { type: 'GraphAdjacencyIndex', initialized: true, wiredToStorage: true }
 //   }
@ -361,7 +361,7 @@ When a plugin is active, brainy automatically logs a provider summary after `ini
 ```
 [brainy] Plugin activated: @soulcraft/cortex
-[brainy] Providers: 8/10 native (@soulcraft/cortex) | default: hnsw, cache
+[brainy] Providers: 8/10 native (@soulcraft/cortex) | default: vector, cache
 ```
 This tells you at a glance how many subsystems are accelerated and which ones are falling back to JavaScript. The log respects `config.silent`.
--- a/docs/README.md
+++ b/docs/README.md
@ -47,7 +47,7 @@ const results = await brain.find({
 | [Noun-Verb Taxonomy](./architecture/noun-verb-taxonomy.md) | 42 nouns + 127 verbs type system |
 | [Stage 3 Canonical Taxonomy](./STAGE3-CANONICAL-TAXONOMY.md) | Complete type reference |
 | [Storage Architecture](./architecture/storage-architecture.md) | Storage adapters and optimization |
-| [Index Architecture](./architecture/index-architecture.md) | HNSW, Graph, and Metadata indexing |
+| [Index Architecture](./architecture/index-architecture.md) | Vector, Graph, and Metadata indexing |
 | [Zero Configuration](./architecture/zero-config.md) | Auto-adapts to any environment |
 ---
@ -81,12 +81,8 @@ See [vfs/](./vfs/) for the complete VFS documentation set.
 | Document | Description |
 |----------|-------------|
-| [Cloud Deployment](./deployment/CLOUD_DEPLOYMENT_GUIDE.md) | Deploy on AWS, GCP, Azure, Cloudflare |
+| [Storage Architecture](./architecture/storage-architecture.md) | Filesystem and memory adapters, on-disk artifact layout, operator-layer backup |
 | [Extending Storage](./EXTENDING_STORAGE.md) | Create custom storage adapters |
 | [AWS S3 Cost Optimization](./operations/cost-optimization-aws-s3.md) | 96% cost savings |
 | [GCS Cost Optimization](./operations/cost-optimization-gcs.md) | 94% savings with Autoclass |
 | [Azure Cost Optimization](./operations/cost-optimization-azure.md) | 95% savings |
 | [R2 Cost Optimization](./operations/cost-optimization-cloudflare-r2.md) | Zero egress fees |
 | [Capacity Planning](./operations/capacity-planning.md) | Scale to millions of entities |
 ---
--- a/docs/SCALING.md
+++ b/docs/SCALING.md
@ -1,502 +1,202 @@
-# 🚀 Brainy Scaling Guide - Enterprise for Everyone
+# Brainy Scaling Guide
-> **One Line Summary**: Start with one node, scale to hundreds. Zero configuration required.
+> **One Line Summary**: Single-node by design — Brainy scales by getting the most out of one machine plus operator-layer backup.
-## 📖 Table of Contents
+## Table of Contents
 - [Quick Start](#quick-start)
- [How It Works](#how-it-works)
+- [How Brainy Scales](#how-brainy-scales)
 - [Storage Configurations](#storage-configurations)
 - [Scaling Patterns](#scaling-patterns)
 - [Real World Examples](#real-world-examples)
 ## Quick Start
-### Single Node (Default)
+### In-Memory
 ```typescript
 import Brainy from '@soulcraft/brainy'
-const brain = new Brainy()  // That's it!
+const brain = new Brainy({ storage: { type: 'memory' } })
 ```
-### Multi-Node (Auto-Discovery)
+### On-Disk (Default for Node)
 ```typescript
 // Node 1
 const brain = new Brainy()  // Starts as primary
 // Node 2 (different server)
 const brain = new Brainy()  // Auto-discovers Node 1, becomes replica!
 ```
 **That's literally all you need!** Brainy handles everything else automatically.
 ## How It Works
 ### 🎯 The Magic: Zero Configuration
 Brainy uses **intelligent defaults** and **auto-discovery** to eliminate configuration:
 1. **First node starts** → Becomes primary automatically
 2. **Second node starts** → Discovers first node via UDP broadcast
 3. **Nodes negotiate** → Elect leader, distribute shards
 4. **Data flows** → Automatic replication and routing
 5. **Node fails** → Automatic failover in <1 second
 ### 🔄 Automatic Node Discovery
 ```typescript
 // Three ways Brainy finds other nodes (auto-selected):
 // 1. LOCAL NETWORK (Default)
 // Uses UDP broadcast on port 7946
 // Perfect for: On-premise, same VPC
 // 2. CLOUD NATIVE (Auto-detected)
 // Kubernetes: Uses k8s DNS service discovery
 // AWS: Uses EC2 tags or Route53
 // Azure: Uses Azure DNS
 // 3. EXPLICIT (When needed)
 const brain = new Brainy({
-  peers: ['node1.example.com', 'node2.example.com']
+  storage: { type: 'filesystem', rootDirectory: './brainy-data' }
 })
 ```
-### 📊 Data Distribution
+## How Brainy Scales
-When you add data, Brainy automatically:
+Brainy 8.0 is a **single-node library**. There is no cluster, no peer discovery, no S3 coordination. Scaling means:
-```typescript
+- **Up**: give the process more RAM, CPU, and IOPS
-brain.add({ name: "John" }, 'person')
+- **Out**: stand up multiple independent Brainy instances behind your own service layer
 - **Cold storage**: snapshot the on-disk artifact off-site so you can rehydrate elsewhere
-// Behind the scenes:
+The three knobs that matter most:
-// 1. Hash ID to determine shard (consistent hashing)
+
-// 2. Find nodes responsible for this shard
+1. **`config.vector.recall`** — `'fast'`, `'balanced'`, or `'accurate'` (default `'balanced'`)
-// 3. Write to primary shard owner
+2. **`config.vector.quantization`** — `{ bits: 4 | 8 }` for memory savings on the open-core JS vector index
-// 4. Replicate to N backup nodes (default: 2)
+3. **`config.vector.persistMode`** — `'immediate'` for durability, `'deferred'` for throughput
-// 5. Confirm write when majority acknowledge
+
-```
+The native vector provider (via the optional `@soulcraft/cortex` package) extends this with a higher-performing index when installed.
 ## Storage Configurations
-### 🗂️ Storage Adapter Patterns
+### Filesystem (Recommended for Production)
 Brainy intelligently adapts to your storage setup:
 #### Pattern 1: Separate Storage Per Node (Recommended)
 ```typescript
 // Node 1 - Own filesystem
 const brain1 = new Brainy({
  storage: '/data/node1'  // or auto: './brainy-data'
 })
 // Node 2 - Own filesystem  
 const brain2 = new Brainy({
  storage: '/data/node2'  // or auto: './brainy-data'
 })
 // ✅ BENEFITS:
 // - No conflicts between nodes
 // - Fast local reads
 // - True horizontal scaling
 // - Survives network partitions
 ```
 #### Pattern 2: Separate S3 Buckets Per Node
 ```typescript
 // Node 1 - Own S3 bucket
 const brain1 = new Brainy({
  storage: 's3://brainy-node-1'  // Auto-uses AWS credentials
 })
 // Node 2 - Own S3 bucket
 const brain2 = new Brainy({
  storage: 's3://brainy-node-2'
 })
 // ✅ BENEFITS:
 // - Infinite storage capacity
 // - Geographic distribution
 // - No local disk needed
 // - Built-in durability
 ```
 #### Pattern 3: Shared S3 Bucket (Coordinated)
 ```typescript
 // All nodes - Shared bucket with coordination
 const brain = new Brainy({
  storage: 's3://shared-brainy-data',
  // Brainy automatically adds node-specific prefixes!
 })
 // What happens automatically:
 // - Node 1 writes to: s3://shared-brainy-data/node-1/
 // - Node 2 writes to: s3://shared-brainy-data/node-2/
 // - Metadata in: s3://shared-brainy-data/_cluster/
 // - Coordination via S3 conditional writes
 // ✅ BENEFITS:
 // - Single bucket to manage
 // - Easy backup/restore
 // - Cost effective
 // - Automatic namespace isolation
 ```
 #### Pattern 4: Mixed Storage (Hybrid)
 ```typescript
 // Hot data on local SSD, cold data in S3
 const brain = new Brainy({
  storage: {
-    hot: '/fast-ssd/brainy',     // Recent/frequent data
+    type: 'filesystem',
-    cold: 's3://brainy-archive'  // Older data
+    rootDirectory: '/var/lib/brainy'
  }
  // Brainy automatically promotes/demotes data!
 })
 ```
 - Stores everything in a sharded JSON tree under `rootDirectory`
 - Atomic writes via rename
 - Survives process restarts
 - Snapshot it off-site with `gsutil rsync`, `aws s3 sync`, `rclone`, or `tar` from your scheduler
-### 🌍 Cloud Provider Auto-Detection
+### Memory
 ```typescript
 const brain = new Brainy({ storage: { type: 'memory' } })
 ```
 - Zero I/O, fastest possible
 - No persistence — process exit discards everything
 - Use for tests and ephemeral caches
 ### Auto
 ```typescript
 const brain = new Brainy({
-  storage: 'cloud://brainy-data'  // Auto-detects provider!
+  storage: { type: 'auto', rootDirectory: './data' }
 })
 // Automatically uses:
 // - AWS: S3 + DynamoDB for metadata
 // - Google Cloud: GCS + Firestore
 // - Azure: Blob Storage + Cosmos DB
 // - Cloudflare: R2 + D1
 // - Vercel: Blob + KV
 ```
-
+- Picks `filesystem` when running on Node with a writable `rootDirectory`
-### 📝 Storage Coordination Rules
+- Falls back to `memory` otherwise
 When multiple nodes share storage, Brainy automatically:
 1. **Namespace Isolation**: Each node gets unique prefix
 2. **Lock-Free Writes**: Uses atomic operations
 3. **Consistent Metadata**: Coordinated via consensus
 4. **Conflict Resolution**: Version vectors for conflicts
 5. **Garbage Collection**: Automatic cleanup of old data
 ## Scaling Patterns
-### 📈 Progressive Scaling Journey
+### Stage 1: Prototype (Memory)
 #### Stage 1: Prototype (1 node, memory)
 ```typescript
-const brain = new Brainy()  // Memory storage, single node
+const brain = new Brainy({ storage: { type: 'memory' } })
-// Perfect for: Development, testing, <1000 items
+// Development, tests, <100K items
 ```
-#### Stage 2: Production (1 node, disk)
+### Stage 2: Production (Filesystem)
 ```typescript
 const brain = new Brainy({
-  storage: './data'  // Persistent storage
+  storage: { type: 'filesystem', rootDirectory: '/var/lib/brainy' }
 })
-// Perfect for: Small apps, <100K items
+// Most production workloads up to ~10M entities on a single host
 ```
-#### Stage 3: High Availability (2-3 nodes)
+### Stage 3: Higher Throughput (Tune the Vector Index)
 ```typescript
 // Just start same code on multiple servers!
 const brain = new Brainy({
-  storage: './data'  // Each node's own storage
+  storage: { type: 'filesystem', rootDirectory: '/var/lib/brainy' },
  vector: {
    recall: 'fast',                // Trade recall for latency
    quantization: { bits: 8 },     // SQ8 quantization
    persistMode: 'deferred'        // Batch persistence
  }
 })
 // Automatic: Leader election, replication, failover
 // Perfect for: Critical apps, <1M items
 ```
-#### Stage 4: Scale Out (N nodes)
+### Stage 4: Multi-Instance (Operator-Layer)
-```typescript
+Run multiple Brainy processes behind your own routing/service layer. Each process owns its own `rootDirectory`. Sync each artifact off-site independently. Brainy itself does not coordinate between processes.
 // Same code, more servers!
 const brain = new Brainy({
  storage: 's3://brainy-{{nodeId}}'  // Template auto-filled
 })
 // Automatic: Sharding, load balancing, geo-distribution
 // Perfect for: Large apps, unlimited items
 ```
 ### 🎯 Common Scaling Scenarios
 #### Scenario: Read-Heavy Application
 ```typescript
 // Brainy auto-detects read-heavy pattern and:
 // 1. Increases cache size
 // 2. Creates more read replicas
 // 3. Routes reads to nearest node
 // 4. Caches popular items on all nodes
 const brain = new Brainy()  // No config needed!
 ```
 #### Scenario: Multi-Tenant SaaS
 ```typescript
 // Brainy auto-detects tenant patterns and:
 // 1. Shards by tenant ID
 // 2. Isolates tenant data
 // 3. Routes by tenant
 // 4. Separate rate limits per tenant
 const brain = new Brainy()  // Detects from your queries!
 ```
 #### Scenario: Geographic Distribution
 ```typescript
 // Deploy nodes in different regions
 // Brainy automatically:
 // 1. Detects node locations (via latency)
 // 2. Replicates data geographically
 // 3. Routes to nearest node
 // 4. Handles region failures
 // US-East
 const brain = new Brainy({ region: 'us-east' })  // Optional hint
 // EU-West (auto-discovers US-East)
 const brain = new Brainy({ region: 'eu-west' })
 ```
 ## Real World Examples
-### Example 1: Blog Platform
+### Example 1: Single-Node App With Backup
 ```typescript
 // Day 1: Single server
 const brain = new Brainy({
-  storage: './blog-data'
+  storage: { type: 'filesystem', rootDirectory: '/var/lib/brainy' }
 })
-
+```
-// Month 6: Add redundancy (on second server)
+Schedule (cron / systemd timer):
-const brain = new Brainy({
+```bash
-  storage: './blog-data'  // Different machine!
+*/15 * * * *  rclone sync /var/lib/brainy remote:brainy-backup
 })
 // Automatically syncs with first server
 // Year 2: Global scale
 // US Server
 const brain = new Brainy({
  storage: 's3://blog-us/data'
 })
 // EU Server  
 const brain = new Brainy({
  storage: 's3://blog-eu/data'
 })
 // Asia Server
 const brain = new Brainy({
  storage: 's3://blog-asia/data'
 })
 // All automatically coordinate!
 ```
-### Example 2: E-Commerce Site
+### Example 2: Tests
 ```typescript
-// Development
+const brain = new Brainy({ storage: { type: 'memory' } })
-const brain = new Brainy()  // Memory storage
+// Fast, no cleanup needed between runs
 // Staging (Kubernetes)
 const brain = new Brainy({
  storage: process.env.STORAGE_PATH  // Uses PVC
 })
 // Auto-discovers other pods via K8s DNS
 // Production (AWS)
 const brain = new Brainy({
  storage: 's3://shop-data',
  cache: 'elasticache://shop-cache'  // Optional
 })
 // Auto-scales with ECS/EKS
 ```
-### Example 3: Analytics Platform
+### Example 3: Multi-Tenant Service
-
+Spin up one Brainy instance per tenant, each in its own directory:
 ```typescript
-// Ingestion nodes (write-optimized)
+function brainForTenant(tenantId: string) {
-const brain = new Brainy({
+  return new Brainy({
-  role: 'writer',  // Hint for optimization
+    storage: {
-  storage: '/fast-nvme/ingest'
+      type: 'filesystem',
-})
+      rootDirectory: `/var/lib/brainy/${tenantId}`
-
+    }
-// Query nodes (read-optimized)
+  })
 const brain = new Brainy({
  role: 'reader',  // More cache, indexes
  storage: 's3://analytics-archive'
 })
 // Automatically coordinates between writers and readers!
 ```
 ## 🔧 Storage Adapter Specifics
 ### Local Filesystem
 ```typescript
 {
  storage: './data'  // or absolute: '/var/lib/brainy'
  // Each node MUST have separate directory
  // Can be network mounted (NFS, EFS)
 }
 ```
 Your service layer handles routing and isolation; Brainy stays simple.
-### AWS S3
+### Example 4: Higher Recall at Scale
 ```typescript
-{
+const brain = new Brainy({
-  storage: 's3://bucket-name/prefix'
+  storage: { type: 'filesystem', rootDirectory: '/var/lib/brainy' },
-  // Uses AWS SDK credentials (env, IAM role, etc)
+  vector: {
-  // Supports S3-compatible (MinIO, Ceph)
+    recall: 'accurate',
-}
+    quantization: { bits: 8 }
 ```
 ### Cloudflare R2
 ```typescript
 {
  storage: 'r2://bucket-name'
  // Uses Wrangler or API tokens
  // Zero egress fees!
 }
 ```
 ### Google Cloud Storage
 ```typescript
 {
  storage: 'gs://bucket-name'
  // Uses Application Default Credentials
 }
 ```
 ### Azure Blob Storage
 ```typescript
 {
  storage: 'azure://container-name'
  // Uses DefaultAzureCredential
 }
 ```
 ### Mixed/Tiered
 ```typescript
 {
  storage: {
    hot: './local-cache',      // Fast SSD
    warm: 's3://regular-data',  // Standard storage
    cold: 's3://glacier-archive' // Cheap archive
  }
  // Automatic tiering based on access patterns
 }
 ```
 ## 🎭 Advanced Patterns
 ### Pattern: Blue-Green Deployment
 ```typescript
 // Blue cluster (current)
 const brain = new Brainy({
  cluster: 'blue',
  storage: 's3://prod-blue'
 })
 // Green cluster (new version)
 const brain = new Brainy({
  cluster: 'green',
  storage: 's3://prod-green',
  syncFrom: 'blue'  // Real-time sync during migration
 })
 ```
-### Pattern: Federation
+## Tuning Knobs Summary
 ```typescript
 // Region 1 Cluster
 const brain1 = new Brainy({
  federation: 'global',
  region: 'us-east',
  storage: 's3://us-east-data'
 })
-// Region 2 Cluster
+| Setting | Values | When to change |
-const brain2 = new Brainy({
+|---------|--------|----------------|
-  federation: 'global',
+| `vector.recall` | `'fast'` / `'balanced'` / `'accurate'` | Trade recall for latency |
-  region: 'eu-west',
+| `vector.quantization.bits` | `4` / `8` | Smaller index, lower memory |
-  storage: 's3://eu-west-data'
+| `vector.persistMode` | `'immediate'` / `'deferred'` | Throughput vs. durability |
-})
+| `storage.cache.maxSize` | integer | Hot-path read cache size |
-// Clusters coordinate for global queries!
+| `storage.cache.ttl` | ms | Cache freshness |
 ```
-### Pattern: Edge Computing
+## Monitoring & Observability
 ```typescript
 // Edge nodes (in CDN POPs)
 const brain = new Brainy({
  mode: 'edge',
  storage: 'memory',  // RAM only
  upstream: 'https://main-cluster.example.com'
 })
 // Caches frequently accessed data at edge
 ```
 ## 📊 Monitoring & Observability
 Brainy automatically exposes metrics:
 ```typescript
-const metrics = brain.getMetrics()
+const stats = await brain.stats()
 // {
-//   nodes: { total: 5, healthy: 5 },
+//   nounCount: 50000,
-//   shards: { total: 20, local: 4 },
+//   verbCount: 80000,
-//   replication: { factor: 2, lag: 45 },
+//   vectorIndex: { ... },
-//   operations: { reads: 10000, writes: 1000 },
+//   storage: { used: '45GB' }
 //   storage: { used: '45GB', available: '955GB' }
 // }
 ```
-## 🚨 Troubleshooting
+## Troubleshooting
-### Issue: Nodes don't discover each other
+### Issue: Slow queries
-```typescript
+1. Switch to `vector.recall: 'fast'`
-// Solution 1: Check network allows UDP 7946
+2. Enable SQ8 quantization
-// Solution 2: Use explicit peers
+3. Increase the read cache (`storage.cache.maxSize`)
-const brain = new Brainy({
+4. Consider the optional native vector provider via `@soulcraft/cortex`
  peers: ['10.0.0.1:7946', '10.0.0.2:7946']
 })
 ```
-### Issue: Storage conflicts
+### Issue: Memory pressure
-```typescript
+1. Enable `vector.quantization: { bits: 4 }` or `{ bits: 8 }`
-// Ensure each node has unique storage path
+2. Reduce `storage.cache.maxSize`
-// ❌ WRONG: All nodes use './data'
+3. Move to `vector.persistMode: 'deferred'` to batch writes
 // ✅ RIGHT: Node1: './data1', Node2: './data2'
 // ✅ RIGHT: Use {{nodeId}} template
 ```
-### Issue: Slow performance
+### Issue: Slow startup after a crash
-```typescript
+1. Use `vector.persistMode: 'immediate'` so the index file stays in sync with storage
-// Brainy auto-tunes, but you can hint:
+2. Verify backup integrity periodically
 const brain = new Brainy({
  profile: 'read-heavy'  // or 'write-heavy', 'balanced'
 })
 ```
-## 🎯 Best Practices
+## Best Practices
-1. **Let Brainy Auto-Configure**: Don't over-configure
+1. **One process = one `rootDirectory`** — never share a directory between processes
-2. **Separate Storage Per Node**: Avoids conflicts
+2. **Snapshot from your scheduler** — Brainy doesn't ship cloud SDKs; use `rclone` / `aws s3 sync` / `gsutil`
-3. **Use S3 for Large Scale**: Infinite capacity
+3. **Profile before tuning** — `recall: 'balanced'` is right for most workloads
-4. **Start Simple**: Single node → Scale when needed
+4. **Install the native vector provider only when measured profiling shows it pays off**
 5. **Monitor Metrics**: Watch for bottlenecks
 6. **Trust Auto-Scaling**: It learns your patterns
-## 🚀 Summary
+## Summary
- **Zero Config**: Just `new Brainy()` at any scale
+- Brainy 8.0 is a **library**, not a cluster
- **Auto-Discovery**: Nodes find each other
+- Storage adapters: `filesystem`, `memory`, `auto`
- **Smart Storage**: Adapts to any backend
+- Vector tuning: `recall`, `quantization`, `persistMode`
- **Progressive Scaling**: 1 → 100 nodes seamlessly
+- Backup is an operator-layer concern — snapshot `rootDirectory`
 - **Self-Tuning**: Learns and optimizes
 - **No DevOps**: It just works!
 **This is Enterprise for Everyone - enterprise-grade scaling with toy-like simplicity!**
 ---
 *Questions? Issues? Visit [github.com/soullabs/brainy](https://github.com/soullabs/brainy)*
--- a/docs/api/README.md
+++ b/docs/api/README.md
@ -65,7 +65,7 @@ Semantic vectors with metadata and relationships - the fundamental data unit in
 Typed connections between entities with optional `data` and `metadata` - building knowledge graphs.
 ### 📊 Data vs Metadata
- **`data`**: Content embedded into vectors. Searchable via **semantic similarity** (HNSW) and **hybrid text+semantic** search. NOT queryable via `where` filters.
+- **`data`**: Content embedded into vectors. Searchable via **semantic similarity** (vector index) and **hybrid text+semantic** search. NOT queryable via `where` filters.
 - **`metadata`**: Structured fields indexed by MetadataIndex. Queryable via `where` filters in `find()`.
 See **[Data Model](../DATA_MODEL.md)** for the full explanation.
@ -232,7 +232,7 @@ const results = await brain.find({
 - **Advanced:** Object with vector + graph + metadata filters
 **FindParams:**
- `query?`: `string` - Text for semantic + hybrid search (searches `data` via HNSW + text index)
+- `query?`: `string` - Text for semantic + hybrid search (searches `data` via the vector index + text index)
 - `type?`: `NounType | NounType[]` - Filter by entity type(s). Alias for `where.noun`.
 - `subtype?`: `string | string[]` - Filter by sub-classification (top-level standard field, fast path). Single string for equality, array for set membership.
 - `where?`: `object` - Metadata filters. See **[Query Operators](../QUERY_OPERATORS.md)** for all operators.
@ -808,7 +808,7 @@ const parentData = await brain.find({}) // Original data unchanged
 **Returns:** `Promise<Brainy>` - New Brainy instance on forked branch
-**How it works:** Snowflake-style COW shares HNSW index, copies only modified nodes (10-20% memory overhead).
+**How it works:** Snowflake-style COW shares the vector index, copies only modified nodes (10-20% memory overhead).
 ---
@ -1787,28 +1787,20 @@ const entities = await snapshot.find({ limit: 100 })
 ```typescript
 const brain = new Brainy({
- // Storage configuration
+  // Storage configuration
- storage: {
+  storage: {
- type: 'memory', // memory | opfs | filesystem | s3 | r2 | gcs | azure
+    type: 'filesystem',           // 'memory' | 'filesystem' | 'auto'
- path: './brainy-data', // For filesystem storage
+    rootDirectory: './brainy-data'
- compression: true, // Enable gzip compression (60-80% savings)
+  },
- // Cloud storage configs (see Storage Adapters section)
+  // Vector index configuration (3 knobs)
- s3Storage: { ... },
+  vector: {
- r2Storage: { ... },
+    recall: 'balanced',           // 'fast' | 'balanced' | 'accurate'
- gcsStorage: { ... },
+    quantization: { bits: 8 },    // 4 | 8 (SQ4 / SQ8)
- azureStorage: { ... }
+    persistMode: 'immediate'      // 'immediate' | 'deferred'
- },
+  },
- // HNSW vector index config
+  // Model configuration (embedded in WASM - zero config needed)
 hnsw: {
 M: 16, // Connections per layer
 efConstruction: 200, // Construction quality
 efSearch: 100, // Search quality
 typeAware: true // Enable type-aware indexing
 },
 // Model configuration (embedded in WASM - zero config needed)
 // Model: all-MiniLM-L6-v2 (384 dimensions)
 // Device: CPU via WASM (works everywhere)
@ -1827,13 +1819,13 @@ await brain.init() // Required! VFS auto-initialized
 ## Storage Adapters
-All 7 storage adapters support **copy-on-write branching**.
+Brainy 8.0 ships two adapters — both support **copy-on-write branching**.
-### Memory (Default)
+### Memory (Default for Tests)
 ```typescript
 const brain = new Brainy({
- storage: { type: 'memory' }
+  storage: { type: 'memory' }
 })
 ```
@ -1841,125 +1833,32 @@ const brain = new Brainy({
 ---
-### OPFS (Browser)
+### Filesystem (Default for Node)
 ```typescript
 const brain = new Brainy({
- storage: { type: 'opfs' }
+  storage: {
    type: 'filesystem',
    rootDirectory: './brainy-data'
  }
 })
 ```
-**Use case:** Browser applications with persistent storage
+**Use case:** Node.js applications, single-node production deployments
 For off-site backup, snapshot `rootDirectory` from your scheduler (`gsutil rsync`, `aws s3 sync`, `rclone`, or `tar`) — Brainy itself doesn't reach out to cloud object stores.
 ---
-### Filesystem (Node.js)
+### Auto
 ```typescript
 const brain = new Brainy({
- storage: {
+  storage: { type: 'auto', rootDirectory: './brainy-data' }
 type: 'filesystem',
 path: './brainy-data',
 compression: true // 60-80% space savings
 }
 })
 ```
-**Use case:** Node.js applications, local persistence
+Picks `'filesystem'` on Node with a writable `rootDirectory`, falls back to `'memory'` otherwise.
 ---
 ### AWS S3
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 's3',
 s3Storage: {
 bucketName: 'my-brainy-data',
 region: 'us-east-1',
 accessKeyId: process.env.AWS_ACCESS_KEY_ID,
 secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
 }
 }
 })
 // Enable Intelligent-Tiering for 96% cost savings
 await brain.storage.enableIntelligentTiering('entities/', 'auto-tier')
 ```
 **Use case:** Production deployments, scalable storage
 **[📖 AWS S3 Cost Optimization →](../operations/cost-optimization-aws-s3.md)**
 ---
 ### Cloudflare R2
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 'r2',
 r2Storage: {
 accountId: process.env.CF_ACCOUNT_ID,
 bucketName: 'my-brainy-data',
 accessKeyId: process.env.CF_ACCESS_KEY_ID,
 secretAccessKey: process.env.CF_SECRET_ACCESS_KEY
 }
 }
 })
 ```
 **Use case:** Zero egress fees, cost-effective storage
 **[📖 R2 Cost Optimization →](../operations/cost-optimization-cloudflare-r2.md)**
 ---
 ### Google Cloud Storage (GCS)
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 'gcs',
 gcsStorage: {
 bucketName: 'my-brainy-data',
 projectId: process.env.GCP_PROJECT_ID,
 keyFilename: './gcp-key.json'
 }
 }
 })
 // Enable auto-tiering
 await brain.storage.enableAutoclass({
 terminalStorageClass: 'ARCHIVE'
 })
 ```
 **Use case:** Google Cloud ecosystem, global distribution
 **[📖 GCS Cost Optimization →](../operations/cost-optimization-gcs.md)**
 ---
 ### Azure Blob Storage
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 'azure',
 azureStorage: {
 accountName: process.env.AZURE_STORAGE_ACCOUNT,
 accountKey: process.env.AZURE_STORAGE_KEY,
 containerName: 'brainy-data'
 }
 }
 })
 ```
 **Use case:** Azure ecosystem, enterprise deployments
 **[📖 Azure Cost Optimization →](../operations/cost-optimization-azure.md)**
 ---
@ -2292,7 +2191,7 @@ console.log(`Fields: ${stats.metadataFields.join(', ')}`)
 **Returns:**
 - `entities` - Total entity count
- `vectors` - Total vectors in HNSW index
+- `vectors` - Total vectors in the vector index
 - `relationships` - Total relationships in graph
 - `metadataFields` - Indexed metadata fields
 - `memoryUsage.vectors` - Vector memory (bytes)
@ -2597,7 +2496,7 @@ For the full taxonomy with all 169 types and their descriptions, see:
 - ✅ **Git-Style Branching** - fork, commit, checkout, listBranches
 - ✅ **Full Branch Isolation** - Parent and fork fully isolated
 - ✅ **Read-Through Inheritance** - Forks see parent + own data
- ✅ **Universal Storage Support** - All 7 adapters support branching
+- ✅ **Universal Storage Support** - Filesystem and memory adapters both support branching
 **[📖 Complete Changes →](../../.strategy/v5.1.0-CHANGES.md)**
--- a/docs/architecture/augmentation-system-audit.md
+++ b/docs/architecture/augmentation-system-audit.md
@ -40,7 +40,7 @@ brain.augmentations.register(augmentation)
 new Brainy({
  cache: true,    // Auto-registers CacheAugmentation
  index: true,    // Auto-registers IndexAugmentation
-  storage: 's3'   // Auto-registers S3StorageAugmentation
+  storage: { type: 'filesystem', rootDirectory: './data' }  // Auto-registers FileSystemStorageAugmentation
 })
 ```
--- a/docs/architecture/data-storage-architecture.md
+++ b/docs/architecture/data-storage-architecture.md
@ -1,8 +1,8 @@
 # Brainy Data Storage Architecture
-**Complete file structure reference for all storage backends**
+**Complete file structure reference**
-This document explains how Brainy stores, indexes, and scales data across all storage backends (GCS, S3, R2, Azure, filesystem, OPFS, memory).
+This document explains how Brainy stores, indexes, and scales data on disk and in memory.
 ---
@ -22,10 +22,10 @@ This document explains how Brainy stores, indexes, and scales data across all st
 ## 1. Complete File Structure
-### v5.11.0 Full Directory Tree
+### Full Directory Tree
 ```
-brainy-data/                                  # Root directory (or bucket name for cloud)
+brainy-data/                                  # Root directory
 │
 ├── branches/                                 # Branch-scoped storage (v5.4.0+, COW always-on)
 │   ├── main/                                # Main branch (default)
@ -34,7 +34,7 @@ brainy-data/                                  # Root directory (or bucket name f
 │   │       │   ├── Character/              # Type-first: entities organized by type
 │   │       │   │   ├── vectors/
 │   │       │   │   │   ├── 00/            # UUID-based sharding (256 shards)
-│   │       │   │   │   │   ├── 001234...uuid.json    # HNSW vector + connections
+│   │       │   │   │   │   ├── 001234...uuid.json    # Vector + graph connections
 │   │       │   │   │   │   └── 00abcd...uuid.json
 │   │       │   │   │   ├── 01/ ... fe/
 │   │       │   │   │   └── ff/
@ -111,11 +111,11 @@ brainy-data/                                  # Root directory (or bucket name f
    ├── statistics.json                      # Global statistics
    ├── counts.json                          # Entity/verb counts by type
    │
-    ├── hnsw/                                # HNSW index metadata
+    ├── vector/                              # Vector index metadata
    │   ├── system.json                      # Entry point, max level
    │   └── nodes/
    │       ├── 00/
-    │       │   └── 001234...uuid.json      # Per-node HNSW data
+    │       │   └── 001234...uuid.json      # Per-node graph data
    │       ├── 01/ ... fe/
    │       └── ff/
    │
@ -151,15 +151,15 @@ Each entity is stored as **2 separate files** for optimal performance.
 {
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "vector": [0.1, 0.2, 0.3, ...],  // 384-dimensional embedding
-  "connections": {                  // HNSW graph connections
+  "connections": {                  // Vector index graph connections
    "0": ["uuid1", "uuid2"],       // Layer 0 neighbors
    "1": ["uuid3", "uuid4"]        // Layer 1 neighbors
  },
-  "level": 2                        // HNSW max level for this node
+  "level": 2                        // Max level for this node
 }
 ```
-**Purpose**: HNSW graph navigation for semantic search
+**Purpose**: Vector index navigation for semantic search
 **Size**: ~4KB per entity (384 dims × 4 bytes × 2.6 overhead)
 **Scale**: Millions of entities
@ -202,7 +202,7 @@ Each relationship is also stored as **2 separate files**.
  "id": "7b2f5e3c-8d4a-4f1e-9c2b-5a6d7e8f9a0b",
  "vector": [0.5, 0.3, 0.7, ...],  // Relationship embedding
  "connections": {
-    "0": ["verb-uuid1", "verb-uuid2"]  // Verb-to-verb HNSW connections
+    "0": ["verb-uuid1", "verb-uuid2"]  // Verb-to-verb vector connections
  },
  "level": 1
 }
@ -334,7 +334,7 @@ Unlike entities and relationships, system metadata consists of **index files** t
    "Character": 50000,
    "Place": 30000
  },
-  "hnswIndexSize": 204800,
+  "vectorIndexSize": 204800,
  "totalNodes": 100000,
  "totalEdges": 175000,
  "lastUpdated": "2025-11-18T..."
@ -369,8 +369,8 @@ Unlike entities and relationships, system metadata consists of **index files** t
 **Purpose**: Fast entity/verb counts by type without scanning storage
-#### HNSW System Metadata
+#### Vector Index System Metadata
-**Location**: `_system/hnsw/system.json`
+**Location**: `_system/vector/system.json`
 ```json
 {
@ -381,10 +381,10 @@ Unlike entities and relationships, system metadata consists of **index files** t
 }
 ```
-**Purpose**: HNSW index entry point and global parameters
+**Purpose**: Vector index entry point and global parameters
-#### HNSW Node Data
+#### Vector Index Node Data
-**Location**: `_system/hnsw/nodes/{shard}/{uuid}.json`
+**Location**: `_system/vector/nodes/{shard}/{uuid}.json`
 ```json
 {
@ -398,7 +398,7 @@ Unlike entities and relationships, system metadata consists of **index files** t
 }
 ```
-**Purpose**: Per-node HNSW graph connections (persisted for fast rebuild)
+**Purpose**: Per-node vector index graph connections (persisted for fast rebuild)
 #### Field Indexes (Hash Indexes)
 **Location**: `_system/metadata_indexes/__metadata_field_index__{field}.json`
@ -491,11 +491,11 @@ const tagRefPath = `_cow/refs/tags/${tagName}.json`
 // System files never use sharding or branching
 const statsPath = `_system/statistics.json`
 const countsPath = `_system/counts.json`
-const hnswSystemPath = `_system/hnsw/system.json`
+const vectorSystemPath = `_system/vector/system.json`
 const fieldIndexPath = `_system/metadata_indexes/__metadata_field_index__${fieldName}.json`
-// HNSW node data IS sharded (entity UUID-based)
+// Vector node data IS sharded (entity UUID-based)
-const hnswNodePath = `_system/hnsw/nodes/${shard}/${entityId}.json`
+const vectorNodePath = `_system/vector/nodes/${shard}/${entityId}.json`
 ```
 ### Path Patterns Summary
@ -512,8 +512,8 @@ const hnswNodePath = `_system/hnsw/nodes/${shard}/${entityId}.json`
 | **COW ref** | `_cow/refs/heads/{branch}.json` | ❌ No | ❌ No |
 | **Statistics** | `_system/statistics.json` | ❌ No | ❌ No |
 | **Counts** | `_system/counts.json` | ❌ No | ❌ No |
-| **HNSW system** | `_system/hnsw/system.json` | ❌ No | ❌ No |
+| **Vector system** | `_system/vector/system.json` | ❌ No | ❌ No |
-| **HNSW node** | `_system/hnsw/nodes/{shard}/{uuid}.json` | ✅ Yes (UUID) | ❌ No |
+| **Vector node** | `_system/vector/nodes/{shard}/{uuid}.json` | ✅ Yes (UUID) | ❌ No |
 | **Field index** | `_system/metadata_indexes/__metadata_field_index__{field}.json` | ❌ No | ❌ No |
 ### Key Principles
@ -521,7 +521,7 @@ const hnswNodePath = `_system/hnsw/nodes/${shard}/${entityId}.json`
 1. **Shard Extraction**: Always use first 2 hex characters of UUID/SHA-256
 2. **ID-First**: Shard + ID come BEFORE type (type is in metadata)
 3. **Branch Isolation**: Only entity data uses branches/
-4. **System Isolation**: System files never use sharding or branching (except HNSW nodes)
+4. **System Isolation**: System files never use sharding or branching (except vector index nodes)
 5. **Content-Addressable**: COW uses SHA-256 hash as filename
 ---
@ -530,7 +530,7 @@ const hnswNodePath = `_system/hnsw/nodes/${shard}/${entityId}.json`
 Brainy uses four complementary index systems for different query patterns.
-### 3.1 HNSW Vector Index (In-Memory with Lazy Loading)
+### 3.1 Vector Index (In-Memory with Lazy Loading)
 **Purpose**: Semantic similarity search
 **Location**: RAM (rebuilt from storage on startup)
@ -538,7 +538,7 @@ Brainy uses four complementary index systems for different query patterns.
 **How It Works**:
 1. Loads `branches/{branch}/entities/nouns/{type}/vectors/**/*.json` files
-2. Builds HNSW graph structure in memory
+2. Builds vector index graph structure in memory
 3. Enables O(log n) approximate nearest neighbor search
 4. Vectors loaded on-demand in lazy mode (zero configuration)
@ -634,10 +634,10 @@ const users = await brain.getNouns({
 ### 4.1 Why Shard?
-**Cloud Storage Limitations**:
+**Filesystem Limitations**:
- GCS/S3: Listing 100K files in one directory = 10-30 seconds
+- Listing 100K files in one directory is slow (`readdir` walks the whole entry list)
- GCS/S3: Max recommended files per directory = 1,000-10,000
+- Most filesystems prefer ≤10,000 entries per directory for fast lookups
- Network: Parallel operations faster than sequential
+- Parallel operations across shards beat serial scans
 **Solution**: Split into 256 shards = ~3,900 files per shard at 1M scale
@ -786,7 +786,7 @@ _cow/blobs/ab/abc123...sha256.bin  (used by both entities)
 ### 6.1 What is ID-First?
-**ID-first storage** organizes entities by **ID shard only** - no type directories! This eliminates 42-type sequential searches that caused 20-21 second delays on cloud storage.
+**ID-first storage** organizes entities by **ID shard only** - no type directories! This eliminates 42-type sequential searches that caused long delays when an entity's type was unknown.
 **Old type-first structure** (v5.12.0):
 ```
@ -807,13 +807,13 @@ branches/main/entities/nouns/00/001234...uuid/metadata.json
 **1. 40x Faster Lookups**
 ```typescript
 // v5.x: Had to search 42 types if type unknown
-// Result: 21 seconds on GCS (42 types × 500ms)
+// Result: 21 seconds (42 types × 500ms)
 // Direct path from ID
 const id = '001234...'
 const shard = id.substring(0, 2)  // '00'
 const path = `branches/main/entities/nouns/${shard}/${id}/metadata.json`
-// Result: <500ms on GCS - 40x faster!
+// Result: <500ms - 40x faster!
 ```
 **2. Simpler Code**
@ -980,9 +980,9 @@ const related = await brain.find('financial projections for Q2')
 ## 8. Storage Backend Mapping
-### 8.1 All Backends Use Same Structure
+### 8.1 Both Adapters Use the Same Structure
-**Filesystem** (local):
+**Filesystem** (default for Node.js):
 ```
 /path/to/brainy-data/
  ├── branches/main/entities/nouns/Character/vectors/00/001234...uuid.json
@ -990,70 +990,21 @@ const related = await brain.find('financial projections for Q2')
  └── _system/statistics.json
 ```
 **Google Cloud Storage** (GCS):
 ```
 gs://my-bucket/
  ├── branches/main/entities/nouns/Character/vectors/00/001234...uuid.json
  ├── _cow/commits/00/00a1b2c3...sha256.json
  └── _system/statistics.json
 ```
 **AWS S3** / **MinIO** / **DigitalOcean Spaces**:
 ```
 s3://my-bucket/
  ├── branches/main/entities/nouns/Character/vectors/00/001234...uuid.json
  ├── _cow/commits/00/00a1b2c3...sha256.json
  └── _system/statistics.json
 ```
 **Cloudflare R2**:
 ```
 r2://my-bucket/
  ├── branches/main/entities/nouns/Character/vectors/00/001234...uuid.json
  ├── _cow/commits/00/00a1b2c3...sha256.json
  └── _system/statistics.json
 ```
 **Azure Blob Storage**:
 ```
 azure://my-container/
  ├── branches/main/entities/nouns/Character/vectors/00/001234...uuid.json
  ├── _cow/commits/00/00a1b2c3...sha256.json
  └── _system/statistics.json
 ```
 **OPFS** (browser):
 ```
 opfs://root/brainy/
  ├── branches/main/entities/nouns/Character/vectors/00/001234...uuid.json
  ├── _cow/commits/00/00a1b2c3...sha256.json
  └── _system/statistics.json
 ```
 **Memory Storage** (in-memory):
 - Uses same path structure
 - Stored in `Map<string, any>`
 - Key = full path (e.g., "branches/main/entities/nouns/Character/vectors/00/001234...uuid.json")
 For off-site backup of the filesystem artifact, snapshot the `rootDirectory` from your scheduler using `gsutil`, `aws s3 sync`, `rclone`, or `tar` — Brainy itself stays local.
 ---
-### 8.2 Backend-Specific Optimizations
+### 8.2 Adapter Characteristics
 **Cloud Storage (GCS, S3, R2, Azure)**:
 - Lifecycle policies for automatic archival (96% cost savings)
 - Intelligent-Tiering (S3) or Autoclass (GCS) for access-pattern optimization
 - Batch operations (1000 objects per request for S3)
 - Parallel uploads/downloads
 **Filesystem**:
 - Optional gzip compression (60-80% space savings)
 - Direct file I/O (fastest for local)
 - Atomic writes with rename
-
+- Sharded directory layout keeps `readdir` fast
 **OPFS**:
 - Quota monitoring (browser storage limits)
 - Persistent storage (survives page refresh)
 - Worker-based I/O (non-blocking)
 **Memory**:
 - No I/O overhead (instant access)
@ -1090,7 +1041,7 @@ opfs://root/brainy/
 | Get entity by ID | 15-30s | 100-150ms | **200x faster** |
 | List all entities | 30-60s | 30-60s | Same |
 | Filter by metadata | 10-30s | 5-50ms | **100-600x faster** (via indexes) |
-| Semantic search | N/A | 1-10ms | N/A (requires HNSW) |
+| Semantic search | N/A | 1-10ms | N/A (requires vector index) |
 | Type filtering | 30-60s | 120-200ms | **150-500x faster** (type-first) |
 | Graph query (getVerbsBySource) | O(total_verbs) | <1ms | **O(1) via index** |
@ -1113,15 +1064,10 @@ opfs://root/brainy/
 | Storage Backend | Max Entities (No Optimization) | Max Entities (Full Optimization) |
 |----------------|-------------------------------|----------------------------------|
 | GCS | ~10,000 | **10M+** |
 | S3 | ~10,000 | **10M+** |
 | R2 | ~10,000 | **10M+** |
 | Azure | ~10,000 | **10M+** |
 | Filesystem | ~100,000 | **10M+** |
 | OPFS | ~50,000 | **1M+** (browser limits) |
 | Memory | Limited by RAM | Limited by RAM |
-**Full optimization** = Sharding + Type-first + COW + Lifecycle policies + Lazy mode
+**Full optimization** = Sharding + Type-first + COW + Lazy mode
 ---
@ -1129,7 +1075,7 @@ opfs://root/brainy/
 | Component | Standard Mode | Lazy Mode | Savings |
 |-----------|---------------|-----------|---------|
-| **HNSW Index (100K entities)** | 149MB | 15-33MB | 5-10x |
+| **Vector Index (100K entities)** | 149MB | 15-33MB | 5-10x |
 | **Graph Index (100K verbs)** | 100MB | 100MB | N/A |
 | **Metadata Indexes** | 10-50MB | 10-50MB | N/A |
 | **UnifiedCache** | 2GB | 2GB | N/A |
@ -1149,17 +1095,15 @@ opfs://root/brainy/
 - Use UUIDs for all entities and relationships
 - Let Brainy handle sharding automatically (type-first + UUID sharding)
 - Use metadata indexes for filtering
 - Enable lifecycle policies for cloud storage (96% cost savings)
 - Use batch operations for bulk deletions
- Enable compression for FileSystem storage (60-80% space savings)
+- Snapshot `rootDirectory` to off-site storage from your scheduler (`gsutil` / `aws s3 sync` / `rclone`)
 - Create branches for experimentation (instant, zero-cost)
 ❌ **Don't**:
 - Try to organize files manually
 - Assume file paths are predictable (use IDs, not paths)
- Store large binary data in metadata (use blob storage or VFS)
+- Store large binary data in metadata (use VFS for blobs)
- Disable COW (can't be disabled in v5.11.0+, always enabled)
+- Disable COW (always enabled)
 - Forget to monitor OPFS quota in browser applications
 ---
@ -1170,7 +1114,7 @@ opfs://root/brainy/
 ✅ Deletes:
 - `branches/` → ALL entity data (all types, all shards, all branches, all forks)
 - `_cow/` → ALL version control (commits, trees, blobs, refs)
- `_system/` → ALL indexes (statistics, HNSW, metadata)
+- `_system/` → ALL indexes (statistics, vector index, metadata)
 ✅ Resets:
 - COW managers (refManager, blobStorage, commitLog) → `undefined`
@ -1237,7 +1181,7 @@ await brain.add({ data: 'Alice', type: 'person' })
   → _cow/refs/heads/main.json (points to new commit)
 10. Update statistics:
   → _system/statistics.json (increment person count)
-11. Update HNSW index (in-memory):
+11. Update vector index (in-memory):
    → Connect to nearest neighbors
 12. Update graph index (in-memory):
    → Add to adjacency maps
@ -1281,7 +1225,7 @@ const results = await brain.find('medieval castle', { k: 10 })
 **What happens in storage**:
 ```
 1. Compute query vector: [0.1, 0.2, 0.3, ...]
-2. Use HNSW index (in-memory):
+2. Use vector index (in-memory):
   → Navigate graph from entry point
   → Find 10 nearest neighbors (1-10ms)
 3. Load vectors from cache or storage:
@ -1363,7 +1307,7 @@ await brain.storage.clear()
   → Result: ALL commits, trees, blobs, refs deleted
 3. Delete all indexes:
   → Remove: _system/ (entire directory)
-   → Result: Statistics, HNSW, metadata indexes deleted
+   → Result: Statistics, vector index, metadata indexes deleted
 4. Reset COW managers in memory:
   → refManager = undefined
   → blobStorage = undefined
@ -1393,13 +1337,13 @@ await brain.init()
 **What happens in storage**:
 ```
 1. Check for persisted indexes:
-   → Load: _system/hnsw/system.json (entry point, max level)
+   → Load: _system/vector/system.json (entry point, max level)
-   → Load: _system/hnsw/nodes/** (graph connections)
+   → Load: _system/vector/nodes/** (graph connections)
   → Load: _system/statistics.json (entity counts)
 2. Decide standard vs lazy mode:
   → Check: entityCount × vectorSize vs. available cache
   → Auto-enable lazy mode if needed
-3. Rebuild HNSW index:
+3. Rebuild vector index:
   → Standard mode: Load all vectors into memory
   → Lazy mode: Load only graph structure (~24 bytes/node)
 4. Rebuild Graph Adjacency index:
@ -1441,7 +1385,7 @@ await brain.addBatch([
   → 1 tree object (or tree fan-out for large trees)
   → 10,000+ blobs (deduplicated)
 5. Update indexes in batch:
-   → HNSW: Batch insert (optimized)
+   → Vector index: Batch insert (optimized)
   → Graph: Batch update
   → Metadata: Batch index update
 ```
@ -1455,25 +1399,23 @@ await brain.addBatch([
 **Complete Storage Structure**:
 - **3 storage layers**: branches/ (data), _cow/ (versions), _system/ (indexes)
 - **2 files per entity**: metadata.json + vector.json (optimized I/O)
- **4 indexes**: HNSW (semantic), Type Index (metadata-based), Graph (relationships), Metadata (fields)
+- **4 indexes**: Vector (semantic), Type Index (metadata-based), Graph (relationships), Metadata (fields)
 - **256 shards**: UUID-based (uniform distribution)
 - **42 noun types + 127 verb types**: Type is metadata, not storage structure
 - **Git-like COW**: Branches, commits, trees, blobs, refs
 - **VFS support**: Traditional file/folder hierarchies
-**Scalability (v6.0.0 Improvements)**:
+**Scalability**:
- **ID-First Storage**: 40x faster on cloud storage (eliminates 42-type search)
+- **ID-First Storage**: 40x faster directory lookups (eliminates 42-type search)
- Sharding: 200x faster for cloud storage
+- Sharding: 200x faster file lookups
 - Type filtering: Still O(type_count) via metadata index
 - Lazy mode: 5-10x less memory for large datasets
 - COW: Instant branches, efficient forks
 - Deduplication: 30-90% storage savings
 **Production Features**:
- Lifecycle policies (96% cost savings on cloud storage)
+- Batch operations (efficient I/O)
- Batch operations (efficient API usage)
+- Operator-layer backup via `gsutil` / `aws s3 sync` / `rclone` against `rootDirectory`
 - Compression (60-80% space savings on filesystem)
 - Quota monitoring (OPFS browser limits)
 - Auto-reinitialization (COW always-on, can't be broken)
 - **Clean architecture**: Removed 500+ lines of type cache complexity
@ -1481,7 +1423,7 @@ await brain.addBatch([
 ## Next Steps
- [Storage Adapters](./storage-architecture.md) - Configure cloud storage backends
+- [Storage Architecture](./storage-architecture.md) - Adapter and backup details
 - [VFS Guide](../vfs/README.md) - Use Virtual File System features
 - [Triple Intelligence](../vfs/TRIPLE_INTELLIGENCE.md) - Semantic file extraction
 - [Scaling Guide](../SCALING.md) - Handle 10M+ entities
@ -1489,6 +1431,5 @@ await brain.addBatch([
 ---
-**Version**: v6.0.0
+**Last Updated**: 2026
-**Last Updated**: 2025-11-19
+**Key Features**: ID-first storage, COW always-on, metadata-based type index, 4-index architecture, VFS support, billion-scale optimization
 **Key Features**: ID-first storage, COW always-on, metadata-based type index, 4-index architecture, VFS support, billion-scale optimization, 40x cloud performance improvement
--- a/docs/architecture/distributed-storage.md
+++ b/docs/architecture/distributed-storage.md
@ -1,550 +0,0 @@
 # 🏗️ Distributed Storage Architecture
 > **Technical deep-dive**: How Brainy coordinates storage across multiple nodes and adapters
 ## Storage Adapter Layer
 ### Base Storage Interface
 Every storage adapter implements this interface:
 ```typescript
 interface StorageAdapter {
  // Basic operations
  get(key: string): Promise<any>
  set(key: string, value: any): Promise<void>
  delete(key: string): Promise<void>
  // Batch operations
  getBatch(keys: string[]): Promise<Map<string, any>>
  setBatch(items: Map<string, any>): Promise<void>
  // Atomic operations (for coordination)
  compareAndSwap(key: string, oldVal: any, newVal: any): Promise<boolean>
  increment(key: string, delta: number): Promise<number>
  // Namespace support
  withNamespace(namespace: string): StorageAdapter
 }
 ```
 ### Storage Coordination Strategies
 #### Strategy 1: Isolated Storage (Default)
 Each node has completely separate storage:
 ```
 Node-1 → Local FS: /data/node1/
         └── shards/
             ├── shard-001/
             ├── shard-045/
             └── shard-127/
 Node-2 → Local FS: /data/node2/
         └── shards/
             ├── shard-023/
             ├── shard-067/
             └── shard-089/
 ```
 **Coordination**: Via network messages only
 - Shard ownership tracked in distributed consensus
 - Data transfer via direct node-to-node communication
 - No storage-level conflicts possible
 #### Strategy 2: Shared Storage with Namespacing
 Multiple nodes share storage but use namespaces:
 ```
 S3 Bucket: brainy-cluster/
 ├── node-abc123/
 │   ├── shards/
 │   └── wal/
 ├── node-def456/
 │   ├── shards/
 │   └── wal/
 └── _cluster/
    ├── topology.json
    ├── shard-map.json
    └── elections/
 ```
 **Coordination**: Via storage-level atomic operations
 - Each node owns its namespace
 - Cluster metadata in shared `_cluster/` namespace
 - Atomic operations for leader election
 - Conditional writes prevent conflicts
 #### Strategy 3: Shared Storage with Fine-Grained Locking
 Advanced mode for full shared storage:
 ```
 S3 Bucket: brainy-shared/
 ├── shards/
 │   ├── 001/
 │   │   ├── data.bin
 │   │   └── .lock (atomic)
 │   ├── 002/
 │   │   ├── data.bin
 │   │   └── .lock
 └── metadata/
    ├── index/
    └── locks/
 ```
 **Coordination**: Via distributed locking
 - Shard-level locks using atomic operations
 - Lock acquisition via compare-and-swap
 - Automatic lock expiry (lease-based)
 - Deadlock detection and recovery
 ## Storage Adapter Implementations
 ### 1. Filesystem Adapter
 ```typescript
 class FilesystemAdapter implements StorageAdapter {
  constructor(private basePath: string) {}
  async get(key: string) {
    const path = this.keyToPath(key)
    return fs.readFile(path, 'json')
  }
  async compareAndSwap(key: string, oldVal: any, newVal: any) {
    // Use file locking for atomicity
    const lockfile = `${this.keyToPath(key)}.lock`
    await flock(lockfile, 'ex')  // Exclusive lock
    try {
      const current = await this.get(key)
      if (deepEqual(current, oldVal)) {
        await this.set(key, newVal)
        return true
      }
      return false
    } finally {
      await funlock(lockfile)
    }
  }
  withNamespace(ns: string) {
    return new FilesystemAdapter(path.join(this.basePath, ns))
  }
 }
 ```
 ### 2. S3 Adapter
 ```typescript
 class S3Adapter implements StorageAdapter {
  constructor(
    private bucket: string,
    private prefix: string = ''
  ) {}
  async get(key: string) {
    const result = await s3.getObject({
      Bucket: this.bucket,
      Key: `${this.prefix}${key}`
    })
    return JSON.parse(result.Body)
  }
  async compareAndSwap(key: string, oldVal: any, newVal: any) {
    // Use S3's conditional writes
    const fullKey = `${this.prefix}${key}`
    // Get current version
    const head = await s3.headObject({
      Bucket: this.bucket,
      Key: fullKey
    })
    // Conditional put with ETag
    try {
      await s3.putObject({
        Bucket: this.bucket,
        Key: fullKey,
        Body: JSON.stringify(newVal),
        IfMatch: head.ETag  // Only succeeds if unchanged
      })
      return true
    } catch (err) {
      if (err.code === 'PreconditionFailed') {
        return false
      }
      throw err
    }
  }
  withNamespace(ns: string) {
    const newPrefix = `${this.prefix}${ns}/`
    return new S3Adapter(this.bucket, newPrefix)
  }
 }
 ```
 ### 3. Cloudflare R2 Adapter
 ```typescript
 class R2Adapter implements StorageAdapter {
  // Similar to S3 but with R2-specific optimizations
  async compareAndSwap(key: string, oldVal: any, newVal: any) {
    // R2 supports conditional headers
    const response = await fetch(`${this.endpoint}/${key}`, {
      method: 'PUT',
      body: JSON.stringify(newVal),
      headers: {
        'If-Match': await this.getETag(key)
      }
    })
    return response.ok
  }
  // R2-specific: Use Workers for edge computing
  async getWithCache(key: string) {
    // Check Cloudflare edge cache first
    const cached = await caches.default.match(key)
    if (cached) return cached.json()
    // Fallback to R2
    const value = await this.get(key)
    // Cache at edge
    await caches.default.put(key, new Response(JSON.stringify(value)))
    return value
  }
 }
 ```
 ## Distributed Coordination Patterns
 ### Pattern 1: Leader-Based Coordination
 ```typescript
 class LeaderCoordinator {
  async acquireShardOwnership(shardId: string) {
    if (!this.isLeader()) {
      // Only leader assigns shards
      return this.requestFromLeader('acquireShard', shardId)
    }
    // Leader logic
    const shardMap = await this.storage.get('_cluster/shard-map')
    if (!shardMap[shardId].owner) {
      shardMap[shardId].owner = this.nodeId
      // Atomic update
      const success = await this.storage.compareAndSwap(
        '_cluster/shard-map',
        shardMap,
        { ...shardMap, [shardId]: { owner: this.nodeId } }
      )
      if (success) {
        this.broadcast('shardAssigned', { shardId, owner: this.nodeId })
      }
    }
  }
 }
 ```
 ### Pattern 2: Consensus-Based Coordination
 ```typescript
 class ConsensusCoordinator {
  async acquireShardOwnership(shardId: string) {
    // Propose to all nodes
    const proposal = {
      type: 'ACQUIRE_SHARD',
      shardId,
      nodeId: this.nodeId,
      term: this.currentTerm
    }
    // Raft consensus
    const votes = await this.gatherVotes(proposal)
    if (votes.length > this.nodes.length / 2) {
      // Majority agreed
      await this.commitProposal(proposal)
      return true
    }
    return false
  }
 }
 ```
 ### Pattern 3: Storage-Native Coordination
 ```typescript
 class StorageNativeCoordinator {
  async acquireShardOwnership(shardId: string) {
    // Use storage adapter's native coordination
    const lockKey = `_locks/shard-${shardId}`
    const lease = {
      owner: this.nodeId,
      expires: Date.now() + 30000  // 30 second lease
    }
    // Try to acquire lock atomically
    const acquired = await this.storage.compareAndSwap(
      lockKey,
      null,  // Must not exist
      lease
    )
    if (acquired) {
      // Start lease renewal
      this.startLeaseRenewal(lockKey, lease)
      return true
    }
    return false
  }
  private startLeaseRenewal(key: string, lease: any) {
    setInterval(async () => {
      const renewed = await this.storage.compareAndSwap(
        key,
        lease,
        { ...lease, expires: Date.now() + 30000 }
      )
      if (!renewed) {
        // Lost lease
        this.handleLeaseLoss(key)
      }
    }, 10000)  // Renew every 10s
  }
 }
 ```
 ## Multi-Storage Patterns
 ### Hybrid Storage (Hot/Cold)
 ```typescript
 class HybridStorageAdapter implements StorageAdapter {
  constructor(
    private hot: StorageAdapter,   // Fast SSD
    private cold: StorageAdapter   // Cheap S3
  ) {}
  async get(key: string) {
    // Try hot storage first
    const hotValue = await this.hot.get(key).catch(() => null)
    if (hotValue) {
      this.updateAccessTime(key)
      return hotValue
    }
    // Fallback to cold storage
    const coldValue = await this.cold.get(key)
    // Promote to hot storage if frequently accessed
    if (this.shouldPromote(key)) {
      await this.hot.set(key, coldValue)
    }
    return coldValue
  }
  async set(key: string, value: any) {
    // Write to hot storage
    await this.hot.set(key, value)
    // Async write to cold storage
    setImmediate(() => {
      this.cold.set(key, value).catch(console.error)
    })
  }
  // Background process to demote cold data
  async runTiering() {
    const hotKeys = await this.hot.listKeys()
    for (const key of hotKeys) {
      const lastAccess = await this.getAccessTime(key)
      if (Date.now() - lastAccess > 7 * 24 * 60 * 60 * 1000) {
        // Not accessed in 7 days, demote to cold
        await this.cold.set(key, await this.hot.get(key))
        await this.hot.delete(key)
      }
    }
  }
 }
 ```
 ### Geo-Distributed Storage
 ```typescript
 class GeoDistributedAdapter implements StorageAdapter {
  constructor(
    private regions: Map<string, StorageAdapter>
  ) {}
  async get(key: string) {
    // Determine closest region
    const region = await this.getClosestRegion()
    // Try local region first
    const localValue = await this.regions.get(region)
      .get(key)
      .catch(() => null)
    if (localValue) return localValue
    // Fallback to other regions
    for (const [name, adapter] of this.regions) {
      if (name !== region) {
        const value = await adapter.get(key).catch(() => null)
        if (value) {
          // Replicate to local region for next time
          this.regions.get(region).set(key, value)
          return value
        }
      }
    }
    throw new Error('Key not found in any region')
  }
  async set(key: string, value: any) {
    // Write to local region immediately
    const region = await this.getClosestRegion()
    await this.regions.get(region).set(key, value)
    // Async replication to other regions
    for (const [name, adapter] of this.regions) {
      if (name !== region) {
        adapter.set(key, value).catch(console.error)
      }
    }
  }
 }
 ```
 ## Storage Optimization Strategies
 ### 1. Write Batching
 ```typescript
 class BatchingAdapter implements StorageAdapter {
  private writeBatch = new Map()
  private batchTimer?: NodeJS.Timeout
  async set(key: string, value: any) {
    this.writeBatch.set(key, value)
    if (!this.batchTimer) {
      this.batchTimer = setTimeout(() => this.flush(), 100)
    }
    if (this.writeBatch.size >= 1000) {
      await this.flush()
    }
  }
  private async flush() {
    if (this.writeBatch.size === 0) return
    const batch = new Map(this.writeBatch)
    this.writeBatch.clear()
    await this.underlying.setBatch(batch)
    if (this.batchTimer) {
      clearTimeout(this.batchTimer)
      this.batchTimer = undefined
    }
  }
 }
 ```
 ### 2. Read Caching
 ```typescript
 class CachingAdapter implements StorageAdapter {
  private cache = new LRU({ max: 10000 })
  async get(key: string) {
    // Check cache
    if (this.cache.has(key)) {
      return this.cache.get(key)
    }
    // Read from storage
    const value = await this.underlying.get(key)
    // Cache for next time
    this.cache.set(key, value)
    return value
  }
  async set(key: string, value: any) {
    // Invalidate cache
    this.cache.delete(key)
    // Write through
    await this.underlying.set(key, value)
  }
 }
 ```
 ### 3. Compression
 ```typescript
 class CompressingAdapter implements StorageAdapter {
  async set(key: string, value: any) {
    const json = JSON.stringify(value)
    // Compress if beneficial
    if (json.length > 1024) {
      const compressed = await gzip(json)
      await this.underlying.set(key, {
        _compressed: true,
        data: compressed.toString('base64')
      })
    } else {
      await this.underlying.set(key, value)
    }
  }
  async get(key: string) {
    const stored = await this.underlying.get(key)
    if (stored._compressed) {
      const compressed = Buffer.from(stored.data, 'base64')
      const json = await gunzip(compressed)
      return JSON.parse(json)
    }
    return stored
  }
 }
 ```
 ## Summary
 Brainy's storage layer is designed for:
 1. **Flexibility**: Works with any storage backend
 2. **Coordination**: Multiple strategies for different needs
 3. **Performance**: Batching, caching, compression
 4. **Scalability**: From single file to geo-distributed
 5. **Simplicity**: Complexity hidden behind simple interface
 The key insight: **Storage is just a plugin**. The intelligence is in the coordination layer above it!
 ---
 *For user-facing documentation, see [SCALING.md](../SCALING.md)*
--- a/docs/architecture/index-architecture.md
+++ b/docs/architecture/index-architecture.md
@ -10,14 +10,14 @@ Brainy has **3 main indexes** at the top level, each with multiple sub-indexes m
 | Index | Purpose | Data Structure | Complexity | File Location | rebuild() Method |
 |-------|---------|----------------|------------|---------------|------------------|
-| **TypeAwareHNSWIndex** | Type-aware vector similarity search | 42 type-specific HNSW hierarchical graphs | O(log n) search | `src/hnsw/typeAwareHNSWIndex.ts` | ✅ Line 403 |
+| **TypeAwareVectorIndex** | Type-aware vector similarity search | 42 type-specific hierarchical graphs | O(log n) search | `src/hnsw/typeAwareHNSWIndex.ts` | ✅ Line 403 |
 | **MetadataIndexManager** | Fast metadata filtering | Chunked sparse indices with bloom filters + zone maps + roaring bitmaps | O(1) exact, O(log n) ranges | `src/utils/metadataIndex.ts` | ✅ Line 2318 |
 | **GraphAdjacencyIndex** | Relationship traversal | 4 LSM-trees + bidirectional adjacency maps | O(1) per hop | `src/graph/graphAdjacencyIndex.ts` | ✅ Line 389 |
 ### Sub-Indexes (Level 2)
-**TypeAwareHNSWIndex contains:**
+**TypeAwareVectorIndex contains:**
- **42 type-specific HNSW indexes** - One per NounType (automatically rebuilt via parent)
+- **42 type-specific vector indexes** - One per NounType (automatically rebuilt via parent)
 **MetadataIndexManager contains:**
 - **ChunkManager** - Adaptive chunked sparse indexing
@ -398,14 +398,16 @@ const DEFAULT_EXCLUDE_FIELDS = [
 **Note**: Timestamp fields like `modified`, `accessed`, `created` are NO LONGER excluded as of they are indexed with automatic bucketing.
-## 2. HNSWIndex - Vector Similarity Search
+## 2. Vector Index - Vector Similarity Search
 **Purpose**: O(log n) semantic similarity search using vector embeddings.
 The default JS implementation is `JsHnswVectorIndex`; an optional native acceleration package (`@soulcraft/cortex`) can register a higher-performing `VectorIndexProvider` through the plugin system. The public API stays the same either way.
 ### Internal Architecture
 ```typescript
-class HNSWIndex {
+class JsHnswVectorIndex {
  // Per-noun indexes for efficiency
  private nouns: Map<string, HNSWNoun> = new Map()
@ -437,7 +439,7 @@ class HNSWNode {
 ### Hierarchical Graph Structure
-HNSW builds a multi-layered graph:
+The default vector index builds a multi-layered graph:
 ```
 Layer 2: [entry] ←→ [node1]                    (sparse, long-range connections)
@ -603,7 +605,7 @@ class UnifiedCache {
 // Each index gets the same cache instance
 const unifiedCache = new UnifiedCache({ maxSize: 1000 })
 this.metadataIndex = new MetadataIndexManager(storage, { unifiedCache })
-this.hnswIndex = new HNSWIndex(storage, { unifiedCache })
+this.vectorIndex = new JsHnswVectorIndex(storage, { unifiedCache })
 this.graphIndex = new GraphAdjacencyIndex(storage, { unifiedCache })
 ```
@ -623,7 +625,7 @@ Each index uses different key prefixes:
 // Metadata index
 cache.set(`meta:${field}:${value}`, indexEntry)
-// HNSW index
+// Vector index
 cache.set(`vector:${id}`, vectorData)
 // Graph index
@ -645,7 +647,7 @@ async add(params: AddParams): Promise<string> {
  // Add to metadata index (field filtering)
  await this.metadataIndex.addToIndex(id, params.metadata)
-  // Add to HNSW index (vector search)
+  // Add to vector index (vector search)
  await this.index.addEntity(id, vector, params.noun)
  // Relationships added via separate relate() calls
@ -700,7 +702,7 @@ async update(params: UpdateParams): Promise<void> {
  await this.metadataIndex.removeFromIndex(params.id, existing.metadata)
  await this.metadataIndex.addToIndex(params.id, params.metadata)
-  // Update HNSW index (re-embed if content changed)
+  // Update vector index (re-embed if content changed)
  if (params.content) {
    const newVector = await this.embedder(params.content)
    await this.index.updateEntity(params.id, newVector)
@ -729,7 +731,7 @@ async stats(): Promise<Statistics> {
    // From deleted items index
    deletedItems: this.deletedItemsIndex.getDeletedCount(),
-    // From HNSW index
+    // From vector index
    vectorIndexSize: this.index.getSize()
  }
 }
@ -746,16 +748,16 @@ async stats(): Promise<Statistics> {
 async init(): Promise<void> {
  // When disableAutoRebuild: false (default)
  const metadataStats = await this.metadataIndex.getStats()
-  const hnswIndexSize = this.index.size()
+  const vectorIndexSize = this.index.size()
  const graphIndexSize = await this.graphIndex.size()
  if (metadataStats.totalEntries === 0 ||
-      hnswIndexSize === 0 ||
+      vectorIndexSize === 0 ||
      graphIndexSize === 0) {
    // Rebuild all indexes in parallel
    await Promise.all([
      metadataStats.totalEntries === 0 ? this.metadataIndex.rebuild() : Promise.resolve(),
-      hnswIndexSize === 0 ? this.index.rebuild() : Promise.resolve(),
+      vectorIndexSize === 0 ? this.index.rebuild() : Promise.resolve(),
      graphIndexSize === 0 ? this.graphIndex.rebuild() : Promise.resolve()
    ])
  }
@ -795,7 +797,7 @@ The **TripleIntelligenceSystem** (`src/triple/TripleIntelligenceSystem.ts`) comb
 class TripleIntelligenceSystem {
  constructor(
    private metadataIndex: MetadataIndexManager,
-    private hnswIndex: HNSWIndex,
+    private vectorIndex: VectorIndexProvider,
    private graphIndex: GraphAdjacencyIndex,
    private embedder: EmbedderFunction,
    private storage: BaseStorage
@ -808,7 +810,7 @@ class TripleIntelligenceSystem {
    // Execute across all three indexes
    const [metadataResults, vectorResults, graphResults] = await Promise.all([
      this.metadataIndex.getIdsForFilter(parsed.filters),
-      this.hnswIndex.search(parsed.vector, parsed.limit),
+      this.vectorIndex.search(parsed.vector, parsed.limit),
      this.graphIndex.traverse(parsed.graphConstraints)
    ])
@ -822,7 +824,7 @@ class TripleIntelligenceSystem {
 ### Operation Complexity by Index
-| Operation | MetadataIndexManager | TypeAwareHNSWIndex | GraphAdjacencyIndex |
+| Operation | MetadataIndexManager | TypeAwareVectorIndex | GraphAdjacencyIndex |
 |-----------|---------------------|-------------------|---------------------|
 | **Add** | O(1) per field | O(log n) | O(1) |
 | **Remove** | O(1) per field | O(log n) | O(1) |
@ -837,14 +839,14 @@ Where:
 - n = total number of entities
 - k = number of matching results
-**Note**: All 3 main indexes have rebuild() methods that load persisted data (O(n)) rather than recomputing (which would be O(n log n) for HNSW).
+**Note**: All 3 main indexes have rebuild() methods that load persisted data (O(n)) rather than recomputing (which would be O(n log n) for the vector index).
 ### Memory Footprint
 | Index | Per-Entity Memory | Notes |
 |-------|-------------------|-------|
 | **MetadataIndexManager** | ~100 bytes | Depends on field count and cardinality (RoaringBitmap32 compression) |
-| **TypeAwareHNSWIndex** | ~1.5 KB | Vector (384 dims × 4 bytes) + graph connections across 42 type-specific indexes |
+| **TypeAwareVectorIndex** | ~1.5 KB | Vector (384 dims × 4 bytes) + graph connections across 42 type-specific indexes |
 | **GraphAdjacencyIndex** | ~50 bytes per relationship | Bidirectional references + metadata in 4 LSM-trees |
 **Total overhead**: ~1.6 KB per entity + ~50 bytes per relationship
@ -868,7 +870,7 @@ All indexes scale gracefully:
 **Key observations**:
 - Graph queries stay O(1) regardless of scale
 - Metadata filtering scales sub-linearly
- Vector search degrades gracefully due to HNSW
+- Vector search degrades gracefully due to the hierarchical index
 - Combined queries remain fast even at scale
 ## Best Practices
@ -881,7 +883,7 @@ All indexes scale gracefully:
 - Field discovery (what filters are available)
 - Type-based querying (find all characters, all items)
-**HNSWIndex**:
+**Vector Index**:
 - Semantic similarity search ("find similar documents")
 - Content-based retrieval ("find posts about AI")
 - Fuzzy matching (when exact matches aren't required)
@ -906,9 +908,9 @@ All indexes scale gracefully:
 ### Memory Management
 1. **Configure UnifiedCache appropriately** - Balance between speed and memory
-2. **Use lazy loading** - HNSW loads vectors on-demand
+2. **Use lazy loading** - Vector index loads vectors on-demand
 3. **Monitor cache hit rates** - Adjust cache size if hit rate is low
-4. **Consider storage adapter** - Memory storage = fastest, S3 = most scalable
+4. **Consider storage adapter** - Memory = fastest, filesystem = persistent
 ## Related Documentation
@ -922,13 +924,13 @@ All indexes scale gracefully:
 ### Level 1: Main Indexes (3)
 All have rebuild() methods and are covered by lazy loading:
-1. **TypeAwareHNSWIndex** - `src/hnsw/typeAwareHNSWIndex.ts:403`
+1. **TypeAwareVectorIndex** - `src/hnsw/typeAwareHNSWIndex.ts:403`
 2. **MetadataIndexManager** - `src/utils/metadataIndex.ts:2318`
 3. **GraphAdjacencyIndex** - `src/graph/graphAdjacencyIndex.ts:389`
 ### Level 2: Sub-Indexes (~50+)
 Automatically managed by parent rebuild():
- **42 type-specific HNSW indexes** (one per NounType)
+- **42 type-specific vector indexes** (one per NounType)
 - **6 metadata components** (ChunkManager, EntityIdMapper, FieldTypeInference, Field Sparse Indexes, Sorted Indexes)
 - **4 LSM-trees** (lsmTreeSource, lsmTreeTarget, lsmTreeVerbsBySource, lsmTreeVerbsByTarget)
 - **In-memory graph structures** (sourceIndex, targetIndex, verbIndex)
--- a/docs/architecture/initialization-and-rebuild.md
+++ b/docs/architecture/initialization-and-rebuild.md
@ -1,6 +1,6 @@
 # Initialization and Rebuild Processes
-This document explains how Brainy's four indexes (MetadataIndex, HNSWIndex, GraphAdjacencyIndex, DeletedItemsIndex) initialize and rebuild from persisted storage.
+This document explains how Brainy's four indexes (MetadataIndex, vector index, GraphAdjacencyIndex, DeletedItemsIndex) initialize and rebuild from persisted storage.
 ## Core Principle: All Indexes Are Disk-Based
@ -11,7 +11,7 @@ This document explains how Brainy's four indexes (MetadataIndex, HNSWIndex, Grap
 | Index | Persisted Data | Storage Method | Since Version |
 |-------|---------------|----------------|---------------|
 | **MetadataIndex** | Field registry + chunked sparse indices with bloom filters + zone maps | `storage.saveMetadata()` | v3.42.0 (chunks), v4.2.1 (registry) |
-| **HNSWIndex** | Vector embeddings + HNSW graph connections | `storage.saveHNSWData()` + `storage.saveHNSWSystem()` | v3.35.0 |
+| **Vector Index** | Vector embeddings + graph connections | `storage.saveHNSWData()` + `storage.saveHNSWSystem()` | v3.35.0 |
 | **GraphAdjacencyIndex** | Relationships via LSM-tree SSTables | LSM-tree auto-persistence | v3.44.0 |
 | **DeletedItemsIndex** | Set of deleted IDs | `storage.saveDeletedItems()` | v3.0.0 |
@ -32,7 +32,7 @@ The MetadataIndex now persists two components:
   - Roaring bitmaps for compressed entity ID storage
   - Loaded on-demand based on query patterns
-All storage operations use the **StorageAdapter** interface, which works with FileSystem, OPFS, S3, GCS, R2, and Memory backends.
+All storage operations use the **StorageAdapter** interface, which works with FileSystem and Memory backends.
 ## Initialization Process
@ -84,12 +84,12 @@ async init(): Promise<void> {
  // STEP 2: Check index sizes (lazy initialization triggers here)
  const metadataStats = await this.metadataIndex.getStats()
-  const hnswIndexSize = this.index.size()
+  const vectorIndexSize = this.index.size()
  const graphIndexSize = await this.graphIndex.size()
  // STEP 3: Rebuild empty indexes from storage in parallel
  if (metadataStats.totalEntries === 0 ||
-      hnswIndexSize === 0 ||
+      vectorIndexSize === 0 ||
      graphIndexSize === 0) {
    const rebuildStartTime = Date.now()
@ -97,7 +97,7 @@ async init(): Promise<void> {
      metadataStats.totalEntries === 0
        ? this.metadataIndex.rebuild()
        : Promise.resolve(),
-      hnswIndexSize === 0
+      vectorIndexSize === 0
        ? this.index.rebuild()
        : Promise.resolve(),
      graphIndexSize === 0
@ -207,13 +207,13 @@ private async ensureIndexesLoaded(): Promise<void> {
 ### What "Rebuild" Actually Means
 **IMPORTANT**: "Rebuild" does NOT mean recomputing data. It means:
-1. **Load persisted data** from storage (HNSW connections, metadata chunks, LSM-tree SSTables)
+1. **Load persisted data** from storage (vector index connections, metadata chunks, LSM-tree SSTables)
 2. **Populate in-memory structures** (Maps, Sets, graphs)
 3. **Apply adaptive caching** (preload vectors if small dataset, lazy load if large)
 **Complexity**: O(N) - linear scan through storage, NOT O(N log N) recomputation!
-### 1. HNSWIndex Rebuild (Correct Pattern)
+### 1. Vector Index Rebuild (Correct Pattern)
 ```typescript
 // src/hnsw/hnswIndex.ts (lines 809-947)
@ -236,7 +236,7 @@ public async rebuild(options: {
  const availableCache = this.unifiedCache.getRemainingCapacity()
  const shouldPreload = vectorMemory < availableCache * 0.3
-  // STEP 4: Load entities with persisted HNSW connections
+  // STEP 4: Load entities with persisted vector index connections
  let hasMore = true
  let cursor: string | undefined = undefined
@ -246,7 +246,7 @@ public async rebuild(options: {
    })
    for (const nounData of result.items) {
-      // Load HNSW graph data from storage (NOT recomputed!)
+      // Load vector graph data from storage (NOT recomputed!)
      const hnswData = await this.storage.getHNSWData(nounData.id)
      // Create noun with restored connections
@ -274,14 +274,14 @@ public async rebuild(options: {
 ```
 **Key Points**:
- ✅ Loads HNSW connections from storage via `getHNSWData()`
+- ✅ Loads vector index connections from storage via `getHNSWData()`
 - ✅ Uses adaptive caching (preload vectors if < 30% of available cache)
 - ✅ O(N) complexity - just loads existing data
 - ❌ Does NOT call `addItem()` which would recompute connections (O(N log N))
-### 2. TypeAwareHNSWIndex Rebuild (Fixed in v3.45.0)
+### 2. TypeAwareVectorIndex Rebuild (Fixed in v3.45.0)
-**Critical Architectural Fix**: TypeAwareHNSWIndex previously had TWO major bugs:
+**Critical Architectural Fix**: The type-aware vector index previously had TWO major bugs:
 1. **Bug #1**: Called `addItem()` during rebuild → O(N log N) recomputation instead of O(N) loading
 2. **Bug #2**: Loaded ALL nouns 31 times in parallel (once per type) → O(31*N) complexity causing timeouts
@ -300,7 +300,7 @@ public async rebuild(options?: {
    index.clear()
  }
-  // STEP 2: Determine preloading strategy (same as HNSWIndex)
+  // STEP 2: Determine preloading strategy (same as vector index)
  const totalNouns = await this.storage.getNounCount()
  const vectorMemory = totalNouns * 384 * 4
  const availableCache = this.unifiedCache.getRemainingCapacity()
@ -319,7 +319,7 @@ public async rebuild(options?: {
      })
      for (const nounData of result.items) {
-        // CORRECT: Load persisted HNSW data (not recomputed!)
+        // CORRECT: Load persisted vector index data (not recomputed!)
        const hnswData = await this.storage.getHNSWData(nounData.id)
        const noun = {
@ -533,7 +533,7 @@ const unifiedCache = getGlobalCache()  // Singleton, 100MB default
 // MetadataIndex
 this.unifiedCache = unifiedCache
-// HNSWIndex
+// Vector index
 this.unifiedCache = unifiedCache
 // GraphAdjacencyIndex
@ -549,7 +549,7 @@ this.unifiedCache = unifiedCache
 ### Rebuild Times (Typical Hardware)
-| Dataset Size | Metadata | HNSW | Graph | Total (Parallel) |
+| Dataset Size | Metadata | Vector | Graph | Total (Parallel) |
 |--------------|----------|------|-------|------------------|
 | 1K entities | 50ms | 100ms | 30ms | **150ms** |
 | 10K entities | 200ms | 500ms | 150ms | **600ms** |
@ -563,7 +563,7 @@ this.unifiedCache = unifiedCache
 | Index | In-Memory Overhead | Disk Storage |
 |-------|-------------------|--------------|
 | **MetadataIndex** | ~100 bytes/entity | ~500 bytes/entity (chunks) |
-| **HNSWIndex** | ~200 bytes/entity (no vectors) | ~1.5 KB/entity (vectors + connections) |
+| **Vector Index** | ~200 bytes/entity (no vectors) | ~1.5 KB/entity (vectors + connections) |
 | **GraphAdjacencyIndex** | ~128 bytes/relationship | ~200 bytes/relationship (LSM-tree) |
 | **DeletedItemsIndex** | ~40 bytes/deleted ID | ~50 bytes/deleted ID |
@ -573,9 +573,9 @@ this.unifiedCache = unifiedCache
 ### O(N) vs O(N log N) Comparison
-**Before fix** (TypeAwareHNSWIndex bug):
+**Before fix** (TypeAwareVectorIndex bug):
 ```typescript
-// BAD: Recomputes HNSW connections during rebuild
+// BAD: Recomputes vector index connections during rebuild
 for (const noun of nouns) {
  await index.addItem(noun)  // O(log N) per item → O(N log N) total
 }
@ -652,7 +652,7 @@ console.timeEnd('rebuild')
 // For 10K entities:
 // - Expected: 500-800ms (loading from storage)
-// - Bug: 5-10 minutes (recomputing HNSW connections)
+// - Bug: 5-10 minutes (recomputing vector index connections)
 ```
 **Solution**: Ensure index is loading from storage, not calling `addItem()` during rebuild.
@ -706,8 +706,8 @@ console.log('Nouns in storage:', nouns.items.length)
 ## Version History
 - **v5.7.7** (November 2025): Added production-scale lazy loading with `ensureIndexesLoaded()` helper. Fixed critical bug where `disableAutoRebuild: true` left indexes empty forever. Added concurrency control (mutex) to prevent duplicate rebuilds from concurrent queries. Added `getIndexStatus()` diagnostic method. Zero-config operation - works automatically.
- **v3.45.0** (October 2025): Fixed TypeAwareHNSWIndex.rebuild() to load from storage instead of recomputing. Removed all snapshot code (unnecessary with correct rebuild pattern). 200-600x speedup.
+- **v3.45.0** (October 2025): Fixed type-aware vector index `rebuild()` to load from storage instead of recomputing. Removed all snapshot code (unnecessary with correct rebuild pattern). 200-600x speedup.
 - **v3.44.0** (October 2025): GraphAdjacencyIndex migrated to LSM-tree storage for billion-scale relationships
 - **v3.42.0** (October 2025): MetadataIndex migrated to chunked sparse indexing
- **v3.35.0** (August 2025): HNSW connections first persisted to storage
+- **v3.35.0** (August 2025): Vector index connections first persisted to storage
 - **v3.0.0** (September 2025): Initial 3-tier index architecture
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@ -6,14 +6,14 @@ Brainy is a multi-dimensional AI database that combines vector similarity, graph
 ### Brainy (Main Entry Point)
 The central orchestrator that manages all subsystems:
- **4-Index Architecture**: MetadataIndex, HNSWIndex, GraphAdjacencyIndex, DeletedItemsIndex (see [Index Architecture](./index-architecture.md))
+- **4-Index Architecture**: MetadataIndex, vector index, GraphAdjacencyIndex, DeletedItemsIndex (see [Index Architecture](./index-architecture.md))
- **Storage System**: Universal storage adapters (FileSystem, S3, OPFS, Memory)
+- **Storage System**: FileSystem and Memory adapters
 - **Augmentation System**: Extensible plugin architecture
 - **Triple Intelligence**: Unified query engine
 ### Triple Intelligence Engine
 Brainy's revolutionary feature that unifies three types of search:
- **Vector Search**: Semantic similarity using HNSW indexing
+- **Vector Search**: Semantic similarity via the pluggable vector index
 - **Graph Traversal**: Relationship-based queries
 - **Field Filtering**: Precise metadata filtering with O(1) performance
@ -42,12 +42,13 @@ brainy-data/
 └── locks/            # Concurrent access control
 ```
-### HNSW Index
+### Vector Index
-Hierarchical Navigable Small World index for efficient vector search:
+Pluggable vector index (`VectorIndexProvider`) for efficient nearest-neighbor search. The default JS implementation, `JsHnswVectorIndex`, uses a hierarchical graph:
 - **Performance**: O(log n) search complexity
- **Memory Efficient**: Product quantization support
+- **Memory Efficient**: SQ4/SQ8 scalar quantization support
- **Scalable**: Handles millions of vectors
+- **Scalable**: Handles millions of vectors per process
 - **Persistent**: Serializable to storage
 - **Swappable**: Replace with a native implementation (such as `@soulcraft/cortex`) via the plugin system without changing application code
 ### Metadata Index Manager
 High-performance field indexing system:
@ -59,7 +60,7 @@ High-performance field indexing system:
 ## Performance Characteristics
 ### Operation Complexity
- **Vector Search**: O(log n) via HNSW
+- **Vector Search**: O(log n) via the vector index
 - **Field Filtering**: O(1) via inverted indexes
 - **Graph Traversal**: O(V + E) for breadth-first search
 - **Add Operation**: O(log n) for index insertion
@ -83,7 +84,6 @@ Brainy's extensible plugin architecture allows for powerful enhancements:
 ### Core Augmentations
 - **Entity Registry**: High-speed deduplication for streaming data
 - **Batch Processing**: Optimized bulk operations
 - **Connection Pool**: Efficient resource management
 - **Request Deduplicator**: Prevents duplicate processing
 ### Creating Custom Augmentations
@ -111,7 +111,7 @@ Multi-layered caching for optimal performance:
 ## Integration Points
 ### Key Objects for Extensions
- `brain.index`: Access HNSW vector index
+- `brain.index`: Access the vector index
 - `brain.metadataIndex`: Access field indexing
 - `brain.graphIndex`: Access graph adjacency index
 - `brain.storage`: Access storage layer
--- a/docs/architecture/storage-architecture.md
+++ b/docs/architecture/storage-architecture.md
@ -1,46 +1,46 @@
 # Storage Architecture
-> **Updated**: Metadata/vector separation, UUID-based sharding, lifecycle management
+> **Updated**: Metadata/vector separation, UUID-based sharding, on-disk artifact for operator-layer backup
 ## Storage Structure
 ### Architecture: Metadata/Vector Separation
-entities and relationships are split into **2 separate files** for optimal performance at billion-entity scale:
+Entities and relationships are split into **2 separate files** for optimal performance at billion-entity scale:
 ```
 brainy-data/
-├── _system/ # System metadata (not sharded)
+├── _system/                              # System metadata (not sharded)
-│ ├── statistics.json # Performance metrics
+│   ├── statistics.json                   # Performance metrics
-│ ├── __metadata_field_index__*.json # Field indexes
+│   ├── __metadata_field_index__*.json    # Field indexes
-│ └── __metadata_sorted_index__*.json # Sorted indexes
+│   └── __metadata_sorted_index__*.json   # Sorted indexes
 │
 ├── entities/
-│ ├── nouns/
+│   ├── nouns/
-│ │ ├── vectors/ # HNSW graph data (sharded by UUID)
+│   │   ├── vectors/                      # Vector graph data (sharded by UUID)
-│ │ │ ├── 00/ # Shard 00 (first 2 hex digits)
+│   │   │   ├── 00/                       # Shard 00 (first 2 hex digits)
-│ │ │ │ ├── 00123456-....json # Vector + HNSW connections
+│   │   │   │   ├── 00123456-....json     # Vector + graph connections
-│ │ │ │ └── 00abcdef-....json
+│   │   │   │   └── 00abcdef-....json
-│ │ │ ├── 01/ ... ff/ # 256 shards total
+│   │   │   ├── 01/ ... ff/               # 256 shards total
-│ │ │
+│   │   │
-│ │ └── metadata/ # Business data (sharded by UUID)
+│   │   └── metadata/                     # Business data (sharded by UUID)
-│ │ ├── 00/
+│   │       ├── 00/
-│ │ │ ├── 00123456-....json # Entity metadata only
+│   │       │   ├── 00123456-....json     # Entity metadata only
-│ │ │ └── 00abcdef-....json
+│   │       │   └── 00abcdef-....json
-│ │ ├── 01/ ... ff/
+│   │       ├── 01/ ... ff/
-│ │
+│   │
-│ └── verbs/
+│   └── verbs/
-│ ├── vectors/ # Relationship vectors (sharded)
+│       ├── vectors/                      # Relationship vectors (sharded)
-│ │ ├── 00/ ... ff/
+│       │   ├── 00/ ... ff/
-│ │
+│       │
-│ └── metadata/ # Relationship data (sharded)
+│       └── metadata/                     # Relationship data (sharded)
-│ ├── 00/ ... ff/
+│           ├── 00/ ... ff/
 ```
 ### Why Split Metadata and Vectors?
 **Performance at scale:**
- **HNSW operations**: Only load vectors (4KB) during search, not metadata (2-10KB)
+- **Vector search operations**: Only load vectors (4KB) during search, not metadata (2-10KB)
 - **Filtering**: Only load metadata during filtering, not vectors
 - **Pagination**: Load metadata IDs first, fetch vectors/metadata on-demand
 - **Result**: 60-70% reduction in I/O for typical queries at million-entity scale
@ -52,115 +52,69 @@ brainy-data/
 const uuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
 const shard = uuid.substring(0, 2) // "3f"
-// Vector path: entities/nouns/vectors/3f/3fa85f64-....json
+// Vector path:   entities/nouns/vectors/3f/3fa85f64-....json
 // Metadata path: entities/nouns/metadata/3f/3fa85f64-....json
 ```
 **Benefits:**
 - **Uniform distribution**: ~3,900 entities per shard (at 1M scale)
- **Cloud storage optimization**: 200x faster than unsharded (30s → 150ms)
+- **Filesystem optimization**: avoids huge flat directories that bog down `readdir`
- **Parallel operations**: Load 256 shards in parallel
+- **Parallel operations**: walk 256 shards in parallel
 - **Predictable**: Deterministic shard assignment
 ## Storage Adapters
-Brainy provides multiple storage adapters with identical APIs and production features:
+Brainy 8.0 ships two adapters, both implementing the same `StorageAdapter` interface:
-### FileSystem Storage (Node.js)
+### FileSystem Storage (Node.js, default)
 ```typescript
 const brain = new Brainy({
- storage: {
+  storage: {
- type: 'filesystem',
+    type: 'filesystem',
- path: './data',
+    rootDirectory: './data'
- compression: true // Gzip compression (60-80% space savings)
+  }
 }
 })
 ```
- **Use case**: Server applications, CLI tools
+- **Use case**: Server applications, CLI tools, single-node deployments
- **Performance**: Direct file I/O with optional compression
+- **Performance**: Direct file I/O
 - **Persistence**: Permanent on disk
 - **Features**:
- - **Gzip Compression**: 60-80% storage savings with minimal CPU overhead
+  - **Batch Delete**: Efficient bulk deletion with retries
- - **Batch Delete**: Efficient bulk deletion with retries
+  - **UUID Sharding**: Automatic 256-shard distribution
 - **UUID Sharding**: Automatic 256-shard distribution
-### S3 Compatible Storage (AWS, MinIO, R2)
+### Memory Storage
 ```typescript
 const brain = new Brainy({
- storage: {
+  storage: {
- type: 's3',
+    type: 'memory'
- bucket: 'my-brainy-data',
+  }
 region: 'us-east-1',
 credentials: {
 accessKeyId: process.env.AWS_ACCESS_KEY_ID,
 secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
 }
 }
 })
 ```
- **Use case**: Distributed applications, cloud deployments
+- **Use case**: Tests, ephemeral workloads, single-process caches
- **Performance**: Network dependent, with intelligent caching
+- **Performance**: No I/O — all data lives in process memory
- **Persistence**: Cloud storage durability (99.999999999%)
+- **Persistence**: None — data is lost when the process exits
 - **Features**:
 - **Lifecycle Policies**: Automatic tier transitions (Standard → IA → Glacier → Deep Archive)
 - **Intelligent-Tiering**: Automatic optimization based on access patterns (up to 95% savings)
 - **Batch Delete**: Efficient bulk deletion (1000 objects per request)
 - **Cost Impact**: $138k/year → $5.9k/year at 500TB (96% savings!)
-### Google Cloud Storage (GCS)
+### Auto
 ```typescript
 const brain = new Brainy({
- storage: {
+  storage: {
- type: 'gcs',
+    type: 'auto',
- bucketName: 'my-brainy-data',
+    rootDirectory: './data'
- keyFilename: './service-account.json' // Or use ADC
+  }
 }
 })
 ```
- **Use case**: Google Cloud deployments
+`'auto'` picks `'filesystem'` when running on Node.js with a writable `rootDirectory`, and falls back to `'memory'` otherwise.
 - **Performance**: Global CDN with edge caching
 - **Persistence**: 99.999999999% durability
 - **Features**:
 - **Lifecycle Policies**: Automatic tier transitions (Standard → Nearline → Coldline → Archive)
 - **Autoclass**: Intelligent automatic tier optimization
 - **Batch Delete**: Efficient bulk operations
 - **Cost Impact**: $138k/year → $8.3k/year at 500TB (94% savings!)
-### Azure Blob Storage
+## Backup and Off-Site Replication
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 'azure',
 connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
 containerName: 'brainy-data'
 }
 })
 ```
 - **Use case**: Azure cloud deployments
 - **Performance**: Global replication with CDN
 - **Persistence**: LRS, ZRS, GRS, RA-GRS options
 - **Features**:
 - **Blob Tier Management**: Hot/Cool/Archive tiers (99% cost savings)
 - **Lifecycle Policies**: Automatic tier transitions and deletions
 - **Batch Delete**: BlobBatchClient for efficient bulk operations
 - **Batch Tier Changes**: Move thousands of blobs efficiently
 - **Archive Rehydration**: Smart rehydration with priority options
-### Origin Private File System (Browser)
+Brainy 8.0 does not embed cloud SDKs. The on-disk artifact at `rootDirectory` is a plain directory tree of JSON files, so backup is an operator-layer concern. Typical patterns:
-```typescript
+
-const brain = new Brainy({
+- `gsutil rsync -r ./data gs://my-bucket/brainy-data`
- storage: {
+- `aws s3 sync ./data s3://my-bucket/brainy-data`
- type: 'opfs'
+- `rclone sync ./data remote:brainy-data`
- }
+- Periodic `tar` snapshots to any object store
-})
+
-```
+Run these from your scheduler (cron, systemd timer, k8s CronJob) — Brainy itself only reads and writes the local directory.
 - **Use case**: Browser applications, PWAs
 - **Performance**: Near-native file system speed
 - **Persistence**: Permanent in browser (with quota limits)
 - **Features**:
 - **Quota Monitoring**: Real-time quota tracking and warnings
 - **Batch Delete**: Efficient bulk deletion
 - **Storage Status**: Detailed usage/available reporting
 ## Metadata Indexing System
@ -170,12 +124,12 @@ Tracks all unique values for each field:
 ```json
 // __metadata_field_index__field_category.json
 {
- "values": {
+  "values": {
- "technology": 45,
+    "technology": 45,
- "science": 32,
+    "science": 32,
- "business": 28
+    "business": 28
- },
+  },
- "lastUpdated": 1699564234567
+  "lastUpdated": 1699564234567
 }
 ```
@ -185,11 +139,11 @@ Maps field+value combinations to entity IDs:
 ```json
 // __metadata_index__category_technology_chunk0.json
 {
- "field": "category",
+  "field": "category",
- "value": "technology",
+  "value": "technology",
- "ids": ["uuid1", "uuid2", "uuid3", ...],
+  "ids": ["uuid1", "uuid2", "uuid3", ...],
- "chunk": 0,
+  "chunk": 0,
- "total": 45
+  "total": 45
 }
 ```
@ -207,14 +161,14 @@ High-performance deduplication system for streaming data:
 ```json
 // __entity_registry__.json
 {
- "mappings": {
+  "mappings": {
- "did:plc:alice123": "550e8400-e29b-41d4-a716-446655440000",
+    "did:plc:alice123": "550e8400-e29b-41d4-a716-446655440000",
- "handle:alice.bsky.social": "550e8400-e29b-41d4-a716-446655440000"
+    "handle:alice.bsky.social": "550e8400-e29b-41d4-a716-446655440000"
- },
+  },
- "stats": {
+  "stats": {
- "totalMappings": 10000,
+    "totalMappings": 10000,
- "lastSync": 1699564234567
+    "lastSync": 1699564234567
- }
+  }
 }
 ```
@ -224,216 +178,46 @@ High-performance deduplication system for streaming data:
 - **Cache**: LRU with configurable TTL
 - **Sync**: Periodic or on-demand
 ## Durability
-Ensures durability and enables recovery:
+Brainy persists writes to disk through the filesystem adapter. Each save is a rename-based atomic write of a JSON file under the appropriate shard. Operators that need point-in-time recovery should snapshot `rootDirectory` (see [Backup and Off-Site Replication](#backup-and-off-site-replication)).
 ```json
 {
 "timestamp": 1699564234567,
 "operation": "add",
 "data": {
 "id": "550e8400-e29b-41d4-a716-446655440000",
 "content": "...",
 "metadata": {}
 },
 "checksum": "sha256:..."
 }
 ```
 ### Recovery Process
 2. Replay operations from last checkpoint
 3. Verify checksums for integrity
 ## Storage Optimization
-### 1. Lifecycle Policies (Cloud Storage)
+### 1. Batch Operations
 **Automatic cost optimization through tier transitions:**
 ```typescript
 // S3: Set lifecycle policy for automatic archival
 await storage.setLifecyclePolicy({
 rules: [{
 id: 'archive-old-data',
 prefix: 'entities/',
 status: 'Enabled',
 transitions: [
 { days: 30, storageClass: 'STANDARD_IA' }, // Move to IA after 30 days
 { days: 90, storageClass: 'GLACIER' }, // Archive after 90 days
 { days: 365, storageClass: 'DEEP_ARCHIVE' } // Deep archive after 1 year
 ]
 }]
 })
 // GCS: Set lifecycle policy
 await storage.setLifecyclePolicy({
 rules: [{
 condition: { age: 30 },
 action: { type: 'SetStorageClass', storageClass: 'NEARLINE' }
 }, {
 condition: { age: 90 },
 action: { type: 'SetStorageClass', storageClass: 'COLDLINE' }
 }, {
 condition: { age: 365 },
 action: { type: 'SetStorageClass', storageClass: 'ARCHIVE' }
 }]
 })
 // Azure: Set lifecycle policy
 await storage.setLifecyclePolicy({
 rules: [{
 name: 'archiveOldData',
 enabled: true,
 type: 'Lifecycle',
 definition: {
 filters: { blobTypes: ['blockBlob'] },
 actions: {
 baseBlob: {
 tierToCool: { daysAfterModificationGreaterThan: 30 },
 tierToArchive: { daysAfterModificationGreaterThan: 90 }
 }
 }
 }
 }]
 })
 ```
 **Cost Impact (500TB dataset):**
 | Storage | Before | After | Savings |
 |---------|--------|-------|---------|
 | **AWS S3** | $138,000/yr | $5,940/yr | **96%** |
 | **GCS** | $138,000/yr | $8,300/yr | **94%** |
 | **Azure** | $107,520/yr | $5,016/yr | **95%** |
 ### 2. Intelligent-Tiering (S3)
 **Automatic optimization without retrieval fees:**
 ```typescript
 // Enable S3 Intelligent-Tiering
 await storage.enableIntelligentTiering('entities/', 'auto-optimize')
 // Benefits:
 // - Automatic tier transitions based on access patterns
 // - No retrieval fees (unlike Glacier)
 // - Up to 95% cost savings
 // - No performance impact on frequently accessed data
 ```
 ### 3. Autoclass (GCS)
 **Google Cloud's intelligent automatic optimization:**
 ```typescript
 // Enable GCS Autoclass
 await storage.enableAutoclass({
 terminalStorageClass: 'ARCHIVE' // Optional: Set lowest tier
 })
 // Benefits:
 // - Automatic optimization based on access patterns
 // - No data retrieval delays
 // - Transparent tier transitions
 // - Up to 94% cost savings
 ```
 ### 4. Compression (FileSystem)
 ```typescript
 // Enable gzip compression for local storage
 const brain = new Brainy({
 storage: {
 type: 'filesystem',
 path: './data',
 compression: true // 60-80% space savings
 }
 })
 // Performance impact:
 // - Write: +10-20ms per file (gzip compression)
 // - Read: +5-10ms per file (gzip decompression)
 // - Space savings: 60-80% for typical JSON data
 // - CPU overhead: Minimal (~5% CPU)
 ```
 ### 5. Batch Operations
 ```typescript
 // Efficient batch delete
 await storage.batchDelete([
- 'entities/nouns/vectors/00/00123456-....json',
+  'entities/nouns/vectors/00/00123456-....json',
- 'entities/nouns/metadata/00/00123456-....json',
+  'entities/nouns/metadata/00/00123456-....json'
- // ... up to 1000 objects
+  // ...
 ])
 // Benefits:
 // - S3: 1000 objects per request (vs 1 per request)
 // - GCS: 100 objects per request
 // - Azure: 256 objects per batch
 // - Automatic retry logic with exponential backoff
 // - Throttling protection
 // Batch writes for performance
 await brain.addBatch([
- { content: "item1", metadata: {} },
+  { content: "item1", metadata: {} },
- { content: "item2", metadata: {} },
+  { content: "item2", metadata: {} },
- { content: "item3", metadata: {} }
+  { content: "item3", metadata: {} }
 ])
 // Single transaction, optimized I/O
 ```
-### 6. Quota Monitoring (OPFS)
+### 2. Caching Strategy
 ```typescript
-// Get quota status for browser storage
+// Configure caching
 const status = await storage.getStorageStatus()
 console.log(status)
 // {
 // type: 'opfs',
 // available: true,
 // details: {
 // usage: 45829120, // 43.7 MB used
 // quota: 536870912, // 512 MB available
 // usagePercent: 8.5,
 // quotaExceeded: false
 // }
 // }
 // Proactive quota management:
 // - Monitor usage before writes
 // - Warn users when approaching quota
 // - Automatically clean up old data
 ```
 ### 7. Tier Management (Azure)
 ```typescript
 // Change blob tier for cost optimization
 await storage.changeBlobTier(blobPath, 'Cool') // Hot → Cool (50% savings)
 await storage.changeBlobTier(blobPath, 'Archive') // Cool → Archive (99% savings)
 // Batch tier changes (efficient)
 await storage.batchChangeTier([blob1, blob2, blob3], 'Cool')
 // Rehydrate from Archive when needed
 await storage.rehydrateBlob(blobPath, 'Standard') // Standard or High priority
 ```
 ### 8. Caching Strategy
 ```typescript
 // Configure caching per storage type
 const brain = new Brainy({
- storage: {
+  storage: {
- type: 'filesystem',
+    type: 'filesystem',
- cache: {
+    rootDirectory: './data',
- enabled: true,
+    cache: {
- maxSize: 1000, // Maximum cached items
+      enabled: true,
- ttl: 300000, // 5 minutes
+      maxSize: 1000,   // Maximum cached items
- strategy: 'lru' // Least recently used
+      ttl: 300000,     // 5 minutes
- }
+      strategy: 'lru'  // Least recently used
- }
+    }
  }
 })
 ```
@ -443,8 +227,8 @@ const brain = new Brainy({
 ```typescript
 // Automatic locking for write operations
 await brain.storage.withLock('resource-id', async () => {
- // Exclusive access to resource
+  // Exclusive access to resource
- await brain.storage.saveNoun(id, data)
+  await brain.storage.saveNoun(id, data)
 })
 ```
@ -459,9 +243,9 @@ await brain.storage.withLock('resource-id', async () => {
 ```typescript
 // Export entire database
 const backup = await brain.export({
- format: 'json',
+  format: 'json',
- includeVectors: true,
+  includeVectors: true,
- includeIndexes: false
+  includeIndexes: false
 })
 ```
@ -469,16 +253,16 @@ const backup = await brain.export({
 ```typescript
 // Import from backup
 await brain.import(backup, {
- mode: 'merge', // or 'replace'
+  mode: 'merge',        // or 'replace'
- validateSchema: true
+  validateSchema: true
 })
 ```
 ### Storage Migration
 ```typescript
 // Migrate between storage types
-const oldBrain = new Brainy({ storage: { type: 'filesystem' } })
+const oldBrain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './old' } })
-const newBrain = new Brainy({ storage: { type: 's3' } })
+const newBrain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './new' } })
 await oldBrain.init()
 await newBrain.init()
@ -490,23 +274,11 @@ await newBrain.import(data)
 ## Performance Tuning
-### Storage-Specific Optimizations
+### FileSystem Optimizations
-
+- **Directory sharding**: 256 shards spread files across subdirectories
 #### FileSystem
 - **Directory sharding**: Split files across subdirectories
 - **Async I/O**: Non-blocking file operations
 - **Buffer pooling**: Reuse buffers for efficiency
 #### S3
 - **Multipart uploads**: For large objects
 - **Request batching**: Combine small operations
 - **CDN integration**: Edge caching for reads
 #### OPFS
 - **Quota management**: Monitor and request increases
 - **Worker offloading**: Heavy operations in workers
 - **Transaction batching**: Group operations
 ### Monitoring
 ```typescript
@ -514,58 +286,34 @@ await newBrain.import(data)
 const stats = await brain.storage.getStatistics()
 console.log(stats)
 // {
-// totalSize: 1048576,
+//   totalSize: 1048576,
-// entityCount: 1000,
+//   entityCount: 1000,
-// indexSize: 204800,
+//   indexSize: 204800,
-// walSize: 10240,
+//   walSize: 10240,
-// cacheHitRate: 0.85
+//   cacheHitRate: 0.85
 // }
 ```
 ## Best Practices
 ### Choose the Right Adapter
-1. **Development**: FileSystem with compression (local persistence, small storage footprint)
+1. **Development & tests**: `memory` for speed, `filesystem` when you need persistence
-2. **Production Server**: FileSystem with compression or cloud storage with lifecycle policies
+2. **Single-node production**: `filesystem` with off-site backup via `gsutil` / `aws s3 sync` / `rclone`
-3. **Browser Apps**: OPFS with quota monitoring
+3. **Multi-node production**: Run Brainy behind a service layer; replicate the on-disk artifact via your operator tooling
 4. **Distributed**: S3/GCS/Azure with Intelligent-Tiering/Autoclass
 ### Optimize for Your Use Case
-1. **Read-heavy**: Enable aggressive caching + cloud CDN
+1. **Read-heavy**: Enable caching and let the OS page cache do its job
-2. **Write-heavy**: Batch operations + async writes
+2. **Write-heavy**: Batch operations and tune the cache `maxSize`
 3. **Real-time**: FileSystem with periodic snapshots
-4. **Archival**: Cloud storage with lifecycle policies (96% cost savings!)
+4. **Archival**: Snapshot `rootDirectory` to cold object storage on a schedule
-5. **Large-scale**: Metadata/vector separation + UUID sharding + lifecycle policies
+5. **Large-scale**: Rely on metadata/vector separation + UUID sharding
 ### Cost Optimization
 1. **Enable lifecycle policies** for cloud storage (automated cost reduction)
 2. **Use Intelligent-Tiering (S3)** or Autoclass (GCS) for automatic optimization
 3. **Enable compression** for FileSystem storage (60-80% space savings)
 4. **Monitor quota** for OPFS (prevent quota exceeded errors)
 5. **Use batch operations** for bulk deletions (efficient API usage)
 6. **Consider tier management** for Azure (Hot/Cool/Archive tiers)
 **Example Cost Savings (500TB dataset):**
 - Without lifecycle policies: **$138,000/year**
 - With lifecycle policies: **$5,940/year**
 - **Savings: $132,060/year (96%)**
 ### Monitor and Maintain
 1. Regular statistics collection
-2. Monitor lifecycle policy effectiveness
+2. Watch disk usage and shard balance
 3. Index optimization
 4. Cache tuning based on hit rates
-5. Track storage costs and tier distribution
+5. Verify backup runs (test restore quarterly)
 6. Review quota usage (OPFS) and storage growth patterns
 ### Production Deployment Checklist
 - ✅ Enable lifecycle policies on cloud storage
 - ✅ Configure batch delete for cleanup operations
 - ✅ Enable compression for FileSystem storage
 - ✅ Set up quota monitoring for OPFS
 - ✅ Configure appropriate tier transitions
 - ✅ Enable Intelligent-Tiering (S3) or Autoclass (GCS)
 - ✅ Monitor storage costs and optimize regularly
 ## API Reference
@ -573,6 +321,5 @@ See the [Storage API](../api/storage.md) for complete method documentation.
 ---
-**Version**: 4.0.0
+**Last Updated**: 2026
-**Last Updated**: 2025-10-17
+**Key Features**: Metadata/vector separation, UUID sharding, filesystem-and-memory adapters, operator-layer backup
 **Key Features**: Metadata/vector separation, UUID sharding, lifecycle management, tier optimization
--- a/docs/augmentations/COMPLETE-REFERENCE.md
+++ b/docs/augmentations/COMPLETE-REFERENCE.md
@ -10,10 +10,10 @@
 import { Brainy } from '@soulcraft/brainy'
 const brain = new Brainy({
- // Augmentations auto-configure based on environment
+  // Augmentations auto-configure based on environment
- storage: 'auto', // Storage augmentation
+  storage: { type: 'auto', rootDirectory: './brainy-data' }, // Storage augmentation
- cache: true, // Cache augmentation
+  cache: true, // Cache augmentation
- index: true // Index augmentation
+  index: true // Index augmentation
 })
 await brain.init() // Augmentations initialize automatically
@ -66,77 +66,27 @@ Augmentations are modular extensions that add functionality to Brainy without cl
 ---
-## Storage Augmentations (8 total)
+## Storage Augmentations
 ### MemoryStorageAugmentation
 **Location**: `src/augmentations/storageAugmentations.ts`
-**Auto-enabled**: When `storage: 'memory'` or in test environments
+**Auto-enabled**: When `storage: { type: 'memory' }` or in test environments
 **Purpose**: In-memory storage for testing and temporary data
 ```typescript
-const brain = new Brainy({ storage: 'memory' })
+const brain = new Brainy({ storage: { type: 'memory' } })
 ```
 ### FileSystemStorageAugmentation
 **Location**: `src/augmentations/storageAugmentations.ts`
-**Auto-enabled**: When `storage: 'filesystem'` or Node.js detected
+**Auto-enabled**: When `storage: { type: 'filesystem' }` or Node.js detected
 **Purpose**: Persistent file-based storage for Node.js applications
 ```typescript
 const brain = new Brainy({
- storage: { type: 'filesystem', path: './data' }
+  storage: { type: 'filesystem', rootDirectory: './data' }
 })
 ```
-### OPFSStorageAugmentation
+For off-site backup, snapshot `rootDirectory` from your scheduler using `gsutil rsync`, `aws s3 sync`, `rclone`, or `tar` — there are no cloud storage augmentations.
 **Location**: `src/augmentations/storageAugmentations.ts`
 **Auto-enabled**: When `storage: 'opfs'` or browser with OPFS support
 **Purpose**: Browser-based persistent storage using Origin Private File System
 ```typescript
 const brain = new Brainy({ storage: 'opfs' })
 ```
 ### S3StorageAugmentation
 **Location**: `src/augmentations/storageAugmentations.ts`
 **Manual**: Requires AWS credentials
 **Purpose**: AWS S3-compatible cloud storage
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 's3',
 bucket: 'my-bucket',
 region: 'us-east-1',
 credentials: { accessKeyId, secretAccessKey }
 }
 })
 ```
 ### R2StorageAugmentation
 **Location**: `src/augmentations/storageAugmentations.ts`
 **Manual**: Requires Cloudflare credentials
 **Purpose**: Cloudflare R2 storage (S3-compatible)
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 'r2',
 accountId: 'xxx',
 bucket: 'my-bucket',
 credentials: { accessKeyId, secretAccessKey }
 }
 })
 ```
 ### GCSStorageAugmentation
 **Location**: `src/augmentations/storageAugmentations.ts`
 **Manual**: Requires Google Cloud credentials
 **Purpose**: Google Cloud Storage
 ```typescript
 const brain = new Brainy({
 storage: {
 type: 'gcs',
 bucket: 'my-bucket',
 projectId: 'my-project'
 }
 })
 ```
 ### StorageAugmentation (base)
 **Location**: `src/augmentations/storageAugmentation.ts`
@ -195,11 +145,6 @@ brain.addNouns([...]) // Automatically batched
 **Auto-enabled**: Always active
 **Purpose**: Prevents duplicate concurrent operations
 ### ConnectionPoolAugmentation
 **Location**: `src/augmentations/connectionPoolAugmentation.ts`
 **Auto-enabled**: For network storage
 **Purpose**: Connection pooling for cloud storage adapters
 ---
 ## Data Integrity Augmentations (3 total)
@ -309,11 +254,11 @@ class NotionSynapse extends SynapseAugmentation {
 ### Auto-Configuration
 ```typescript
 const brain = new Brainy({
- // These auto-register augmentations:
+  // These auto-register augmentations:
- storage: 'auto', // Storage augmentation
+  storage: { type: 'auto', rootDirectory: './brainy-data' }, // Storage augmentation
- cache: true, // Cache augmentation
+  cache: true,   // Cache augmentation
- index: true, // Index augmentation
+  index: true,   // Index augmentation
- metrics: true // Metrics augmentation
+  metrics: true  // Metrics augmentation
 })
 ```
@ -403,7 +348,7 @@ Most augmentations have minimal overhead:
 - **Cache**: ~1ms per search (saves 10-100ms on hits)
 - **Index**: ~1ms per operation (saves 100ms+ on queries)
 - **Metrics**: <1ms per operation
- **Storage**: Varies by adapter (memory: 0ms, S3: 50-200ms)
+- **Storage**: Varies by adapter (memory: 0ms, filesystem: 1-10ms)
 ---
--- a/docs/augmentations/README.md
+++ b/docs/augmentations/README.md
@ -55,10 +55,11 @@ Replace or enhance the storage layer.
 | Augmentation | Description | Timing | Status |
 |-------------|-------------|--------|--------|
 | **S3StorageAugmentation** | Use S3 as storage backend | `replace` | 📝 Example |
 | **RedisAugmentation** | Redis caching layer | `around` | 📝 Example |
 | **PostgresAugmentation** | PostgreSQL persistence | `replace` | 📝 Example |
 > Brainy 8.0 ships `filesystem` and `memory` adapters out of the box. For off-site backup of the filesystem artifact, snapshot `rootDirectory` from your scheduler (`gsutil rsync`, `aws s3 sync`, `rclone`, `tar`).
 ### 🔄 Real-time & Sync
 Handle real-time updates and synchronization.
@ -73,7 +74,6 @@ Core infrastructure and reliability features.
 | Augmentation | Description | Timing | Status |
 |-------------|-------------|--------|--------|
 | **ConnectionPoolAugmentation** | Optimize cloud storage connections | `before` | ✅ Production |
 | **RequestDeduplicatorAugmentation** | Prevent duplicate concurrent requests | `before` | ✅ Production |
 | **TransactionAugmentation** | ACID transaction support | `around` | 🚧 Planned |
 | **CacheAugmentation** | Multi-level caching | `around` | ✅ Production |
--- a/docs/guides/distributed-system.md
+++ b/docs/guides/distributed-system.md
@ -1,406 +0,0 @@
 # Distributed Brainy System Guide
 ## Overview
 Brainy introduces a groundbreaking **zero-configuration distributed system** that transforms how vector databases scale. Unlike traditional distributed databases that require complex setup (Consul, etcd, Zookeeper), Brainy uses your existing storage (S3, GCS, R2) as the coordination layer.
 ## Key Innovation: Storage-Based Coordination
 Instead of requiring separate infrastructure for coordination, Brainy leverages your storage backend:
 ```typescript
 // Traditional distributed database setup:
 // ❌ Setup Consul/etcd
 // ❌ Configure node discovery
 // ❌ Setup health checks  
 // ❌ Configure sharding
 // ❌ Setup replication
 // Brainy distributed setup:
 const brain = new Brainy({
  storage: { 
    type: 's3',
    options: { bucket: 'my-data' }
  },
  distributed: true  // ✅ That's it!
 })
 ```
 ## Real-World Scenarios
 ### 1. Processing Multiple Streaming Data Sources (Bluesky, Twitter, etc.)
 **Problem**: You need to ingest millions of posts from multiple social media firehoses simultaneously while maintaining search performance.
 **Traditional Approach**:
 - Separate ingestion and search clusters
 - Complex queue systems (Kafka, RabbitMQ)
 - Manual sharding configuration
 - Complicated backpressure handling
 **Brainy Solution**:
 ```typescript
 // Node 1: Bluesky Ingestion
 const ingestionNode1 = new Brainy({
  storage: { type: 's3', options: { bucket: 'social-data' }},
  distributed: true,
  writeOnly: true  // Optimized for writes
 })
 // Continuously ingest Bluesky firehose
 blueskyStream.on('post', async (post) => {
  await ingestionNode1.add({
    content: post.text,
    author: post.author,
    timestamp: post.createdAt,
    platform: 'bluesky'
  }, 'social-post')
 })
 // Node 2: Twitter Ingestion (separate machine)
 const ingestionNode2 = new Brainy({
  storage: { type: 's3', options: { bucket: 'social-data' }},
  distributed: true,
  writeOnly: true
 })
 // Node 3-5: Search nodes (auto-balanced)
 const searchNode = new Brainy({
  storage: { type: 's3', options: { bucket: 'social-data' }},
  distributed: true,
  readOnly: true  // Optimized for queries
 })
 // Search across ALL data from ALL sources
 const results = await searchNode.find('AI trends', 100)
 // Automatically queries all shards across all nodes!
 ```
 **Benefits**:
 - **Auto-sharding**: Data automatically distributed by content hash
 - **No bottlenecks**: Each ingestion node writes directly to storage
 - **Live search**: Search nodes see new data immediately
 - **Auto-scaling**: Add nodes anytime, data rebalances automatically
 ### 2. Multi-Tenant SaaS Application
 **Problem**: Each customer needs isolated, fast search across their documents, with ability to scale per customer.
 **Brainy Solution**:
 ```typescript
 // Spin up dedicated nodes per large customer
 const enterpriseNode = new Brainy({
  storage: { 
    type: 's3', 
    options: { 
      bucket: 'customer-data',
      prefix: 'customer-123/'  // Isolated data
    }
  },
  distributed: true
 })
 // Shared nodes for smaller customers
 const sharedNode = new Brainy({
  storage: { 
    type: 's3', 
    options: { bucket: 'shared-customers' }
  },
  distributed: true
 })
 // Domain-based sharding ensures customer data stays together
 await sharedNode.add(document, 'document', {
  customerId: 'cust-456',  // Used for shard assignment
  domain: 'customer-456'    // Keeps related data together
 })
 ```
 ### 3. Global Knowledge Graph with Local Inference
 **Problem**: Building a knowledge graph that needs both global connectivity and local LLM inference.
 **Brainy Solution**:
 ```typescript
 // Edge nodes near users (with GPU)
 const edgeNode = new Brainy({
  storage: { type: 's3', options: { bucket: 'knowledge-graph' }},
  distributed: true,
  models: {
    embed: { model: 'BAAI/bge-base-en-v1.5' },
    chat: { model: 'meta-llama/Llama-3.2-3B-Instruct' }
  }
 })
 // Central nodes for graph operations
 const graphNode = new Brainy({
  storage: { type: 's3', options: { bucket: 'knowledge-graph' }},
  distributed: true,
  augmentations: ['graph', 'triple-intelligence']
 })
 // Local inference with global knowledge
 const context = await edgeNode.find(userQuery, 10)
 const response = await edgeNode.chat(userQuery, { context })
 // Graph traversal across all nodes
 const connections = await graphNode.traverse({
  start: 'concept:AI',
  depth: 3,
  relationship: 'related-to'
 })
 ```
 ## Competitive Advantages
 ### vs. Pinecone/Weaviate/Qdrant
 | Feature | Traditional Vector DBs | Brainy Distributed |
 |---------|----------------------|-------------------|
 | Setup Complexity | High (k8s, operators) | Zero (just storage) |
 | Minimum Nodes | 3-5 for HA | 1 (scale as needed) |
 | Coordination | External (etcd, Consul) | Built-in (via storage) |
 | Data Locality | Random sharding | Domain-aware sharding |
 | Query Planning | Basic | Triple Intelligence |
 | Cost at Scale | High (always-on clusters) | Low (scale to zero) |
 ### vs. Neo4j/ArangoDB (Graph Databases)
 | Feature | Graph Databases | Brainy Distributed |
 |---------|----------------|-------------------|
 | Vector Search | Bolt-on/Limited | Native HNSW |
 | Embedding Generation | External | Built-in (30+ models) |
 | Distributed Transactions | Complex/Slow | Eventually consistent |
 | Natural Language | No | Native (Triple Intelligence) |
 | Setup | Very Complex | Zero config |
 ### vs. Elasticsearch/OpenSearch
 | Feature | Elasticsearch | Brainy Distributed |
 |---------|--------------|-------------------|
 | Vector Support | Added later (slow) | Native (fast HNSW) |
 | Cluster Management | Complex (master nodes) | Automatic (via storage) |
 | Shard Rebalancing | Manual/Risky | Automatic/Safe |
 | Memory Usage | Very High | Efficient |
 | Query Language | Complex DSL | Natural language |
 ## Innovative Features
 ### 1. Domain-Aware Sharding
 Unlike hash-based sharding, Brainy understands data relationships:
 ```typescript
 // Documents about the same topic stay on the same shard
 await brain.add(doc1, 'document', { domain: 'physics' })
 await brain.add(doc2, 'document', { domain: 'physics' })
 // Both documents on same shard = faster related queries
 // Customer data stays together
 await brain.add(order, 'order', { customerId: 'cust-123' })
 await brain.add(invoice, 'invoice', { customerId: 'cust-123' })
 // Same customer = same shard = better locality
 ```
 ### 2. Streaming Shard Migration
 Zero-downtime data movement between nodes:
 ```typescript
 // Automatically triggered when nodes join/leave
 // Uses HTTP streaming for efficiency
 // Validates data integrity
 // Atomic ownership transfer
 // No query downtime!
 ```
 ### 3. Storage-Based Consensus
 No Raft/Paxos complexity:
 ```typescript
 // Leader election via storage atomic operations
 // Health monitoring via storage heartbeats
 // Configuration consensus via storage CAS
 // No split-brain issues!
 ```
 ### 4. Intelligent Query Planning
 The distributed query planner understands:
 - Which shards contain relevant data
 - Node health and latency
 - Data locality and caching
 - Triple Intelligence scoring
 ```typescript
 // Automatically optimizes query execution
 const results = await brain.find('quantum physics')
 // Planner knows:
 // - Physics domain → shard-3
 // - Node-2 has shard-3 cached
 // - Route query to node-2
 // - Merge results with Triple Intelligence
 ```
 ## Performance Characteristics
 ### Scalability
 - **Horizontal**: Add nodes anytime
 - **Vertical**: Nodes can differ in size
 - **Geographic**: Nodes can be globally distributed
 - **Elastic**: Scale to zero when idle
 ### Throughput
 - **Writes**: Linear scaling with nodes
 - **Reads**: Sub-linear (due to caching)
 - **Mixed**: Read/write optimized nodes
 ### Latency
 - **Local queries**: ~10ms p50
 - **Distributed queries**: ~50ms p50
 - **Shard migration**: Streaming (no bulk pause)
 ## Use Cases Where Brainy Excels
 ### ✅ Perfect For:
 1. **Multi-source data ingestion** (social media, logs, events)
 2. **Global search applications** (distributed teams)
 3. **Multi-tenant SaaS** (customer isolation)
 4. **Knowledge graphs** (with vector search)
 5. **Edge AI applications** (local inference, global knowledge)
 6. **Document intelligence** (contracts, research papers)
 7. **Real-time analytics** (streaming + search)
 ### ⚠️ Consider Alternatives For:
 1. **Strong consistency requirements** (use PostgreSQL)
 2. **Sub-millisecond latency** (use Redis)
 3. **Complex transactions** (use traditional RDBMS)
 4. **Purely structured data** (use columnar stores)
 ## Migration from Other Systems
 ### From Pinecone/Weaviate:
 ```typescript
 // Your existing vector search still works
 const results = await brain.search(embedding, 10)
 // But now you can scale horizontally!
 // And add graph relationships!
 // And use natural language!
 ```
 ### From Elasticsearch:
 ```typescript
 // Import your documents
 await brain.import('./elasticsearch-export.json')
 // Queries are simpler
 const results = await brain.find('user query')
 // No complex DSL needed!
 ```
 ### From Neo4j:
 ```typescript
 // Import your graph
 await brain.importGraph('./neo4j-export.cypher')
 // Now with vector search!
 const similar = await brain.find('concepts like quantum computing')
 ```
 ## Deployment Patterns
 ### 1. Start Simple, Scale Later
 ```typescript
 // Day 1: Single node
 const brain = new Brainy({ storage: 's3' })
 // Month 2: Growing data, add distribution
 const brain = new Brainy({ 
  storage: 's3',
  distributed: true  // Just add this!
 })
 // Month 6: Multiple nodes auto-balance
 // No migration needed!
 ```
 ### 2. Geographic Distribution
 ```typescript
 // US Node
 const usNode = new Brainy({
  storage: { region: 'us-east-1' },
  distributed: true
 })
 // EU Node  
 const euNode = new Brainy({
  storage: { region: 'eu-west-1' },
  distributed: true
 })
 // They automatically coordinate!
 ```
 ### 3. Specialized Nodes
 ```typescript
 // GPU nodes for embedding
 const embedNode = new Brainy({
  distributed: true,
  writeOnly: true,
  models: { embed: 'large-model' }
 })
 // CPU nodes for search
 const searchNode = new Brainy({
  distributed: true,
  readOnly: true
 })
 ```
 ## Monitoring & Operations
 ### Health Checks
 ```typescript
 const health = await brain.getClusterHealth()
 // {
 //   nodes: 5,
 //   healthy: 5,
 //   shards: 16,
 //   status: 'green'
 // }
 ```
 ### Shard Distribution
 ```typescript
 const shards = await brain.getShardDistribution()
 // Shows which nodes own which shards
 ```
 ### Migration Status
 ```typescript
 const migrations = await brain.getActiveMigrations()
 // Shows ongoing shard movements
 ```
 ## Conclusion
 Brainy's distributed system is **production-ready** and offers:
 1. **True zero-configuration** - Just add `distributed: true`
 2. **Storage-based coordination** - No external dependencies
 3. **Intelligent sharding** - Domain-aware data placement
 4. **Automatic operations** - Rebalancing, failover, scaling
 5. **Unified interface** - Vector + Graph + Document + LLM
 This is not just another distributed database. It's a fundamental rethinking of how distributed systems should work in the cloud era.
 ## Next Steps
 1. [Try the distributed quick start](./distributed-quickstart.md)
 2. [Read the architecture deep dive](../architecture/distributed-storage.md)
 3. [View benchmarks](../benchmarks/distributed-performance.md)
 4. [Deploy to production](./production-deployment.md)
--- a/docs/guides/import-flow.md
+++ b/docs/guides/import-flow.md
@ -1687,11 +1687,11 @@ verbCounts['CreatedBy']
 ---
-### 8. Storage by Cloud Provider
+### 8. Storage Layout
-Brainy supports multiple storage adapters:
+Brainy 8.0 ships two adapters: filesystem and memory.
-#### File System (Local)
+#### Filesystem (Default)
 ```
 .brainy/
 ├── nouns/
@ -1701,43 +1701,18 @@ Brainy supports multiple storage adapters:
 └── index.json
 ```
 #### Google Cloud Storage (GCS)
 ```
 gs://my-bucket/brainy/
 ├── nouns/
 │   └── ent_mona_lisa_1730000000000.json
 ├── nouns-metadata/
 │   └── ent_mona_lisa_1730000000000.json
 └── ...
 ```
 #### Amazon S3
 ```
 s3://my-bucket/brainy/
 ├── nouns/
 │   └── ent_mona_lisa_1730000000000.json
 └── ...
 ```
 #### Cloudflare R2
 ```
 r2://my-bucket/brainy/
 ├── nouns/
 │   └── ent_mona_lisa_1730000000000.json
 └── ...
 ```
 **Configuration**:
 ```typescript
 const brain = await Brainy.create({
  storage: {
-    type: 'gcs',
+    type: 'filesystem',
-    bucket: 'my-bucket',
+    rootDirectory: './.brainy'
    prefix: 'brainy/'
  }
 })
 ```
 For off-site backup, snapshot `rootDirectory` from your scheduler with `gsutil rsync`, `aws s3 sync`, `rclone`, or `tar`. Brainy itself doesn't reach out to object storage.
 ---
 ## Performance & Scale
--- a/docs/guides/inspection.md
+++ b/docs/guides/inspection.md
@ -17,10 +17,7 @@ store. This guide covers the safe ways to query a running Brainy directory.
 ## The cardinal rule
-**Never open a second writer on the same directory.** It will throw on
+**Never open a second writer on the same directory.** Filesystem storage will throw, and any other write path will corrupt the live writer's state. Use `Brainy.openReadOnly()` or the `brainy inspect` CLI instead.
 filesystem storage; on cloud storage it'll silently overwrite the live
 writer's state. Use `Brainy.openReadOnly()` or the `brainy inspect` CLI
 instead.
 ## The CLI is the fastest path
@ -97,7 +94,7 @@ $ brainy inspect health /data/brain
 {
  "overall": "warn",
  "checks": [
-    { "name": "index-parity", "status": "pass", "message": "HNSW (1851) and metadata (1851) agree." },
+    { "name": "index-parity", "status": "pass", "message": "Vector (1851) and metadata (1851) agree." },
    { "name": "field-registry", "status": "pass", "message": "23 fields registered for 1851 entities." },
    { "name": "seeded-records", "status": "warn", "message": "15 entities tagged _seeded:true." },
    { "name": "writer-heartbeat", "status": "pass", "message": "Writer healthy (PID 1774431...)." }
--- a/docs/transactions.md
+++ b/docs/transactions.md
@ -11,7 +11,7 @@ Brainy's transaction system provides **atomic operations** with automatic rollba
 - **Atomicity**: All operations succeed or all rollback
 - **Consistency**: Indexes and storage remain consistent
 - **Automatic**: Transparently used by all `brain.add()`, `brain.update()`, `brain.delete()`, and `brain.relate()` operations
- **Compatible**: Works seamlessly with COW, sharding, type-aware storage, and distributed storage
+- **Compatible**: Works seamlessly with COW, sharding, and type-aware storage
 ## Architecture
@ -154,37 +154,27 @@ await brain.update({
 - Storage layer uses O(1) ID-first path construction
 - No type cache needed (removed in a previous version)
 - Type counters adjusted on commit/rollback
- 40x faster on cloud storage (eliminates 42-type search)
+- 40x faster path lookups (eliminates 42-type search)
-### Distributed Storage
+### Storage Adapter Interface
 ✅ **Fully Compatible**
-Transactions work with distributed/remote storage:
+Transactions go through the `StorageAdapter` interface, so both shipped adapters (filesystem, memory) and any custom plugin adapter inherit the same atomicity guarantees:
 ```typescript
 // Works with S3, Azure, GCS, etc.
 const brain = new Brainy({
- storage: {
+  storage: { type: 'filesystem', rootDirectory: './data' }
 type: 's3Compatible',
 config: { /* S3 config */ }
 }
 })
-// Transactions ensure atomicity at write coordinator level
+await brain.add({ data: { name: 'Entity' }, type: NounType.Thing })
 await brain.add({ data: { name: 'Remote Entity' }, type: NounType.Thing })
 ```
 **How It Works:**
 - Transactions operate through `StorageAdapter` interface
- Remote storage adapters implement same interface
+- Custom adapters registered via the plugin system implement the same interface
- Atomicity guaranteed at write-coordinator level
+- Atomicity guaranteed at the write-coordinator level
- Read-after-write consistency maintained
+- Read-after-write consistency maintained inside a single Brainy process
 **Design Philosophy:**
 - **Single-node writes** (most common): Fully atomic ✅
 - **Distributed reads + centralized writes**: Transactions on primary ✅
 - **Multi-primary**: Transactions per-instance, cross-instance via coordinator ✅
 ## Examples
@ -404,17 +394,17 @@ setInterval(() => {
 ### 5. Understand Atomicity Guarantees
 **What Transactions GUARANTEE:**
- ✅ Atomicity within single Brainy instance
+- ✅ Atomicity within a single Brainy process
 - ✅ Consistent state across all indexes
 - ✅ Automatic rollback on failure
- ✅ Works with all storage adapters (local, remote, COW, sharded)
+- ✅ Works with all storage adapters (filesystem, memory, custom plugin adapters)
 **What Transactions DON'T Provide:**
 - ❌ Two-phase commit across multiple Brainy instances
- ❌ Distributed locking across nodes
+- ❌ Distributed locking across processes
 - ❌ Cross-datacenter ACID guarantees
-**Design:** Transactions ensure atomicity at the **write coordinator level**. For multi-instance scenarios, use `DistributedCoordinator`.
+**Design:** Transactions ensure atomicity at the **write-coordinator level** inside one process. Cross-instance coordination, if you need it, lives in your service layer.
 ## Testing Transactions
@ -453,7 +443,6 @@ See `tests/transaction/integration/` for comprehensive integration tests coverin
 - COW integration (`cow-transactions.test.ts`)
 - Sharding integration (`sharding-transactions.test.ts`)
 - TypeAware integration (`typeaware-transactions.test.ts`)
 - Distributed storage integration (`distributed-transactions.test.ts`)
 ## Troubleshooting
@ -552,7 +541,7 @@ interface StorageAdapter {
 }
 ```
-**Key Insight:** All storage adapters (filesystem, S3, Azure, GCS, memory) implement this interface. Transactions work with **any** storage adapter automatically.
+**Key Insight:** Both shipped storage adapters (filesystem, memory) — and any custom plugin adapter — implement this interface. Transactions work with **any** storage adapter automatically.
 ## Additional Resources
@ -565,13 +554,13 @@ interface StorageAdapter {
 - Initial transaction system release
 - Atomic operations with rollback
- - Compatible with COW, sharding, type-aware, distributed
+ - Compatible with COW, sharding, type-aware storage
 - 36/36 unit tests passing
 - 35 integration test scenarios
 ## Summary
-Brainy's transaction system provides **production-ready atomic operations** with automatic rollback. It works transparently with all Brainy APIs and is fully compatible with advanced features like COW, sharding, type-aware storage, and distributed storage.
+Brainy's transaction system provides **production-ready atomic operations** with automatic rollback. It works transparently with all Brainy APIs and is fully compatible with advanced features like COW, sharding, and type-aware storage.
 **Key Takeaways:**
 - ✅ **Automatic**: No manual transaction management needed
--- a/docs/vfs/COMMON_PATTERNS.md
+++ b/docs/vfs/COMMON_PATTERNS.md
@ -80,17 +80,16 @@ const brain = new Brainy({
  }
 })
-// ✅ Pattern 2: Cloud storage (production)
+// ✅ Pattern 2: Filesystem (production default)
 const brain = new Brainy({
  storage: {
-    type: 's3',
+    type: 'filesystem',
-    bucket: 'my-vfs-data',
+    rootDirectory: '/var/lib/brainy'
    region: 'us-west-2'
  }
 })
 // ✅ Pattern 3: Auto-detection (recommended)
-const brain = new Brainy()  // Automatically chooses best storage
+const brain = new Brainy()  // Picks filesystem on Node, memory in browser
 ```
 ## 🔍 Search Patterns
@ -563,7 +562,7 @@ function vfsMiddleware() {
 | ❌ **Avoid These Patterns** | ✅ **Use These Instead** |
 |---------------------------|------------------------|
 | Manual tree filtering | `vfs.getDirectChildren()` |
-| Memory storage for files | Filesystem or cloud storage |
+| Memory storage for files | Filesystem (snapshot off-site for backup) |
 | Sequential file operations | Parallel processing with limits |
 | Manual relationship tracking | Built-in `vfs.addRelationship()` |
 | Loading entire directories | Paginated/lazy loading |
--- a/docs/vfs/VFS_API_GUIDE.md
+++ b/docs/vfs/VFS_API_GUIDE.md
@ -632,60 +632,20 @@ VFS works with all built-in Brainy storage adapters:
 // Memory (testing/development)
 const brain = new Brainy({ storage: { type: 'memory' } })
-// Filesystem (local development)
+// Filesystem (production default)
 const brain = new Brainy({
  storage: {
    type: 'filesystem',
-    path: './brainy-data'
+    rootDirectory: './brainy-data'
  }
 })
-// S3-compatible storage (production)
+// Both work identically with VFS
 const brain = new Brainy({
  storage: {
    type: 's3',
    bucket: 'my-bucket',
    region: 'us-east-1'
  }
 })
 // Cloudflare R2 (production)
 const brain = new Brainy({
  storage: {
    type: 'r2',
    accountId: 'your-account-id',
    bucket: 'my-bucket'
  }
 })
 // Google Cloud Storage (production)
 const brain = new Brainy({
  storage: {
    type: 'gcs',
    bucket: 'my-bucket',
    projectId: 'my-project'
  }
 })
 // Azure Blob Storage (production)
 const brain = new Brainy({
  storage: {
    type: 'azure',
    accountName: 'myaccount',
    containerName: 'my-container'
  }
 })
 // OPFS (browser-native persistence)
 const brain = new Brainy({ storage: { type: 'opfs' } })
 // TypeAware storage (optimized for entity types)
 const brain = new Brainy({ storage: { type: 'typeaware' } })
 // All work identically with VFS
 const vfs = new VirtualFileSystem(brain)
 ```
 For off-site backup of the filesystem artifact, snapshot `rootDirectory` from your scheduler (`gsutil rsync`, `aws s3 sync`, `rclone`, `tar`).
 **Custom Storage Adapters:** Redis, PostgreSQL, and other databases can be added via the [extension system](../api/EXTENSIBILITY.md). See `src/config/extensibleConfig.ts` for examples.
 ### Best Practices