@soulcraft/brainy 4.7.2 → 4.7.4

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 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.
 
+### [4.7.4](https://github.com/soulcraftlabs/brainy/compare/v4.7.3...v4.7.4) (2025-10-27)
+
+**CRITICAL SYSTEMIC VFS BUG FIX - Workshop Team Unblocked!**
+
+This hotfix resolves a systemic bug affecting ALL storage adapters that caused VFS queries to return empty results even when data existed.
+
+#### 🐛 Critical Bug Fixes
+
+* **storage**: Fix systemic metadata skip bug across ALL 7 storage adapters
+  - **Impact**: VFS queries returned empty arrays despite 577 "Contains" relationships existing
+  - **Root Cause**: All storage adapters skipped entities if metadata file read returned null
+  - **Bug Pattern**: `if (!metadata) continue` in getNouns()/getVerbs() methods
+  - **Fixed Locations**: 12 bug sites across 7 adapters (TypeAware, Memory, FileSystem, GCS, S3, R2, OPFS, Azure)
+  - **Solution**: Allow optional metadata with `metadata: (metadata || {}) as NounMetadata`
+  - **Result**: Workshop team UNBLOCKED - VFS entities now queryable
+
+* **neural**: Fix SmartExtractor weighted score threshold bug (28 test failures → 4)
+  - **Root Cause**: Single signal with 0.8 confidence × 0.2 weight = 0.16 < 0.60 threshold
+  - **Solution**: Use original confidence when only one signal matches
+  - **Impact**: Entity type extraction now works correctly
+
+* **neural**: Fix PatternSignal priority ordering
+  - Specific patterns (organization "Inc", location "City, ST") now ranked higher than generic patterns
+  - Prevents person full-name pattern from overriding organization/location indicators
+
+* **api**: Fix Brainy.relate() weight parameter not returned in getRelations()
+  - **Root Cause**: Weight stored in metadata but read from wrong location
+  - **Solution**: Extract weight from metadata: `v.metadata?.weight ?? 1.0`
+
+#### 📊 Test Results
+
+- TypeAwareStorageAdapter: 17/17 tests passing (was 7 failures)
+- SmartExtractor: 42/46 tests passing (was 28 failures)
+- Neural domain clustering: 3/3 tests passing
+- Brainy.relate() weight: 1/1 test passing
+
+#### 🏗️ Architecture Notes
+
+**Two-Phase Fix**:
+1. Storage Layer (NOW FIXED): Returns ALL entities, even with empty metadata
+2. VFS Layer (ALREADY SAFE): PathResolver uses optional chaining `entity.metadata?.vfsType`
+
+**Result**: Valid VFS entities pass through, invalid entities safely filtered out.
+
+### [4.7.3](https://github.com/soulcraftlabs/brainy/compare/v4.7.2...v4.7.3) (2025-10-27)
+
+- fix(storage): CRITICAL - preserve vectors when updating HNSW connections (v4.7.3) (46e7482)
+
+
 ### [4.4.0](https://github.com/soulcraftlabs/brainy/compare/v4.3.2...v4.4.0) (2025-10-24)
 
 - docs: update CHANGELOG for v4.4.0 release (a3c8a28)

package/dist/brainy.js

@@ -2561,7 +2561,7 @@ export class Brainy {
             from: v.sourceId,
             to: v.targetId,
             type: (v.verb || v.type),
-            weight: v.weight,
+            weight: v.metadata?.weight ?? 1.0, // v4.7.4: weight is in metadata
             metadata: v.metadata,
             service: v.metadata?.service,
             createdAt: typeof v.createdAt === 'number' ? v.createdAt : Date.now()

package/dist/neural/SmartExtractor.js

@@ -402,8 +402,16 @@ export class SmartExtractor {
                 bestSignals = data.signals;
             }
         }
+        // Determine final confidence score
+        // FIX: When only one signal matches, use its original confidence instead of weighted score
+        // The weighted score is too low when only one signal matches (e.g., 0.8 * 0.2 = 0.16 < 0.60 threshold)
+        let finalConfidence = bestScore;
+        if (bestSignals.length === 1) {
+            // Single signal: use its original confidence
+            finalConfidence = bestSignals[0].confidence;
+        }
         // Check minimum confidence threshold
