@soulcraft/brainy 5.10.2 → 5.10.4

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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)
+
+
 ### [5.10.2](https://github.com/soulcraftlabs/brainy/compare/v5.10.1...v5.10.2) (2025-11-14)
 
 - docs: remove external project references from documentation (ccd6c54)

package/README.md

@@ -197,6 +197,7 @@ const brain = new Brainy({
 })
 ```
 **Scale:** Thousands to hundreds of thousands • **Performance:** <5ms queries
+**→ [Production Service Architecture](docs/PRODUCTION_SERVICE_ARCHITECTURE.md)** — Singleton patterns, caching, and scaling for Express/Node.js services
 
 ### 🏢 Growing Company → Multi-Million Scale
 ```javascript

package/dist/brainy.js

@@ -1829,6 +1829,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

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

@@ -240,6 +240,19 @@ 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
     /**
      * Save statistics data to storage
      */

package/dist/storage/adapters/azureBlobStorage.js

@@ -866,6 +866,11 @@ export class AzureBlobStorage extends BaseStorage {
             this.blobStorage = undefined;
             this.commitLog = undefined;
             this.cowEnabled = false;
+            // v5.10.4: Create persistent marker blob (CRITICAL FIX)
+            // Bug: cowEnabled = false only affects current instance, not future instances
+            // Fix: Create marker blob that persists across instance restarts
+            // When new instance calls initializeCOW(), it checks for this marker
+            await this.createClearMarker();
             // Clear caches
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();
@@ -908,6 +913,45 @@ 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
+     */
+    async checkClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const markerPath = `${this.systemPrefix}cow-disabled`;
+            const blockBlobClient = this.containerClient.getBlockBlobClient(markerPath);
+            const exists = await blockBlobClient.exists();
+            return exists;
+        }
+        catch (error) {
+            this.logger.warn('AzureBlobStorage.checkClearMarker: Error checking marker', error);
+            return false;
+        }
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    async createClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const markerPath = `${this.systemPrefix}cow-disabled`;
+            const blockBlobClient = this.containerClient.getBlockBlobClient(markerPath);
+            // Create empty marker blob
+            await blockBlobClient.upload(Buffer.from(''), 0, {
+                blobHTTPHeaders: { blobContentType: 'text/plain' }
+            });
+        }
+        catch (error) {
+            this.logger.error('AzureBlobStorage.createClearMarker: Failed to create marker blob', error);
+            // Don't throw - marker creation failure shouldn't break clear()
+        }
+    }
     /**
      * Save statistics data to storage
      */

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

@@ -171,6 +171,19 @@ 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
     /**
      * 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)) {
@@ -888,6 +885,11 @@ export class FileSystemStorage extends BaseStorage {
             this.blobStorage = undefined;
             this.commitLog = undefined;
             this.cowEnabled = false;
+            // v5.10.4: Create persistent marker file (CRITICAL FIX)
+            // Bug: cowEnabled = false only affects current instance, not future instances
+            // Fix: Create marker file that persists across instance restarts
+            // When new instance calls initializeCOW(), it checks for this marker
+            await this.createClearMarker();
         }
         // Clear the statistics cache
         this.statisticsCache = null;
@@ -915,6 +917,47 @@ 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
+     */
+    async checkClearMarker() {
+        // Check if fs module is available
+        if (!fs || !fs.promises) {
+            return false;
+        }
+        try {
+            const markerPath = path.join(this.systemDir, 'cow-disabled');
+            await fs.promises.access(markerPath, fs.constants.F_OK);
+            return true; // Marker exists
+        }
+        catch (error) {
+            return false; // Marker doesn't exist (ENOENT) or can't be accessed
+        }
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    async createClearMarker() {
+        // Check if fs module is available
+        if (!fs || !fs.promises) {
+            console.warn('FileSystemStorage.createClearMarker: fs module not available, skipping marker creation');
+            return;
+        }
+        try {
+            const markerPath = path.join(this.systemDir, 'cow-disabled');
+            // Create empty marker file
+            await fs.promises.writeFile(markerPath, '', 'utf8');
+        }
+        catch (error) {
+            console.error('FileSystemStorage.createClearMarker: Failed to create marker file', error);
+            // Don't throw - marker creation failure shouldn't break clear()
+        }
+    }
     /**
      * Get information about storage usage and capacity
      */

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

@@ -228,6 +228,19 @@ 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
     /**
      * Save statistics data to storage
      */

package/dist/storage/adapters/gcsStorage.js

@@ -789,6 +789,11 @@ export class GcsStorage extends BaseStorage {
             this.blobStorage = undefined;
             this.commitLog = undefined;
             this.cowEnabled = false;
+            // v5.10.4: Create persistent marker object (CRITICAL FIX)
+            // Bug: cowEnabled = false only affects current instance, not future instances
+            // Fix: Create marker object that persists across instance restarts
+            // When new instance calls initializeCOW(), it checks for this marker
+            await this.createClearMarker();
             // Clear caches
             this.nounCacheManager.clear();
             this.verbCacheManager.clear();
@@ -834,6 +839,43 @@ 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
+     */
+    async checkClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const markerPath = `${this.systemPrefix}cow-disabled`;
+            const file = this.bucket.file(markerPath);
+            const [exists] = await file.exists();
+            return exists;
+        }
+        catch (error) {
+            this.logger.warn('GCSStorage.checkClearMarker: Error checking marker', error);
+            return false;
+        }
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    async createClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const markerPath = `${this.systemPrefix}cow-disabled`;
+            const file = this.bucket.file(markerPath);
+            // Create empty marker object
+            await file.save('', { contentType: 'text/plain' });
+        }
+        catch (error) {
+            this.logger.error('GCSStorage.createClearMarker: Failed to create marker object', error);
+            // Don't throw - marker creation failure shouldn't break clear()
+        }
+    }
     /**
      * Save statistics data to storage
      */

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

