@soulcraft/brainy 5.10.3 → 5.11.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [5.10.4](https://github.com/soulcraftlabs/brainy/compare/v5.10.3...v5.10.4) (2025-11-17)
+
+- fix: critical clear() data persistence regression (v5.10.4) (aba1563)
+
+
 ### [5.10.3](https://github.com/soulcraftlabs/brainy/compare/v5.10.2...v5.10.3) (2025-11-14)
 
 - docs: add production service architecture guide to public docs (759e7fa)

package/dist/brainy.d.ts

@@ -1009,6 +1009,51 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
         timestamp: number;
         metadata?: Record<string, any>;
     }>>;
+    /**
+     * Stream commit history (memory-efficient)
+     *
+     * Use this for large commit histories (1000s of snapshots) where memory
+     * efficiency is critical. Yields commits one at a time without accumulating
+     * them in memory.
+     *
+     * For small histories (< 100 commits), use getHistory() for simpler API.
+     *
+     * @param options - History options
+     * @param options.limit - Maximum number of commits to stream
+     * @param options.since - Only include commits after this timestamp
+     * @param options.until - Only include commits before this timestamp
+     * @param options.author - Filter by author name
+     *
+     * @yields Commit metadata in reverse chronological order (newest first)
+     *
+     * @example
+     * ```typescript
+     * // Stream all commits without memory accumulation
+     * for await (const commit of brain.streamHistory({ limit: 10000 })) {
+     *   console.log(`${commit.timestamp}: ${commit.message}`)
+     * }
+     *
+     * // Stream with filtering
+     * for await (const commit of brain.streamHistory({
+     *   author: 'alice',
+     *   since: Date.now() - 86400000  // Last 24 hours
+     * })) {
+     *   // Process commit
+     * }
+     * ```
+     */
+    streamHistory(options?: {
+        limit?: number;
+        since?: number;
+        until?: number;
+        author?: string;
+    }): AsyncIterableIterator<{
+        hash: string;
+        message: string;
+        author: string;
+        timestamp: number;
+        metadata?: Record<string, any>;
+    }>;
     /**
      * Get total count of nouns - O(1) operation
      * @returns Promise that resolves to the total number of nouns
@@ -1019,6 +1064,50 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * @returns Promise that resolves to the total number of verbs
      */
     getVerbCount(): Promise<number>;
+    /**
+     * Get memory statistics and limits (v5.11.0)
+     *
+     * Returns detailed memory information including:
+     * - Current heap usage
+     * - Container memory limits (if detected)
+     * - Query limits and how they were calculated
+     * - Memory allocation recommendations
+     *
+     * Use this to debug why query limits are low or to understand
+     * memory allocation in production environments.
+     *
+     * @returns Memory statistics and configuration
+     *
+     * @example
+     * ```typescript
+     * const stats = brain.getMemoryStats()
+     * console.log(`Query limit: ${stats.limits.maxQueryLimit}`)
+     * console.log(`Basis: ${stats.limits.basis}`)
+     * console.log(`Free memory: ${Math.round(stats.memory.free / 1024 / 1024)}MB`)
+     * ```
+     */
+    getMemoryStats(): {
+        memory: {
+            heapUsed: number;
+            heapTotal: number;
+            external: number;
+            rss: number;
+            free: number;
+            total: number;
+            containerLimit: number | null;
+        };
+        limits: {
+            maxQueryLimit: number;
+            maxQueryLength: number;
+            maxVectorDimensions: number;
+            basis: 'override' | 'reservedMemory' | 'containerMemory' | 'freeMemory';
+        };
+        config: {
+            maxQueryLimit?: number;
+            reservedQueryMemory?: number;
+        };
+        recommendations?: string[];
+    };
     /**
      * Neural API - Advanced AI operations
      */

package/dist/brainy.js

@@ -25,6 +25,7 @@ import { NULL_HASH } from './storage/cow/constants.js';
 import { createPipeline } from './streaming/pipeline.js';
 import { configureLogger, LogLevel } from './utils/logger.js';
 import { TransactionManager } from './transaction/TransactionManager.js';
+import { ValidationConfig } from './utils/paramValidation.js';
 import { SaveNounMetadataOperation, SaveNounOperation, AddToTypeAwareHNSWOperation, AddToHNSWOperation, AddToMetadataIndexOperation, SaveVerbMetadataOperation, SaveVerbOperation, AddToGraphIndexOperation, RemoveFromHNSWOperation, RemoveFromTypeAwareHNSWOperation, RemoveFromMetadataIndexOperation, RemoveFromGraphIndexOperation, UpdateNounMetadataOperation, DeleteNounMetadataOperation, DeleteVerbMetadataOperation } from './transaction/operations/index.js';
 import { DistributedCoordinator, ShardManager, CacheSync, ReadWriteSeparation } from './distributed/index.js';
 import { NounType } from './types/graphTypes.js';
@@ -45,6 +46,14 @@ export class Brainy {
         this.lazyRebuildPromise = null;
         // Normalize configuration with defaults
         this.config = this.normalizeConfig(config);
+        // Configure memory limits (v5.11.0)
+        // This must happen early, before any validation occurs
+        if (this.config.maxQueryLimit !== undefined || this.config.reservedQueryMemory !== undefined) {
+            ValidationConfig.reconfigure({
+                maxQueryLimit: this.config.maxQueryLimit,
+                reservedQueryMemory: this.config.reservedQueryMemory
+            });
+        }
         // Setup core components
         this.distance = cosineDistance;
         this.embedder = this.setupEmbedder();
@@ -1829,6 +1838,10 @@ export class Brainy {
                 // Recreate index if no clear method
                 this.index = this.setupIndex();
             }
+            // v5.10.4: Recreate metadata index to clear cached data
+            // Bug: Metadata index cache was not being cleared, causing find() with type filters to return stale data
+            this.metadataIndex = new MetadataIndexManager(this.storage);
+            await this.metadataIndex.init();
             // Reset dimensions
             this.dimensions = undefined;
             // Clear any cached sub-APIs
@@ -2684,6 +2697,67 @@ export class Brainy {
             }));
         });
     }
