@soulcraft/brainy 3.32.2 → 3.35.0

package/dist/storage/adapters/memoryStorage.js

@@ -595,5 +595,48 @@ export class MemoryStorage extends BaseStorage {
         // No persistence needed for in-memory storage
         // Counts are always accurate from the live data structures
     }
+    // =============================================
+    // HNSW Index Persistence (v3.35.0+)
+    // =============================================
+    /**
+     * Get vector for a noun
+     */
+    async getNounVector(id) {
+        const noun = this.nouns.get(id);
+        return noun ? [...noun.vector] : null;
+    }
+    /**
+     * Save HNSW graph data for a noun
+     */
+    async saveHNSWData(nounId, hnswData) {
+        // For memory storage, HNSW data is already in the noun object
+        // This method is a no-op since saveNoun already stores the full graph
+        // But we store it separately for consistency with other adapters
+        const path = `hnsw/${nounId}.json`;
+        await this.writeObjectToPath(path, hnswData);
+    }
+    /**
+     * Get HNSW graph data for a noun
+     */
+    async getHNSWData(nounId) {
+        const path = `hnsw/${nounId}.json`;
+        const data = await this.readObjectFromPath(path);
+        return data || null;
+    }
+    /**
+     * Save HNSW system data (entry point, max level)
+     */
+    async saveHNSWSystem(systemData) {
+        const path = 'system/hnsw-system.json';
+        await this.writeObjectToPath(path, systemData);
+    }
+    /**
+     * Get HNSW system data
+     */
+    async getHNSWSystem() {
+        const path = 'system/hnsw-system.json';
+        const data = await this.readObjectFromPath(path);
+        return data || null;
+    }
 }
 //# sourceMappingURL=memoryStorage.js.map

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

@@ -262,5 +262,41 @@ export declare class OPFSStorage extends BaseStorage {
      * Persist counts to OPFS storage
      */
     protected persistCounts(): Promise<void>;
+    /**
+     * Get a noun's vector for HNSW rebuild
+     */
+    getNounVector(id: string): Promise<number[] | null>;
+    /**
+     * Save HNSW graph data for a noun
+     * Storage path: nouns/hnsw/{shard}/{id}.json
+     */
+    saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    /**
+     * Get HNSW graph data for a noun
+     * Storage path: nouns/hnsw/{shard}/{id}.json
+     */
+    getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    /**
+     * Save HNSW system data (entry point, max level)
+     * Storage path: index/hnsw-system.json
+     */
+    saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    /**
+     * Get HNSW system data (entry point, max level)
+     * Storage path: index/hnsw-system.json
+     */
+    getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
 }
 export {};

package/dist/storage/adapters/opfsStorage.js

@@ -1471,5 +1471,106 @@ export class OPFSStorage extends BaseStorage {
             console.error('Error persisting counts to OPFS:', error);
         }
     }
