@soulcraft/brainy 3.9.1 → 3.10.0

package/README.md

@@ -9,11 +9,11 @@
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
 
-**🧠 Brainy - Universal Knowledge Protocol™**
+**🧠 Brainy - The Knowledge Operating System**
 
-**World's first Triple Intelligence™ database** unifying vector similarity, graph relationships, and document filtering in one magical API. **Framework-friendly design** works seamlessly with Next.js, React, Vue, Angular, and any modern JavaScript framework.
+**The world's first Knowledge Operating System** where every piece of knowledge - files, concepts, entities, ideas - exists as living information that understands itself, evolves over time, and connects to everything related. Built on revolutionary Triple Intelligence™ that unifies vector similarity, graph relationships, and document filtering in one magical API.
 
-**Why Brainy Leads**: We're the first to solve the impossible—combining three different database paradigms (vector, graph, document) into one unified query interface. This breakthrough enables us to be the Universal Knowledge Protocol where all tools, augmentations, and AI models speak the same language.
+**Why Brainy Changes Everything**: Traditional systems trap knowledge in files or database rows. Brainy liberates it. Your characters exist across stories. Your concepts span projects. Your APIs remember their evolution. Every piece of knowledge - whether it's code, prose, or pure ideas - lives, breathes, and connects in a unified intelligence layer where everything understands its meaning, remembers its history, and relates to everything else.
 
 **Framework-first design.** Built for modern web development with zero configuration and automatic framework compatibility. O(log n) performance, <10ms search latency, production-ready.
 
@@ -182,7 +182,7 @@ If using nvm: `nvm use` (we provide a `.nvmrc` file)
 
 ### World's First Triple Intelligence™ Engine
 
-**The breakthrough that enables the Universal Knowledge Protocol:**
+**The breakthrough that enables The Knowledge Operating System:**
 
 - **Vector Search**: Semantic similarity with HNSW indexing
 - **Graph Relationships**: Navigate connected knowledge like Neo4j
@@ -190,7 +190,7 @@ If using nvm: `nvm use` (we provide a `.nvmrc` file)
 - **Unified in ONE API**: No separate queries, no complex joins
 - **First to solve this**: Others do vector OR graph OR document—we do ALL
 
-### Universal Knowledge Protocol with Infinite Expressiveness
+### The Knowledge Operating System with Infinite Expressiveness
 
 **Enabled by Triple Intelligence, standardized for everyone:**
 
