@soulcraft/brainy 3.9.0 → 3.10.0

package/README.md

@@ -9,15 +9,15 @@
 [![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 3.0 - 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.
 
-## 🎉 What's New in 3.0
+## 🎉 Key Features
 
 ### 🧠 **Triple Intelligence™ Engine**
 
@@ -49,7 +49,7 @@ npm install @soulcraft/brainy
 ### 🎯 **True Zero Configuration**
 
 ```javascript
-import {Brainy} from '@soulcraft/brainy'
+import { Brainy, NounType } from '@soulcraft/brainy'
 
 // Just this - auto-detects everything!
 const brain = new Brainy()
@@ -58,7 +58,7 @@ await brain.init()
 // Add entities with automatic embedding
 const jsId = await brain.add({
     data: "JavaScript is a programming language",
-    type: "concept",
+    nounType: NounType.Concept,
     metadata: {
         type: "language",
         year: 1995,
@@ -68,7 +68,7 @@ const jsId = await brain.add({
 
 const nodeId = await brain.add({
     data: "Node.js runtime environment",
-    type: "concept",
+    nounType: NounType.Concept,
     metadata: {
         type: "runtime",
         year: 2009,
@@ -100,7 +100,7 @@ const filtered = await brain.find({
 
 ## 🌐 Framework Integration
 
-**Brainy 3.0 is framework-first!** Works seamlessly with any modern JavaScript framework:
+**Brainy is framework-first!** Works seamlessly with any modern JavaScript framework:
 
 ### ⚛️ **React & Next.js**
 ```javascript
@@ -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,11 +190,11 @@ 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:**
 
-- **24 Noun Types × 40 Verb Types**: 960 base combinations
+- **31 Noun Types × 40 Verb Types**: 1,240 base combinations
 - **∞ Expressiveness**: Unlimited metadata = model ANY data
 - **One Language**: All tools, augmentations, AI models speak the same types
 - **Perfect Interoperability**: Move data between any Brainy instance
@@ -209,12 +209,62 @@ 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 3.0 automatically configures **everything**:
+Brainy automatically configures **everything**:
 
 ```javascript
-import {Brainy} from '@soulcraft/brainy'
+import { Brainy } from '@soulcraft/brainy'
 
 // 1. Pure zero-config - detects everything
 const brain = new Brainy()
@@ -368,6 +418,8 @@ const brain = new Brainy({
 ### Real-World Example: Social Media Firehose
 
 ```javascript
+import { Brainy, NounType } from '@soulcraft/brainy'
+
 // Ingestion nodes (optimized for writes)
 const ingestionNode = new Brainy({
     storage: {type: 's3', options: {bucket: 'social-data'}},
@@ -378,7 +430,7 @@ const ingestionNode = new Brainy({
 // Process Bluesky firehose
 blueskyStream.on('post', async (post) => {
     await ingestionNode.add(post, {
-        nounType: 'social-post',
+        nounType: NounType.Message,
         platform: 'bluesky',
         author: post.author,
         timestamp: post.createdAt
@@ -417,21 +469,19 @@ const trending = await searchNode.find('trending AI topics', {
 ```javascript
 // Store documentation with rich relationships
 const apiGuide = await brain.add("REST API Guide", {
-    nounType: 'document',
+    nounType: NounType.Document,
     title: "API Guide",
     category: "documentation",
     version: "2.0"
 })
 
 const author = await brain.add("Jane Developer", {
-    nounType: 'person',
-    type: "person",
+    nounType: NounType.Person,
     role: "tech-lead"
 })
 
 const project = await brain.add("E-commerce Platform", {
-    nounType: 'project',
-    type: "project",
+    nounType: NounType.Project,
     status: "active"
 })
 
@@ -462,21 +512,18 @@ const similar = await brain.search(existingContent, {
 ```javascript
 // Store conversation with relationships
 const userId = await brain.add("User 123", {
-    nounType: 'user',
-    type: "user",
+    nounType: NounType.User,
     tier: "premium"
 })
 
 const messageId = await brain.add(userMessage, {
-    nounType: 'message',
-    type: "message",
+    nounType: NounType.Message,
     timestamp: Date.now(),
     session: "abc"
 })
 
 const topicId = await brain.add("Product Support", {
-    nounType: 'topic',
-    type: "topic",
+    nounType: NounType.Topic,
     category: "support"
 })
 
@@ -602,7 +649,7 @@ for (const cluster of feedbackClusters) {
 }
 
 // Find related documents
-const docId = await brain.add("Machine learning guide", { nounType: 'document' })
+const docId = await brain.add("Machine learning guide", { nounType: NounType.Document })
 const similar = await neural.neighbors(docId, 5)
 // Returns 5 most similar documents
 
@@ -637,7 +684,7 @@ Brainy includes enterprise-grade capabilities at no extra cost. **No premium tie
 - **Built-in monitoring** with metrics and health checks
 - **Production ready** with circuit breakers and backpressure
 
-📖 **Enterprise features coming in Brainy 3.1** - Stay tuned!
+📖 **More enterprise features coming soon** - Stay tuned!
 
 ## 📊 Benchmarks
 
@@ -651,19 +698,20 @@ Brainy includes enterprise-grade capabilities at no extra cost. **No premium tie
 | Bulk Import (1000 items)         | 2.3s        | +8MB     |
 | **Production Scale (10M items)** | **5.8ms**   | **12GB** |
 
-## 🔄 Migration from 2.x
+## 🔄 Migration from Previous Versions
 
-Key changes for upgrading to 3.0:
+Key changes in the latest version:
 
 - Search methods consolidated into `search()` and `find()`
 - Result format now includes full objects with metadata
-- New natural language capabilities
+- Enhanced natural language capabilities
+- Distributed architecture support
 
 ## 🤝 Contributing
 
 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
 
@@ -678,10 +726,10 @@ We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 ### The Math of Infinite Expressiveness
 
 ```
-24 Nouns × 40 Verbs × ∞ Metadata × Triple Intelligence = Universal Protocol
+31 Nouns × 40 Verbs × ∞ Metadata × Triple Intelligence = Universal Protocol
 ```
 
-- **960 base combinations** from standardized types
+- **1,240 base combinations** from standardized types
 - **∞ domain specificity** via unlimited metadata
 - **∞ relationship depth** via graph traversal
 - **= Model ANYTHING**: From quantum physics to social networks
@@ -708,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>;
     /**