-        if (!bestType || bestScore < this.options.minConfidence) {
+        if (!bestType || finalConfidence < this.options.minConfidence) {
             return null;
         }
         // Track signal contributions
@@ -415,7 +423,7 @@ export class SmartExtractor {
         const evidence = `Ensemble: ${signalNames} (${bestSignals.length} signal${bestSignals.length > 1 ? 's' : ''} agree)`;
         return {
             type: bestType,
-            confidence: Math.min(bestScore, 1.0), // Cap at 1.0
+            confidence: Math.min(finalConfidence, 1.0), // Cap at 1.0
             source: 'ensemble',
             evidence,
             metadata: {
@@ -444,7 +452,9 @@ export class SmartExtractor {
             return null;
         }
         const best = validResults[0];
-        if (best.weightedScore < this.options.minConfidence) {
+        // FIX: Use original confidence, not weighted score for threshold check
+        // Weighted score is for ranking signals, not for absolute threshold
+        if (best.confidence < this.options.minConfidence) {
             return null;
         }
         return {

package/dist/neural/signals/PatternSignal.js

@@ -63,30 +63,50 @@ export class PatternSignal {
      * - Document: files, papers, reports
      */
     initializePatterns() {
-        // Person patterns
-        this.addPatterns(NounType.Person, 0.80, [
-            /\b(?:Dr|Prof|Mr|Mrs|Ms|Sir|Lady|Lord)\s+[A-Z][a-z]+/,
-            /\b[A-Z][a-z]+\s+[A-Z][a-z]+(?:\s+[A-Z][a-z]+)?\b/, // Full names
-            /\b(?:CEO|CTO|CFO|COO|VP|Director|Manager|Engineer|Developer|Designer)\b/i,
-            /\b(?:author|creator|founder|inventor|contributor|maintainer)\b/i,
-            /\b(?:user|member|participant|attendee|speaker|presenter)\b/i
+        // Organization patterns - HIGH PRIORITY (must check before person full name pattern)
+        this.addPatterns(NounType.Organization, 0.88, [
+            /\b(?:Inc|LLC|Corp|Ltd|GmbH|SA|AG)\b/, // Strong org indicators
+            /\b[A-Z][a-z]+\s+(?:Company|Corporation|Enterprises|Industries|Group)\b/
         ]);
-        // Location patterns
-        this.addPatterns(NounType.Location, 0.75, [
-            /\b(?:city|town|village|country|nation|state|province)\b/i,
-            /\b(?:street|avenue|road|boulevard|lane|drive)\b/i,
-            /\b(?:building|tower|center|complex|headquarters)\b/i,
-            /\b(?:north|south|east|west|central)\s+[A-Z][a-z]+/i,
-            /\b[A-Z][a-z]+,\s*[A-Z]{2}\b/ // City, State format
+        // Location patterns - HIGH PRIORITY (city/country format, addresses)
+        this.addPatterns(NounType.Location, 0.86, [
+            /\b[A-Z][a-z]+,\s*[A-Z]{2}\b/, // City, State format (e.g., "Paris, FR")
+            /\b(?:street|avenue|road|boulevard|lane|drive)\b/i
         ]);
-        // Organization patterns
-        this.addPatterns(NounType.Organization, 0.78, [
-            /\b(?:Inc|LLC|Corp|Ltd|GmbH|SA|AG)\b/,
-            /\b[A-Z][a-z]+\s+(?:Company|Corporation|Enterprises|Industries|Group)\b/,
+        // Event patterns - HIGH PRIORITY (specific event keywords)
+        this.addPatterns(NounType.Event, 0.84, [
+            /\b(?:conference|summit|symposium|workshop|seminar|webinar)\b/i,
+            /\b(?:hackathon|bootcamp)\b/i
+        ]);
+        // Person patterns - SPECIFIC INDICATORS (high confidence)
+        this.addPatterns(NounType.Person, 0.82, [
+            /\b(?:Dr|Prof|Mr|Mrs|Ms|Sir|Lady|Lord)\s+[A-Z][a-z]+/, // Titles
+            /\b(?:CEO|CTO|CFO|COO|VP|Director|Manager|Engineer|Developer|Designer)\b/i, // Roles
+            /\b(?:author|creator|founder|inventor|contributor|maintainer)\b/i
+        ]);
+        // Organization patterns - MEDIUM PRIORITY
+        this.addPatterns(NounType.Organization, 0.76, [
             /\b(?:university|college|institute|academy|school)\b/i,
             /\b(?:department|division|team|committee|board)\b/i,
             /\b(?:government|agency|bureau|ministry|administration)\b/i
         ]);
+        // Location patterns - MEDIUM PRIORITY
+        this.addPatterns(NounType.Location, 0.74, [
+            /\b(?:city|town|village|country|nation|state|province)\b/i,
+            /\b(?:building|tower|center|complex|headquarters)\b/i,
+            /\b(?:north|south|east|west|central)\s+[A-Z][a-z]+/i
+        ]);
+        // Event patterns - MEDIUM PRIORITY
+        this.addPatterns(NounType.Event, 0.72, [
+            /\b(?:meeting|session|call|standup|retrospective|sprint)\b/i,
+            /\b(?:release|launch|deployment|rollout|update)\b/i,
+            /\b(?:training|course|tutorial)\b/i
+        ]);
+        // Person patterns - GENERIC (low confidence, catches full names but easily overridden)
+        this.addPatterns(NounType.Person, 0.68, [
+            /\b[A-Z][a-z]+\s+[A-Z][a-z]+(?:\s+[A-Z][a-z]+)?\b/, // Full names (generic, low priority)
+            /\b(?:user|member|participant|attendee|speaker|presenter)\b/i
+        ]);
         // Technology patterns (Thing type)
         this.addPatterns(NounType.Thing, 0.82, [
             /\b(?:JavaScript|TypeScript|Python|Java|C\+\+|Go|Rust|Swift|Kotlin)\b/,

package/dist/storage/adapters/azureBlobStorage.js

@@ -942,9 +942,8 @@ export class AzureBlobStorage extends BaseStorage {
             const node = await this.getNode(id);
             if (!node)
                 continue;
+            // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
             const metadata = await this.getNounMetadata(id);
-            if (!metadata)
-                continue;
             // Apply filters if provided
             if (options.filter) {
                 if (options.filter.nounType) {
@@ -960,7 +959,7 @@ export class AzureBlobStorage extends BaseStorage {
             // Combine node with metadata
             items.push({
                 ...node,
-                metadata
+                metadata: (metadata || {}) // Empty if none
             });
             count++;
         }
@@ -1275,13 +1274,38 @@ export class AzureBlobStorage extends BaseStorage {
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
         try {
+            // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
             const shard = getShardIdFromUuid(nounId);
             const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
             const blockBlobClient = this.containerClient.getBlockBlobClient(key);
-            const content = JSON.stringify(hnswData, null, 2);
-            await blockBlobClient.upload(content, content.length, {
-                blobHTTPHeaders: { blobContentType: 'application/json' }
-            });
+            try {
+                // Read existing node data
+                const downloadResponse = await blockBlobClient.download(0);
+                const existingData = await this.streamToBuffer(downloadResponse.readableStreamBody);
+                const existingNode = JSON.parse(existingData.toString());
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode,
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                const content = JSON.stringify(updatedNode, null, 2);
+                await blockBlobClient.upload(content, content.length, {
+                    blobHTTPHeaders: { blobContentType: 'application/json' }
+                });
+            }
+            catch (error) {
+                // If node doesn't exist yet, create it with just HNSW data
+                if (error.statusCode === 404 || error.code === 'BlobNotFound') {
+                    const content = JSON.stringify(hnswData, null, 2);
+                    await blockBlobClient.upload(content, content.length, {
+                        blobHTTPHeaders: { blobContentType: 'application/json' }
+                    });
+                }
+                else {
+                    throw error;
+                }
+            }
         }
         catch (error) {
             this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);

package/dist/storage/adapters/fileSystemStorage.js

@@ -745,11 +745,10 @@ export class FileSystemStorage extends BaseStorage {
                     const data = await fs.promises.readFile(this.getNodePath(id), 'utf-8');
                     const parsedNoun = JSON.parse(data);
                     // v4.0.0: Load metadata from separate storage
+                    // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
                     const metadata = await this.getNounMetadata(id);
-                    if (!metadata)
-                        continue;
                     // Apply filter if provided
-                    if (options.filter) {
+                    if (options.filter && metadata) {
                         let matches = true;
                         for (const [key, value] of Object.entries(options.filter)) {
                             if (metadata[key] !== value) {
@@ -775,7 +774,7 @@ export class FileSystemStorage extends BaseStorage {
                         vector: parsedNoun.vector,
                         connections: connections,
                         level: parsedNoun.level || 0,
-                        metadata: metadata
+                        metadata: (metadata || {}) // Empty if none
                     };
                     items.push(nounWithMetadata);
                     successfullyLoaded++;
@@ -2156,12 +2155,34 @@ export class FileSystemStorage extends BaseStorage {
      */
     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));
+        // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
+        // Previous implementation overwrote the entire file, destroying vector data
+        // Now we READ the existing node, UPDATE only connections/level, then WRITE back the complete node
+        const filePath = this.getNodePath(nounId);
+        try {
+            // Read existing node data
+            const existingData = await fs.promises.readFile(filePath, 'utf-8');
+            const existingNode = JSON.parse(existingData);
+            // Preserve id and vector, update only HNSW graph metadata
+            const updatedNode = {
+                ...existingNode, // Preserve all existing fields (id, vector, etc.)
+                level: hnswData.level,
+                connections: hnswData.connections
+            };
+            // Write back the COMPLETE node with updated HNSW data
+            await fs.promises.writeFile(filePath, JSON.stringify(updatedNode, null, 2));
+        }
+        catch (error) {
+            // If node doesn't exist yet, create it with just HNSW data
+            // This should only happen during initial node creation
+            if (error.code === 'ENOENT') {
+                await this.ensureDirectoryExists(path.dirname(filePath));
+                await fs.promises.writeFile(filePath, JSON.stringify(hnswData, null, 2));
+            }
+            else {
+                throw error;
+            }
+        }
     }
     /**
      * Get HNSW graph data for a noun

package/dist/storage/adapters/gcsStorage.js

@@ -804,9 +804,8 @@ export class GcsStorage extends BaseStorage {
         // v4.0.0: Combine nodes with metadata to create HNSWNounWithMetadata[]
         const items = [];
         for (const node of result.nodes) {
+            // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
             const metadata = await this.getNounMetadata(node.id);
-            if (!metadata)
-                continue;
             // Apply filters if provided
             if (options.filter) {
                 // Filter by noun type
@@ -839,7 +838,7 @@ export class GcsStorage extends BaseStorage {
                 vector: [...node.vector],
                 connections: new Map(node.connections),
                 level: node.level || 0,
-                metadata: metadata
+                metadata: (metadata || {}) // Empty if none
             };
             items.push(nounWithMetadata);
         }
@@ -1469,14 +1468,41 @@ export class GcsStorage extends BaseStorage {
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
         try {
-            // Use sharded path for HNSW data
+            // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
+            // Previous implementation overwrote the entire file, destroying vector data
+            // Now we READ the existing node, UPDATE only connections/level, then WRITE back the complete node
             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
-            });
+            try {
+                // Read existing node data
+                const [existingData] = await file.download();
+                const existingNode = JSON.parse(existingData.toString());
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode, // Preserve all existing fields (id, vector, etc.)
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                // Write back the COMPLETE node with updated HNSW data
+                await file.save(JSON.stringify(updatedNode, null, 2), {
+                    contentType: 'application/json',
+                    resumable: false
+                });
+            }
+            catch (error) {
+                // If node doesn't exist yet, create it with just HNSW data
+                // This should only happen during initial node creation
+                if (error.code === 404) {
+                    await file.save(JSON.stringify(hnswData, null, 2), {
+                        contentType: 'application/json',
+                        resumable: false
+                    });
+                }
+                else {
+                    throw error;
+                }
+            }
         }
         catch (error) {
             this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);

package/dist/storage/adapters/memoryStorage.js

@@ -152,16 +152,15 @@ export class MemoryStorage extends BaseStorage {
             if (!noun)
                 continue;
             // Get metadata from separate storage
+            // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
             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: metadata // Include metadata field
+                metadata: (metadata || {}) // Include metadata field (empty if none)
             };
             // Copy connections
             for (const [level, connections] of noun.connections.entries()) {
@@ -357,9 +356,9 @@ export class MemoryStorage extends BaseStorage {
             if (!hnswVerb)
                 continue;
             // Get metadata from separate storage
+            // FIX v4.7.4: Don't skip verbs without metadata - metadata is optional in v4.0.0
+            // Core fields (verb, sourceId, targetId) are in HNSWVerb itself
             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,
@@ -369,8 +368,8 @@ export class MemoryStorage extends BaseStorage {
                 verb: hnswVerb.verb,
                 sourceId: hnswVerb.sourceId,
                 targetId: hnswVerb.targetId,
-                // Metadata field
-                metadata: metadata
+                // Metadata field (empty if none)
+                metadata: metadata || {}
             };
             // Copy connections
             for (const [level, connections] of hnswVerb.connections.entries()) {

package/dist/storage/adapters/opfsStorage.js

@@ -1411,11 +1411,10 @@ export class OPFSStorage extends BaseStorage {
             const noun = await this.getNoun_internal(id);
             if (noun) {
                 // Load metadata for filtering and combining
+                // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
                 const metadata = await this.getNounMetadata(id);
-                if (!metadata)
-                    continue;
                 // Apply filters if provided
-                if (options.filter) {
+                if (options.filter && metadata) {
                     // Filter by noun type
                     if (options.filter.nounType) {
                         const nounTypes = Array.isArray(options.filter.nounType)
@@ -1453,7 +1452,7 @@ export class OPFSStorage extends BaseStorage {
                     vector: [...noun.vector],
                     connections: new Map(noun.connections),
                     level: noun.level || 0,
-                    metadata: metadata
+                    metadata: (metadata || {}) // Empty if none
                 };
                 items.push(nounWithMetadata);
             }
@@ -1516,11 +1515,11 @@ export class OPFSStorage extends BaseStorage {
             const hnswVerb = await this.getVerb_internal(id);
             if (hnswVerb) {
                 // Load metadata for filtering and combining
+                // FIX v4.7.4: Don't skip verbs without metadata - metadata is optional in v4.0.0
+                // Core fields (verb, sourceId, targetId) are in HNSWVerb itself
                 const metadata = await this.getVerbMetadata(id);
-                if (!metadata)
-                    continue;
                 // Apply filters if provided
-                if (options.filter) {
+                if (options.filter && metadata) {
                     // Filter by verb type
                     // v4.0.0: verb field is in HNSWVerb structure (NOT in metadata)
                     if (options.filter.verbType) {
@@ -1581,7 +1580,7 @@ export class OPFSStorage extends BaseStorage {
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: metadata
+                    metadata: (metadata || {}) // Empty if none
                 };
                 items.push(verbWithMetadata);
             }
@@ -1693,17 +1692,32 @@ export class OPFSStorage extends BaseStorage {
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
         try {
-            // Get or create the hnsw directory under nouns
+            // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
             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();
+            try {
+                // Read existing node data
+                const file = await fileHandle.getFile();
+                const existingData = await file.text();
+                const existingNode = JSON.parse(existingData);
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode,
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                const writable = await fileHandle.createWritable();
+                await writable.write(JSON.stringify(updatedNode, null, 2));
+                await writable.close();
+            }
+            catch (error) {
+                // If node doesn't exist or read fails, create with just HNSW data
+                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);

package/dist/storage/adapters/r2Storage.js

@@ -753,9 +753,30 @@ export class R2Storage extends BaseStorage {
     }
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
+        // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
         const shard = getShardIdFromUuid(nounId);
         const key = `entities/nouns/hnsw/${shard}/${nounId}.json`;
-        await this.writeObjectToPath(key, hnswData);
+        try {
+            // Read existing node data
+            const existingNode = await this.readObjectFromPath(key);
+            if (existingNode) {
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode,
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                await this.writeObjectToPath(key, updatedNode);
+            }
+            else {
+                // Node doesn't exist yet, create with just HNSW data
+                await this.writeObjectToPath(key, hnswData);
+            }
+        }
+        catch (error) {
+            // If read fails, create with just HNSW data
+            await this.writeObjectToPath(key, hnswData);
+        }
     }
     async getHNSWData(nounId) {
         await this.ensureInitialized();
@@ -862,11 +883,10 @@ export class R2Storage extends BaseStorage {
             const noun = await this.getNoun_internal(id);
             if (noun) {
                 // v4.0.0: Load metadata and combine with noun to create HNSWNounWithMetadata
+                // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
                 const metadata = await this.getNounMetadata(id);
-                if (!metadata)
-                    continue;
                 // Apply filters if provided
-                if (options.filter) {
+                if (options.filter && metadata) {
                     // Filter by noun type
                     if (options.filter.nounType) {
                         const nounTypes = Array.isArray(options.filter.nounType)
@@ -904,7 +924,7 @@ export class R2Storage extends BaseStorage {
                     vector: [...noun.vector],
                     connections: new Map(noun.connections),
                     level: noun.level || 0,
-                    metadata: metadata
+                    metadata: (metadata || {}) // Empty if none
                 };
                 items.push(nounWithMetadata);
             }

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -2867,11 +2867,10 @@ export class S3CompatibleStorage extends BaseStorage {
         // v4.0.0: Combine nodes with metadata to create HNSWNounWithMetadata[]
         const nounsWithMetadata = [];
         for (const node of result.nodes) {
+            // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
             const metadata = await this.getNounMetadata(node.id);
-            if (!metadata)
-                continue;
             // Apply filters if provided
-            if (options.filter) {
+            if (options.filter && metadata) {
                 // Filter by noun type
                 if (options.filter.nounType) {
                     const nounTypes = Array.isArray(options.filter.nounType)
@@ -2906,7 +2905,7 @@ export class S3CompatibleStorage extends BaseStorage {
                 vector: [...node.vector],
                 connections: new Map(node.connections),
                 level: node.level || 0,
-                metadata: metadata
+                metadata: (metadata || {}) // Empty if none
             };
             nounsWithMetadata.push(nounWithMetadata);
         }
@@ -3055,16 +3054,45 @@ export class S3CompatibleStorage extends BaseStorage {
     async saveHNSWData(nounId, hnswData) {
         await this.ensureInitialized();
         try {
-            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
-            // Use sharded path for HNSW data
+            const { PutObjectCommand, GetObjectCommand } = await import('@aws-sdk/client-s3');
+            // CRITICAL FIX (v4.7.3): Must preserve existing node data (id, vector) when updating HNSW metadata
             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'
-            }));
+            try {
+                // Read existing node data
+                const getResponse = await this.s3Client.send(new GetObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: key
+                }));
+                const existingData = await getResponse.Body.transformToString();
+                const existingNode = JSON.parse(existingData);
+                // Preserve id and vector, update only HNSW graph metadata
+                const updatedNode = {
+                    ...existingNode,
+                    level: hnswData.level,
+                    connections: hnswData.connections
+                };
+                await this.s3Client.send(new PutObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: key,
+                    Body: JSON.stringify(updatedNode, null, 2),
+                    ContentType: 'application/json'
+                }));
+            }
+            catch (error) {
+                // If node doesn't exist yet, create it with just HNSW data
+                if (error.name === 'NoSuchKey' || error.Code === 'NoSuchKey') {
+                    await this.s3Client.send(new PutObjectCommand({
+                        Bucket: this.bucketName,
+                        Key: key,
+                        Body: JSON.stringify(hnswData, null, 2),
+                        ContentType: 'application/json'
+                    }));
+                }
+                else {
+                    throw error;
+                }
+            }
         }
         catch (error) {
             this.logger.error(`Failed to save HNSW data for ${nounId}:`, error);

package/dist/storage/adapters/typeAwareStorageAdapter.js

@@ -354,19 +354,26 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                     // Check sourceId from HNSWVerb (v4.0.0: core fields are in HNSWVerb)
                     if (hnswVerb.sourceId !== sourceId)
                         continue;
-                    // Load metadata separately
+                    // Load metadata separately (optional in v4.0.0!)
+                    // FIX: Don't skip verbs without metadata - metadata is optional!
+                    // VFS relationships often have NO metadata (just verb/source/target)
                     const metadata = await this.getVerbMetadata(id);
-                    if (!metadata)
-                        continue;
                     // Create HNSWVerbWithMetadata (verbs don't have level field)
+                    // Convert connections from plain object to Map<number, Set<string>>
+                    const connectionsMap = new Map();
+                    if (hnswVerb.connections && typeof hnswVerb.connections === 'object') {
+                        for (const [level, ids] of Object.entries(hnswVerb.connections)) {
+                            connectionsMap.set(Number(level), new Set(ids));
+                        }
+                    }
                     const verbWithMetadata = {
                         id: hnswVerb.id,
                         vector: [...hnswVerb.vector],
-                        connections: new Map(hnswVerb.connections),
+                        connections: connectionsMap,
                         verb: hnswVerb.verb,
                         sourceId: hnswVerb.sourceId,
                         targetId: hnswVerb.targetId,
-                        metadata: metadata
+                        metadata: metadata || {} // Empty metadata if none exists
                     };
                     verbs.push(verbWithMetadata);
                 }
@@ -399,19 +406,25 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                     // Check targetId from HNSWVerb (v4.0.0: core fields are in HNSWVerb)
                     if (hnswVerb.targetId !== targetId)
                         continue;
-                    // Load metadata separately
+                    // Load metadata separately (optional in v4.0.0!)
+                    // FIX: Don't skip verbs without metadata - metadata is optional!
                     const metadata = await this.getVerbMetadata(id);
-                    if (!metadata)
-                        continue;
                     // Create HNSWVerbWithMetadata (verbs don't have level field)
+                    // Convert connections from plain object to Map<number, Set<string>>
+                    const connectionsMap = new Map();
+                    if (hnswVerb.connections && typeof hnswVerb.connections === 'object') {
+                        for (const [level, ids] of Object.entries(hnswVerb.connections)) {
+                            connectionsMap.set(Number(level), new Set(ids));
+                        }
+                    }
                     const verbWithMetadata = {
                         id: hnswVerb.id,
                         vector: [...hnswVerb.vector],
-                        connections: new Map(hnswVerb.connections),
+                        connections: connectionsMap,
                         verb: hnswVerb.verb,
                         sourceId: hnswVerb.sourceId,
                         targetId: hnswVerb.targetId,
-                        metadata: metadata
+                        metadata: metadata || {} // Empty metadata if none exists
                     };
                     verbs.push(verbWithMetadata);
                 }
@@ -439,19 +452,25 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                     continue;
                 // Cache type from HNSWVerb for future O(1) retrievals
                 this.verbTypeCache.set(hnswVerb.id, hnswVerb.verb);
-                // Load metadata separately
+                // Load metadata separately (optional in v4.0.0!)
+                // FIX: Don't skip verbs without metadata - metadata is optional!
                 const metadata = await this.getVerbMetadata(hnswVerb.id);
-                if (!metadata)
-                    continue;
                 // Create HNSWVerbWithMetadata (verbs don't have level field)
+                // Convert connections from plain object to Map<number, Set<string>>
+                const connectionsMap = new Map();
+                if (hnswVerb.connections && typeof hnswVerb.connections === 'object') {
+                    for (const [level, ids] of Object.entries(hnswVerb.connections)) {
+                        connectionsMap.set(Number(level), new Set(ids));
+                    }
+                }
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
-                    connections: new Map(hnswVerb.connections),
+                    connections: connectionsMap,
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: metadata
+                    metadata: metadata || {} // Empty metadata if none exists
                 };
                 verbs.push(verbWithMetadata);
             }

package/package.json

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