+    /**
+     * Stream commit history (memory-efficient)
+     *
+     * Use this for large commit histories (1000s of snapshots) where memory
+     * efficiency is critical. Yields commits one at a time without accumulating
+     * them in memory.
+     *
+     * For small histories (< 100 commits), use getHistory() for simpler API.
+     *
+     * @param options - History options
+     * @param options.limit - Maximum number of commits to stream
+     * @param options.since - Only include commits after this timestamp
+     * @param options.until - Only include commits before this timestamp
+     * @param options.author - Filter by author name
+     *
+     * @yields Commit metadata in reverse chronological order (newest first)
+     *
+     * @example
+     * ```typescript
+     * // Stream all commits without memory accumulation
+     * for await (const commit of brain.streamHistory({ limit: 10000 })) {
+     *   console.log(`${commit.timestamp}: ${commit.message}`)
+     * }
+     *
+     * // Stream with filtering
+     * for await (const commit of brain.streamHistory({
+     *   author: 'alice',
+     *   since: Date.now() - 86400000  // Last 24 hours
+     * })) {
+     *   // Process commit
+     * }
+     * ```
+     */
+    async *streamHistory(options) {
+        await this.ensureInitialized();
+        if (!('commitLog' in this.storage) || !('refManager' in this.storage)) {
+            throw new Error('History streaming requires COW-enabled storage (v5.0.0+)');
+        }
+        const commitLog = this.storage.commitLog;
+        const currentBranch = await this.getCurrentBranch();
+        const blobStorage = this.storage.blobStorage;
+        // Stream commits from CommitLog
+        for await (const commit of commitLog.streamHistory(currentBranch, {
+            maxCount: options?.limit,
+            since: options?.since,
+            until: options?.until
+        })) {
+            // Filter by author if specified
+            if (options?.author && commit.author !== options.author) {
+                continue;
+            }
+            // Map to expected format (compute hash for commit)
+            yield {
+                hash: blobStorage.constructor.hash(Buffer.from(JSON.stringify(commit))),
+                message: commit.message,
+                author: commit.author,
+                timestamp: commit.timestamp,
+                metadata: commit.metadata
+            };
+        }
+    }
     /**
      * Get total count of nouns - O(1) operation
      * @returns Promise that resolves to the total number of nouns
@@ -2700,6 +2774,86 @@ export class Brainy {
         await this.ensureInitialized();
         return this.storage.getVerbCount();
     }
+    /**
+     * Get memory statistics and limits (v5.11.0)
+     *
+     * Returns detailed memory information including:
+     * - Current heap usage
+     * - Container memory limits (if detected)
+     * - Query limits and how they were calculated
+     * - Memory allocation recommendations
+     *
+     * Use this to debug why query limits are low or to understand
+     * memory allocation in production environments.
+     *
+     * @returns Memory statistics and configuration
+     *
+     * @example
+     * ```typescript
+     * const stats = brain.getMemoryStats()
+     * console.log(`Query limit: ${stats.limits.maxQueryLimit}`)
+     * console.log(`Basis: ${stats.limits.basis}`)
+     * console.log(`Free memory: ${Math.round(stats.memory.free / 1024 / 1024)}MB`)
+     * ```
+     */
+    getMemoryStats() {
+        const config = ValidationConfig.getInstance();
+        const heapStats = process.memoryUsage ? process.memoryUsage() : {
+            heapUsed: 0,
+            heapTotal: 0,
+            external: 0,
+            rss: 0
+        };
+        // Get system memory info
+        let freeMemory = 0;
+        let totalMemory = 0;
+        if (typeof window === 'undefined') {
+            try {
+                const os = require('node:os');
+                freeMemory = os.freemem();
+                totalMemory = os.totalmem();
+            }
+            catch (e) {
+                // OS module not available
+            }
+        }
+        const stats = {
+            memory: {
+                heapUsed: heapStats.heapUsed,
+                heapTotal: heapStats.heapTotal,
+                external: heapStats.external,
+                rss: heapStats.rss,
+                free: freeMemory,
+                total: totalMemory,
+                containerLimit: config.detectedContainerLimit
+            },
+            limits: {
+                maxQueryLimit: config.maxLimit,
+                maxQueryLength: config.maxQueryLength,
+                maxVectorDimensions: config.maxVectorDimensions,
+                basis: config.limitBasis
+            },
+            config: {
+                maxQueryLimit: this.config.maxQueryLimit,
+                reservedQueryMemory: this.config.reservedQueryMemory
+            },
+            recommendations: []
+        };
+        // Generate recommendations based on stats
+        if (stats.limits.basis === 'freeMemory' && stats.memory.containerLimit) {
+            stats.recommendations.push(`Container detected (${Math.round(stats.memory.containerLimit / 1024 / 1024)}MB) but limits based on free memory. ` +
+                `Consider setting reservedQueryMemory config option for better limits.`);
+        }
+        if (stats.limits.maxQueryLimit < 5000 && stats.memory.containerLimit && stats.memory.containerLimit > 2 * 1024 * 1024 * 1024) {
+            stats.recommendations.push(`Query limit is low (${stats.limits.maxQueryLimit}) despite ${Math.round(stats.memory.containerLimit / 1024 / 1024 / 1024)}GB container. ` +
+                `Consider: new Brainy({ reservedQueryMemory: 1073741824 }) to reserve 1GB for queries.`);
+        }
+        if (stats.limits.basis === 'override') {
+            stats.recommendations.push(`Using explicit maxQueryLimit override (${stats.limits.maxQueryLimit}). ` +
+                `Auto-detection bypassed.`);
+        }
+        return stats;
+    }
     // ============= SUB-APIS =============
     /**
      * Neural API - Advanced AI operations
@@ -3989,7 +4143,10 @@ export class Brainy {
             disableMetrics: config?.disableMetrics ?? false,
             disableAutoOptimize: config?.disableAutoOptimize ?? false,
             batchWrites: config?.batchWrites ?? true,
-            maxConcurrentOperations: config?.maxConcurrentOperations ?? 10
+            maxConcurrentOperations: config?.maxConcurrentOperations ?? 10,
+            // Memory management options (v5.11.0)
+            maxQueryLimit: config?.maxQueryLimit ?? undefined,
+            reservedQueryMemory: config?.reservedQueryMemory ?? undefined
         };
     }
     /**

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

@@ -240,6 +240,16 @@ export declare class AzureBlobStorage extends BaseStorage {
         quota: number | null;
         details?: Record<string, any>;
     }>;
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker blob exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Save statistics data to storage
      */

