@soulcraft/brainy 3.50.2 → 4.0.0

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

@@ -2,9 +2,8 @@
  * Memory Storage Adapter
  * In-memory storage adapter for environments where persistent storage is not available or needed
  */
-import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
+import { HNSWNoun, HNSWVerb, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../../coreTypes.js';
 import { BaseStorage } from '../baseStorage.js';
-import { PaginatedResult } from '../../types/paginationTypes.js';
 /**
  * In-memory storage adapter
  * Uses Maps to store data in memory
@@ -24,18 +23,19 @@ export declare class MemoryStorage extends BaseStorage {
      */
     init(): Promise<void>;
     /**
-     * Save a noun to storage
+     * Save a noun to storage (v4.0.0: pure vector only, no metadata)
      */
     protected saveNoun_internal(noun: HNSWNoun): Promise<void>;
     /**
-     * Get a noun from storage (internal implementation)
-     * Combines vector data from nouns map with metadata from getNounMetadata()
+     * Get a noun from storage (v4.0.0: returns pure vector only)
+     * Base class handles combining with metadata
      */
     protected getNoun_internal(id: string): Promise<HNSWNoun | null>;
     /**
      * Get nouns with pagination and filtering
+     * v4.0.0: Returns HNSWNounWithMetadata[] (includes metadata field)
      * @param options Pagination and filtering options
-     * @returns Promise that resolves to a paginated result of nouns
+     * @returns Promise that resolves to a paginated result of nouns with metadata
      */
     getNouns(options?: {
         pagination?: {
@@ -48,16 +48,22 @@ export declare class MemoryStorage extends BaseStorage {
             service?: string | string[];
             metadata?: Record<string, any>;
         };
-    }): Promise<PaginatedResult<HNSWNoun>>;
+    }): Promise<{
+        items: HNSWNounWithMetadata[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     /**
      * Get nouns with pagination - simplified interface for compatibility
+     * v4.0.0: Returns HNSWNounWithMetadata[] (includes metadata field)
      */
     getNounsWithPagination(options?: {
         limit?: number;
         cursor?: string;
         filter?: any;
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -70,22 +76,23 @@ export declare class MemoryStorage extends BaseStorage {
      */
     protected getNounsByNounType_internal(nounType: string): Promise<HNSWNoun[]>;
     /**
-     * Delete a noun from storage
+     * Delete a noun from storage (v4.0.0)
      */
     protected deleteNoun_internal(id: string): Promise<void>;
     /**
-     * Save a verb to storage
+     * Save a verb to storage (v4.0.0: pure vector + core fields, no metadata)
      */
     protected saveVerb_internal(verb: HNSWVerb): Promise<void>;
     /**
-     * Get a verb from storage (internal implementation)
-     * Combines vector data from verbs map with metadata from getVerbMetadata()
+     * Get a verb from storage (v4.0.0: returns pure vector + core fields)
+     * Base class handles combining with metadata
      */
     protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
     /**
      * Get verbs with pagination and filtering
+     * v4.0.0: Returns HNSWVerbWithMetadata[] (includes metadata field)
      * @param options Pagination and filtering options
-     * @returns Promise that resolves to a paginated result of verbs
+     * @returns Promise that resolves to a paginated result of verbs with metadata
      */
     getVerbs(options?: {
         pagination?: {
@@ -100,22 +107,27 @@ export declare class MemoryStorage extends BaseStorage {
             service?: string | string[];
             metadata?: Record<string, any>;
         };
-    }): Promise<PaginatedResult<GraphVerb>>;
+    }): Promise<{
+        items: HNSWVerbWithMetadata[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     /**
      * Get verbs by source
      * @deprecated Use getVerbs() with filter.sourceId instead
      */
-    protected getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
+    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by target
      * @deprecated Use getVerbs() with filter.targetId instead
      */
-    protected getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
+    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by type
      * @deprecated Use getVerbs() with filter.verbType instead
      */
-    protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Delete a verb from storage
      */
@@ -169,7 +181,7 @@ export declare class MemoryStorage extends BaseStorage {
      */
     protected getStatisticsData(): Promise<StatisticsData | null>;
     /**
-     * Initialize counts from in-memory storage - O(1) operation
+     * Initialize counts from in-memory storage - O(1) operation (v4.0.0)
      */
     protected initializeCounts(): Promise<void>;
     /**

package/dist/storage/adapters/memoryStorage.js

@@ -36,19 +36,19 @@ export class MemoryStorage extends BaseStorage {
         this.isInitialized = true;
     }
     /**
-     * Save a noun to storage
+     * Save a noun to storage (v4.0.0: pure vector only, no metadata)
      */
     async saveNoun_internal(noun) {
         const isNew = !this.nouns.has(noun.id);
         // Create a deep copy to avoid reference issues
-        // CRITICAL: Only save lightweight vector data (no metadata)
-        // Metadata is saved separately via saveNounMetadata() (2-file system)
+        // v4.0.0: Store ONLY vector data (no metadata field)
+        // Metadata is saved separately via saveNounMetadata() by base class
         const nounCopy = {
             id: noun.id,
             vector: [...noun.vector],
             connections: new Map(),
             level: noun.level || 0
-            // NO metadata field - saved separately for scalability
+            // ✅ NO metadata field in v4.0.0
         };
         // Copy connections
         for (const [level, connections] of noun.connections.entries()) {
@@ -56,15 +56,11 @@ export class MemoryStorage extends BaseStorage {
         }
         // Save the noun directly in the nouns map
         this.nouns.set(noun.id, nounCopy);
-        // Update counts for new entities
-        if (isNew) {
-            const type = noun.metadata?.type || noun.metadata?.nounType || 'default';
-            this.incrementEntityCount(type);
-        }
+        // Note: Count tracking happens in saveNounMetadata since type info is in metadata now
     }
     /**
-     * Get a noun from storage (internal implementation)
-     * Combines vector data from nouns map with metadata from getNounMetadata()
+     * Get a noun from storage (v4.0.0: returns pure vector only)
+     * Base class handles combining with metadata
      */
     async getNoun_internal(id) {
         // Get the noun directly from the nouns map
@@ -74,28 +70,25 @@ export class MemoryStorage extends BaseStorage {
             return null;
         }
         // Return a deep copy to avoid reference issues
+        // v4.0.0: Return ONLY vector data (no metadata field)
         const nounCopy = {
             id: noun.id,
             vector: [...noun.vector],
             connections: new Map(),
             level: noun.level || 0
+            // ✅ NO metadata field in v4.0.0
         };
         // Copy connections
         for (const [level, connections] of noun.connections.entries()) {
             nounCopy.connections.set(level, new Set(connections));
         }
-        // Get metadata (entity data in 2-file system)
-        const metadata = await this.getNounMetadata(id);
-        // Combine into complete noun object
-        return {
-            ...nounCopy,
-            metadata: metadata || {}
-        };
+        return nounCopy;
     }
     /**
      * Get nouns with pagination and filtering
+     * v4.0.0: Returns HNSWNounWithMetadata[] (includes metadata field)
      * @param options Pagination and filtering options
-     * @returns Promise that resolves to a paginated result of nouns
+     * @returns Promise that resolves to a paginated result of nouns with metadata
      */
     async getNouns(options = {}) {
         const pagination = options.pagination || {};
@@ -113,13 +106,14 @@ export class MemoryStorage extends BaseStorage {
         // First, collect all noun IDs that match the filter criteria
         const matchingIds = [];
         // Iterate through all nouns to find matches
+        // v4.0.0: Load metadata from separate storage (no embedded metadata field)
         for (const [nounId, noun] of this.nouns.entries()) {
-            // Check the noun's embedded metadata field
-            const nounMetadata = noun.metadata || {};
-            // Also check separate metadata store for backward compatibility
-            const separateMetadata = await this.getMetadata(nounId);
-            // Merge both metadata sources (noun.metadata takes precedence)
-            const metadata = { ...separateMetadata, ...nounMetadata };
+            // Get metadata from separate storage
+            const metadata = await this.getNounMetadata(nounId);
+            // Skip if no metadata (shouldn't happen in v4.0.0 but be defensive)
+            if (!metadata) {
+                continue;
+            }
             // Filter by noun type if specified
             if (nounTypes && metadata.noun && !nounTypes.includes(metadata.noun)) {
                 continue;
@@ -150,24 +144,29 @@ export class MemoryStorage extends BaseStorage {
         // Create cursor for next page if there are more results
         const nextCursor = hasMore ? `${offset + limit}` : undefined;
         // Fetch the actual nouns for the current page
+        // v4.0.0: Return HNSWNounWithMetadata (includes metadata field)
         const items = [];
         for (const id of paginatedIds) {
             const noun = this.nouns.get(id);
             if (!noun)
                 continue;
-            // Create a deep copy to avoid reference issues
-            const nounCopy = {
+            // Get metadata from separate storage
+            const metadata = await this.getNounMetadata(id);
+            if (!metadata)
+                continue; // Skip if no metadata
+            // v4.0.0: Create HNSWNounWithMetadata with metadata field
+            const nounWithMetadata = {
                 id: noun.id,
                 vector: [...noun.vector],
                 connections: new Map(),
                 level: noun.level || 0,
-                metadata: noun.metadata
+                metadata: metadata // Include metadata field
             };
             // Copy connections
             for (const [level, connections] of noun.connections.entries()) {
-                nounCopy.connections.set(level, new Set(connections));
+                nounWithMetadata.connections.set(level, new Set(connections));
             }
-            items.push(nounCopy);
+            items.push(nounWithMetadata);
         }
         return {
             items,
@@ -178,6 +177,7 @@ export class MemoryStorage extends BaseStorage {
     }
     /**
      * Get nouns with pagination - simplified interface for compatibility
+     * v4.0.0: Returns HNSWNounWithMetadata[] (includes metadata field)
      */
     async getNounsWithPagination(options = {}) {
         // Convert to the getNouns format
@@ -210,33 +210,33 @@ export class MemoryStorage extends BaseStorage {
         return result.items;
     }
     /**
-     * Delete a noun from storage
+     * Delete a noun from storage (v4.0.0)
      */
     async deleteNoun_internal(id) {
-        const noun = this.nouns.get(id);
-        if (noun) {
-            const type = noun.metadata?.type || noun.metadata?.nounType || 'default';
+        // v4.0.0: Get type from separate metadata storage
+        const metadata = await this.getNounMetadata(id);
+        if (metadata) {
+            const type = metadata.noun || 'default';
             this.decrementEntityCount(type);
         }
         this.nouns.delete(id);
     }
     /**
-     * Save a verb to storage
+     * Save a verb to storage (v4.0.0: pure vector + core fields, no metadata)
      */
     async saveVerb_internal(verb) {
         const isNew = !this.verbs.has(verb.id);
         // Create a deep copy to avoid reference issues
-        // ARCHITECTURAL FIX (v3.50.1): Include core relational fields
+        // v4.0.0: Include core relational fields but NO metadata field
         const verbCopy = {
             id: verb.id,
             vector: [...verb.vector],
             connections: new Map(),
-            // CORE RELATIONAL DATA
+            // CORE RELATIONAL DATA (part of HNSWVerb in v4.0.0)
             verb: verb.verb,
             sourceId: verb.sourceId,
-            targetId: verb.targetId,
-            // User metadata (if any)
-            metadata: verb.metadata
+            targetId: verb.targetId
+            // ✅ NO metadata field in v4.0.0
         };
         // Copy connections
         for (const [level, connections] of verb.connections.entries()) {
@@ -244,12 +244,11 @@ export class MemoryStorage extends BaseStorage {
         }
         // Save the verb directly in the verbs map
         this.verbs.set(verb.id, verbCopy);
-        // Count tracking will be handled in saveVerbMetadata_internal
-        // since HNSWVerb doesn't contain type information
+        // Note: Count tracking happens in saveVerbMetadata since metadata is separate
     }
     /**
-     * Get a verb from storage (internal implementation)
-     * Combines vector data from verbs map with metadata from getVerbMetadata()
+     * Get a verb from storage (v4.0.0: returns pure vector + core fields)
+     * Base class handles combining with metadata
      */
     async getVerb_internal(id) {
         // Get the verb directly from the verbs map
@@ -259,17 +258,16 @@ export class MemoryStorage extends BaseStorage {
             return null;
         }
         // Return a deep copy of the HNSWVerb
-        // ARCHITECTURAL FIX (v3.50.1): Include core relational fields
+        // v4.0.0: Include core relational fields but NO metadata field
         const verbCopy = {
             id: verb.id,
             vector: [...verb.vector],
             connections: new Map(),
-            // CORE RELATIONAL DATA
+            // CORE RELATIONAL DATA (part of HNSWVerb in v4.0.0)
             verb: verb.verb,
             sourceId: verb.sourceId,
-            targetId: verb.targetId,
-            // User metadata
-            metadata: verb.metadata
+            targetId: verb.targetId
+            // ✅ NO metadata field in v4.0.0
         };
         // Copy connections
         for (const [level, connections] of verb.connections.entries()) {
@@ -279,8 +277,9 @@ export class MemoryStorage extends BaseStorage {
     }
     /**
      * Get verbs with pagination and filtering
+     * v4.0.0: Returns HNSWVerbWithMetadata[] (includes metadata field)
      * @param options Pagination and filtering options
-     * @returns Promise that resolves to a paginated result of verbs
+     * @returns Promise that resolves to a paginated result of verbs with metadata
      */
     async getVerbs(options = {}) {
         const pagination = options.pagination || {};
@@ -304,26 +303,31 @@ export class MemoryStorage extends BaseStorage {
         // First, collect all verb IDs that match the filter criteria
         const matchingIds = [];
         // Iterate through all verbs to find matches
+        // v4.0.0: Core fields (verb, sourceId, targetId) are in HNSWVerb, not metadata
         for (const [verbId, hnswVerb] of this.verbs.entries()) {
-            // Get the metadata for this verb to do filtering
+            // Get the metadata for service/data filtering
             const metadata = await this.getVerbMetadata(verbId);
             // Filter by verb type if specified
-            if (verbTypes && metadata && !verbTypes.includes(metadata.type || metadata.verb || '')) {
+            // v4.0.0: verb type is in HNSWVerb.verb
+            if (verbTypes && !verbTypes.includes(hnswVerb.verb || '')) {
                 continue;
             }
             // Filter by source ID if specified
-            if (sourceIds && metadata && !sourceIds.includes(metadata.sourceId || metadata.source || '')) {
+            // v4.0.0: sourceId is in HNSWVerb.sourceId
+            if (sourceIds && !sourceIds.includes(hnswVerb.sourceId || '')) {
                 continue;
             }
             // Filter by target ID if specified
-            if (targetIds && metadata && !targetIds.includes(metadata.targetId || metadata.target || '')) {
+            // v4.0.0: targetId is in HNSWVerb.targetId
+            if (targetIds && !targetIds.includes(hnswVerb.targetId || '')) {
                 continue;
             }
             // Filter by metadata fields if specified
-            if (filter.metadata && metadata && metadata.data) {
+            if (filter.metadata && metadata) {
                 let metadataMatch = true;
                 for (const [key, value] of Object.entries(filter.metadata)) {
-                    if (metadata.data[key] !== value) {
+                    const metadataValue = metadata[key];
+                    if (metadataValue !== value) {
                         metadataMatch = false;
                         break;
                     }
@@ -332,8 +336,7 @@ export class MemoryStorage extends BaseStorage {
                     continue;
             }
             // Filter by service if specified
-            if (services && metadata && metadata.createdBy && metadata.createdBy.augmentation &&
-                !services.includes(metadata.createdBy.augmentation)) {
+            if (services && metadata && metadata.service && !services.includes(metadata.service)) {
                 continue;
             }
             // If we got here, the verb matches all filters
@@ -346,41 +349,33 @@ export class MemoryStorage extends BaseStorage {
         // Create cursor for next page if there are more results
         const nextCursor = hasMore ? `${offset + limit}` : undefined;
         // Fetch the actual verbs for the current page
+        // v4.0.0: Return HNSWVerbWithMetadata (includes metadata field)
         const items = [];
         for (const id of paginatedIds) {
             const hnswVerb = this.verbs.get(id);
-            const metadata = await this.getVerbMetadata(id);
             if (!hnswVerb)
                 continue;
-            if (!metadata) {
-                console.warn(`Verb ${id} found but no metadata - creating minimal GraphVerb`);
-                // Return minimal GraphVerb if metadata is missing
-                items.push({
-                    id: hnswVerb.id,
-                    vector: hnswVerb.vector,
-                    sourceId: '',
-                    targetId: ''
-                });
-                continue;
-            }
-            // Create a complete GraphVerb by combining HNSWVerb with metadata
-            const graphVerb = {
+            // Get metadata from separate storage
+            const metadata = await this.getVerbMetadata(id);
+            if (!metadata)
+                continue; // Skip if no metadata
+            // v4.0.0: Create HNSWVerbWithMetadata with metadata field
+            const verbWithMetadata = {
                 id: hnswVerb.id,
                 vector: [...hnswVerb.vector],
-                sourceId: metadata.sourceId,
-                targetId: metadata.targetId,
-                source: metadata.source,
-                target: metadata.target,
-                verb: metadata.verb,
-                type: metadata.type,
-                weight: metadata.weight,
-                createdAt: metadata.createdAt,
-                updatedAt: metadata.updatedAt,
-                createdBy: metadata.createdBy,
-                data: metadata.data,
-                metadata: metadata.metadata || metadata.data // Use metadata.metadata (user's custom metadata)
+                connections: new Map(),
+                // Core relational fields (part of HNSWVerb)
+                verb: hnswVerb.verb,
+                sourceId: hnswVerb.sourceId,
+                targetId: hnswVerb.targetId,
+                // Metadata field
+                metadata: metadata
             };
-            items.push(graphVerb);
+            // Copy connections
+            for (const [level, connections] of hnswVerb.connections.entries()) {
+                verbWithMetadata.connections.set(level, new Set(connections));
+            }
+            items.push(verbWithMetadata);
         }
         return {
             items,
@@ -601,22 +596,32 @@ export class MemoryStorage extends BaseStorage {
         // to check multiple storage locations
     }
     /**
-     * Initialize counts from in-memory storage - O(1) operation
+     * Initialize counts from in-memory storage - O(1) operation (v4.0.0)
      */
     async initializeCounts() {
         // For memory storage, initialize counts from current in-memory state
         this.totalNounCount = this.nouns.size;
-        this.totalVerbCount = this.verbMetadata.size;
-        // Initialize type-based counts by scanning current data
+        this.totalVerbCount = this.verbs.size;
+        // Initialize type-based counts by scanning metadata storage (v4.0.0)
         this.entityCounts.clear();
         this.verbCounts.clear();
-        for (const noun of this.nouns.values()) {
-            const type = noun.metadata?.type || noun.metadata?.nounType || 'default';
-            this.entityCounts.set(type, (this.entityCounts.get(type) || 0) + 1);
+        // Count nouns by loading metadata for each
+        for (const [nounId, noun] of this.nouns.entries()) {
+            const metadata = await this.getNounMetadata(nounId);
+            if (metadata) {
+                const type = metadata.noun || 'default';
+                this.entityCounts.set(type, (this.entityCounts.get(type) || 0) + 1);
+            }
         }
-        for (const verbMetadata of this.verbMetadata.values()) {
-            const type = verbMetadata?.verb || verbMetadata?.type || 'default';
-            this.verbCounts.set(type, (this.verbCounts.get(type) || 0) + 1);
+        // Count verbs by loading metadata for each
+        for (const [verbId, verb] of this.verbs.entries()) {
+            const metadata = await this.getVerbMetadata(verbId);
+            if (metadata) {
+                // VerbMetadata doesn't have verb type - that's in HNSWVerb now
+                // Use the verb's type from the HNSWVerb itself
+                const type = verb.verb || 'default';
+                this.verbCounts.set(type, (this.verbCounts.get(type) || 0) + 1);
+            }
         }
     }
     /**

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

@@ -2,7 +2,7 @@
  * OPFS (Origin Private File System) Storage Adapter
  * Provides persistent storage for the vector database using the Origin Private File System API
  */
-import { GraphVerb, HNSWNoun, HNSWVerb, StatisticsData } from '../../coreTypes.js';
+import { HNSWNoun, HNSWVerb, HNSWNounWithMetadata, HNSWVerbWithMetadata, StatisticsData } from '../../coreTypes.js';
 import { BaseStorage } from '../baseStorage.js';
 import '../../types/fileSystemTypes.js';
 type HNSWNode = HNSWNoun;
@@ -87,7 +87,8 @@ export declare class OPFSStorage extends BaseStorage {
     protected saveEdge(edge: Edge): Promise<void>;
     /**
      * Get a verb from storage (internal implementation)
-     * Combines vector data from getEdge() with metadata from getVerbMetadata()
+     * v4.0.0: Returns ONLY vector + core relational fields (no metadata field)
+     * Base class combines with metadata via getVerb() -> HNSWVerbWithMetadata
      */
     protected getVerb_internal(id: string): Promise<HNSWVerb | null>;
     /**
@@ -101,27 +102,27 @@ export declare class OPFSStorage extends BaseStorage {
     /**
      * Get verbs by source (internal implementation)
      */
-    protected getVerbsBySource_internal(sourceId: string): Promise<GraphVerb[]>;
+    protected getVerbsBySource_internal(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get edges by source
      */
-    protected getEdgesBySource(sourceId: string): Promise<GraphVerb[]>;
+    protected getEdgesBySource(sourceId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by target (internal implementation)
      */
-    protected getVerbsByTarget_internal(targetId: string): Promise<GraphVerb[]>;
+    protected getVerbsByTarget_internal(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get edges by target
      */
-    protected getEdgesByTarget(targetId: string): Promise<GraphVerb[]>;
+    protected getEdgesByTarget(targetId: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get verbs by type (internal implementation)
      */
-    protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    protected getVerbsByType_internal(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Get edges by type
      */
-    protected getEdgesByType(type: string): Promise<GraphVerb[]>;
+    protected getEdgesByType(type: string): Promise<HNSWVerbWithMetadata[]>;
     /**
      * Delete a verb from storage (internal implementation)
      */
@@ -159,6 +160,10 @@ export declare class OPFSStorage extends BaseStorage {
      * Clear all data from storage
      */
     clear(): Promise<void>;
+    private quotaWarningThreshold;
+    private quotaCriticalThreshold;
+    private lastQuotaCheck;
+    private quotaCheckInterval;
     /**
      * Get information about storage usage and capacity
      */
@@ -168,6 +173,39 @@ export declare class OPFSStorage extends BaseStorage {
         quota: number | null;
         details?: Record<string, any>;
     }>;
+    /**
+     * Get detailed quota status with warnings (v4.0.0)
+     * Monitors storage usage and warns when approaching quota limits
+     *
+     * @returns Promise that resolves to quota status with warning levels
+     *
+     * @example
+     * const status = await storage.getQuotaStatus()
+     * if (status.warning) {
+     *   console.warn(`Storage ${status.usagePercent}% full: ${status.warningMessage}`)
+     * }
+     */
+    getQuotaStatus(): Promise<{
+        usage: number;
+        quota: number | null;
+        usagePercent: number;
+        remaining: number | null;
+        status: 'ok' | 'warning' | 'critical';
+        warning: boolean;
+        warningMessage?: string;
+    }>;
+    /**
+     * Monitor quota during operations (v4.0.0)
+     * Automatically checks quota at regular intervals and warns if approaching limits
+     * Call this before write operations to ensure quota is available
+     *
+     * @returns Promise that resolves when quota check is complete
+     *
+     * @example
+     * await storage.monitorQuota()  // Checks quota if interval has passed
+     * await storage.saveNoun(noun)  // Proceed with write operation
+     */
+    monitorQuota(): Promise<void>;
     /**
      * Get the statistics key for a specific date
      * @param date The date to get the key for
@@ -226,7 +264,7 @@ export declare class OPFSStorage extends BaseStorage {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: HNSWNoun[];
+        items: HNSWNounWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;
@@ -247,7 +285,7 @@ export declare class OPFSStorage extends BaseStorage {
             metadata?: Record<string, any>;
         };
     }): Promise<{
-        items: GraphVerb[];
+        items: HNSWVerbWithMetadata[];
         totalCount?: number;
         hasMore: boolean;
         nextCursor?: string;