@soulcraft/brainy 3.32.2 → 3.35.0

package/dist/neural/naturalLanguageProcessor.js

@@ -10,6 +10,7 @@
  */
 import { PatternLibrary } from './patternLibrary.js';
 import { NounType, VerbType } from '../types/graphTypes.js';
+import { getNounTypeEmbeddings, getVerbTypeEmbeddings } from './embeddedTypeEmbeddings.js';
 export class NaturalLanguageProcessor {
     constructor(brain) {
         this.initialized = false;
@@ -54,41 +55,26 @@ export class NaturalLanguageProcessor {
     }
     /**
      * Initialize embeddings for all NounTypes and VerbTypes
-     * These are fixed types that never change - perfect for caching
+     * PRODUCTION OPTIMIZATION (v3.33.0): Uses pre-computed type embeddings
+     * Zero runtime cost - embeddings are loaded instantly from embedded data
      */
     async initializeTypeEmbeddings() {
         if (this.typeEmbeddingsInitialized)
             return;
-        // Embed all NounTypes (30+ types)
-        for (const [key, value] of Object.entries(NounType)) {
-            if (typeof value === 'string') {
-                // Embed both the key (Person) and value (person)
-                const keyEmbedding = await this.getEmbedding(key);
-                const valueEmbedding = await this.getEmbedding(value);
-                this.nounTypeEmbeddings.set(key, keyEmbedding);
-                this.nounTypeEmbeddings.set(value, valueEmbedding);
-                // Also embed common variations
-                const spaceSeparated = key.replace(/([A-Z])/g, ' $1').trim().toLowerCase();
-                if (spaceSeparated !== value) {
-                    const variantEmbedding = await this.getEmbedding(spaceSeparated);
-                    this.nounTypeEmbeddings.set(spaceSeparated, variantEmbedding);
-                }
-            }
-        }
-        // Embed all VerbTypes (40+ types)
-        for (const [key, value] of Object.entries(VerbType)) {
-            if (typeof value === 'string') {
-                const keyEmbedding = await this.getEmbedding(key);
-                const valueEmbedding = await this.getEmbedding(value);
-                this.verbTypeEmbeddings.set(key, keyEmbedding);
-                this.verbTypeEmbeddings.set(value, valueEmbedding);
-                // Common variations for verbs
-                const spaceSeparated = key.replace(/([A-Z])/g, ' $1').trim().toLowerCase();
-                if (spaceSeparated !== value) {
-                    const variantEmbedding = await this.getEmbedding(spaceSeparated);
-                    this.verbTypeEmbeddings.set(spaceSeparated, variantEmbedding);
-                }
-            }
+        // Load pre-computed embeddings (instant, no computation)
+        const nounEmbeddings = getNounTypeEmbeddings();
+        const verbEmbeddings = getVerbTypeEmbeddings();
+        // Store noun type embeddings with all variations for lookup
+        for (const [type, embedding] of nounEmbeddings.entries()) {
+            this.nounTypeEmbeddings.set(type, embedding);
+            // Also store lowercase version for case-insensitive matching
+            this.nounTypeEmbeddings.set(type.toLowerCase(), embedding);
+        }
+        // Store verb type embeddings with all variations for lookup
+        for (const [type, embedding] of verbEmbeddings.entries()) {
+            this.verbTypeEmbeddings.set(type, embedding);
+            // Also store lowercase version for case-insensitive matching
+            this.verbTypeEmbeddings.set(type.toLowerCase(), embedding);
         }
         this.typeEmbeddingsInitialized = true;
     }

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

@@ -23,6 +23,23 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
     abstract getNounMetadata(id: string): Promise<any | null>;
     abstract saveVerbMetadata(id: string, metadata: any): Promise<void>;
     abstract getVerbMetadata(id: string): Promise<any | null>;
+    abstract getNounVector(id: string): Promise<number[] | null>;
+    abstract saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    abstract getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    abstract saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    abstract getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
     abstract clear(): Promise<void>;
     abstract getStorageStatus(): Promise<{
         type: string;
@@ -263,6 +280,12 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
         timestamp: number;
     }>;
     protected readonly COUNT_CACHE_TTL = 60000;
+    protected pendingCountPersist: boolean;
+    protected lastCountPersistTime: number;
+    protected scheduledCountPersistTimeout: NodeJS.Timeout | null;
+    protected pendingCountOperations: number;
+    protected countPersistBatchSize: number;
+    protected countPersistInterval: number;
     /**
      * Get total noun count - O(1) operation
      * @returns Promise that resolves to the total number of nouns
@@ -303,6 +326,37 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
      * @param type The verb type
      */
     protected decrementVerbCount(type: string): Promise<void>;
+    /**
+     * Detect if this storage adapter uses cloud storage (network I/O)
+     * Cloud storage benefits from batching; local storage does not.
+     *
+     * Override this method in subclasses for accurate detection.
+     * Default implementation checks storage type from getStorageStatus().
+     *
+     * @returns true if cloud storage (GCS, S3, R2), false if local (File, Memory)
+     */
+    protected isCloudStorage(): boolean;
+    /**
+     * Schedule a smart batched persist operation.
+     *
+     * Strategy:
+     * - Local Storage: Persist immediately (fast, no network latency)
+     * - Cloud Storage: Batch persist (10 ops OR 5 seconds, whichever first)
+     *
+     * This mirrors the statistics batching pattern for consistency.
+     */
+    protected scheduleCountPersist(): Promise<void>;
+    /**
+     * Flush counts immediately to storage.
+     *
+     * Used for:
+     * - Graceful shutdown (SIGTERM handler)
+     * - Forced persist (batch threshold reached)
+     * - Local storage immediate persist
+     *
+     * This is the public API that shutdown hooks can call.
+     */
+    flushCounts(): Promise<void>;
     /**
      * Initialize counts from storage - must be implemented by each adapter
      * @protected

package/dist/storage/adapters/baseStorageAdapter.js

@@ -48,6 +48,17 @@ export class BaseStorageAdapter {
         this.verbCounts = new Map(); // verb type -> count
         this.countCache = new Map();
         this.COUNT_CACHE_TTL = 60000; // 1 minute cache TTL
+        // =============================================
+        // Smart Count Batching (v3.32.3+)
+        // =============================================
+        // Count batching state - mirrors statistics batching pattern
+        this.pendingCountPersist = false; // Counts changed since last persist?
+        this.lastCountPersistTime = 0; // Timestamp of last persist
+        this.scheduledCountPersistTimeout = null; // Scheduled persist timer
+        this.pendingCountOperations = 0; // Operations since last persist
+        // Batching configuration (overridable by subclasses for custom strategies)
+        this.countPersistBatchSize = 10; // Operations before forcing persist (cloud storage)
+        this.countPersistInterval = 5000; // Milliseconds before forcing persist (cloud storage)
     }
     /**
      * Save statistics data
@@ -659,10 +670,10 @@ export class BaseStorageAdapter {
         const mutex = getGlobalMutex();
         await mutex.runExclusive(`count-entity-${type}`, async () => {
             this.incrementEntityCount(type);
-            // CRITICAL FIX: Persist counts on EVERY change for cloud storage adapters
-            // This ensures counts survive container restarts (GCS, S3, etc.)
-            // For memory/file storage, this is fast; for cloud storage, it's essential
-            await this.persistCounts();
+            // Smart batching (v3.32.3+): Adapts to storage type
+            // - Cloud storage (GCS, S3): Batches 10 ops OR 5 seconds
+            // - Local storage (File, Memory): Persists immediately
+            await this.scheduleCountPersist();
         });
     }
     /**
@@ -693,8 +704,8 @@ export class BaseStorageAdapter {
         const mutex = getGlobalMutex();
         await mutex.runExclusive(`count-entity-${type}`, async () => {
             this.decrementEntityCount(type);
-            // CRITICAL FIX: Persist counts on EVERY change for cloud storage adapters
-            await this.persistCounts();
+            // Smart batching (v3.32.3+): Adapts to storage type
+            await this.scheduleCountPersist();
         });
     }
     /**
@@ -711,8 +722,8 @@ export class BaseStorageAdapter {
                 count: this.totalVerbCount,
                 timestamp: Date.now()
             });
-            // CRITICAL FIX: Persist counts on EVERY change for cloud storage adapters
-            await this.persistCounts();
+            // Smart batching (v3.32.3+): Adapts to storage type
+            await this.scheduleCountPersist();
         });
     }
     /**
@@ -737,9 +748,93 @@ export class BaseStorageAdapter {
                 count: this.totalVerbCount,
                 timestamp: Date.now()
             });
-            // CRITICAL FIX: Persist counts on EVERY change for cloud storage adapters
-            await this.persistCounts();
+            // Smart batching (v3.32.3+): Adapts to storage type
+            await this.scheduleCountPersist();
         });
     }
+    // =============================================
+    // Smart Batching Methods (v3.32.3+)
+    // =============================================
+    /**
+     * Detect if this storage adapter uses cloud storage (network I/O)
+     * Cloud storage benefits from batching; local storage does not.
+     *
+     * Override this method in subclasses for accurate detection.
+     * Default implementation checks storage type from getStorageStatus().
+     *
+     * @returns true if cloud storage (GCS, S3, R2), false if local (File, Memory)
+     */
+    isCloudStorage() {
+        // Default: assume local storage (conservative, prefers reliability over performance)
+        // Subclasses should override this for accurate detection
+        return false;
+    }
+    /**
+     * Schedule a smart batched persist operation.
+     *
+     * Strategy:
+     * - Local Storage: Persist immediately (fast, no network latency)
+     * - Cloud Storage: Batch persist (10 ops OR 5 seconds, whichever first)
+     *
+     * This mirrors the statistics batching pattern for consistency.
+     */
+    async scheduleCountPersist() {
+        // Mark counts as pending persist
+        this.pendingCountPersist = true;
+        this.pendingCountOperations++;
+        // Local storage: persist immediately (fast enough, no benefit from batching)
+        if (!this.isCloudStorage()) {
+            await this.flushCounts();
+            return;
+        }
+        // Cloud storage: use smart batching
+        // Persist if we've hit the batch size threshold
+        if (this.pendingCountOperations >= this.countPersistBatchSize) {
+            await this.flushCounts();
+            return;
+        }
+        // Otherwise, schedule a time-based persist if not already scheduled
+        if (!this.scheduledCountPersistTimeout) {
+            this.scheduledCountPersistTimeout = setTimeout(() => {
+                this.flushCounts().catch(error => {
+                    console.error('Failed to flush counts on timer:', error);
+                });
+            }, this.countPersistInterval);
+        }
+    }
+    /**
+     * Flush counts immediately to storage.
+     *
+     * Used for:
+     * - Graceful shutdown (SIGTERM handler)
+     * - Forced persist (batch threshold reached)
+     * - Local storage immediate persist
+     *
+     * This is the public API that shutdown hooks can call.
+     */
+    async flushCounts() {
+        // Clear any scheduled persist
+        if (this.scheduledCountPersistTimeout) {
+            clearTimeout(this.scheduledCountPersistTimeout);
+            this.scheduledCountPersistTimeout = null;
+        }
+        // Nothing to flush?
+        if (!this.pendingCountPersist) {
+            return;
+        }
+        try {
+            // Persist to storage (implemented by subclass)
+            await this.persistCounts();
+            // Update state
+            this.lastCountPersistTime = Date.now();
+            this.pendingCountPersist = false;
+            this.pendingCountOperations = 0;
+        }
+        catch (error) {
+            console.error('❌ CRITICAL: Failed to flush counts to storage:', error);
+            // Keep pending flag set so we retry on next operation
+            throw error;
+        }
+    }
 }
 //# sourceMappingURL=baseStorageAdapter.js.map

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

@@ -361,5 +361,37 @@ export declare class FileSystemStorage extends BaseStorage {
      * Check if a file exists (handles both sharded and non-sharded)
      */
     private fileExists;
+    /**
+     * Get vector for a noun
+     */
+    getNounVector(id: string): Promise<number[] | null>;
+    /**
+     * Save HNSW graph data for a noun
+     */
+    saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    /**
+     * Get HNSW graph data for a noun
+     */
+    getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    /**
+     * Save HNSW system data (entry point, max level)
+     */
+    saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    /**
+     * Get HNSW system data
+     */
+    getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
 }
 export {};

package/dist/storage/adapters/fileSystemStorage.js

@@ -2108,5 +2108,71 @@ export class FileSystemStorage extends BaseStorage {
             return false;
         }
     }
+    // =============================================
+    // HNSW Index Persistence (v3.35.0+)
+    // =============================================
+    /**
+     * Get vector for a noun
+     */
+    async getNounVector(id) {
+        await this.ensureInitialized();
+        const noun = await this.getNode(id);
+        return noun ? noun.vector : null;
+    }
+    /**
+     * Save HNSW graph data for a noun
+     */
+    async saveHNSWData(nounId, hnswData) {
+        await this.ensureInitialized();
+        // Use sharded path for HNSW data
+        const shard = nounId.substring(0, 2).toLowerCase();
+        const hnswDir = path.join(this.rootDir, 'entities', 'nouns', 'hnsw', shard);
+        await this.ensureDirectoryExists(hnswDir);
+        const filePath = path.join(hnswDir, `${nounId}.json`);
+        await fs.promises.writeFile(filePath, JSON.stringify(hnswData, null, 2));
+    }
+    /**
+     * Get HNSW graph data for a noun
+     */
+    async getHNSWData(nounId) {
+        await this.ensureInitialized();
+        const shard = nounId.substring(0, 2).toLowerCase();
+        const filePath = path.join(this.rootDir, 'entities', 'nouns', 'hnsw', shard, `${nounId}.json`);
+        try {
+            const data = await fs.promises.readFile(filePath, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.error(`Error reading HNSW data for ${nounId}:`, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Save HNSW system data (entry point, max level)
+     */
+    async saveHNSWSystem(systemData) {
+        await this.ensureInitialized();
+        const filePath = path.join(this.systemDir, 'hnsw-system.json');
+        await fs.promises.writeFile(filePath, JSON.stringify(systemData, null, 2));
+    }
+    /**
+     * Get HNSW system data
+     */
+    async getHNSWSystem() {
+        await this.ensureInitialized();
+        const filePath = path.join(this.systemDir, 'hnsw-system.json');
+        try {
+            const data = await fs.promises.readFile(filePath, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                console.error('Error reading HNSW system data:', error);
+            }
+            return null;
+        }
+    }
 }
 //# sourceMappingURL=fileSystemStorage.js.map

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

@@ -102,6 +102,15 @@ export declare class GcsStorage extends BaseStorage {
      * Override base class method to detect GCS-specific throttling errors
      */
     protected isThrottlingError(error: any): boolean;
+    /**
+     * Override base class to enable smart batching for cloud storage (v3.32.3+)
+     *
+     * GCS is cloud storage with network latency (~50ms per write).
+     * Smart batching reduces writes from 1000 ops → 100 batches.
+     *
+     * @returns true (GCS is cloud storage)
+     */
+    protected isCloudStorage(): boolean;
     /**
      * Apply backpressure before starting an operation
      * @returns Request ID for tracking
@@ -330,5 +339,41 @@ export declare class GcsStorage extends BaseStorage {
      * Persist counts to 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: 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>;
 }
 export {};

package/dist/storage/adapters/gcsStorage.js

@@ -195,6 +195,17 @@ export class GcsStorage extends BaseStorage {
             message.includes('rate limit') ||
             message.includes('too many requests'));
     }
+    /**
+     * Override base class to enable smart batching for cloud storage (v3.32.3+)
+     *
+     * GCS is cloud storage with network latency (~50ms per write).
+     * Smart batching reduces writes from 1000 ops → 100 batches.
+     *
+     * @returns true (GCS is cloud storage)
+     */
+    isCloudStorage() {
+        return true; // GCS benefits from batching
+    }
     /**
      * Apply backpressure before starting an operation
      * @returns Request ID for tracking
@@ -1128,15 +1139,32 @@ export class GcsStorage extends BaseStorage {
     async initializeCountsFromScan() {
         try {
             prodLog.info('📊 Scanning GCS bucket to initialize counts...');
+            prodLog.info(`🔍 Noun prefix: ${this.nounPrefix}`);
+            prodLog.info(`🔍 Verb prefix: ${this.verbPrefix}`);
             // Count nouns
             const [nounFiles] = await this.bucket.getFiles({ prefix: this.nounPrefix });
-            this.totalNounCount = nounFiles?.filter((f) => f.name?.endsWith('.json')).length || 0;
+            prodLog.info(`🔍 Found ${nounFiles?.length || 0} total files under noun prefix`);
+            const jsonNounFiles = nounFiles?.filter((f) => f.name?.endsWith('.json')) || [];
+            this.totalNounCount = jsonNounFiles.length;
+            if (jsonNounFiles.length > 0 && jsonNounFiles.length <= 5) {
+                prodLog.info(`📄 Sample noun files: ${jsonNounFiles.slice(0, 5).map((f) => f.name).join(', ')}`);
+            }
             // Count verbs
             const [verbFiles] = await this.bucket.getFiles({ prefix: this.verbPrefix });
-            this.totalVerbCount = verbFiles?.filter((f) => f.name?.endsWith('.json')).length || 0;
+            prodLog.info(`🔍 Found ${verbFiles?.length || 0} total files under verb prefix`);
+            const jsonVerbFiles = verbFiles?.filter((f) => f.name?.endsWith('.json')) || [];
+            this.totalVerbCount = jsonVerbFiles.length;
+            if (jsonVerbFiles.length > 0 && jsonVerbFiles.length <= 5) {
+                prodLog.info(`📄 Sample verb files: ${jsonVerbFiles.slice(0, 5).map((f) => f.name).join(', ')}`);
+            }
             // Save initial counts
-            await this.persistCounts();
-            prodLog.info(`✅ Initialized counts from scan: ${this.totalNounCount} nouns, ${this.totalVerbCount} verbs`);
+            if (this.totalNounCount > 0 || this.totalVerbCount > 0) {
+                await this.persistCounts();
+                prodLog.info(`✅ Initialized counts from scan: ${this.totalNounCount} nouns, ${this.totalVerbCount} verbs`);
+            }
+            else {
+                prodLog.warn(`⚠️  No entities found during bucket scan. Check that entities exist and prefixes are correct.`);
+            }
         }
         catch (error) {
             // CRITICAL FIX: Don't silently fail - this prevents data loss scenarios
@@ -1167,5 +1195,95 @@ export class GcsStorage extends BaseStorage {
             this.logger.error('Error persisting counts:', 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.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 {
+            // Use sharded path for HNSW data
+            const shard = getShardIdFromUuid(nounId);
+            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
+            const file = this.bucket.file(key);
+            await file.save(JSON.stringify(hnswData, null, 2), {
+                contentType: 'application/json',
+                resumable: false
+            });
+        }
+        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 shard = getShardIdFromUuid(nounId);
+            const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
+            const file = this.bucket.file(key);
+            const [contents] = await file.download();
+            return JSON.parse(contents.toString());
+        }
+        catch (error) {
+            if (error.code === 404) {
+                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 key = `${this.systemPrefix}hnsw-system.json`;
+            const file = this.bucket.file(key);
+            await file.save(JSON.stringify(systemData, null, 2), {
+                contentType: 'application/json',
+                resumable: false
+            });
+        }
+        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 key = `${this.systemPrefix}hnsw-system.json`;
+            const file = this.bucket.file(key);
+            const [contents] = await file.download();
+            return JSON.parse(contents.toString());
+        }
+        catch (error) {
+            if (error.code === 404) {
+                return null;
+            }
+            this.logger.error('Failed to get HNSW system data:', error);
+            throw new Error(`Failed to get HNSW system data: ${error}`);
+        }
+    }
 }
 //# sourceMappingURL=gcsStorage.js.map

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

@@ -174,4 +174,36 @@ export declare class MemoryStorage extends BaseStorage {
      * Persist counts to storage - no-op for memory storage
      */
     protected persistCounts(): Promise<void>;
+    /**
+     * Get vector for a noun
+     */
+    getNounVector(id: string): Promise<number[] | null>;
+    /**
+     * Save HNSW graph data for a noun
+     */
+    saveHNSWData(nounId: string, hnswData: {
+        level: number;
+        connections: Record<string, string[]>;
+    }): Promise<void>;
+    /**
+     * Get HNSW graph data for a noun
+     */
+    getHNSWData(nounId: string): Promise<{
+        level: number;
+        connections: Record<string, string[]>;
+    } | null>;
+    /**
+     * Save HNSW system data (entry point, max level)
+     */
+    saveHNSWSystem(systemData: {
+        entryPointId: string | null;
+        maxLevel: number;
+    }): Promise<void>;
+    /**
+     * Get HNSW system data
+     */
+    getHNSWSystem(): Promise<{
+        entryPointId: string | null;
+        maxLevel: number;
+    } | null>;
 }