package/dist/storage/adapters/azureBlobStorage.js

@@ -859,13 +859,11 @@ export class AzureBlobStorage extends BaseStorage {
                     await blockBlobClient.delete();
                 }
             }
-            // CRITICAL: Reset COW state to prevent automatic reinitialization
-            // When COW data is cleared, we must also clear the COW managers
-            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            // v5.11.0: Reset COW managers (but don't disable COW - it's always enabled)
+            // COW will re-initialize automatically on next use
             this.refManager = undefined;
             this.blobStorage = undefined;
             this.commitLog = undefined;
-            this.cowEnabled = false;
             // Clear caches
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();
@@ -908,6 +906,16 @@ export class AzureBlobStorage extends BaseStorage {
             };
         }
     }
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker blob exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Save statistics data to storage
      */

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

@@ -171,6 +171,16 @@ export declare class FileSystemStorage extends BaseStorage {
      * Provides progress tracking, backup options, and instance name confirmation
      */
     clearEnhanced(options?: import('../enhancedClearOperations.js').ClearOptions): Promise<import('../enhancedClearOperations.js').ClearResult>;
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker file exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Get information about storage usage and capacity
      */

package/dist/storage/adapters/fileSystemStorage.js

@@ -859,16 +859,13 @@ export class FileSystemStorage extends BaseStorage {
                 }
             }
         };
-        // Remove all files in the nouns directory
-        await removeDirectoryContents(this.nounsDir);
-        // Remove all files in the verbs directory
-        await removeDirectoryContents(this.verbsDir);
-        // Remove all files in the metadata directory
-        await removeDirectoryContents(this.metadataDir);
-        // Remove all files in the noun metadata directory
-        await removeDirectoryContents(this.nounMetadataDir);
-        // Remove all files in the verb metadata directory
-        await removeDirectoryContents(this.verbMetadataDir);
+        // v5.10.4: Clear the entire branches/ directory (branch-based storage)
+        // Bug fix: Data is stored in branches/main/entities/, not just entities/
+        // The branch-based structure was introduced for COW support
+        const branchesDir = path.join(this.rootDir, 'branches');
+        if (await this.directoryExists(branchesDir)) {
+            await removeDirectoryContents(branchesDir);
+        }
         // Remove all files in both system directories
         await removeDirectoryContents(this.systemDir);
         if (await this.directoryExists(this.indexDir)) {
@@ -881,13 +878,11 @@ export class FileSystemStorage extends BaseStorage {
         if (await this.directoryExists(cowDir)) {
             // Delete the entire _cow/ directory (not just contents)
             await fs.promises.rm(cowDir, { recursive: true, force: true });
-            // CRITICAL: Reset COW state to prevent automatic reinitialization
-            // When COW data is cleared, we must also clear the COW managers
-            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            // v5.11.0: Reset COW managers (but don't disable COW - it's always enabled)
+            // COW will re-initialize automatically on next use
             this.refManager = undefined;
             this.blobStorage = undefined;
             this.commitLog = undefined;
-            this.cowEnabled = false;
         }
         // Clear the statistics cache
         this.statisticsCache = null;
@@ -915,6 +910,16 @@ export class FileSystemStorage extends BaseStorage {
         }
         return result;
     }
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker file exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Get information about storage usage and capacity
      */

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

@@ -228,6 +228,16 @@ export declare class GcsStorage extends BaseStorage {
         quota: number | null;
         details?: Record<string, any>;
     }>;
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker object exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Save statistics data to storage
      */

package/dist/storage/adapters/gcsStorage.js

@@ -772,23 +772,18 @@ export class GcsStorage extends BaseStorage {
                     await file.delete();
                 }
             };
-            // Clear all data directories
-            await deleteObjectsWithPrefix(this.nounPrefix);
-            await deleteObjectsWithPrefix(this.verbPrefix);
-            await deleteObjectsWithPrefix(this.metadataPrefix);
-            await deleteObjectsWithPrefix(this.verbMetadataPrefix);
-            await deleteObjectsWithPrefix(this.systemPrefix);
-            // v5.6.1: Clear COW (copy-on-write) version control data
-            // This includes all git-like versioning data (commits, trees, blobs, refs)
-            // Must be deleted to fully clear all data including version history
+            // v5.11.0: Clear ALL data using correct paths
+            // Delete entire branches/ directory (includes ALL entities, ALL types, ALL VFS data, ALL forks)
+            await deleteObjectsWithPrefix('branches/');
+            // Delete COW version control data
             await deleteObjectsWithPrefix('_cow/');