@@ -101,6 +101,19 @@ 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: No-op for HistoricalStorageAdapter (read-only)
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
     /**
      * WRITE BLOCKED: Historical storage is read-only
      */

package/dist/storage/adapters/historicalStorageAdapter.js

@@ -226,6 +226,23 @@ 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
+     */
+    async checkClearMarker() {
+        return false; // Read-only adapter - COW state managed by underlying storage
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: No-op for HistoricalStorageAdapter (read-only)
+     * @protected
+     */
+    async createClearMarker() {
+        // No-op: HistoricalStorageAdapter is read-only, doesn't create markers
+    }
     // ============= Override Write Methods (Read-Only) =============
     /**
      * WRITE BLOCKED: Historical storage is read-only

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

@@ -79,6 +79,19 @@ 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: No-op for MemoryStorage (doesn't persist)
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
     /**
      * Save statistics data to storage
      * @param statistics The statistics data to save

package/dist/storage/adapters/memoryStorage.js

@@ -158,6 +158,24 @@ 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
+     */
+    async checkClearMarker() {
+        return false; // MemoryStorage doesn't persist - marker doesn't survive restart
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: No-op for MemoryStorage (doesn't persist)
+     * @protected
+     */
+    async createClearMarker() {
+        // No-op: MemoryStorage doesn't persist, so marker is not needed
+        // clear() in memory already resets all state, no marker survives restart
+    }
     /**
      * Save statistics data to storage
      * @param statistics The statistics data to save

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

@@ -94,6 +94,19 @@ 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
     private quotaWarningThreshold;
     private quotaCriticalThreshold;
     private lastQuotaCheck;

package/dist/storage/adapters/opfsStorage.js

@@ -400,6 +400,11 @@ export class OPFSStorage extends BaseStorage {
                 this.blobStorage = undefined;
                 this.commitLog = undefined;
                 this.cowEnabled = false;
+                // v5.10.4: Create persistent marker file (CRITICAL FIX)
+                // Bug: cowEnabled = false only affects current instance, not future instances
+                // Fix: Create marker file that persists across instance restarts
+                // When new instance calls initializeCOW(), it checks for this marker
+                await this.createClearMarker();
             }
             catch (error) {
                 // Ignore if _cow directory doesn't exist (not all instances use COW)
@@ -418,6 +423,51 @@ export class OPFSStorage extends BaseStorage {
             throw error;
         }
     }
+    /**
+     * 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
+     */
+    async checkClearMarker() {
+        await this.ensureInitialized();
+        try {
+            // Get system directory (may not exist yet)
+            const systemDir = await this.rootDir.getDirectoryHandle('system', { create: false });
+            // Try to get the marker file
+            await systemDir.getFileHandle('cow-disabled', { create: false });
+            return true; // Marker exists
+        }
+        catch (error) {
+            if (error.name === 'NotFoundError') {
+                return false; // Marker doesn't exist (or system dir doesn't exist)
+            }
+            // Other errors (permissions, etc.) - treat as marker not existing
+            console.warn('OPFSStorage.checkClearMarker: Error checking marker', error);
+            return false;
+        }
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    async createClearMarker() {
+        await this.ensureInitialized();
+        try {
+            // Get or create system directory
+            const systemDir = await this.rootDir.getDirectoryHandle('system', { create: true });
+            // Create empty marker file
+            const fileHandle = await systemDir.getFileHandle('cow-disabled', { create: true });
+            const writable = await fileHandle.createWritable();
+            await writable.write(new Uint8Array(0)); // Empty file
+            await writable.close();
+        }
+        catch (error) {
+            console.error('OPFSStorage.createClearMarker: Failed to create marker file', error);
+            // Don't throw - marker creation failure shouldn't break clear()
+        }
+    }
     /**
      * Get information about storage usage and capacity
      */

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

@@ -200,5 +200,18 @@ export declare class R2Storage 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
 }
 export {};

package/dist/storage/adapters/r2Storage.js

@@ -787,6 +787,11 @@ export class R2Storage extends BaseStorage {
         this.blobStorage = undefined;
         this.commitLog = undefined;
         this.cowEnabled = false;
+        // v5.10.4: Create persistent marker object (CRITICAL FIX)
+        // Bug: cowEnabled = false only affects current instance, not future instances
+        // Fix: Create marker object that persists across instance restarts
+        // When new instance calls initializeCOW(), it checks for this marker
+        await this.createClearMarker();
         this.nounCacheManager.clear();
         this.verbCacheManager.clear();
         this.totalNounCount = 0;
@@ -813,5 +818,40 @@ export class R2Storage 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
+     */
+    async checkClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const markerPath = `${this.systemPrefix}cow-disabled`;
+            const data = await this.readObjectFromPath(markerPath);
+            return data !== null; // Marker exists if we got any data
+        }
+        catch (error) {
+            prodLog.warn('R2Storage.checkClearMarker: Error checking marker', error);
+            return false;
+        }
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    async createClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const markerPath = `${this.systemPrefix}cow-disabled`;
+            // Create empty marker object
+            await this.writeObjectToPath(markerPath, '');
+        }
+        catch (error) {
+            prodLog.error('R2Storage.createClearMarker: Failed to create marker object', error);
+            // Don't throw - marker creation failure shouldn't break clear()
+        }
+    }
 }
 //# sourceMappingURL=r2Storage.js.map

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