+    // HNSW Index Persistence (v3.35.0+)
+    /**
+     * Get a noun's vector for HNSW rebuild
+     */
+    async getNounVector(id) {
+        await this.ensureInitialized();
+        const noun = await this.getNoun_internal(id);
+        return noun ? noun.vector : null;
+    }
+    /**
+     * Save HNSW graph data for a noun
+     * Storage path: nouns/hnsw/{shard}/{id}.json
+     */
+    async saveHNSWData(nounId, hnswData) {
+        await this.ensureInitialized();
+        try {
+            // Get or create the hnsw directory under nouns
+            const hnswDir = await this.nounsDir.getDirectoryHandle('hnsw', { create: true });
+            // Use sharded path for HNSW data
+            const shard = getShardIdFromUuid(nounId);
+            const shardDir = await hnswDir.getDirectoryHandle(shard, { create: true });
+            // Create or get the file in the shard directory
+            const fileHandle = await shardDir.getFileHandle(`${nounId}.json`, { create: true });
+            // Write the HNSW data to the file
+            const writable = await fileHandle.createWritable();
+            await writable.write(JSON.stringify(hnswData, null, 2));
+            await writable.close();
+        }
+        catch (error) {
+            console.error(`Failed to save HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW graph data for a noun
+     * Storage path: nouns/hnsw/{shard}/{id}.json
+     */
+    async getHNSWData(nounId) {
+        await this.ensureInitialized();
+        try {
+            // Get the hnsw directory under nouns
+            const hnswDir = await this.nounsDir.getDirectoryHandle('hnsw');
+            // Use sharded path for HNSW data
+            const shard = getShardIdFromUuid(nounId);
+            const shardDir = await hnswDir.getDirectoryHandle(shard);
+            // Get the file handle from the shard directory
+            const fileHandle = await shardDir.getFileHandle(`${nounId}.json`);
+            // Read the HNSW data from the file
+            const file = await fileHandle.getFile();
+            const text = await file.text();
+            return JSON.parse(text);
+        }
+        catch (error) {
+            if (error.name === 'NotFoundError') {
+                return null;
+            }
+            console.error(`Failed to get HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to get HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Save HNSW system data (entry point, max level)
+     * Storage path: index/hnsw-system.json
+     */
+    async saveHNSWSystem(systemData) {
+        await this.ensureInitialized();
+        try {
+            // Create or get the file in the index directory
+            const fileHandle = await this.indexDir.getFileHandle('hnsw-system.json', { create: true });
+            // Write the system data to the file
+            const writable = await fileHandle.createWritable();
+            await writable.write(JSON.stringify(systemData, null, 2));
+            await writable.close();
+        }
+        catch (error) {
+            console.error('Failed to save HNSW system data:', error);
+            throw new Error(`Failed to save HNSW system data: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW system data (entry point, max level)
+     * Storage path: index/hnsw-system.json
+     */
+    async getHNSWSystem() {
+        await this.ensureInitialized();
+        try {
+            // Get the file handle from the index directory
+            const fileHandle = await this.indexDir.getFileHandle('hnsw-system.json');
+            // Read the system data from the file
+            const file = await fileHandle.getFile();
+            const text = await file.text();
+            return JSON.parse(text);
+        }
+        catch (error) {
+            if (error.name === 'NotFoundError') {
+                return null;
+            }
+            console.error('Failed to get HNSW system data:', error);
+            throw new Error(`Failed to get HNSW system data: ${error}`);
+        }
+    }
 }
 //# sourceMappingURL=opfsStorage.js.map

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

@@ -563,4 +563,49 @@ export declare class S3CompatibleStorage extends BaseStorage {
      * Persist counts to S3 storage
      */
     protected persistCounts(): Promise<void>;
+    /**
+     * Override base class to enable smart batching for cloud storage (v3.32.3+)
+     *
+     * S3 is cloud storage with network latency (~50ms per write).
+     * Smart batching reduces writes from 1000 ops → 100 batches.
+     *
+     * @returns true (S3 is cloud storage)
+     */
+    protected isCloudStorage(): boolean;
+    /**
+     * Get a noun's vector for HNSW rebuild
+     */
+    getNounVector(id: string): Promise<number[] | null>;
+    /**
+     * Save HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    /**
+     * Get HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    /**
+     * Save HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    /**
+     * Get HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
 }

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -2754,5 +2754,128 @@ export class S3CompatibleStorage extends BaseStorage {
             console.error('Error persisting counts to S3:', error);
         }
     }
+    /**
+     * Override base class to enable smart batching for cloud storage (v3.32.3+)
+     *
+     * S3 is cloud storage with network latency (~50ms per write).
+     * Smart batching reduces writes from 1000 ops → 100 batches.
+     *
+     * @returns true (S3 is cloud storage)
+     */
+    isCloudStorage() {
+        return true; // S3 benefits from batching
+    }
+    // HNSW Index Persistence (v3.35.0+)
+    /**
+     * Get a noun's vector for HNSW rebuild
+     */
+    async getNounVector(id) {
+        await this.ensureInitialized();
+        const noun = await this.getNode(id);
+        return noun ? noun.vector : null;
+    }
+    /**
+     * Save HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    async saveHNSWData(nounId, hnswData) {
+        await this.ensureInitialized();
+        try {
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            // Use sharded path for HNSW data
+            const shard = getShardIdFromUuid(nounId);
+            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
+            await this.s3Client.send(new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(hnswData, null, 2),
+                ContentType: 'application/json'
+            }));
+        }
+        catch (error) {
+            this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to save HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW graph data for a noun
+     * Storage path: entities/nouns/hnsw/{shard}/{id}.json
+     */
+    async getHNSWData(nounId) {
+        await this.ensureInitialized();
+        try {
+            const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+            const shard = getShardIdFromUuid(nounId);
+            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
+            const response = await this.s3Client.send(new GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: key
+            }));
+            if (!response || !response.Body) {
+                return null;
+            }
+            const bodyContents = await response.Body.transformToString();
+            return JSON.parse(bodyContents);
+        }
+        catch (error) {
+            if (error.name === 'NoSuchKey' ||
+                error.message?.includes('NoSuchKey') ||
+                error.message?.includes('not found')) {
+                return null;
+            }
+            this.logger.error(`Failed to get HNSW data for ${nounId}:`, error);
+            throw new Error(`Failed to get HNSW data for ${nounId}: ${error}`);
+        }
+    }
+    /**
+     * Save HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    async saveHNSWSystem(systemData) {
+        await this.ensureInitialized();
+        try {
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            const key = `${this.systemPrefix}hnsw-system.json`;
+            await this.s3Client.send(new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(systemData, null, 2),
+                ContentType: 'application/json'
+            }));
+        }
+        catch (error) {
+            this.logger.error('Failed to save HNSW system data:', error);
+            throw new Error(`Failed to save HNSW system data: ${error}`);
+        }
+    }
+    /**
+     * Get HNSW system data (entry point, max level)
+     * Storage path: system/hnsw-system.json
+     */
+    async getHNSWSystem() {
+        await this.ensureInitialized();
+        try {
+            const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+            const key = `${this.systemPrefix}hnsw-system.json`;
+            const response = await this.s3Client.send(new GetObjectCommand({
+                Bucket: this.bucketName,
+                Key: key
+            }));
+            if (!response || !response.Body) {
+                return null;
+            }
+            const bodyContents = await response.Body.transformToString();
+            return JSON.parse(bodyContents);
+        }
+        catch (error) {
+            if (error.name === 'NoSuchKey' ||
+                error.message?.includes('NoSuchKey') ||
+                error.message?.includes('not found')) {
+                return null;
+            }
+            this.logger.error('Failed to get HNSW system data:', error);
+            throw new Error(`Failed to get HNSW system data: ${error}`);
+        }
+    }
 }
 //# sourceMappingURL=s3CompatibleStorage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.32.2",
+  "version": "3.35.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -55,7 +55,10 @@
     "node": "22.x"
   },
   "scripts": {
-    "build": "npm run build:patterns:if-needed && tsc && tsc -p tsconfig.cli.json",
+    "build": "npm run build:types:if-needed && npm run build:patterns:if-needed && tsc && tsc -p tsconfig.cli.json",
+    "build:types": "tsx scripts/buildTypeEmbeddings.ts",
+    "build:types:if-needed": "node scripts/check-type-embeddings.cjs || npm run build:types",
+    "build:types:force": "npm run build:types",
     "build:patterns": "tsx scripts/buildEmbeddedPatterns.ts",
     "build:patterns:if-needed": "node scripts/check-patterns.cjs || npm run build:patterns",
     "build:patterns:force": "npm run build:patterns",