-            // CRITICAL: Reset COW state to prevent automatic reinitialization
-            // When COW data is cleared, we must also clear the COW managers
-            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            // Delete system metadata
+            await deleteObjectsWithPrefix('_system/');
+            // v5.11.0: Reset COW managers (but don't disable COW - it's always enabled)
+            // COW will re-initialize automatically on next use
             this.refManager = undefined;
             this.blobStorage = undefined;
             this.commitLog = undefined;
-            this.cowEnabled = false;
             // Clear caches
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();
@@ -834,6 +829,16 @@ export class GcsStorage extends BaseStorage {
             };
         }
     }
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker object exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Save statistics data to storage
      */

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

@@ -101,6 +101,16 @@ export declare class HistoricalStorageAdapter extends BaseStorage {
         quota: number | null;
         details?: Record<string, any>;
     }>;
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: No-op for HistoricalStorageAdapter (read-only, doesn't manage COW)
+     * @returns Always false (read-only adapter doesn't manage COW state)
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * WRITE BLOCKED: Historical storage is read-only
      */

package/dist/storage/adapters/historicalStorageAdapter.js

@@ -226,6 +226,16 @@ export class HistoricalStorageAdapter extends BaseStorage {
             }
         };
     }
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: No-op for HistoricalStorageAdapter (read-only, doesn't manage COW)
+     * @returns Always false (read-only adapter doesn't manage COW state)
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     // ============= Override Write Methods (Read-Only) =============
     /**
      * WRITE BLOCKED: Historical storage is read-only

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

@@ -79,6 +79,16 @@ export declare class MemoryStorage extends BaseStorage {
         quota: number | null;
         details?: Record<string, any>;
     }>;
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: No-op for MemoryStorage (doesn't persist)
+     * @returns Always false (marker doesn't persist in memory)
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Save statistics data to storage
      * @param statistics The statistics data to save

package/dist/storage/adapters/memoryStorage.js

@@ -158,6 +158,16 @@ export class MemoryStorage extends BaseStorage {
             }
         };
     }
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: No-op for MemoryStorage (doesn't persist)
+     * @returns Always false (marker doesn't persist in memory)
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Save statistics data to storage
      * @param statistics The statistics data to save

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

@@ -94,6 +94,16 @@ export declare class OPFSStorage extends BaseStorage {
      * Clear all data from storage
      */
     clear(): Promise<void>;
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker file exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     private quotaWarningThreshold;
     private quotaCriticalThreshold;
     private lastQuotaCheck;

package/dist/storage/adapters/opfsStorage.js

@@ -42,6 +42,16 @@ export class OPFSStorage extends BaseStorage {
         this.statistics = null;
         this.activeLocks = new Set();
         this.lockPrefix = 'opfs-lock-';
+        /**
+         * Check if COW has been explicitly disabled via clear()
+         * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+         * @returns true if marker file exists, false otherwise
+         * @protected
+         */
+        /**
+         * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+         * COW is now always enabled - marker files are no longer used
+         */
         // Quota monitoring configuration (v4.0.0)
         this.quotaWarningThreshold = 0.8; // Warn at 80% usage
         this.quotaCriticalThreshold = 0.95; // Critical at 95% usage
@@ -393,13 +403,11 @@ export class OPFSStorage extends BaseStorage {
             try {
                 // Delete the entire _cow/ directory (not just contents)
                 await this.rootDir.removeEntry('_cow', { recursive: true });
-                // CRITICAL: Reset COW state to prevent automatic reinitialization
-                // When COW data is cleared, we must also clear the COW managers
-                // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+                // v5.11.0: Reset COW managers (but don't disable COW - it's always enabled)
+                // COW will re-initialize automatically on next use
                 this.refManager = undefined;
                 this.blobStorage = undefined;
                 this.commitLog = undefined;
-                this.cowEnabled = false;
             }
             catch (error) {
                 // Ignore if _cow directory doesn't exist (not all instances use COW)

package/dist/storage/adapters/r2Storage.js

@@ -771,22 +771,27 @@ export class R2Storage extends BaseStorage {
     async clear() {
         await this.ensureInitialized();
         prodLog.info('🧹 R2: Clearing all data from bucket...');
-        // Clear all prefixes (v5.6.1: includes _cow/ for version control data)
-        // _cow/ stores all git-like versioning data (commits, trees, blobs, refs)
-        // Must be deleted to fully clear all data including version history
-        for (const prefix of [this.nounPrefix, this.verbPrefix, this.metadataPrefix, this.verbMetadataPrefix, this.systemPrefix, '_cow/']) {
-            const objects = await this.listObjectsUnderPath(prefix);
-            for (const key of objects) {
-                await this.deleteObjectFromPath(key);
-            }
-        }
-        // CRITICAL: Reset COW state to prevent automatic reinitialization
-        // When COW data is cleared, we must also clear the COW managers
-        // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+        // v5.11.0: Clear ALL data using correct paths
+        // Delete entire branches/ directory (includes ALL entities, ALL types, ALL VFS data, ALL forks)
+        const branchObjects = await this.listObjectsUnderPath('branches/');
+        for (const key of branchObjects) {
+            await this.deleteObjectFromPath(key);
+        }
+        // Delete COW version control data
+        const cowObjects = await this.listObjectsUnderPath('_cow/');
+        for (const key of cowObjects) {
+            await this.deleteObjectFromPath(key);
+        }
+        // Delete system metadata
+        const systemObjects = await this.listObjectsUnderPath('_system/');
+        for (const key of systemObjects) {
+            await this.deleteObjectFromPath(key);
+        }
+        // v5.11.0: Reset COW managers (but don't disable COW - it's always enabled)
+        // COW will re-initialize automatically on next use
         this.refManager = undefined;
         this.blobStorage = undefined;
         this.commitLog = undefined;
-        this.cowEnabled = false;
         this.nounCacheManager.clear();
         this.verbCacheManager.clear();
         this.totalNounCount = 0;

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

@@ -373,6 +373,16 @@ export declare class S3CompatibleStorage extends BaseStorage {
         quota: number | null;
         details?: Record<string, any>;
     }>;
+    /**
+     * Check if COW has been explicitly disabled via clear()
+     * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+     * @returns true if marker object exists, false otherwise
+     * @protected
+     */
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+     * COW is now always enabled - marker files are no longer used
+     */
     protected statisticsBatchUpdateTimerId: NodeJS.Timeout | null;
     protected statisticsModified: boolean;
     protected lastStatisticsFlushTime: number;

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -89,6 +89,16 @@ export class S3CompatibleStorage extends BaseStorage {
         this.hnswLocks = new Map();
         // Node cache to avoid redundant API calls
         this.nodeCache = new Map();
+        /**
+         * Check if COW has been explicitly disabled via clear()
+         * v5.10.4: Fixes bug where clear() doesn't persist across instance restarts
+         * @returns true if marker object exists, false otherwise
+         * @protected
+         */
+        /**
+         * v5.11.0: Removed checkClearMarker() and createClearMarker() methods
+         * COW is now always enabled - marker files are no longer used
+         */
         // Batch update timer ID
         this.statisticsBatchUpdateTimerId = null;
         // Flag to indicate if statistics have been modified since last save
@@ -1611,27 +1621,18 @@ export class S3CompatibleStorage extends BaseStorage {
                     }
                 }
             };
-            // Delete all objects in the nouns directory
-            await deleteObjectsWithPrefix(this.nounPrefix);
-            // Delete all objects in the verbs directory
-            await deleteObjectsWithPrefix(this.verbPrefix);
-            // Delete all objects in the noun metadata directory
-            await deleteObjectsWithPrefix(this.metadataPrefix);
-            // Delete all objects in the verb metadata directory
-            await deleteObjectsWithPrefix(this.verbMetadataPrefix);
-            // Delete all objects in the index directory
-            await deleteObjectsWithPrefix(this.indexPrefix);
-            // v5.6.1: Delete COW (copy-on-write) version control data
-            // This includes all git-like versioning data (commits, trees, blobs, refs)
-            // Must be deleted to fully clear all data including version history
+            // v5.11.0: Clear ALL data using correct paths
+            // Delete entire branches/ directory (includes ALL entities, ALL types, ALL VFS data, ALL forks)
+            await deleteObjectsWithPrefix('branches/');
+            // Delete COW version control data
             await deleteObjectsWithPrefix('_cow/');
-            // CRITICAL: Reset COW state to prevent automatic reinitialization
-            // When COW data is cleared, we must also clear the COW managers
-            // Otherwise initializeCOW() will auto-recreate initial commit on next operation
+            // Delete system metadata
+            await deleteObjectsWithPrefix('_system/');
+            // v5.11.0: Reset COW managers (but don't disable COW - it's always enabled)
+            // COW will re-initialize automatically on next use
             this.refManager = undefined;
             this.blobStorage = undefined;
             this.commitLog = undefined;
-            this.cowEnabled = false;
             // Clear the statistics cache
             this.statisticsCache = null;
             this.statisticsModified = false;

package/dist/storage/baseStorage.d.ts

@@ -58,7 +58,6 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
     blobStorage?: BlobStorage;
     commitLog?: CommitLog;
     currentBranch: string;
-    protected cowEnabled: boolean;
     protected nounCountsByType: Uint32Array<ArrayBuffer>;
     protected verbCountsByType: Uint32Array<ArrayBuffer>;
     protected nounTypeCache: Map<string, NounType>;
@@ -88,6 +87,8 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Called during init() to ensure all data is stored with branch prefixes from the start
      * RefManager/BlobStorage/CommitLog are lazy-initialized on first fork()
      * @param branch - Branch name to use (default: 'main')
+     *
+     * v5.11.0: COW is always enabled - this method now just sets the branch name (idempotent)
      */
     enableCOWLightweight(branch?: string): void;
     /**
@@ -119,6 +120,8 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * Read object with inheritance from parent branches (COW layer)
      * Tries current branch first, then walks commit history
      * @protected - Available to subclasses for COW implementation
+     *
+     * v5.11.0: COW is always enabled - always use branch-scoped paths with inheritance
      */
     protected readWithInheritance(path: string, branch?: string): Promise<any | null>;
     /**
@@ -137,6 +140,8 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * This enables fork to see parent's data in pagination operations
      *
      * Simplified approach: All branches inherit from main
+     *
+     * v5.11.0: COW is always enabled - always use inheritance
      */
     protected listObjectsWithInheritance(prefix: string, branch?: string): Promise<string[]>;
     /**
@@ -327,6 +332,10 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * This method should be implemented by each specific adapter
      */
     abstract clear(): Promise<void>;
+    /**
+     * v5.11.0: Removed checkClearMarker() and createClearMarker() abstract methods
+     * COW is now always enabled - marker files are no longer used
+     */
     /**
      * Get information about storage usage and capacity
      * This method should be implemented by each specific adapter

package/dist/storage/baseStorage.js

@@ -83,7 +83,7 @@ export class BaseStorage extends BaseStorageAdapter {
         // Memory footprint: Bounded by batch size (typically <1000 items during imports)
         this.writeCache = new Map();
         this.currentBranch = 'main';
-        this.cowEnabled = false;
+        // v5.11.0: Removed cowEnabled flag - COW is ALWAYS enabled (mandatory, cannot be disabled)
         // Type-first indexing support (v5.4.0)
         // Built into all storage adapters for billion-scale efficiency
         this.nounCountsByType = new Uint32Array(NOUN_TYPE_COUNT); // 168 bytes (Stage 3: 42 types)
@@ -191,13 +191,11 @@ export class BaseStorage extends BaseStorageAdapter {
      * Called during init() to ensure all data is stored with branch prefixes from the start
      * RefManager/BlobStorage/CommitLog are lazy-initialized on first fork()
      * @param branch - Branch name to use (default: 'main')
+     *
+     * v5.11.0: COW is always enabled - this method now just sets the branch name (idempotent)
      */
     enableCOWLightweight(branch = 'main') {
-        if (this.cowEnabled) {
-            return;
-        }
         this.currentBranch = branch;
-        this.cowEnabled = true;
         // RefManager/BlobStorage/CommitLog remain undefined until first fork()
     }
     /**
@@ -212,19 +210,15 @@ export class BaseStorage extends BaseStorageAdapter {
      * @returns Promise that resolves when COW is initialized
      */
     async initializeCOW(options) {
-        // v5.6.1: If COW was explicitly disabled (e.g., via clear()), don't reinitialize
-        // This prevents automatic recreation of COW data after clear() operations
-        if (this.cowEnabled === false) {
+        // v5.11.0: COW is ALWAYS enabled - idempotent initialization only
+        // Removed marker file check (cowEnabled flag removed, COW is mandatory)
+        // Check if RefManager already initialized (idempotent)
+        if (this.refManager && this.blobStorage && this.commitLog) {
             return;
         }
-        // Check if RefManager already initialized (full COW setup complete)
-        if (this.refManager) {
-            return;
-        }
-        // Enable lightweight COW if not already enabled
-        if (!this.cowEnabled) {
-            this.currentBranch = options?.branch || 'main';
-            this.cowEnabled = true;
+        // Set current branch if provided
+        if (options?.branch) {
+            this.currentBranch = options.branch;
         }
         // Create COWStorageAdapter bridge
         // This adapts BaseStorage's methods to the simple key-value interface
@@ -326,7 +320,7 @@ export class BaseStorage extends BaseStorageAdapter {
                 await this.refManager.setHead(this.currentBranch);
             }
         }
-        this.cowEnabled = true;
+        // v5.11.0: COW is always enabled - no flag to set
     }
     /**
      * Resolve branch-scoped path for COW isolation
@@ -340,9 +334,7 @@ export class BaseStorage extends BaseStorageAdapter {
         if (basePath.startsWith('_cow/')) {
             return basePath; // COW metadata is global across all branches
         }
-        if (!this.cowEnabled) {
-            return basePath; // COW disabled, use direct path
-        }
+        // v5.11.0: COW is always enabled - always use branch-scoped paths
         const targetBranch = branch || this.currentBranch || 'main';
         // Branch-scoped path: branches/<branch>/<basePath>
         return `branches/${targetBranch}/${basePath}`;
@@ -366,17 +358,10 @@ export class BaseStorage extends BaseStorageAdapter {
      * Read object with inheritance from parent branches (COW layer)
      * Tries current branch first, then walks commit history
      * @protected - Available to subclasses for COW implementation
+     *
+     * v5.11.0: COW is always enabled - always use branch-scoped paths with inheritance
      */
     async readWithInheritance(path, branch) {
-        if (!this.cowEnabled) {
-            // COW disabled: check write cache, then direct read
-            // v5.7.2: Check cache first for read-after-write consistency
-            const cachedData = this.writeCache.get(path);
-            if (cachedData !== undefined) {
-                return cachedData;
-            }
-            return this.readObjectFromPath(path);
-        }
         const targetBranch = branch || this.currentBranch || 'main';
         const branchPath = this.resolveBranchPath(path, targetBranch);
         // v5.7.2: Check write cache FIRST (synchronous, instant)
@@ -453,11 +438,10 @@ export class BaseStorage extends BaseStorageAdapter {
      * This enables fork to see parent's data in pagination operations
      *
      * Simplified approach: All branches inherit from main
+     *
+     * v5.11.0: COW is always enabled - always use inheritance
      */
     async listObjectsWithInheritance(prefix, branch) {
-        if (!this.cowEnabled) {
-            return this.listObjectsInBranch(prefix, branch);
-        }
         const targetBranch = branch || this.currentBranch || 'main';
         // Collect paths from current branch
         const pathsSet = new Set();

package/dist/storage/cow/CommitLog.d.ts

@@ -115,6 +115,30 @@ export declare class CommitLog {
         since?: number;
         until?: number;
     }): Promise<CommitObject[]>;
+    /**
+     * Stream commit history (memory-efficient for large histories)
+     *
+     * Yields commits one at a time without accumulating in memory.
+     * Use this for large commit histories (1000s of commits) where
+     * memory efficiency is important.
+     *
+     * @param ref - Starting ref
+     * @param options - Walk options
+     * @yields Commits in reverse chronological order (newest first)
+     *
+     * @example
+     * ```typescript
+     * // Stream all commits without memory accumulation
+     * for await (const commit of commitLog.streamHistory('main', { maxCount: 10000 })) {
+     *   console.log(commit.message)
+     * }
+     * ```
+     */
+    streamHistory(ref: string, options?: {
+        maxCount?: number;
+        since?: number;
+        until?: number;
+    }): AsyncIterableIterator<CommitObject>;
     /**
      * Count commits between two commits
      *

package/dist/storage/cow/CommitLog.js

@@ -183,6 +183,43 @@ export class CommitLog {
         }
         return commits;
     }
+    /**
+     * Stream commit history (memory-efficient for large histories)
+     *
+     * Yields commits one at a time without accumulating in memory.
+     * Use this for large commit histories (1000s of commits) where
+     * memory efficiency is important.
+     *
+     * @param ref - Starting ref
+     * @param options - Walk options
+     * @yields Commits in reverse chronological order (newest first)
+     *
+     * @example
+     * ```typescript
+     * // Stream all commits without memory accumulation
+     * for await (const commit of commitLog.streamHistory('main', { maxCount: 10000 })) {
+     *   console.log(commit.message)
+     * }
+     * ```
+     */
+    async *streamHistory(ref, options) {
+        let count = 0;
+        for await (const commit of this.walk(ref, {
+            maxDepth: options?.maxCount,
+            until: options?.until
+        })) {
+            // Filter by since timestamp if provided
+            if (options?.since && commit.timestamp < options.since) {
+                continue;
+            }
+            yield commit;
+            count++;
+            // Stop after maxCount commits
+            if (options?.maxCount && count >= options.maxCount) {
+                break;
+            }
+        }
+    }
     /**
      * Count commits between two commits
      *

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

@@ -494,6 +494,8 @@ export interface BrainyConfig {
     disableAutoOptimize?: boolean;
     batchWrites?: boolean;
     maxConcurrentOperations?: number;
+    maxQueryLimit?: number;
+    reservedQueryMemory?: number;
     verbose?: boolean;
     silent?: boolean;
 }

package/dist/utils/paramValidation.d.ts

@@ -5,6 +5,49 @@
  * Only enforces universal truths, learns everything else
  */
 import { FindParams, AddParams, UpdateParams, RelateParams } from '../types/brainy.types.js';
+/**
+ * Configuration options for ValidationConfig
+ */
+export interface ValidationConfigOptions {
+    /**
+     * Explicit maximum query limit override
+     * Bypasses all auto-detection
+     */
+    maxQueryLimit?: number;
+    /**
+     * Memory reserved for query operations (in bytes)
+     * Bypasses auto-detection but still applies safety limits
+     */
+    reservedQueryMemory?: number;
+}
+/**
+ * Auto-configured limits based on system resources
+ * These adapt to available memory and observed performance
+ */
+export declare class ValidationConfig {
+    private static instance;
+    maxLimit: number;
+    maxQueryLength: number;
+    maxVectorDimensions: number;
+    limitBasis: 'override' | 'reservedMemory' | 'containerMemory' | 'freeMemory';
+    detectedContainerLimit: number | null;
+    private avgQueryTime;
+    private queryCount;
+    private constructor();
+    static getInstance(options?: ValidationConfigOptions): ValidationConfig;
+    /**
+     * Reset singleton (for testing or reconfiguration)
+     */
+    static reset(): void;
+    /**
+     * Reconfigure with new options
+     */
+    static reconfigure(options: ValidationConfigOptions): ValidationConfig;
+    /**
+     * Learn from actual usage to adjust limits
+     */
+    recordQuery(duration: number, resultCount: number): void;
+}
 /**
  * Universal validations - things that are always invalid
  * These are mathematical/logical truths, not configuration

package/dist/utils/paramValidation.js

@@ -5,14 +5,16 @@
  * Only enforces universal truths, learns everything else
  */
 import { NounType, VerbType } from '../types/graphTypes.js';
-// Dynamic import for Node.js os module
+// Dynamic import for Node.js os and fs modules
 let os = null;
+let fs = null;
 if (typeof window === 'undefined') {
     try {
         os = await import('node:os');
+        fs = await import('node:fs');
     }
     catch (e) {
-        // OS module not available
+        // OS/FS modules not available
     }
 }
 // Browser-safe memory detection
@@ -30,46 +32,157 @@ const getAvailableMemory = () => {
     // Browser fallback: assume 2GB available
     return 2 * 1024 * 1024 * 1024;
 };
+/**
+ * Detect container memory limit (Docker/Kubernetes/Cloud Run)
+ *
+ * Production-grade detection for containerized environments.
+ * Supports:
+ * - cgroup v1 (legacy Docker/K8s)
+ * - cgroup v2 (modern systems)
+ * - Environment variables (Cloud Run, GCP, AWS, Azure)
+ *
+ * @returns Container memory limit in bytes, or null if not containerized
+ */
+const getContainerMemoryLimit = () => {
+    // Not in Node.js environment
+    if (!fs) {
+        return null;
+    }
+    try {
+        // 1. Check environment variables first (fastest, most reliable for Cloud Run)
+        // Google Cloud Run
+        if (process.env.CLOUD_RUN_MEMORY) {
+            // Format: "512Mi", "1Gi", "2Gi", "4Gi"
+            const match = process.env.CLOUD_RUN_MEMORY.match(/^(\d+)(Mi|Gi)$/);
+            if (match) {
+                const value = parseInt(match[1]);
+                const unit = match[2];
+                return unit === 'Gi' ? value * 1024 * 1024 * 1024 : value * 1024 * 1024;
+            }
+        }
+        // Generic MEMORY_LIMIT env var (bytes)
+        if (process.env.MEMORY_LIMIT) {
+            const limit = parseInt(process.env.MEMORY_LIMIT);
+            if (!isNaN(limit) && limit > 0) {
+                return limit;
+            }
+        }
+        // 2. Check cgroup v2 (modern Docker/K8s)
+        try {
+            const cgroupV2Path = '/sys/fs/cgroup/memory.max';
+            const cgroupV2Content = fs.readFileSync(cgroupV2Path, 'utf8').trim();
+            // "max" means no limit, otherwise it's bytes
+            if (cgroupV2Content !== 'max') {
+                const limit = parseInt(cgroupV2Content);
+                if (!isNaN(limit) && limit > 0) {
+                    return limit;
+                }
+            }
+        }
+        catch (e) {
+            // cgroup v2 not available, try v1
+        }
+        // 3. Check cgroup v1 (legacy Docker/K8s)
+        try {
+            const cgroupV1Path = '/sys/fs/cgroup/memory/memory.limit_in_bytes';
+            const cgroupV1Content = fs.readFileSync(cgroupV1Path, 'utf8').trim();
+            const limit = parseInt(cgroupV1Content);
+            // Very large values (> 1 PB) indicate no limit
+            const ONE_PETABYTE = 1024 * 1024 * 1024 * 1024 * 1024;
+            if (!isNaN(limit) && limit > 0 && limit < ONE_PETABYTE) {
+                return limit;
+            }
+        }
+        catch (e) {
+            // cgroup v1 not available
+        }
+        // Not containerized or no limit set
+        return null;
+    }
+    catch (e) {
+        // Error reading cgroup files
+        return null;
+    }
+};
 /**
  * Auto-configured limits based on system resources
  * These adapt to available memory and observed performance
  */
-class ValidationConfig {
-    constructor() {
+export class ValidationConfig {
+    constructor(options) {
         // Performance observations
         this.avgQueryTime = 0;
         this.queryCount = 0;
-        // Auto-configure based on system resources
-        const totalMemory = getSystemMemory();
-        const availableMemory = getAvailableMemory();
-        // Scale limits based on available memory
-        // 1GB = 10K limit, 8GB = 80K limit, etc.
-        this.maxLimit = Math.min(100000, // Absolute max for safety
-        Math.floor(availableMemory / (1024 * 1024 * 100)) * 1000);
-        // Query length scales with memory too
-        this.maxQueryLength = Math.min(50000, Math.floor(availableMemory / (1024 * 1024 * 10)) * 1000);
         // Vector dimensions (standard for all-MiniLM-L6-v2)
         this.maxVectorDimensions = 384;
+        // Detect container memory limit
+        this.detectedContainerLimit = getContainerMemoryLimit();
+        // Priority 1: Explicit override (highest priority)
+        if (options?.maxQueryLimit !== undefined) {
+            this.maxLimit = Math.min(options.maxQueryLimit, 100000); // Still cap at 100k for safety
+            this.limitBasis = 'override';
+            // Scale query length with limit
+            this.maxQueryLength = Math.min(50000, this.maxLimit * 5);
+            return;
+        }
+        // Priority 2: Reserved memory specified
+        if (options?.reservedQueryMemory !== undefined) {
+            this.maxLimit = Math.min(100000, Math.floor(options.reservedQueryMemory / (1024 * 1024 * 100)) * 1000);
+            this.limitBasis = 'reservedMemory';
+            this.maxQueryLength = Math.min(50000, Math.floor(options.reservedQueryMemory / (1024 * 1024 * 10)) * 1000);
+            return;
+        }
+        // Priority 3: Container detected (smart containerized behavior)
+        if (this.detectedContainerLimit) {
+            // In containers, assume 75% used by graph data (EXPECTED)
+            // Reserve 25% for query operations
+            const queryMemory = this.detectedContainerLimit * 0.25;
+            this.maxLimit = Math.min(100000, Math.floor(queryMemory / (1024 * 1024 * 100)) * 1000);
+            this.limitBasis = 'containerMemory';
+            this.maxQueryLength = Math.min(50000, Math.floor(queryMemory / (1024 * 1024 * 10)) * 1000);
+            return;
+        }
+        // Priority 4: Free memory (fallback, current behavior)
+        const availableMemory = getAvailableMemory();
+        this.maxLimit = Math.min(100000, Math.floor(availableMemory / (1024 * 1024 * 100)) * 1000);
+        this.limitBasis = 'freeMemory';
+        this.maxQueryLength = Math.min(50000, Math.floor(availableMemory / (1024 * 1024 * 10)) * 1000);
     }
-    static getInstance() {
+    static getInstance(options) {
         if (!ValidationConfig.instance) {
-            ValidationConfig.instance = new ValidationConfig();
+            ValidationConfig.instance = new ValidationConfig(options);
         }
         return ValidationConfig.instance;
     }
+    /**
+     * Reset singleton (for testing or reconfiguration)
+     */
+    static reset() {
+        ValidationConfig.instance = null;
+    }
+    /**
+     * Reconfigure with new options
+     */
+    static reconfigure(options) {
+        ValidationConfig.instance = new ValidationConfig(options);
+        return ValidationConfig.instance;
+    }
     /**
      * Learn from actual usage to adjust limits
      */
     recordQuery(duration, resultCount) {
         this.queryCount++;
         this.avgQueryTime = (this.avgQueryTime * (this.queryCount - 1) + duration) / this.queryCount;
-        // If queries are consistently fast with large results, increase limits
-        if (this.avgQueryTime < 100 && resultCount > this.maxLimit * 0.8) {
-            this.maxLimit = Math.min(this.maxLimit * 1.5, 100000);
-        }
-        // If queries are slow, reduce limits
-        if (this.avgQueryTime > 1000) {
-            this.maxLimit = Math.max(this.maxLimit * 0.8, 1000);
+        // Only auto-adjust if not using explicit overrides
+        if (this.limitBasis !== 'override') {
+            // If queries are consistently fast with large results, increase limits
+            if (this.avgQueryTime < 100 && resultCount > this.maxLimit * 0.8) {
+                this.maxLimit = Math.min(this.maxLimit * 1.5, 100000);
+            }
+            // If queries are slow, reduce limits
+            if (this.avgQueryTime > 1000) {
+                this.maxLimit = Math.max(this.maxLimit * 0.8, 1000);
+            }
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.10.3",
+  "version": "5.11.0",
   "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",