@soulcraft/brainy 6.2.6 → 6.2.8

package/dist/brainy.d.ts

@@ -1795,6 +1795,10 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * - 87% memory reduction through separate graphs per entity type
      * - 10x faster type-specific queries
      * - Automatic type routing
+     *
+     * v6.2.8: Smart defaults for HNSW persistence mode
+     * - Cloud storage (GCS/S3/R2/Azure): 'deferred' for 30-50× faster adds
+     * - Local storage (FileSystem/Memory/OPFS): 'immediate' (already fast)
      */
     private setupIndex;
     /**
@@ -1846,6 +1850,9 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private rebuildIndexesIfNeeded;
     /**
      * Close and cleanup
+     *
+     * v6.2.8: Now flushes HNSW dirty nodes before closing
+     * This ensures deferred persistence mode data is saved
      */
     close(): Promise<void>;
     /**

package/dist/brainy.js

@@ -3974,20 +3974,35 @@ export class Brainy {
      * - 87% memory reduction through separate graphs per entity type
      * - 10x faster type-specific queries
      * - Automatic type routing
+     *
+     * v6.2.8: Smart defaults for HNSW persistence mode
+     * - Cloud storage (GCS/S3/R2/Azure): 'deferred' for 30-50× faster adds
+     * - Local storage (FileSystem/Memory/OPFS): 'immediate' (already fast)
      */
     setupIndex() {
         const indexConfig = {
             ...this.config.index,
             distanceFunction: this.distance
         };
+        // v6.2.8: Determine persist mode (user config > smart default)
+        let persistMode = this.config.hnswPersistMode || 'immediate';
+        // Smart default: Use deferred mode for cloud storage adapters
+        if (!this.config.hnswPersistMode) {
+            const storageType = this.config.storage?.type || 'auto';
+            const cloudStorageTypes = ['gcs', 's3', 'r2', 'azure'];
+            if (cloudStorageTypes.includes(storageType)) {
+                persistMode = 'deferred';
+            }
+        }
         // Phase 2: Use TypeAwareHNSWIndex for billion-scale optimization
         if (this.config.storage?.type !== 'memory') {
             return new TypeAwareHNSWIndex(indexConfig, this.distance, {
                 storage: this.storage,
-                useParallelization: true
+                useParallelization: true,
+                persistMode
             });
         }
-        return new HNSWIndex(indexConfig);
+        return new HNSWIndex(indexConfig, this.distance, { persistMode });
     }
     /**
      * Setup augmentations
@@ -4071,7 +4086,9 @@ export class Brainy {
             maxConcurrentOperations: config?.maxConcurrentOperations ?? 10,
             // Memory management options (v5.11.0)
             maxQueryLimit: config?.maxQueryLimit ?? undefined,
-            reservedQueryMemory: config?.reservedQueryMemory ?? undefined
+            reservedQueryMemory: config?.reservedQueryMemory ?? undefined,
+            // HNSW persistence mode (v6.2.8) - undefined = smart default in setupIndex
+            hnswPersistMode: config?.hnswPersistMode ?? undefined
         };
     }
     /**
@@ -4241,8 +4258,16 @@ export class Brainy {
     }
     /**
      * Close and cleanup
+     *
+     * v6.2.8: Now flushes HNSW dirty nodes before closing
+     * This ensures deferred persistence mode data is saved
      */
     async close() {
+        // v6.2.8: Flush HNSW dirty nodes before closing
+        // In deferred persistence mode, this persists all pending HNSW graph data
+        if (this.index && typeof this.index.flush === 'function') {
+            await this.index.flush();
+        }
         // Shutdown augmentations
         const augs = this.augmentationRegistry.getAll();
         for (const aug of augs) {

package/dist/hnsw/hnswIndex.d.ts

@@ -19,9 +19,13 @@ export declare class HNSWIndex {
     private cowEnabled;
     private cowModifiedNodes;
     private cowParent;
+    private persistMode;
+    private dirtyNodes;
+    private dirtySystem;
     constructor(config?: Partial<HNSWConfig>, distanceFunction?: DistanceFunction, options?: {
         useParallelization?: boolean;
         storage?: BaseStorage;
+        persistMode?: 'immediate' | 'deferred';
     });
     /**
      * Set whether to use parallelization for performance-critical operations
@@ -31,6 +35,29 @@ export declare class HNSWIndex {
      * Get whether parallelization is enabled
      */
     getUseParallelization(): boolean;
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes.
+     *
+     * This is automatically called by:
+     * - brain.close()
+     * - brain.flush()
+     * - Process shutdown (SIGTERM/SIGINT)
+     *
+     * @returns Number of nodes flushed
+     */
+    flush(): Promise<number>;
+    /**
+     * Get the number of dirty (unpersisted) nodes
+     * Useful for monitoring and debugging
+     */
+    getDirtyNodeCount(): number;
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode(): 'immediate' | 'deferred';
     /**
      * Enable COW (Copy-on-Write) mode - Instant fork via shallow copy
      *

package/dist/hnsw/hnswIndex.js

@@ -28,6 +28,12 @@ export class HNSWIndex {
         this.cowEnabled = false;
         this.cowModifiedNodes = new Set();
         this.cowParent = null;
+        // v6.2.8: Deferred HNSW persistence for cloud storage performance
+        // In deferred mode, HNSW connections are only persisted on flush/close
+        // This reduces GCS operations from 70 to 2-3 per add() (30-50× faster)
+        this.persistMode = 'immediate';
+        this.dirtyNodes = new Set(); // Nodes with unpersisted HNSW data
+        this.dirtySystem = false; // Whether system data (entryPoint, maxLevel) needs persist
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.distanceFunction = distanceFunction;
         this.useParallelization =
@@ -35,6 +41,7 @@ export class HNSWIndex {
                 ? options.useParallelization
                 : true;
         this.storage = options.storage || null;
+        this.persistMode = options.persistMode || 'immediate';
         // Use SAME UnifiedCache as Graph and Metadata for fair memory competition
         this.unifiedCache = getGlobalCache();
     }
@@ -50,6 +57,82 @@ export class HNSWIndex {
     getUseParallelization() {
         return this.useParallelization;
     }
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes.
+     *
+     * This is automatically called by:
+     * - brain.close()
+     * - brain.flush()
+     * - Process shutdown (SIGTERM/SIGINT)
+     *
+     * @returns Number of nodes flushed
+     */
+    async flush() {
+        if (!this.storage) {
+            return 0;
+        }
+        if (this.dirtyNodes.size === 0 && !this.dirtySystem) {
+            return 0;
+        }
+        const startTime = Date.now();
+        const nodeCount = this.dirtyNodes.size;
+        // Batch persist all dirty nodes concurrently
+        if (this.dirtyNodes.size > 0) {
+            const batchSize = 50; // Reasonable batch size for cloud storage
+            const nodeIds = Array.from(this.dirtyNodes);
+            for (let i = 0; i < nodeIds.length; i += batchSize) {
+                const batch = nodeIds.slice(i, i + batchSize);
+                const promises = batch.map(nodeId => {
+                    const noun = this.nouns.get(nodeId);
+                    if (!noun)
+                        return Promise.resolve(); // Node was deleted
+                    const connectionsObj = {};
+                    for (const [level, nounIds] of noun.connections.entries()) {
+                        connectionsObj[level.toString()] = Array.from(nounIds);
+                    }
+                    return this.storage.saveHNSWData(nodeId, {
+                        level: noun.level,
+                        connections: connectionsObj
+                    }).catch(error => {
+                        console.error(`[HNSW flush] Failed to persist node ${nodeId}:`, error);
+                    });
+                });
+                await Promise.allSettled(promises);
+            }
+            this.dirtyNodes.clear();
+        }
+        // Persist system data if dirty
+        if (this.dirtySystem) {
+            await this.storage.saveHNSWSystem({
+                entryPointId: this.entryPointId,
+                maxLevel: this.maxLevel
+            }).catch(error => {
+                console.error('[HNSW flush] Failed to persist system data:', error);
+            });
+            this.dirtySystem = false;
+        }
+        const duration = Date.now() - startTime;
+        if (nodeCount > 0) {
+            prodLog.info(`[HNSW] Flushed ${nodeCount} dirty nodes in ${duration}ms`);
+        }
+        return nodeCount;
+    }
+    /**
+     * Get the number of dirty (unpersisted) nodes
+     * Useful for monitoring and debugging
+     */
+    getDirtyNodeCount() {
+        return this.dirtyNodes.size;
+    }
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode() {
+        return this.persistMode;
+    }
     /**
      * Enable COW (Copy-on-Write) mode - Instant fork via shallow copy
      *
@@ -284,14 +367,11 @@ export class HNSWIndex {
                 }
                 // Persist updated neighbor HNSW data (v3.35.0+)
                 //
-                // PERFORMANCE OPTIMIZATION (v4.10.0): Concurrent neighbor updates
-                // Previously (v4.9.2): Serial await - 100% safe but 48-64× slower
-                // Now: Promise.allSettled() - 48-64× faster bulk imports
-                // Safety: All storage adapters handle concurrent writes via:
-                //   - Optimistic locking with retry (GCS/S3/Azure/R2)
-                //   - Mutex serialization (Memory/OPFS/FileSystem)
-                // Trade-off: More retry activity under high contention (expected and handled)
-                if (this.storage) {
+                // v6.2.8: Deferred persistence mode for cloud storage performance
+                // In deferred mode, we track dirty nodes instead of persisting immediately
+                // This reduces GCS operations from 70 to 2-3 per add() (30-50× faster)
+                if (this.storage && this.persistMode === 'immediate') {
+                    // IMMEDIATE MODE: Original behavior - persist each neighbor update
                     const neighborConnectionsObj = {};
                     for (const [lvl, nounIds] of neighbor.connections.entries()) {
                         neighborConnectionsObj[lvl.toString()] = Array.from(nounIds);
@@ -304,9 +384,13 @@ export class HNSWIndex {
                         })
                     });
                 }
+                else if (this.persistMode === 'deferred') {
+                    // DEFERRED MODE: Track dirty nodes for later batch persistence
+                    this.dirtyNodes.add(neighborId);
+                }
             }
-            // Execute all neighbor updates concurrently (with optional batch size limiting)
-            if (neighborUpdates.length > 0) {
+            // Execute all neighbor updates concurrently (only in immediate mode)
+            if (neighborUpdates.length > 0 && this.persistMode === 'immediate') {
                 const batchSize = this.config.maxConcurrentNeighborWrites || neighborUpdates.length;
                 const allFailures = [];
                 // Process in chunks if batch size specified
@@ -360,8 +444,9 @@ export class HNSWIndex {
             this.highLevelNodes.get(nounLevel).add(id);
         }
         // Persist HNSW graph data to storage (v3.35.0+)
-        if (this.storage) {
-            // Convert connections Map to serializable format
+        // v6.2.8: Respect persistMode setting
+        if (this.storage && this.persistMode === 'immediate') {
+            // IMMEDIATE MODE: Original behavior - persist new entity and system data
             const connectionsObj = {};
             for (const [level, nounIds] of noun.connections.entries()) {
                 connectionsObj[level.toString()] = Array.from(nounIds);
@@ -380,6 +465,11 @@ export class HNSWIndex {
                 console.error('Failed to persist HNSW system data:', error);
             });
         }
+        else if (this.persistMode === 'deferred') {
+            // DEFERRED MODE: Track dirty nodes for later batch persistence
+            this.dirtyNodes.add(id);
+            this.dirtySystem = true;
+        }
         return id;
     }
     /**

package/dist/hnsw/typeAwareHNSWIndex.d.ts

@@ -43,16 +43,18 @@ export declare class TypeAwareHNSWIndex {
     private distanceFunction;
     private storage;
     private useParallelization;
+    private persistMode;
     /**
      * Create a new TypeAwareHNSWIndex
      *
      * @param config HNSW configuration (M, efConstruction, efSearch, ml)
      * @param distanceFunction Distance function (default: euclidean)
-     * @param options Additional options (storage, parallelization)
+     * @param options Additional options (storage, parallelization, persistMode)
      */
     constructor(config?: Partial<HNSWConfig>, distanceFunction?: DistanceFunction, options?: {
         useParallelization?: boolean;
         storage?: BaseStorage;
+        persistMode?: 'immediate' | 'deferred';
     });
     /**
      * Enable COW (Copy-on-Write) mode - Instant fork via shallow copy
@@ -63,6 +65,24 @@ export declare class TypeAwareHNSWIndex {
      * @param parent - Parent TypeAwareHNSWIndex to copy from
      */
     enableCOW(parent: TypeAwareHNSWIndex): void;
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage for all type-specific indexes
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes across
+     * all type-specific indexes.
+     *
+     * @returns Total number of nodes flushed across all indexes
+     */
+    flush(): Promise<number>;
+    /**
+     * Get the total number of dirty (unpersisted) nodes across all type-specific indexes
+     */
+    getDirtyNodeCount(): number;
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode(): 'immediate' | 'deferred';
     /**
      * Get or create HNSW index for a specific type (lazy initialization)
      *

package/dist/hnsw/typeAwareHNSWIndex.js

@@ -35,7 +35,7 @@ export class TypeAwareHNSWIndex {
      *
      * @param config HNSW configuration (M, efConstruction, efSearch, ml)
      * @param distanceFunction Distance function (default: euclidean)
-     * @param options Additional options (storage, parallelization)
+     * @param options Additional options (storage, parallelization, persistMode)
      */
     constructor(config = {}, distanceFunction = euclideanDistance, options = {}) {
         // One HNSW index per noun type (lazy initialization)
@@ -47,6 +47,7 @@ export class TypeAwareHNSWIndex {
             options.useParallelization !== undefined
                 ? options.useParallelization
                 : true;
+        this.persistMode = options.persistMode || 'immediate';
         prodLog.info('TypeAwareHNSWIndex initialized (Phase 2: Type-Aware HNSW)');
     }
     /**
@@ -64,13 +65,51 @@ export class TypeAwareHNSWIndex {
         for (const [type, parentIndex] of parent.indexes.entries()) {
             const childIndex = new HNSWIndex(this.config, this.distanceFunction, {
                 useParallelization: this.useParallelization,
-                storage: this.storage || undefined
+                storage: this.storage || undefined,
+                persistMode: this.persistMode
             });
             childIndex.enableCOW(parentIndex);
             this.indexes.set(type, childIndex);
         }
         prodLog.info(`TypeAwareHNSWIndex COW enabled: ${parent.indexes.size} type-specific indexes shallow copied`);
     }
+    /**
+     * v6.2.8: Flush dirty HNSW data to storage for all type-specific indexes
+     *
+     * In deferred persistence mode, HNSW connections are tracked as dirty but not
+     * immediately persisted. Call flush() to persist all pending changes across
+     * all type-specific indexes.
+     *
+     * @returns Total number of nodes flushed across all indexes
+     */
+    async flush() {
+        if (this.indexes.size === 0) {
+            return 0;
+        }
+        const flushPromises = Array.from(this.indexes.values()).map(index => index.flush());
+        const results = await Promise.all(flushPromises);
+        const totalFlushed = results.reduce((sum, count) => sum + count, 0);
+        if (totalFlushed > 0) {
+            prodLog.info(`[TypeAwareHNSW] Flushed ${totalFlushed} dirty nodes across ${this.indexes.size} type indexes`);
+        }
+        return totalFlushed;
+    }
+    /**
+     * Get the total number of dirty (unpersisted) nodes across all type-specific indexes
+     */
+    getDirtyNodeCount() {
+        let total = 0;
+        for (const index of this.indexes.values()) {
+            total += index.getDirtyNodeCount();
+        }
+        return total;
+    }
+    /**
+     * Get the current persist mode
+     */
+    getPersistMode() {
+        return this.persistMode;
+    }
     /**
      * Get or create HNSW index for a specific type (lazy initialization)
      *
@@ -90,7 +129,8 @@ export class TypeAwareHNSWIndex {
             prodLog.info(`Creating HNSW index for type: ${type}`);
             const index = new HNSWIndex(this.config, this.distanceFunction, {
                 useParallelization: this.useParallelization,
-                storage: this.storage || undefined
+                storage: this.storage || undefined,
+                persistMode: this.persistMode
             });
             this.indexes.set(type, index);
         }

package/dist/storage/adapters/azureBlobStorage.d.ts

@@ -52,10 +52,6 @@ export declare class AzureBlobStorage extends BaseStorage {
     private nounWriteBuffer;
     private verbWriteBuffer;
     private requestCoalescer;
-    private highVolumeMode;
-    private lastVolumeCheck;
-    private volumeCheckInterval;
-    private forceHighVolumeMode;
     private nounCacheManager;
     private verbCacheManager;
     private logger;
@@ -155,10 +151,6 @@ export declare class AzureBlobStorage extends BaseStorage {
      * @param requestId Request ID from applyBackpressure()
      */
     private releaseBackpressure;
-    /**
-     * Check if high-volume mode should be enabled
-     */
-    private checkVolumeMode;
     /**
      * Flush noun buffer to Azure
      */
@@ -169,6 +161,7 @@ export declare class AzureBlobStorage extends BaseStorage {
     private flushVerbBuffer;
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     protected saveNode(node: HNSWNode): Promise<void>;
     /**
@@ -231,6 +224,7 @@ export declare class AzureBlobStorage extends BaseStorage {
     private streamToBuffer;
     /**
      * Save an edge to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     protected saveEdge(edge: Edge): Promise<void>;
     /**

package/dist/storage/adapters/azureBlobStorage.js

@@ -59,11 +59,6 @@ export class AzureBlobStorage extends BaseStorage {
         this.verbWriteBuffer = null;
         // Request coalescer for deduplication
         this.requestCoalescer = null;
-        // High-volume mode detection
-        this.highVolumeMode = false;
-        this.lastVolumeCheck = 0;
-        this.volumeCheckInterval = 1000; // Check every second
-        this.forceHighVolumeMode = false; // Environment variable override
         // Module logger
         this.logger = createModuleLogger('AzureBlobStorage');
         // v5.4.0: HNSW mutex locks to prevent read-modify-write races
@@ -83,12 +78,7 @@ export class AzureBlobStorage extends BaseStorage {
         // Initialize cache managers
         this.nounCacheManager = new CacheManager(options.cacheConfig);
         this.verbCacheManager = new CacheManager(options.cacheConfig);
-        // Check for high-volume mode override
-        if (typeof process !== 'undefined' && process.env?.BRAINY_FORCE_HIGH_VOLUME === 'true') {
-            this.forceHighVolumeMode = true;
-            this.highVolumeMode = true;
-            prodLog.info('🚀 High-volume mode FORCED via BRAINY_FORCE_HIGH_VOLUME environment variable');
-        }
+        // v6.2.7: Write buffering always enabled - no env var check needed
     }
     /**
      * Get Azure Blob-optimized batch configuration with native batch API support
@@ -326,29 +316,7 @@ export class AzureBlobStorage extends BaseStorage {
             this.backpressure.releasePermission(requestId, success);
         }
     }
-    /**
-     * Check if high-volume mode should be enabled
-     */
-    checkVolumeMode() {
-        if (this.forceHighVolumeMode) {
-            return; // Already forced on
-        }
-        const now = Date.now();
-        if (now - this.lastVolumeCheck < this.volumeCheckInterval) {
-            return;
-        }
-        this.lastVolumeCheck = now;
-        // Enable high-volume mode if we have many pending operations
-        const shouldEnable = this.pendingOperations > 20;
-        if (shouldEnable && !this.highVolumeMode) {
-            this.highVolumeMode = true;
-            prodLog.info('🚀 High-volume mode ENABLED (pending operations:', this.pendingOperations, ')');
-        }
-        else if (!shouldEnable && this.highVolumeMode && !this.forceHighVolumeMode) {
-            this.highVolumeMode = false;
-            prodLog.info('🐌 High-volume mode DISABLED (pending operations:', this.pendingOperations, ')');
-        }
-    }
+    // v6.2.7: Removed checkVolumeMode() - write buffering always enabled for cloud storage
     /**
      * Flush noun buffer to Azure
      */
@@ -380,26 +348,21 @@ export class AzureBlobStorage extends BaseStorage {
     // v5.4.0: Removed saveNoun_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     async saveNode(node) {
         await this.ensureInitialized();
-        // ALWAYS check if we should use high-volume mode (critical for detection)
-        this.checkVolumeMode();
-        // Use write buffer in high-volume mode
-        if (this.highVolumeMode && this.nounWriteBuffer) {
-            this.logger.trace(`📝 BUFFERING: Adding noun ${node.id} to write buffer (high-volume mode active)`);
-            // v6.2.6: CRITICAL FIX - Populate cache BEFORE buffering for read-after-write consistency
-            // Without this, add() returns but relate() can't find the entity (cloud storage production bug)
+        // v6.2.7: Always use write buffer - cloud storage benefits from batching
+        if (this.nounWriteBuffer) {
+            this.logger.trace(`📝 BUFFERING: Adding noun ${node.id} to write buffer`);
+            // v6.2.6: Populate cache BEFORE buffering for read-after-write consistency
             if (node.vector && Array.isArray(node.vector) && node.vector.length > 0) {
                 this.nounCacheManager.set(node.id, node);
             }
             await this.nounWriteBuffer.add(node.id, node);
             return;
         }
-        else if (!this.highVolumeMode) {
-            this.logger.trace(`📝 DIRECT WRITE: Saving noun ${node.id} directly (high-volume mode inactive)`);
-        }
-        // Direct write in normal mode
+        // Fallback to direct write if buffer not initialized (shouldn't happen after init)
         await this.saveNodeDirect(node);
     }
     /**
@@ -776,20 +739,19 @@ export class AzureBlobStorage extends BaseStorage {
     // v5.4.0: Removed saveVerb_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Save an edge to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     async saveEdge(edge) {
         await this.ensureInitialized();
-        // Check volume mode
-        this.checkVolumeMode();
-        // Use write buffer in high-volume mode
-        if (this.highVolumeMode && this.verbWriteBuffer) {
+        // v6.2.7: Always use write buffer - cloud storage benefits from batching
+        if (this.verbWriteBuffer) {
             this.logger.trace(`📝 BUFFERING: Adding verb ${edge.id} to write buffer`);
-            // v6.2.6: CRITICAL FIX - Populate cache BEFORE buffering for read-after-write consistency
+            // v6.2.6: Populate cache BEFORE buffering for read-after-write consistency
             this.verbCacheManager.set(edge.id, edge);
             await this.verbWriteBuffer.add(edge.id, edge);
             return;
         }
-        // Direct write in normal mode
+        // Fallback to direct write if buffer not initialized (shouldn't happen after init)
         await this.saveEdgeDirect(edge);
     }
     /**

package/dist/storage/adapters/gcsStorage.d.ts

@@ -54,10 +54,6 @@ export declare class GcsStorage extends BaseStorage {
     private nounWriteBuffer;
     private verbWriteBuffer;
     private requestCoalescer;
-    private highVolumeMode;
-    private lastVolumeCheck;
-    private volumeCheckInterval;
-    private forceHighVolumeMode;
     private nounCacheManager;
     private verbCacheManager;
     private logger;
@@ -133,10 +129,6 @@ export declare class GcsStorage extends BaseStorage {
      * @param requestId Request ID from applyBackpressure()
      */
     private releaseBackpressure;
-    /**
-     * Check if high-volume mode should be enabled
-     */
-    private checkVolumeMode;
     /**
      * Flush noun buffer to GCS
      */
@@ -147,6 +139,7 @@ export declare class GcsStorage extends BaseStorage {
     private flushVerbBuffer;
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     protected saveNode(node: HNSWNode): Promise<void>;
     /**
@@ -212,6 +205,7 @@ export declare class GcsStorage extends BaseStorage {
     protected listObjectsUnderPath(prefix: string): Promise<string[]>;
     /**
      * Save an edge to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     protected saveEdge(edge: Edge): Promise<void>;
     /**

package/dist/storage/adapters/gcsStorage.js

@@ -63,11 +63,6 @@ export class GcsStorage extends BaseStorage {
         this.verbWriteBuffer = null;
         // Request coalescer for deduplication
         this.requestCoalescer = null;
-        // High-volume mode detection - MUCH more aggressive
-        this.highVolumeMode = false;
-        this.lastVolumeCheck = 0;
-        this.volumeCheckInterval = 1000; // Check every second, not 5
-        this.forceHighVolumeMode = false; // Environment variable override
         // Module logger
         this.logger = createModuleLogger('GcsStorage');
         // v5.4.0: HNSW mutex locks to prevent read-modify-write races
@@ -92,12 +87,7 @@ export class GcsStorage extends BaseStorage {
         // Initialize cache managers
         this.nounCacheManager = new CacheManager(options.cacheConfig);
         this.verbCacheManager = new CacheManager(options.cacheConfig);
-        // Check for high-volume mode override
-        if (typeof process !== 'undefined' && process.env?.BRAINY_FORCE_HIGH_VOLUME === 'true') {
-            this.forceHighVolumeMode = true;
-            this.highVolumeMode = true;
-            prodLog.info('🚀 High-volume mode FORCED via BRAINY_FORCE_HIGH_VOLUME environment variable');
-        }
+        // v6.2.7: Write buffering always enabled - no env var check needed
     }
     /**
      * Initialize the storage adapter
@@ -251,29 +241,7 @@ export class GcsStorage extends BaseStorage {
             this.backpressure.releasePermission(requestId, success);
         }
     }
-    /**
-     * Check if high-volume mode should be enabled
-     */
-    checkVolumeMode() {
-        if (this.forceHighVolumeMode) {
-            return; // Already forced on
-        }
-        const now = Date.now();
-        if (now - this.lastVolumeCheck < this.volumeCheckInterval) {
-            return;
-        }
-        this.lastVolumeCheck = now;
-        // Enable high-volume mode if we have many pending operations
-        const shouldEnable = this.pendingOperations > 20;
-        if (shouldEnable && !this.highVolumeMode) {
-            this.highVolumeMode = true;
-            prodLog.info('🚀 High-volume mode ENABLED (pending operations:', this.pendingOperations, ')');
-        }
-        else if (!shouldEnable && this.highVolumeMode && !this.forceHighVolumeMode) {
-            this.highVolumeMode = false;
-            prodLog.info('🐌 High-volume mode DISABLED (pending operations:', this.pendingOperations, ')');
-        }
-    }
+    // v6.2.7: Removed checkVolumeMode() - write buffering always enabled for cloud storage
     /**
      * Flush noun buffer to GCS
      */
@@ -305,27 +273,21 @@ export class GcsStorage extends BaseStorage {
     // v5.4.0: Removed saveNoun_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     async saveNode(node) {
         await this.ensureInitialized();
-        // ALWAYS check if we should use high-volume mode (critical for detection)
-        this.checkVolumeMode();
-        // Use write buffer in high-volume mode
-        if (this.highVolumeMode && this.nounWriteBuffer) {
-            this.logger.trace(`📝 BUFFERING: Adding noun ${node.id} to write buffer (high-volume mode active)`);
-            // v6.2.6: CRITICAL FIX - Populate cache BEFORE buffering for read-after-write consistency
-            // Without this, add() returns but relate() can't find the entity (GCS production bug)
-            // The buffer flushes asynchronously, but cache ensures immediate reads succeed
+        // v6.2.7: Always use write buffer - cloud storage benefits from batching
+        if (this.nounWriteBuffer) {
+            this.logger.trace(`📝 BUFFERING: Adding noun ${node.id} to write buffer`);
+            // v6.2.6: Populate cache BEFORE buffering for read-after-write consistency
             if (node.vector && Array.isArray(node.vector) && node.vector.length > 0) {
                 this.nounCacheManager.set(node.id, node);
             }
             await this.nounWriteBuffer.add(node.id, node);
             return;
         }
-        else if (!this.highVolumeMode) {
-            this.logger.trace(`📝 DIRECT WRITE: Saving noun ${node.id} directly (high-volume mode inactive)`);
-        }
-        // Direct write in normal mode
+        // Fallback to direct write if buffer not initialized (shouldn't happen after init)
         await this.saveNodeDirect(node);
     }
     /**
@@ -646,21 +608,19 @@ export class GcsStorage extends BaseStorage {
     // v5.4.0: Removed saveVerb_internal - now inherit from BaseStorage's type-first implementation
     /**
      * Save an edge to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     async saveEdge(edge) {
         await this.ensureInitialized();
-        // Check volume mode
-        this.checkVolumeMode();
-        // Use write buffer in high-volume mode
-        if (this.highVolumeMode && this.verbWriteBuffer) {
+        // v6.2.7: Always use write buffer - cloud storage benefits from batching
+        if (this.verbWriteBuffer) {
             this.logger.trace(`📝 BUFFERING: Adding verb ${edge.id} to write buffer`);
-            // v6.2.6: CRITICAL FIX - Populate cache BEFORE buffering for read-after-write consistency
-            // Without this, relate() might not find the verb immediately after creation
+            // v6.2.6: Populate cache BEFORE buffering for read-after-write consistency
             this.verbCacheManager.set(edge.id, edge);
             await this.verbWriteBuffer.add(edge.id, edge);
             return;
         }
-        // Direct write in normal mode
+        // Fallback to direct write if buffer not initialized (shouldn't happen after init)
         await this.saveEdgeDirect(edge);
     }
     /**

package/dist/storage/adapters/r2Storage.d.ts

@@ -58,10 +58,6 @@ export declare class R2Storage extends BaseStorage {
     private nounWriteBuffer;
     private verbWriteBuffer;
     private requestCoalescer;
-    private highVolumeMode;
-    private lastVolumeCheck;
-    private volumeCheckInterval;
-    private forceHighVolumeMode;
     private nounCacheManager;
     private verbCacheManager;
     private logger;
@@ -139,10 +135,6 @@ export declare class R2Storage extends BaseStorage {
      * Release backpressure after completing an operation
      */
     private releaseBackpressure;
-    /**
-     * Check if high-volume mode should be enabled
-     */
-    private checkVolumeMode;
     /**
      * Flush noun buffer to R2
      */
@@ -153,6 +145,7 @@ export declare class R2Storage extends BaseStorage {
     private flushVerbBuffer;
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     protected saveNode(node: HNSWNode): Promise<void>;
     /**
@@ -179,6 +172,10 @@ export declare class R2Storage extends BaseStorage {
      * List all objects under a specific prefix in R2
      */
     protected listObjectsUnderPath(prefix: string): Promise<string[]>;
+    /**
+     * Save an edge to storage
+     * v6.2.7: Always uses write buffer for consistent performance
+     */
     protected saveEdge(edge: Edge): Promise<void>;
     private saveEdgeDirect;
     protected getEdge(id: string): Promise<Edge | null>;

package/dist/storage/adapters/r2Storage.js

@@ -65,11 +65,6 @@ export class R2Storage extends BaseStorage {
         this.verbWriteBuffer = null;
         // Request coalescer for deduplication
         this.requestCoalescer = null;
-        // High-volume mode detection (R2-specific thresholds)
-        this.highVolumeMode = false;
-        this.lastVolumeCheck = 0;
-        this.volumeCheckInterval = 800; // Check more frequently on R2
-        this.forceHighVolumeMode = false;
         // Module logger
         this.logger = createModuleLogger('R2Storage');
         // v5.4.0: HNSW mutex locks to prevent read-modify-write races
@@ -94,12 +89,7 @@ export class R2Storage extends BaseStorage {
             warmCacheTTL: options.cacheConfig?.warmCacheTTL || 3600000 // 1 hour
         });
         this.verbCacheManager = new CacheManager(options.cacheConfig);
-        // Check for high-volume mode override
-        if (typeof process !== 'undefined' && process.env?.BRAINY_FORCE_HIGH_VOLUME === 'true') {
-            this.forceHighVolumeMode = true;
-            this.highVolumeMode = true;
-            prodLog.info('🚀 R2: High-volume mode FORCED via environment variable');
-        }
+        // v6.2.7: Write buffering always enabled - no env var check needed
     }
     /**
      * Get R2-optimized batch configuration with native batch API support
@@ -295,29 +285,7 @@ export class R2Storage extends BaseStorage {
             this.backpressure.releasePermission(requestId, success);
         }
     }
-    /**
-     * Check if high-volume mode should be enabled
-     */
-    checkVolumeMode() {
-        if (this.forceHighVolumeMode) {
-            return;
-        }
-        const now = Date.now();
-        if (now - this.lastVolumeCheck < this.volumeCheckInterval) {
-            return;
-        }
-        this.lastVolumeCheck = now;
-        // R2 threshold: enable at 15 pending operations (lower than S3/GCS)
-        const shouldEnable = this.pendingOperations > 15;
-        if (shouldEnable && !this.highVolumeMode) {
-            this.highVolumeMode = true;
-            prodLog.info('🚀 R2: High-volume mode ENABLED (pending:', this.pendingOperations, ')');
-        }
-        else if (!shouldEnable && this.highVolumeMode && !this.forceHighVolumeMode) {
-            this.highVolumeMode = false;
-            prodLog.info('🐌 R2: High-volume mode DISABLED (pending:', this.pendingOperations, ')');
-        }
-    }
+    // v6.2.7: Removed checkVolumeMode() - write buffering always enabled for cloud storage
     /**
      * Flush noun buffer to R2
      */
@@ -348,22 +316,21 @@ export class R2Storage extends BaseStorage {
     }
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     async saveNode(node) {
         await this.ensureInitialized();
-        this.checkVolumeMode();
-        // Use write buffer in high-volume mode
-        if (this.highVolumeMode && this.nounWriteBuffer) {
+        // v6.2.7: Always use write buffer - cloud storage benefits from batching
+        if (this.nounWriteBuffer) {
             this.logger.trace(`📝 BUFFERING: Adding noun ${node.id} to write buffer`);
-            // v6.2.6: CRITICAL FIX - Populate cache BEFORE buffering for read-after-write consistency
-            // Without this, add() returns but relate() can't find the entity (cloud storage production bug)
+            // v6.2.6: Populate cache BEFORE buffering for read-after-write consistency
             if (node.vector && Array.isArray(node.vector) && node.vector.length > 0) {
                 this.nounCacheManager.set(node.id, node);
             }
             await this.nounWriteBuffer.add(node.id, node);
             return;
         }
-        // Direct write in normal mode
+        // Fallback to direct write if buffer not initialized (shouldn't happen after init)
         await this.saveNodeDirect(node);
     }
     /**
@@ -572,15 +539,20 @@ export class R2Storage extends BaseStorage {
         }
     }
     // Verb storage methods (similar to noun methods - implementing key methods for space)
+    /**
+     * Save an edge to storage
+     * v6.2.7: Always uses write buffer for consistent performance
+     */
     async saveEdge(edge) {
         await this.ensureInitialized();
-        this.checkVolumeMode();
-        if (this.highVolumeMode && this.verbWriteBuffer) {
-            // v6.2.6: CRITICAL FIX - Populate cache BEFORE buffering for read-after-write consistency
+        // v6.2.7: Always use write buffer - cloud storage benefits from batching
+        if (this.verbWriteBuffer) {
+            // v6.2.6: Populate cache BEFORE buffering for read-after-write consistency
             this.verbCacheManager.set(edge.id, edge);
             await this.verbWriteBuffer.add(edge.id, edge);
             return;
         }
+        // Fallback to direct write if buffer not initialized (shouldn't happen after init)
         await this.saveEdgeDirect(edge);
     }
     async saveEdgeDirect(edge) {

package/dist/storage/adapters/s3CompatibleStorage.d.ts

@@ -73,10 +73,6 @@ export declare class S3CompatibleStorage extends BaseStorage {
     private cacheSync?;
     private readWriteSeparation?;
     private requestCoalescer;
-    private highVolumeMode;
-    private lastVolumeCheck;
-    private volumeCheckInterval;
-    private forceHighVolumeMode;
     private operationExecutors;
     private nounCacheManager;
     private verbCacheManager;
@@ -193,10 +189,6 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * Initialize request coalescer
      */
     private initializeCoalescer;
-    /**
-     * Check if we should enable high-volume mode
-     */
-    private checkVolumeMode;
     /**
      * Bulk write nouns to S3
      */
@@ -239,6 +231,7 @@ export declare class S3CompatibleStorage extends BaseStorage {
     private getBatchSize;
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     protected saveNode(node: HNSWNode): Promise<void>;
     /**

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -78,11 +78,6 @@ export class S3CompatibleStorage extends BaseStorage {
         // ShardManager is no longer used - sharding is deterministic
         // Request coalescer for deduplication
         this.requestCoalescer = null;
-        // High-volume mode detection - MUCH more aggressive
-        this.highVolumeMode = false;
-        this.lastVolumeCheck = 0;
-        this.volumeCheckInterval = 1000; // Check every second, not 5
-        this.forceHighVolumeMode = false; // Environment variable override
         // Module logger
         this.logger = createModuleLogger('S3Storage');
         // v5.4.0: HNSW mutex locks to prevent read-modify-write races
@@ -526,79 +521,7 @@ export class S3CompatibleStorage extends BaseStorage {
             await this.processCoalescedBatch(batch);
         });
     }
-    /**
-     * Check if we should enable high-volume mode
-     */
-    checkVolumeMode() {
-        const now = Date.now();
-        if (now - this.lastVolumeCheck < this.volumeCheckInterval) {
-            return;
-        }
-        this.lastVolumeCheck = now;
-        // Check environment variable override
-        const envThreshold = process.env.BRAINY_BUFFER_THRESHOLD;
-        const threshold = envThreshold ? parseInt(envThreshold) : 0; // Default to 0 for immediate activation!
-        // Force enable from environment
-        if (process.env.BRAINY_FORCE_BUFFERING === 'true') {
-            this.forceHighVolumeMode = true;
-        }
-        // Get metrics
-        const backpressureStatus = this.backpressure.getStatus();
-        const socketMetrics = this.socketManager.getMetrics();
-        // Reasonable high-volume detection - only activate under real load
-        const isTestEnvironment = process.env.NODE_ENV === 'test';
-        const explicitlyDisabled = process.env.BRAINY_FORCE_BUFFERING === 'false';
-        // Use reasonable thresholds instead of emergency aggressive ones
-        const reasonableThreshold = Math.max(threshold, 10); // At least 10 pending operations
-        const highSocketUtilization = 0.8; // 80% socket utilization 
-        const highRequestRate = 50; // 50 requests per second
-        const significantErrors = 5; // 5 consecutive errors
-        const shouldEnableHighVolume = !isTestEnvironment && // Disable in test environment
-            !explicitlyDisabled && // Allow explicit disabling
-            (this.forceHighVolumeMode || // Environment override
-                backpressureStatus.queueLength >= reasonableThreshold || // High queue backlog
-                socketMetrics.pendingRequests >= reasonableThreshold || // Many pending requests
-                this.pendingOperations >= reasonableThreshold || // Many pending ops
-                socketMetrics.socketUtilization >= highSocketUtilization || // High socket pressure
-                (socketMetrics.requestsPerSecond >= highRequestRate) || // High request rate
-                (this.consecutiveErrors >= significantErrors)); // Significant error pattern
-        if (shouldEnableHighVolume && !this.highVolumeMode) {
-            this.highVolumeMode = true;
-            this.logger.warn(`🚨 HIGH-VOLUME MODE ACTIVATED 🚨`);
-            this.logger.warn(`  Queue Length: ${backpressureStatus.queueLength}`);
-            this.logger.warn(`  Pending Requests: ${socketMetrics.pendingRequests}`);
-            this.logger.warn(`  Pending Operations: ${this.pendingOperations}`);
-            this.logger.warn(`  Socket Utilization: ${(socketMetrics.socketUtilization * 100).toFixed(1)}%`);
-            this.logger.warn(`  Requests/sec: ${socketMetrics.requestsPerSecond}`);
-            this.logger.warn(`  Consecutive Errors: ${this.consecutiveErrors}`);
-            this.logger.warn(`  Threshold: ${threshold}`);
-            // Adjust buffer parameters for high volume
-            const queueLength = Math.max(backpressureStatus.queueLength, socketMetrics.pendingRequests, 100);
-            if (this.nounWriteBuffer) {
-                this.nounWriteBuffer.adjustForLoad(queueLength);
-                const stats = this.nounWriteBuffer.getStats();
-                this.logger.warn(`  Noun Buffer: ${stats.bufferSize} items, ${stats.totalWrites} total writes`);
-            }
-            if (this.verbWriteBuffer) {
-                this.verbWriteBuffer.adjustForLoad(queueLength);
-                const stats = this.verbWriteBuffer.getStats();
-                this.logger.warn(`  Verb Buffer: ${stats.bufferSize} items, ${stats.totalWrites} total writes`);
-            }
-            if (this.requestCoalescer) {
-                this.requestCoalescer.adjustParameters(queueLength);
-                const sizes = this.requestCoalescer.getQueueSizes();
-                this.logger.warn(`  Coalescer: ${sizes.total} queued operations`);
-            }
-        }
-        else if (!shouldEnableHighVolume && this.highVolumeMode && !this.forceHighVolumeMode) {
-            this.highVolumeMode = false;
-            this.logger.info('✅ High-volume mode deactivated - load normalized');
-        }
-        // Log current status every 10 checks when in high-volume mode
-        if (this.highVolumeMode && (now % 10000) < this.volumeCheckInterval) {
-            this.logger.info(`📊 High-volume mode status: Queue=${backpressureStatus.queueLength}, Pending=${socketMetrics.pendingRequests}, Sockets=${(socketMetrics.socketUtilization * 100).toFixed(1)}%`);
-        }
-    }
+    // v6.2.7: Removed checkVolumeMode() - write buffering always enabled for cloud storage
     /**
      * Bulk write nouns to S3
      */
@@ -802,26 +725,21 @@ export class S3CompatibleStorage extends BaseStorage {
     // v5.4.0: Removed 10 *_internal method overrides (lines 984-2069) - now inherit from BaseStorage's type-first implementation
     /**
      * Save a node to storage
+     * v6.2.7: Always uses write buffer for consistent performance
      */
     async saveNode(node) {
         await this.ensureInitialized();
-        // ALWAYS check if we should use high-volume mode (critical for detection)
-        this.checkVolumeMode();
-        // Use write buffer in high-volume mode
-        if (this.highVolumeMode && this.nounWriteBuffer) {
-            this.logger.trace(`📝 BUFFERING: Adding noun ${node.id} to write buffer (high-volume mode active)`);
-            // v6.2.6: CRITICAL FIX - Populate cache BEFORE buffering for read-after-write consistency
-            // Without this, add() returns but relate() can't find the entity (cloud storage production bug)
-            // The buffer flushes asynchronously, but cache ensures immediate reads succeed
+        // v6.2.7: Always use write buffer - cloud storage benefits from batching
+        if (this.nounWriteBuffer) {
+            this.logger.trace(`📝 BUFFERING: Adding noun ${node.id} to write buffer`);
+            // v6.2.6: Populate cache BEFORE buffering for read-after-write consistency
             if (node.vector && Array.isArray(node.vector) && node.vector.length > 0) {
                 this.nounCacheManager.set(node.id, node);
             }
             await this.nounWriteBuffer.add(node.id, node);
             return;
         }
-        else if (!this.highVolumeMode) {
-            this.logger.trace(`📝 DIRECT WRITE: Saving noun ${node.id} directly (high-volume mode inactive)`);
-        }
+        // Fallback to direct write if buffer not initialized (shouldn't happen after init)
         // Apply backpressure before starting operation
         const requestId = await this.applyBackpressure();
         try {

package/dist/types/brainy.types.d.ts

@@ -552,6 +552,7 @@ export interface BrainyConfig {
     disableAutoOptimize?: boolean;
     batchWrites?: boolean;
     maxConcurrentOperations?: number;
+    hnswPersistMode?: 'immediate' | 'deferred';
     maxQueryLimit?: number;
     reservedQueryMemory?: number;
     verbose?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "6.2.6",
+  "version": "6.2.8",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",