@@ -373,6 +373,19 @@ 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
+     */
+    protected checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    protected createClearMarker(): Promise<void>;
     protected statisticsBatchUpdateTimerId: NodeJS.Timeout | null;
     protected statisticsModified: boolean;
     protected lastStatisticsFlushTime: number;

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -1632,6 +1632,11 @@ export class S3CompatibleStorage extends BaseStorage {
             this.blobStorage = undefined;
             this.commitLog = undefined;
             this.cowEnabled = false;
+            // v5.10.4: Create persistent marker object (CRITICAL FIX)
+            // Bug: cowEnabled = false only affects current instance, not future instances
+            // Fix: Create marker object that persists across instance restarts
+            // When new instance calls initializeCOW(), it checks for this marker
+            await this.createClearMarker();
             // Clear the statistics cache
             this.statisticsCache = null;
             this.statisticsModified = false;
@@ -1731,6 +1736,54 @@ export class S3CompatibleStorage 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
+     */
+    async checkClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const { HeadObjectCommand } = await import('@aws-sdk/client-s3');
+            const markerKey = `${this.systemPrefix}cow-disabled`;
+            await this.s3Client.send(new HeadObjectCommand({
+                Bucket: this.bucketName,
+                Key: markerKey
+            }));
+            return true; // Marker exists
+        }
+        catch (error) {
+            if (error.name === 'NotFound' || error.$metadata?.httpStatusCode === 404) {
+                return false; // Marker doesn't exist
+            }
+            prodLog.warn('S3CompatibleStorage.checkClearMarker: Error checking marker', error);
+            return false;
+        }
+    }
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * @protected
+     */
+    async createClearMarker() {
+        await this.ensureInitialized();
+        try {
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            const markerKey = `${this.systemPrefix}cow-disabled`;
+            // Create empty marker object
+            await this.s3Client.send(new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: markerKey,
+                Body: Buffer.from(''),
+                ContentType: 'text/plain'
+            }));
+        }
+        catch (error) {
+            prodLog.error('S3CompatibleStorage.createClearMarker: Failed to create marker object', error);
+            // Don't throw - marker creation failure shouldn't break clear()
+        }
+    }
     /**
      * Get the statistics key for a specific date
      * @param date The date to get the key for

package/dist/storage/baseStorage.d.ts

@@ -327,6 +327,21 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * This method should be implemented by each specific adapter
      */
     abstract 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
+     * Each adapter checks for a marker file/object (e.g., "_system/cow-disabled")
+     * @returns true if COW was disabled by clear(), false otherwise
+     * @protected
+     */
+    protected abstract checkClearMarker(): Promise<boolean>;
+    /**
+     * Create marker indicating COW has been explicitly disabled
+     * v5.10.4: Called by clear() to prevent COW reinitialization on new instances
+     * Each adapter creates a marker file/object (e.g., "_system/cow-disabled")
+     * @protected
+     */
+    protected abstract createClearMarker(): Promise<void>;
     /**
      * Get information about storage usage and capacity
      * This method should be implemented by each specific adapter

package/dist/storage/baseStorage.js

@@ -212,6 +212,14 @@ export class BaseStorage extends BaseStorageAdapter {
      * @returns Promise that resolves when COW is initialized
      */
     async initializeCOW(options) {
+        // v5.10.4: Check for persistent marker file (CRITICAL FIX)
+        // Bug: Setting cowEnabled = false on OLD instance doesn't affect NEW instances
+        // Fix: Check storage for persistent marker created by clear()
+        // If marker exists, COW was explicitly disabled and should NOT reinitialize
+        const markerExists = await this.checkClearMarker();
+        if (markerExists) {
+            return; // COW was disabled by clear() - don't recreate _cow/ directory
+        }
         // 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) {

package/package.json

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