@@ -209,6 +209,56 @@ await brain.find("Popular JavaScript libraries similar to Vue")
 await brain.find("Documentation about authentication from last month")
 ```
 
+### 🧠🌐 **Knowledge Graph + Virtual Filesystem - Where Ideas Come Alive**
+
+**Store ANY knowledge. Connect EVERYTHING. Files are optional.**
+
+- **Living Knowledge**: Characters, concepts, and systems that exist independently of files
+- **Universal Connections**: Link files to entities, entities to concepts, anything to anything
+- **Semantic Intelligence**: Find knowledge by meaning, not by where it's stored
+- **Optional Files**: Use filesystem operations when helpful, pure knowledge when not
+- **Perfect Memory**: Every piece of knowledge remembers its entire history
+- **Knowledge Evolution**: Watch ideas grow and connect across time and projects
+
+```javascript
+import { Brainy } from '@soulcraft/brainy'
+
+const brain = new Brainy({ storage: { type: 'memory' } })
+await brain.init()
+const vfs = brain.vfs()
+await vfs.init()
+
+// Start with familiar files if you want
+await vfs.writeFile('/story.txt', 'A tale of adventure...')
+
+// But knowledge doesn't need files!
+const alice = await vfs.createEntity({
+  name: 'Alice',
+  type: 'character',
+  description: 'Brave explorer discovering quantum worlds'
+})
+
+const quantumPhysics = await vfs.createConcept({
+  name: 'Quantum Entanglement',
+  domain: 'physics',
+  keywords: ['superposition', 'measurement', 'correlation']
+})
+
+// Connect EVERYTHING - files, entities, concepts
+await vfs.linkEntities(alice, quantumPhysics, 'studies')
+await vfs.addRelationship('/story.txt', alice.id, 'features')
+
+// Find knowledge by meaning, not location
+const physics = await vfs.search('quantum mechanics')
+// Returns: files, entities, concepts, relationships - ALL knowledge
+
+// Knowledge transcends boundaries
+const aliceKnowledge = await vfs.getEntityGraph(alice)
+// Her relationships, appearances, evolution - her entire existence
+```
+
+**Your knowledge isn't trapped anymore.** Characters live beyond stories. APIs exist beyond code files. Concepts connect across domains. This is knowledge that happens to support files, not a filesystem that happens to store knowledge.
+
 ### 🎯 Zero Configuration Philosophy
 
 Brainy automatically configures **everything**:
@@ -661,7 +711,7 @@ Key changes in the latest version:
 
 We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-## 🧠 The Universal Knowledge Protocol Explained
+## 🧠 The Knowledge Operating System Explained
 
 ### How We Achieved The Impossible
 
@@ -706,6 +756,14 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 - [Next.js Integration](docs/guides/nextjs-integration.md) - **NEW!** React and Next.js examples
 - [Vue.js Integration](docs/guides/vue-integration.md) - **NEW!** Vue and Nuxt examples
 
+### Virtual Filesystem & Knowledge Layer 🧠📁
+- [VFS Core Documentation](docs/vfs/VFS_CORE.md) - **NEW!** Complete filesystem architecture and API
+- [VFS + Knowledge Layer](docs/vfs/VFS_KNOWLEDGE_LAYER.md) - **NEW!** Intelligent knowledge management features
+- [Examples & Scenarios](docs/vfs/VFS_EXAMPLES_SCENARIOS.md) - **NEW!** Real-world use cases and code
+- [VFS API Guide](docs/vfs/VFS_API_GUIDE.md) - Complete API reference
+- [Knowledge Layer API](docs/vfs/KNOWLEDGE_LAYER_API.md) - Advanced knowledge features
+- [Knowledge Layer Overview](docs/KNOWLEDGE_LAYER_OVERVIEW.md) - Non-technical guide
+
 ### Core Documentation
 - [Getting Started Guide](docs/guides/getting-started.md)
 - [API Reference](docs/api/README.md)

package/dist/augmentations/KnowledgeAugmentation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Knowledge Layer Augmentation for VFS
+ *
+ * Adds intelligent features to VFS without modifying core functionality:
+ * - Event recording for all operations
+ * - Semantic versioning based on content changes
+ * - Entity and concept extraction
+ * - Git bridge for import/export
+ *
+ * This is a TRUE augmentation - VFS works perfectly without it
+ */
+import { Brainy } from '../brainy.js';
+import { BaseAugmentation } from './brainyAugmentation.js';
+export declare class KnowledgeAugmentation extends BaseAugmentation {
+    name: string;
+    timing: 'after';
+    metadata: 'none';
+    operations: any;
+    priority: number;
+    constructor(config?: any);
+    execute<T = any>(operation: string, params: any, next: () => Promise<T>): Promise<T>;
+    private eventRecorder?;
+    private semanticVersioning?;
+    private entitySystem?;
+    private conceptSystem?;
+    private gitBridge?;
+    private originalMethods;
+    initialize(context: any): Promise<void>;
+    augment(brain: Brainy): Promise<void>;
+    /**
+     * Wrap a VFS method to add Knowledge Layer functionality
+     */
+    private wrapMethod;
+    /**
+     * Add Knowledge Layer methods to VFS
+     */
+    private addKnowledgeMethods;
+    private isSemanticChange;
+    cleanup(brain: Brainy): Promise<void>;
+}

package/dist/augmentations/KnowledgeAugmentation.js

@@ -0,0 +1,251 @@
+/**
+ * Knowledge Layer Augmentation for VFS
+ *
+ * Adds intelligent features to VFS without modifying core functionality:
+ * - Event recording for all operations
+ * - Semantic versioning based on content changes
+ * - Entity and concept extraction
+ * - Git bridge for import/export
+ *
+ * This is a TRUE augmentation - VFS works perfectly without it
+ */
+import { BaseAugmentation } from './brainyAugmentation.js';
+import { EventRecorder } from '../vfs/EventRecorder.js';
+import { SemanticVersioning } from '../vfs/SemanticVersioning.js';
+import { PersistentEntitySystem } from '../vfs/PersistentEntitySystem.js';
+import { ConceptSystem } from '../vfs/ConceptSystem.js';
+import { GitBridge } from '../vfs/GitBridge.js';
+export class KnowledgeAugmentation extends BaseAugmentation {
+    constructor(config = {}) {
+        super(config);
+        this.name = 'knowledge';
+        this.timing = 'after'; // Process after VFS operations
+        this.metadata = 'none'; // No metadata access needed
+        this.operations = []; // VFS-specific augmentation, no operation interception
+        this.priority = 100; // Run last
+        this.originalMethods = new Map();
+    }
+    async execute(operation, params, next) {
+        // Pass through - this augmentation works at VFS level, not operation level
+        return await next();
+    }
+    async initialize(context) {
+        await this.augment(context.brain);
+    }
+    async augment(brain) {
+        // Only augment if VFS exists
+        const vfs = brain.vfs?.();
+        if (!vfs) {
+            console.warn('KnowledgeAugmentation: VFS not found, skipping');
+            return;
+        }
+        // Initialize Knowledge Layer components
+        this.eventRecorder = new EventRecorder(brain);
+        this.semanticVersioning = new SemanticVersioning(brain);
+        this.entitySystem = new PersistentEntitySystem(brain);
+        this.conceptSystem = new ConceptSystem(brain);
+        this.gitBridge = new GitBridge(vfs, brain);
+        // Wrap VFS methods to add intelligence WITHOUT slowing them down
+        this.wrapMethod(vfs, 'writeFile', async (original, path, data, options) => {
+            // Call original first (stays fast)
+            const result = await original.call(vfs, path, data, options);
+            // Knowledge processing in background (non-blocking)
+            setImmediate(async () => {
+                try {
+                    // Record event
+                    if (this.eventRecorder) {
+                        await this.eventRecorder.recordEvent({
+                            type: 'write',
+                            path,
+                            content: data,
+                            size: data.length,
+                            author: options?.author || 'system'
+                        });
+                    }
+                    // Check for semantic versioning
+                    if (this.semanticVersioning) {
+                        const existingContent = await vfs.readFile(path).catch(() => null);
+                        const shouldVersion = existingContent && this.isSemanticChange(existingContent, data);
+                        if (shouldVersion) {
+                            await this.semanticVersioning.createVersion(path, data, {
+                                message: 'Automatic semantic version'
+                            });
+                        }
+                    }
+                    // Extract concepts
+                    if (this.conceptSystem && options?.extractConcepts !== false) {
+                        await this.conceptSystem.extractAndLinkConcepts(path, data);
+                    }
+                    // Extract entities
+                    if (this.entitySystem && options?.extractEntities !== false) {
+                        await this.entitySystem.extractEntities(data.toString('utf8'), data);
+                    }
+                }
+                catch (error) {
+                    // Knowledge Layer errors should not affect VFS operations
+                    console.debug('KnowledgeLayer background processing error:', error);
+                }
+            });
+            return result;
+        });
+        this.wrapMethod(vfs, 'unlink', async (original, path) => {
+            const result = await original.call(vfs, path);
+            // Record deletion event
+            setImmediate(async () => {
+                if (this.eventRecorder) {
+                    await this.eventRecorder.recordEvent({
+                        type: 'delete',
+                        path,
+                        author: 'system'
+                    });
+                }
+            });
+            return result;
+        });
+        this.wrapMethod(vfs, 'rename', async (original, oldPath, newPath) => {
+            const result = await original.call(vfs, oldPath, newPath);
+            // Record rename event
+            setImmediate(async () => {
+                if (this.eventRecorder) {
+                    await this.eventRecorder.recordEvent({
+                        type: 'rename',
+                        path: oldPath,
+                        metadata: { newPath },
+                        author: 'system'
+                    });
+                }
+            });
+            return result;
+        });
+        // Add Knowledge Layer methods to VFS
+        this.addKnowledgeMethods(vfs);
+        console.log('✨ Knowledge Layer augmentation enabled');
+    }
+    /**
+     * Wrap a VFS method to add Knowledge Layer functionality
+     */
+    wrapMethod(vfs, methodName, wrapper) {
+        const original = vfs[methodName];
+        if (!original)
+            return;
+        // Store original for cleanup
+        this.originalMethods.set(methodName, original);
+        // Replace with wrapped version
+        vfs[methodName] = async (...args) => {
+            return await wrapper(original, ...args);
+        };
+    }
+    /**
+     * Add Knowledge Layer methods to VFS
+     */
+    addKnowledgeMethods(vfs) {
+        // Event history
+        vfs.getHistory = async (path, options) => {
+            if (!this.eventRecorder)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.eventRecorder.getHistory(path, options);
+        };
+        vfs.reconstructAtTime = async (path, timestamp) => {
+            if (!this.eventRecorder)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.eventRecorder.reconstructFileAtTime(path, timestamp);
+        };
+        // Semantic versioning
+        vfs.getVersions = async (path) => {
+            if (!this.semanticVersioning)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.semanticVersioning.getVersions(path);
+        };
+        vfs.restoreVersion = async (path, versionId) => {
+            if (!this.semanticVersioning)
+                throw new Error('Knowledge Layer not initialized');
+            const version = await this.semanticVersioning.getVersion(path, versionId);
+            if (version) {
+                await vfs.writeFile(path, version);
+            }
+        };
+        // Entities
+        vfs.findEntity = async (query) => {
+            if (!this.entitySystem)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.entitySystem.findEntity(query);
+        };
+        vfs.getEntityAppearances = async (entityId) => {
+            if (!this.entitySystem)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.entitySystem.getEvolution(entityId);
+        };
+        // Concepts
+        vfs.getConcepts = async (path) => {
+            if (!this.conceptSystem)
+                throw new Error('Knowledge Layer not initialized');
+            const concepts = await this.conceptSystem.findConcepts({ manifestedIn: path });
+            return concepts;
+        };
+        vfs.getConceptGraph = async (options) => {
+            if (!this.conceptSystem)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.conceptSystem.getConceptGraph(options);
+        };
+        // Git bridge
+        vfs.exportToGit = async (vfsPath, gitPath) => {
+            if (!this.gitBridge)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.gitBridge.exportToGit(vfsPath, gitPath);
+        };
+        vfs.importFromGit = async (gitPath, vfsPath) => {
+            if (!this.gitBridge)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.gitBridge.importFromGit(gitPath, vfsPath);
+        };
+        // Temporal coupling
+        vfs.findTemporalCoupling = async (path, windowMs) => {
+            if (!this.eventRecorder)
+                throw new Error('Knowledge Layer not initialized');
+            return await this.eventRecorder.findTemporalCoupling(path, windowMs);
+        };
+    }
+    isSemanticChange(oldContent, newContent) {
+        // Simple heuristic - significant size change or different content
+        const oldStr = oldContent.toString('utf8');
+        const newStr = newContent.toString('utf8');
+        // Check for significant size change (>10%)
+        const sizeDiff = Math.abs(oldStr.length - newStr.length) / oldStr.length;
+        if (sizeDiff > 0.1)
+            return true;
+        // Check for structural changes (simplified)
+        const oldLines = oldStr.split('\n').filter(l => l.trim());
+        const newLines = newStr.split('\n').filter(l => l.trim());
+        // Different number of non-empty lines
+        return Math.abs(oldLines.length - newLines.length) > 5;
+    }
+    async cleanup(brain) {
+        const vfs = brain.vfs?.();
+        if (!vfs)
+            return;
+        // Restore original methods
+        for (const [methodName, original] of this.originalMethods) {
+            vfs[methodName] = original;
+        }
+        // Remove added methods
+        delete vfs.getHistory;
+        delete vfs.reconstructAtTime;
+        delete vfs.getVersions;
+        delete vfs.restoreVersion;
+        delete vfs.findEntity;
+        delete vfs.getEntityAppearances;
+        delete vfs.getConcepts;
+        delete vfs.getConceptGraph;
+        delete vfs.exportToGit;
+        delete vfs.importFromGit;
+        delete vfs.findTemporalCoupling;
+        // Clean up components
+        this.eventRecorder = undefined;
+        this.semanticVersioning = undefined;
+        this.entitySystem = undefined;
+        this.conceptSystem = undefined;
+        this.gitBridge = undefined;
+        console.log('Knowledge Layer augmentation removed');
+    }
+}
+//# sourceMappingURL=KnowledgeAugmentation.js.map

package/dist/augmentations/defaultAugmentations.d.ts

@@ -25,6 +25,7 @@ export declare function createDefaultAugmentations(config?: {
     metrics?: boolean | Record<string, any>;
     monitoring?: boolean | Record<string, any>;
     display?: boolean | Record<string, any>;
+    knowledge?: boolean | Record<string, any>;
 }): BaseAugmentation[];
 /**
  * Get augmentation by name with type safety

package/dist/augmentations/defaultAugmentations.js

@@ -11,6 +11,7 @@ import { CacheAugmentation } from './cacheAugmentation.js';
 import { MetricsAugmentation } from './metricsAugmentation.js';
 import { MonitoringAugmentation } from './monitoringAugmentation.js';
 import { UniversalDisplayAugmentation } from './universalDisplayAugmentation.js';
+import { KnowledgeAugmentation } from './KnowledgeAugmentation.js';
 /**
  * Create default augmentations for zero-config operation
  * Returns an array of augmentations to be registered
@@ -44,6 +45,10 @@ export function createDefaultAugmentations(config = {}) {
         const monitoringConfig = typeof config.monitoring === 'object' ? config.monitoring : {};
         augmentations.push(new MonitoringAugmentation(monitoringConfig));
     }
+    // Knowledge Layer augmentation for VFS intelligence
+    if (config.knowledge !== false) {
+        augmentations.push(new KnowledgeAugmentation());
+    }
     return augmentations;
 }
 /**

package/dist/brainy.d.ts

@@ -8,6 +8,7 @@ import { Vector } from './coreTypes.js';
 import { ImprovedNeuralAPI } from './neural/improvedNeuralAPI.js';
 import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js';
 import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
+import { VirtualFileSystem } from './vfs/VirtualFileSystem.js';
 import { Entity, Relation, Result, AddParams, UpdateParams, RelateParams, FindParams, SimilarParams, GetRelationsParams, AddManyParams, DeleteManyParams, RelateManyParams, BatchResult, BrainyConfig } from './types/brainy.types.js';
 import { NounType } from './types/graphTypes.js';
 import { BrainyInterface } from './types/brainyDataInterface.js';
@@ -34,6 +35,7 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private _neural?;
     private _nlp?;
     private _tripleIntelligence?;
+    private _vfs?;
     private initialized;
     private dimensions?;
     constructor(config?: BrainyConfig);
@@ -48,6 +50,10 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Ensure Brainy is initialized
      */
     private ensureInitialized;
+    /**
+     * Check if Brainy is initialized
+     */
+    get isInitialized(): boolean;
     /**
      * Add an entity to the database
      */
@@ -133,6 +139,10 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * Natural Language Processing API
      */
     nlp(): NaturalLanguageProcessor;
+    /**
+     * Virtual File System API - Knowledge Operating System
+     */
+    vfs(): VirtualFileSystem;
     /**
      * Data Management API - backup, restore, import, export
      */
@@ -333,6 +343,7 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
     private verbsToRelations;
     /**
      * Embed data into vector
+     * Handles any data type by converting to string representation
      */
     embed(data: any): Promise<Vector>;
     /**

package/dist/brainy.js

@@ -14,6 +14,7 @@ import { createDefaultAugmentations } from './augmentations/defaultAugmentations
 import { ImprovedNeuralAPI } from './neural/improvedNeuralAPI.js';
 import { NaturalLanguageProcessor } from './neural/naturalLanguageProcessor.js';
 import { TripleIntelligenceSystem } from './triple/TripleIntelligenceSystem.js';
+import { VirtualFileSystem } from './vfs/VirtualFileSystem.js';
 import { MetadataIndexManager } from './utils/metadataIndex.js';
 import { GraphAdjacencyIndex } from './graph/graphAdjacencyIndex.js';
 import { createPipeline } from './streaming/pipeline.js';
@@ -138,6 +139,12 @@ export class Brainy {
             throw new Error('Brainy not initialized. Call init() first.');
         }
     }
+    /**
+     * Check if Brainy is initialized
+     */
+    get isInitialized() {
+        return this.initialized;
+    }
     // ============= CORE CRUD OPERATIONS =============
     /**
      * Add an entity to the database
@@ -895,6 +902,15 @@ export class Brainy {
         }
         return this._nlp;
     }
+    /**
+     * Virtual File System API - Knowledge Operating System
+     */
+    vfs() {
+        if (!this._vfs) {
+            this._vfs = new VirtualFileSystem(this);
+        }
+        return this._vfs;
+    }
     /**
      * Data Management API - backup, restore, import, export
      */
@@ -1448,9 +1464,79 @@ export class Brainy {
     }
     /**
      * Embed data into vector
+     * Handles any data type by converting to string representation
      */
     async embed(data) {
-        return this.embedder(data);
+        // Handle different data types intelligently
+        let textToEmbed;
+        if (typeof data === 'string') {
+            textToEmbed = data;
+        }
+        else if (Array.isArray(data)) {
+            // Array of items - convert each to string
+            textToEmbed = data.map(item => {
+                if (typeof item === 'string')
+                    return item;
+                if (typeof item === 'number' || typeof item === 'boolean')
+                    return String(item);
+                if (item && typeof item === 'object') {
+                    // For objects, try to extract meaningful text
+                    if (item.data)
+                        return String(item.data);
+                    if (item.content)
+                        return String(item.content);
+                    if (item.text)
+                        return String(item.text);
+                    if (item.name)
+                        return String(item.name);
+                    if (item.title)
+                        return String(item.title);
+                    if (item.description)
+                        return String(item.description);
+                    // Fallback to JSON for complex objects
+                    try {
+                        return JSON.stringify(item);
+                    }
+                    catch {
+                        return String(item);
+                    }
+                }
+                return String(item);
+            });
+        }
+        else if (data && typeof data === 'object') {
+            // Single object - extract meaningful text
+            if (data.data)
+                textToEmbed = String(data.data);
+            else if (data.content)
+                textToEmbed = String(data.content);
+            else if (data.text)
+                textToEmbed = String(data.text);
+            else if (data.name)
+                textToEmbed = String(data.name);
+            else if (data.title)
+                textToEmbed = String(data.title);
+            else if (data.description)
+                textToEmbed = String(data.description);
+            else {
+                // For complex objects, create a descriptive string
+                try {
+                    textToEmbed = JSON.stringify(data);
+                }
+                catch {
+                    textToEmbed = String(data);
+                }
+            }
+        }
+        else if (data === null || data === undefined) {
+            // Handle null/undefined gracefully
+            textToEmbed = '';
+        }
+        else {
+            // Numbers, booleans, etc - convert to string
+            textToEmbed = String(data);
+        }
+        return this.embedder(textToEmbed);
     }
     /**
      * Warm up the system

package/dist/embeddings/EmbeddingManager.js

@@ -165,8 +165,20 @@ export class EmbeddingManager {
         if (!this.model) {
             throw new Error('Model not initialized');
         }
-        // Handle array input
-        const input = Array.isArray(text) ? text.join(' ') : text;
+        // CRITICAL FIX: Ensure input is always a string
+        let input;
+        if (Array.isArray(text)) {
+            // Join array elements, converting each to string first
+            input = text.map(t => typeof t === 'string' ? t : String(t)).join(' ');
+        }
+        else if (typeof text === 'string') {
+            input = text;
+        }
+        else {
+            // This shouldn't happen but let's be defensive
+            console.warn('EmbeddingManager.embed received non-string input:', typeof text);
+            input = String(text);
+        }
         // Generate embedding
         const output = await this.model(input, {
             pooling: 'mean',

package/dist/utils/mutex.d.ts

@@ -29,7 +29,9 @@ export declare class FileMutex implements MutexInterface {
     private lockDir;
     private processLocks;
     private lockTimers;
+    private modulesLoaded;
     constructor(lockDir: string);
+    private loadNodeModules;
     acquire(key: string, timeout?: number): Promise<() => void>;
     private release;
     runExclusive<T>(key: string, fn: () => Promise<T>, timeout?: number): Promise<T>;

package/dist/utils/mutex.js

@@ -74,14 +74,25 @@ export class FileMutex {
     constructor(lockDir) {
         this.processLocks = new Map();
         this.lockTimers = new Map();
+        this.modulesLoaded = false;
         this.lockDir = lockDir;
-        // Lazy load Node.js modules
+    }
+    async loadNodeModules() {
+        if (this.modulesLoaded)
+            return;
         if (typeof window === 'undefined') {
-            this.fs = require('fs');
-            this.path = require('path');
+            // Modern ESM-compatible dynamic imports
+            const [fs, path] = await Promise.all([
+                import('fs'),
+                import('path')
+            ]);
+            this.fs = fs;
+            this.path = path;
+            this.modulesLoaded = true;
         }
     }
     async acquire(key, timeout = 30000) {
+        await this.loadNodeModules();
         if (!this.fs || !this.path) {
             throw new Error('FileMutex is only available in Node.js environments');
         }