@soulcraft/brainy 3.10.0 → 3.12.0

package/dist/vfs/ConceptSystem.d.ts

@@ -6,10 +6,11 @@
  * PRODUCTION-READY: Real implementation using Brainy
  */
 import { Brainy } from '../brainy.js';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
 /**
  * Universal concept that exists independently of files
  */
-export interface UniversalConcept {
+export interface UniversalConcept extends ManagedEntity {
     id: string;
     name: string;
     description?: string;
@@ -23,6 +24,7 @@ export interface UniversalConcept {
     lastUpdated: number;
     version: number;
     metadata: Record<string, any>;
+    conceptType?: string;
 }
 /**
  * A link between concepts
@@ -38,7 +40,7 @@ export interface ConceptLink {
 /**
  * A manifestation of a concept in a specific location
  */
-export interface ConceptManifestation {
+export interface ConceptManifestation extends ManagedEntity {
     id: string;
     conceptId: string;
     filePath: string;
@@ -90,8 +92,7 @@ export interface ConceptGraph {
  * - "Dependency Injection" pattern across multiple codebases
  * - "Sustainability" theme in various research papers
  */
-export declare class ConceptSystem {
-    private brain;
+export declare class ConceptSystem extends EntityManager {
     private config;
     private conceptCache;
     constructor(brain: Brainy, config?: ConceptSystemConfig);

package/dist/vfs/ConceptSystem.js

@@ -8,6 +8,7 @@
 import { NounType, VerbType } from '../types/graphTypes.js';
 import { cosineDistance } from '../utils/distance.js';
 import { v4 as uuidv4 } from '../universal/uuid.js';
+import { EntityManager } from './EntityManager.js';
 /**
  * Universal Concept System
  *
@@ -18,9 +19,9 @@ import { v4 as uuidv4 } from '../universal/uuid.js';
  * - "Dependency Injection" pattern across multiple codebases
  * - "Sustainability" theme in various research papers
  */
-export class ConceptSystem {
+export class ConceptSystem extends EntityManager {
     constructor(brain, config) {
-        this.brain = brain;
+        super(brain, 'vfs-concept');
         this.conceptCache = new Map();
         this.config = {
             autoLink: config?.autoLink ?? false,
@@ -36,13 +37,20 @@ export class ConceptSystem {
         const conceptId = uuidv4();
         const timestamp = Date.now();
         const universalConcept = {
-            ...concept,
             id: conceptId,
+            name: concept.name,
+            description: concept.description,
+            domain: concept.domain,
+            category: concept.category,
+            keywords: concept.keywords,
+            strength: concept.strength,
+            metadata: concept.metadata || {},
             created: timestamp,
             lastUpdated: timestamp,
             version: 1,
             links: [],
-            manifestations: []
+            manifestations: [],
+            conceptType: 'universal' // Add conceptType for querying
         };
         // Generate embedding for concept
         let embedding;
@@ -52,24 +60,15 @@ export class ConceptSystem {
         catch (error) {
             console.warn('Failed to generate concept embedding:', error);
         }
-        // Store concept in Brainy
-        const brainyEntity = await this.brain.add({
-            type: NounType.Concept,
-            data: Buffer.from(JSON.stringify(universalConcept)),
-            metadata: {
-                ...universalConcept,
-                conceptType: 'universal',
-                system: 'vfs-concept'
-            },
-            vector: embedding
-        });
+        // Store concept using EntityManager
+        await this.storeEntity(universalConcept, NounType.Concept, embedding, Buffer.from(JSON.stringify(universalConcept)));
         // Auto-link to similar concepts if enabled
         if (this.config.autoLink) {
             await this.autoLinkConcept(conceptId);
         }
         // Update cache
         this.conceptCache.set(conceptId, universalConcept);
-        return brainyEntity;
+        return conceptId; // Return domain ID, not Brainy ID
     }
     /**
      * Find concepts by various criteria
@@ -93,16 +92,11 @@ export class ConceptSystem {
         // File manifestation search
         if (query.manifestedIn) {
             // Find concepts that have manifestations in this file
-            const manifestationResults = await this.brain.find({
-                where: {
-                    filePath: query.manifestedIn,
-                    eventType: 'concept-manifestation',
-                    system: 'vfs-concept'
-                },
-                type: NounType.Event,
-                limit: 1000
-            });
-            const conceptIds = manifestationResults.map(r => r.entity.metadata.conceptId);
+            const manifestationResults = await this.findEntities({
+                filePath: query.manifestedIn,
+                eventType: 'concept-manifestation'
+            }, NounType.Event, 1000);
+            const conceptIds = manifestationResults.map(m => m.conceptId);
             if (conceptIds.length > 0) {
                 searchQuery.id = { $in: conceptIds };
             }
@@ -110,39 +104,43 @@ export class ConceptSystem {
                 return []; // No concepts found in this file
             }
         }
-        // Search in Brainy
-        let results = await this.brain.find({
-            where: searchQuery,
-            type: NounType.Concept,
-            limit: 1000
-        });
+        // Search using EntityManager
+        const results = await this.findEntities(searchQuery, NounType.Concept, 1000);
         // If searching for similar concepts, use vector similarity
         if (query.similar) {
             try {
                 const queryEmbedding = await this.generateTextEmbedding(query.similar);
                 if (queryEmbedding) {
                     // Get all concepts and rank by similarity
-                    const allConcepts = await this.brain.find({
-                        where: { conceptType: 'universal', system: 'vfs-concept' },
-                        type: NounType.Concept,
-                        limit: 10000
-                    });
-                    const withSimilarity = allConcepts
-                        .filter(c => c.entity.vector && c.entity.vector.length > 0)
+                    const allConcepts = await this.findEntities({ conceptType: 'universal' }, NounType.Concept, 10000);
+                    // For similarity search, we need to get the actual vector data from Brainy
+                    const conceptsWithVectors = [];
+                    for (const concept of allConcepts) {
+                        if (concept.brainyId) {
+                            const brainyEntity = await this.brain.get(concept.brainyId);
+                            if (brainyEntity?.vector && brainyEntity.vector.length > 0) {
+                                conceptsWithVectors.push({
+                                    concept,
+                                    vector: brainyEntity.vector
+                                });
+                            }
+                        }
+                    }
+                    const withSimilarity = conceptsWithVectors
                         .map(c => ({
-                        concept: c,
-                        similarity: 1 - cosineDistance(queryEmbedding, c.entity.vector)
+                        concept: c.concept,
+                        similarity: 1 - cosineDistance(queryEmbedding, c.vector)
                     }))
                         .filter(s => s.similarity > this.config.similarityThreshold)
                         .sort((a, b) => b.similarity - a.similarity);
-                    results = withSimilarity.map(s => s.concept);
+                    return withSimilarity.map(s => s.concept);
                 }
             }
             catch (error) {
                 console.warn('Failed to perform concept similarity search:', error);
             }
         }
-        return results.map(r => r.entity.metadata);
+        return results;
     }
     /**
      * Link two concepts together
@@ -182,16 +180,11 @@ export class ConceptSystem {
             toConcept.lastUpdated = Date.now();
             await this.updateConcept(toConcept);
         }
-        // Create Brainy relationship
-        await this.brain.relate({
-            from: fromConceptId,
-            to: toConceptId,
-            type: this.getVerbType(relationship),
-            metadata: {
-                strength: link.strength,
-                context: link.context,
-                bidirectional: link.bidirectional
-            }
+        // Create relationship using EntityManager
+        await this.createRelationship(fromConceptId, toConceptId, this.getVerbType(relationship), {
+            strength: link.strength,
+            context: link.context,
+            bidirectional: link.bidirectional
         });
         return linkId;
     }
@@ -216,22 +209,14 @@ export class ConceptSystem {
             timestamp,
             extractedBy: options?.extractedBy ?? 'manual'
         };
-        // Store manifestation as Brainy event
-        await this.brain.add({
-            type: NounType.Event,
-            data: Buffer.from(context),
-            metadata: {
-                ...manifestation,
-                eventType: 'concept-manifestation',
-                system: 'vfs-concept'
-            }
-        });
-        // Create relationship to concept
-        await this.brain.relate({
-            from: manifestationId,
-            to: conceptId,
-            type: VerbType.Implements
-        });
+        // Store manifestation as managed entity (with eventType for manifestations)
+        const manifestationWithEventType = {
+            ...manifestation,
+            eventType: 'concept-manifestation'
+        };
+        await this.storeEntity(manifestationWithEventType, NounType.Event, undefined, Buffer.from(context));
+        // Create relationship to concept using EntityManager
+        await this.createRelationship(manifestationId, conceptId, VerbType.Implements);
         // Update concept with new manifestation
         concept.manifestations.push(manifestation);
         concept.lastUpdated = timestamp;
@@ -314,12 +299,7 @@ export class ConceptSystem {
         if (options?.minStrength) {
             query.strength = { $gte: options.minStrength };
         }
-        const results = await this.brain.find({
-            where: query,
-            type: NounType.Concept,
-            limit: options?.maxConcepts || 1000
-        });
-        const concepts = results.map(r => r.entity.metadata);
+        const concepts = await this.findEntities(query, NounType.Concept, options?.maxConcepts || 1000);
         // Build graph structure
         const graphConcepts = concepts.map(c => ({
             id: c.id,
@@ -365,14 +345,8 @@ export class ConceptSystem {
         if (options?.minConfidence) {
             query.confidence = { $gte: options.minConfidence };
         }
-        const results = await this.brain.find({
-            where: query,
-            type: NounType.Event,
-            limit: options?.limit || 1000
-        });
-        return results
-            .map(r => r.entity.metadata)
-            .sort((a, b) => b.timestamp - a.timestamp);
+        const manifestations = await this.findEntities(query, NounType.Event, options?.limit || 1000);
+        return manifestations.sort((a, b) => b.timestamp - a.timestamp);
     }
     /**
      * Auto-link concept to similar concepts
@@ -403,48 +377,21 @@ export class ConceptSystem {
         if (this.conceptCache.has(conceptId)) {
             return this.conceptCache.get(conceptId);
         }
-        // Query from Brainy
-        const results = await this.brain.find({
-            where: {
-                id: conceptId,
-                conceptType: 'universal',
-                system: 'vfs-concept'
-            },
-            type: NounType.Concept,
-            limit: 1
-        });
-        if (results.length === 0) {
-            return null;
+        // Query using EntityManager
+        const concept = await this.getEntity(conceptId);
+        if (concept) {
+            this.conceptCache.set(conceptId, concept);
         }
-        const concept = results[0].entity.metadata;
-        this.conceptCache.set(conceptId, concept);
         return concept;
     }
     /**
      * Update stored concept
      */
     async updateConcept(concept) {
-        // Find the Brainy entity
-        const results = await this.brain.find({
-            where: {
-                id: concept.id,
-                conceptType: 'universal',
-                system: 'vfs-concept'
-            },
-            type: NounType.Concept,
-            limit: 1
-        });
-        if (results.length > 0) {
-            await this.brain.update({
-                id: results[0].entity.id,
-                data: Buffer.from(JSON.stringify(concept)),
-                metadata: {
-                    ...concept,
-                    conceptType: 'universal',
-                    system: 'vfs-concept'
-                }
-            });
-        }
+        // Add conceptType metadata before updating
+        concept.conceptType = 'universal';
+        // Update using EntityManager
+        await this.updateEntity(concept);
         // Update cache
         this.conceptCache.set(concept.id, concept);
     }

package/dist/vfs/EventRecorder.d.ts

@@ -5,10 +5,11 @@
  * PRODUCTION-READY: No mocks, real implementation
  */
 import { Brainy } from '../brainy.js';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
 /**
  * File operation event
  */
-export interface FileEvent {
+export interface FileEvent extends ManagedEntity {
     id: string;
     type: 'create' | 'write' | 'append' | 'delete' | 'move' | 'rename' | 'mkdir' | 'rmdir';
     path: string;
@@ -20,12 +21,12 @@ export interface FileEvent {
     metadata?: Record<string, any>;
     previousHash?: string;
     oldPath?: string;
+    eventType?: string;
 }
 /**
  * Event Recorder - Stores all file operations as searchable events
  */
-export declare class EventRecorder {
-    private brain;
+export declare class EventRecorder extends EntityManager {
     constructor(brain: Brainy);
     /**
      * Record a file operation event

package/dist/vfs/EventRecorder.js

@@ -7,12 +7,13 @@
 import { NounType } from '../types/graphTypes.js';
 import { v4 as uuidv4 } from '../universal/uuid.js';
 import { createHash } from 'crypto';
+import { EntityManager } from './EntityManager.js';
 /**
  * Event Recorder - Stores all file operations as searchable events
  */
-export class EventRecorder {
+export class EventRecorder extends EntityManager {
     constructor(brain) {
-        this.brain = brain;
+        super(brain, 'vfs');
     }
     /**
      * Record a file operation event
@@ -24,24 +25,32 @@ export class EventRecorder {
         const hash = event.content
             ? createHash('sha256').update(event.content).digest('hex')
             : undefined;
-        // Store event as Brainy entity
-        const entity = await this.brain.add({
-            type: NounType.Event,
-            data: event.content || Buffer.from(JSON.stringify(event)),
-            metadata: {
-                ...event,
-                id: eventId,
-                timestamp,
-                hash,
-                eventType: 'file-operation',
-                system: 'vfs'
-            },
-            // Generate embedding for content-based events
-            vector: event.content && event.content.length < 100000
-                ? await this.generateEventEmbedding(event)
-                : undefined
-        });
-        return entity;
+        // Create file event
+        const fileEvent = {
+            id: eventId,
+            type: event.type,
+            path: event.path,
+            timestamp,
+            content: event.content,
+            size: event.size,
+            hash,
+            author: event.author,
+            metadata: event.metadata,
+            previousHash: event.previousHash,
+            oldPath: event.oldPath
+        };
+        // Generate embedding for content-based events
+        const embedding = event.content && event.content.length < 100000
+            ? await this.generateEventEmbedding(event)
+            : undefined;
+        // Add eventType for event classification
+        const eventWithType = {
+            ...fileEvent,
+            eventType: 'file-operation'
+        };
+        // Store event using EntityManager
+        await this.storeEntity(eventWithType, NounType.Event, embedding, event.content || Buffer.from(JSON.stringify(event)));
+        return eventId;
     }
     /**
      * Get all events matching criteria
@@ -65,18 +74,8 @@ export class EventRecorder {
         if (options?.types && options.types.length > 0) {
             query.type = { $in: options.types };
         }
-        // Query events from Brainy
-        const results = await this.brain.find({
-            where: query,
-            type: NounType.Event,
-            limit
-        });
-        const events = [];
-        for (const result of results) {
-            if (result.entity?.metadata) {
-                events.push(result.entity.metadata);
-            }
-        }
+        // Query using EntityManager
+        const events = await this.findEntities(query, NounType.Event, limit);
         return events.sort((a, b) => b.timestamp - a.timestamp);
     }
     /**
@@ -99,27 +98,8 @@ export class EventRecorder {
         if (options?.types && options.types.length > 0) {
             query.type = { $in: options.types };
         }
-        // Query events from Brainy
-        const results = await this.brain.find({
-            where: query,
-            type: NounType.Event,
-            limit: options?.limit || 100,
-            // Sort by timestamp descending (newest first)
-            // Note: Sorting would need to be implemented in Brainy
-        });
-        // Convert results to FileEvent format
-        const events = results.map(r => ({
-            id: r.entity.metadata.id,
-            type: r.entity.metadata.type,
-            path: r.entity.metadata.path,
-            timestamp: r.entity.metadata.timestamp,
-            content: r.entity.metadata.content,
-            size: r.entity.metadata.size,
-            hash: r.entity.metadata.hash,
-            author: r.entity.metadata.author,
-            metadata: r.entity.metadata.metadata,
-            previousHash: r.entity.metadata.previousHash
-        }));
+        // Query using EntityManager
+        const events = await this.findEntities(query, NounType.Event, options?.limit || 100);
         // Sort by timestamp (newest first)
         return events.sort((a, b) => b.timestamp - a.timestamp);
     }
@@ -168,19 +148,16 @@ export class EventRecorder {
         if (until) {
             query.timestamp.$lte = until;
         }
-        const results = await this.brain.find({
-            where: query,
-            type: NounType.Event,
-            limit: 1000
-        });
-        return results.map(r => ({
-            id: r.entity.metadata.id,
-            type: r.entity.metadata.type,
-            path: r.entity.metadata.path,
-            timestamp: r.entity.metadata.timestamp,
-            size: r.entity.metadata.size,
-            hash: r.entity.metadata.hash,
-            author: r.entity.metadata.author
+        // Query using EntityManager
+        const events = await this.findEntities(query, NounType.Event, 1000);
+        return events.map(event => ({
+            id: event.id,
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+            size: event.size,
+            hash: event.hash,
+            author: event.author
         }));
     }
     /**
@@ -282,7 +259,7 @@ export class EventRecorder {
         for (let i = 0; i < events.length; i++) {
             // Keep every Nth event for history sampling
             if (i % keepEvery !== 0) {
-                await this.brain.delete(events[i].id);
+                await this.deleteEntity(events[i].id);
                 pruned++;
             }
         }

package/dist/vfs/PathResolver.d.ts

@@ -40,10 +40,12 @@ export declare class PathResolver {
     private fullResolve;
     /**
      * Resolve a child entity by name within a parent directory
+     * Uses proper graph relationships instead of metadata queries
      */
     private resolveChild;
     /**
      * Get all children of a directory
+     * Uses proper graph relationships to traverse the tree
      */
     getChildren(dirId: string): Promise<VFSEntity[]>;
     /**

package/dist/vfs/PathResolver.js

@@ -122,69 +122,56 @@ export class PathResolver {
     }
     /**
      * Resolve a child entity by name within a parent directory
+     * Uses proper graph relationships instead of metadata queries
      */
     async resolveChild(parentId, name) {
         // Check parent cache first
         const cachedChildren = this.parentCache.get(parentId);
         if (cachedChildren && cachedChildren.has(name)) {
-            // We know this child exists, find it by path since parent queries don't work
-            const parentEntity = await this.getEntity(parentId);
-            const parentPath = parentEntity.metadata.path;
-            const childPath = this.joinPath(parentPath, name);
-            const pathResults = await this.brain.find({
-                where: { path: childPath },
-                limit: 1
-            });
-            if (pathResults.length > 0) {
-                return pathResults[0].entity.id;
-            }
+            // Use cached knowledge to quickly find the child
+            // Still need to verify it exists
         }
-        // Since parent field queries don't work reliably, construct the expected path
-        // and query by path instead
-        const parentEntity = await this.getEntity(parentId);
-        const parentPath = parentEntity.metadata.path;
-        const childPath = this.joinPath(parentPath, name);
-        const results = await this.brain.find({
-            where: { path: childPath },
-            limit: 1
+        // Use proper graph traversal to find children
+        // Get all relationships where parentId contains other entities
+        const relations = await this.brain.getRelations({
+            from: parentId,
+            type: VerbType.Contains
         });
-        if (results.length > 0) {
-            const childId = results[0].entity.id;
-            // Update parent cache
-            if (!this.parentCache.has(parentId)) {
-                this.parentCache.set(parentId, new Set());
+        // Find the child with matching name
+        for (const relation of relations) {
+            const childEntity = await this.brain.get(relation.to);
+            if (childEntity && childEntity.metadata?.name === name) {
+                // Update parent cache
+                if (!this.parentCache.has(parentId)) {
+                    this.parentCache.set(parentId, new Set());
+                }
+                this.parentCache.get(parentId).add(name);
+                return childEntity.id;
             }
-            this.parentCache.get(parentId).add(name);
-            return childId;
         }
         return null;
     }
     /**
      * Get all children of a directory
+     * Uses proper graph relationships to traverse the tree
      */
     async getChildren(dirId) {
-        // Use Brainy's relationship query to find all children
-        const results = await this.brain.find({
-            connected: {
-                from: dirId,
-                via: VerbType.Contains
-            },
-            limit: 10000 // Large limit for directories
+        // Use proper graph API to get all Contains relationships from this directory
+        const relations = await this.brain.getRelations({
+            from: dirId,
+            type: VerbType.Contains
         });
-        // Filter and process valid VFS entities only
         const validChildren = [];
         const childNames = new Set();
-        for (const result of results) {
-            const entity = result.entity;
-            // Only include entities with proper VFS metadata and non-empty names
-            if (entity.metadata?.vfsType &&
-                entity.metadata?.name &&
-                entity.metadata?.path &&
-                entity.id !== dirId) { // Don't include the directory itself
+        // Fetch all child entities
+        for (const relation of relations) {
+            const entity = await this.brain.get(relation.to);
+            if (entity && entity.metadata?.vfsType && entity.metadata?.name) {
                 validChildren.push(entity);
                 childNames.add(entity.metadata.name);
             }
         }
+        // Update cache
         this.parentCache.set(dirId, childNames);
         return validChildren;
     }

package/dist/vfs/PersistentEntitySystem.d.ts

@@ -6,10 +6,11 @@
  * PRODUCTION-READY: Real implementation using Brainy
  */
 import { Brainy } from '../brainy.js';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
 /**
  * Persistent entity that exists across files and evolves over time
  */
-export interface PersistentEntity {
+export interface PersistentEntity extends ManagedEntity {
     id: string;
     name: string;
     type: string;
@@ -20,11 +21,12 @@ export interface PersistentEntity {
     created: number;
     lastUpdated: number;
     version: number;
+    entityType?: string;
 }
 /**
  * An appearance of an entity in a specific file/location
  */
-export interface EntityAppearance {
+export interface EntityAppearance extends ManagedEntity {
     id: string;
     entityId: string;
     filePath: string;
@@ -38,6 +40,7 @@ export interface EntityAppearance {
     version: number;
     changes?: EntityChange[];
     confidence: number;
+    eventType?: string;
 }
 /**
  * A change/evolution to an entity
@@ -69,8 +72,7 @@ export interface PersistentEntityConfig {
  * - Business entities that appear in multiple reports
  * - Code classes/functions that span multiple files
  */
-export declare class PersistentEntitySystem {
-    private brain;
+export declare class PersistentEntitySystem extends EntityManager {
     private config;
     private entityCache;
     constructor(brain: Brainy, config?: PersistentEntityConfig);
@@ -129,13 +131,13 @@ export declare class PersistentEntitySystem {
      */
     updateReferences(oldPath: string, newPath: string): Promise<void>;
     /**
-     * Get entity by ID
+     * Get persistent entity by ID
      */
-    private getEntity;
+    getPersistentEntity(entityId: string): Promise<PersistentEntity | null>;
     /**
-     * Update stored entity
+     * Update stored entity (rename to avoid parent method conflict)
      */
-    private updateEntity;
+    private updatePersistentEntity;
     /**
      * Detect changes in entity from context
      */

package/dist/vfs/PersistentEntitySystem.js

@@ -8,6 +8,7 @@
 import { NounType, VerbType } from '../types/graphTypes.js';
 import { cosineDistance } from '../utils/distance.js';
 import { v4 as uuidv4 } from '../universal/uuid.js';
+import { EntityManager } from './EntityManager.js';
 /**
  * Persistent Entity System
  *
@@ -18,9 +19,9 @@ import { v4 as uuidv4 } from '../universal/uuid.js';
  * - Business entities that appear in multiple reports
  * - Code classes/functions that span multiple files
  */
-export class PersistentEntitySystem {
+export class PersistentEntitySystem extends EntityManager {
     constructor(brain, config) {
-        this.brain = brain;
+        super(brain, 'vfs-entity');
         this.entityCache = new Map();
         this.config = {
             autoExtract: config?.autoExtract ?? false,
@@ -36,12 +37,17 @@ export class PersistentEntitySystem {
         const entityId = uuidv4();
         const timestamp = Date.now();
         const persistentEntity = {
-            ...entity,
             id: entityId,
+            name: entity.name,
+            type: entity.type,
+            description: entity.description,
+            aliases: entity.aliases,
+            attributes: entity.attributes,
             created: timestamp,
             lastUpdated: timestamp,
             version: 1,
-            appearances: []
+            appearances: [],
+            entityType: 'persistent' // Add entityType for querying
         };
         // Generate embedding for entity description
         let embedding;
@@ -53,29 +59,17 @@ export class PersistentEntitySystem {
         catch (error) {
             console.warn('Failed to generate entity embedding:', error);
         }
-        // Store entity in Brainy
-        const brainyEntity = await this.brain.add({
-            type: NounType.Concept,
-            data: Buffer.from(JSON.stringify(persistentEntity)),
-            metadata: {
-                ...persistentEntity,
-                entityType: 'persistent',
-                system: 'vfs-entity'
-            },
-            vector: embedding
-        });
+        // Store entity using EntityManager
+        await this.storeEntity(persistentEntity, NounType.Concept, embedding, Buffer.from(JSON.stringify(persistentEntity)));
         // Update cache
         this.entityCache.set(entityId, persistentEntity);
-        return brainyEntity;
+        return entityId; // Return domain ID, not Brainy ID
     }
     /**
      * Find an existing entity by name or attributes
      */
     async findEntity(query) {
-        const searchQuery = {
-            entityType: 'persistent',
-            system: 'vfs-entity'
-        };
+        const searchQuery = {};
         if (query.name) {
             // Search by exact name or aliases
             searchQuery.$or = [
@@ -91,45 +85,46 @@ export class PersistentEntitySystem {
                 searchQuery[`attributes.${key}`] = value;
             }
         }
-        // Search in Brainy
-        let results = await this.brain.find({
-            where: searchQuery,
-            type: NounType.Concept,
-            limit: 100
-        });
+        // Add system metadata for EntityManager
+        searchQuery.entityType = 'persistent';
+        // Search using EntityManager
+        let results = await this.findEntities(searchQuery, NounType.Concept, 100);
         // If searching for similar entities, use vector similarity
         if (query.similar) {
             try {
                 const queryEmbedding = await this.generateTextEmbedding(query.similar);
                 if (queryEmbedding) {
-                    // Get all entities and rank by similarity
-                    const allEntities = await this.brain.find({
-                        where: { entityType: 'persistent', system: 'vfs-entity' },
-                        type: NounType.Concept,
-                        limit: 1000
-                    });
+                    // Get all entities and rank by similarity using EntityManager
+                    const allEntities = await this.findEntities({}, NounType.Concept, 1000);
                     const withSimilarity = allEntities
-                        .filter(e => e.entity.vector && e.entity.vector.length > 0)
-                        .map(e => ({
-                        entity: e,
-                        similarity: 1 - cosineDistance(queryEmbedding, e.entity.vector)
-                    }))
-                        .filter(s => s.similarity > this.config.similarityThreshold)
+                        .filter(e => e.brainyId) // Only entities with brainyId have vectors
+                        .map(async (e) => {
+                        const brainyEntity = await this.brain.get(e.brainyId);
+                        if (brainyEntity?.vector) {
+                            return {
+                                entity: e,
+                                similarity: 1 - cosineDistance(queryEmbedding, brainyEntity.vector)
+                            };
+                        }
+                        return null;
+                    });
+                    const resolved = (await Promise.all(withSimilarity))
+                        .filter(s => s !== null && s.similarity > this.config.similarityThreshold)
                         .sort((a, b) => b.similarity - a.similarity);
-                    results = withSimilarity.map(s => s.entity);
+                    results = resolved.map(s => s.entity);
                 }
             }
             catch (error) {
                 console.warn('Failed to perform similarity search:', error);
             }
         }
-        return results.map(r => r.entity.metadata);
+        return results;
     }
     /**
      * Record an appearance of an entity in a file
      */
     async recordAppearance(entityId, filePath, context, options) {
-        const entity = await this.getEntity(entityId);
+        const entity = await this.getPersistentEntity(entityId);
         if (!entity) {
             throw new Error(`Entity ${entityId} not found`);
         }
@@ -151,22 +146,14 @@ export class PersistentEntitySystem {
             changes,
             confidence: options?.confidence ?? 1.0
         };
-        // Store appearance as Brainy entity
-        await this.brain.add({
-            type: NounType.Event,
-            data: Buffer.from(context),
-            metadata: {
-                ...appearance,
-                eventType: 'entity-appearance',
-                system: 'vfs-entity'
-            }
-        });
-        // Create relationship to entity
-        await this.brain.relate({
-            from: appearanceId,
-            to: entityId,
-            type: VerbType.References
-        });
+        // Store appearance as managed entity (with eventType for appearances)
+        const appearanceWithEventType = {
+            ...appearance,
+            eventType: 'entity-appearance'
+        };
+        await this.storeEntity(appearanceWithEventType, NounType.Event, undefined, Buffer.from(context));
+        // Create relationship to entity using EntityManager
+        await this.createRelationship(appearanceId, entityId, VerbType.References);
         // Update entity with new appearance
         entity.appearances.push(appearance);
         entity.lastUpdated = timestamp;
@@ -186,14 +173,14 @@ export class PersistentEntitySystem {
                 .slice(0, this.config.maxAppearances);
         }
         // Update stored entity
-        await this.updateEntity(entity);
+        await this.updatePersistentEntity(entity);
         return appearanceId;
     }
     /**
      * Get entity evolution history
      */
     async getEvolution(entityId) {
-        const entity = await this.getEntity(entityId);
+        const entity = await this.getPersistentEntity(entityId);
         if (!entity) {
             throw new Error(`Entity ${entityId} not found`);
         }
@@ -248,7 +235,7 @@ export class PersistentEntitySystem {
      * Evolve an entity with new information
      */
     async evolveEntity(entityId, updates, source, reason) {
-        const entity = await this.getEntity(entityId);
+        const entity = await this.getPersistentEntity(entityId);
         if (!entity) {
             throw new Error(`Entity ${entityId} not found`);
         }
@@ -272,7 +259,7 @@ export class PersistentEntitySystem {
         entity.lastUpdated = timestamp;
         entity.version++;
         // Update stored entity
-        await this.updateEntity(entity);
+        await this.updatePersistentEntity(entity);
         // Record evolution event
         if (changes.length > 0) {
             await this.brain.add({
@@ -306,7 +293,7 @@ export class PersistentEntitySystem {
             // Character names (capitalized words)
             /\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*\b/g,
             // API endpoints
-            /\/api\/[a-zA-Z0-9\/\-_]+/g,
+            /\/api\/[a-zA-Z0-9/\-_]+/g,
             // Class names
             /class\s+([A-Z][a-zA-Z0-9_]*)/g,
             // Function names
@@ -329,7 +316,7 @@ export class PersistentEntitySystem {
                     entities.push(entityId);
                 }
                 // Record appearance for existing or new entity
-                const entity = existing[0] || await this.getEntity(entities[entities.length - 1]);
+                const entity = existing[0] || await this.getPersistentEntity(entities[entities.length - 1]);
                 if (entity) {
                     await this.recordAppearance(entity.id, filePath, this.extractContext(text, match.index || 0), { confidence: 0.7, extractChanges: true });
                 }
@@ -371,34 +358,25 @@ export class PersistentEntitySystem {
         }
     }
     /**
-     * Get entity by ID
+     * Get persistent entity by ID
      */
-    async getEntity(entityId) {
+    async getPersistentEntity(entityId) {
         // Check cache first
         if (this.entityCache.has(entityId)) {
             return this.entityCache.get(entityId);
         }
-        // Query from Brainy
-        const results = await this.brain.find({
-            where: {
-                id: entityId,
-                entityType: 'persistent',
-                system: 'vfs-entity'
-            },
-            type: NounType.Concept,
-            limit: 1
-        });
-        if (results.length === 0) {
-            return null;
+        // Use parent getEntity method
+        const entity = await super.getEntity(entityId);
+        if (entity) {
+            // Cache and return
+            this.entityCache.set(entityId, entity);
         }
-        const entity = results[0].entity.metadata;
-        this.entityCache.set(entityId, entity);
         return entity;
     }
     /**
-     * Update stored entity
+     * Update stored entity (rename to avoid parent method conflict)
      */
-    async updateEntity(entity) {
+    async updatePersistentEntity(entity) {
         // Find the Brainy entity
         const results = await this.brain.find({
             where: {

package/dist/vfs/SemanticVersioning.d.ts

@@ -5,10 +5,11 @@
  * PRODUCTION-READY: Real implementation using embeddings
  */
 import { Brainy } from '../brainy.js';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
 /**
  * Version metadata
  */
-export interface Version {
+export interface Version extends ManagedEntity {
     id: string;
     path: string;
     version: number;
@@ -35,8 +36,7 @@ export interface SemanticVersioningConfig {
  * Creates versions only when content meaning changes significantly
  * Uses vector embeddings to detect semantic changes
  */
-export declare class SemanticVersioning {
-    private brain;
+export declare class SemanticVersioning extends EntityManager {
     private config;
     private versionCache;
     constructor(brain: Brainy, config?: SemanticVersioningConfig);

package/dist/vfs/SemanticVersioning.js

@@ -8,15 +8,16 @@ import { NounType, VerbType } from '../types/graphTypes.js';
 import { cosineDistance } from '../utils/distance.js';
 import { createHash } from 'crypto';
 import { v4 as uuidv4 } from '../universal/uuid.js';
+import { EntityManager } from './EntityManager.js';
 /**
  * Semantic Versioning System
  *
  * Creates versions only when content meaning changes significantly
  * Uses vector embeddings to detect semantic changes
  */
-export class SemanticVersioning {
+export class SemanticVersioning extends EntityManager {
     constructor(brain, config) {
-        this.brain = brain;
+        super(brain, 'vfs-version');
         this.versionCache = new Map();
         this.config = {
             threshold: config?.threshold ?? 0.3,
@@ -81,32 +82,30 @@ export class SemanticVersioning {
         catch (error) {
             console.warn('Failed to generate embedding for version:', error);
         }
-        // Store version as Brainy entity
-        const entity = await this.brain.add({
-            type: NounType.State,
-            data: content, // Store actual content
-            metadata: {
-                id: versionId,
-                path,
-                version: versionNumber,
-                timestamp,
-                hash,
-                semanticHash,
-                size: content.length,
-                author: metadata?.author,
-                message: metadata?.message,
-                parentVersion,
-                system: 'vfs-version'
-            },
-            vector: embedding
-        });
+        // Create version entity
+        const version = {
+            id: versionId,
+            path,
+            version: versionNumber,
+            timestamp,
+            hash,
+            semanticHash,
+            size: content.length,
+            author: metadata?.author,
+            message: metadata?.message,
+            parentVersion
+        };
+        // Store version using EntityManager (with actual content as data)
+        await this.storeEntity(version, NounType.State, embedding, content);
         // Create relationship to parent version if exists
         if (parentVersion) {
-            await this.brain.relate({
-                from: entity,
-                to: parentVersion,
-                type: VerbType.Succeeds
-            });
+            try {
+                await this.createRelationship(versionId, parentVersion, VerbType.Succeeds);
+            }
+            catch (error) {
+                console.warn(`Failed to create parent relationship for version ${versionId}:`, error);
+                // Continue without relationship - non-critical for version functionality
+            }
         }
         // Update cache
         if (!this.versionCache.has(path)) {
@@ -136,18 +135,11 @@ export class SemanticVersioning {
         if (this.versionCache.has(path)) {
             return this.versionCache.get(path);
         }
-        // Query from Brainy
-        const results = await this.brain.find({
-            where: {
-                path,
-                system: 'vfs-version'
-            },
-            type: NounType.State,
-            limit: this.config.maxVersions * 2 // Get extra in case some are pruned
-        });
-        const versions = results
-            .map(r => r.entity.metadata)
-            .sort((a, b) => b.timestamp - a.timestamp); // Newest first
+        // Query using EntityManager
+        const versions = await this.findEntities({ path }, NounType.State, this.config.maxVersions * 2 // Get extra in case some are pruned
+        );
+        // Sort by timestamp (newest first)
+        versions.sort((a, b) => b.timestamp - a.timestamp);
         // Update cache
         this.versionCache.set(path, versions);
         return versions;
@@ -156,19 +148,18 @@ export class SemanticVersioning {
      * Get a specific version's content
      */
     async getVersion(path, versionId) {
-        const results = await this.brain.find({
-            where: {
-                id: versionId,
-                path,
-                system: 'vfs-version'
-            },
-            type: NounType.State,
-            limit: 1
-        });
-        if (results.length === 0) {
+        // Get the version entity
+        const version = await this.getEntity(versionId);
+        if (!version || version.path !== path) {
+            return null;
+        }
+        // Get the content from Brainy using the Brainy ID
+        const brainyId = await this.getBrainyId(versionId);
+        if (!brainyId) {
             return null;
         }
-        return results[0].entity.data;
+        const entity = await this.brain.get(brainyId);
+        return entity?.data;
     }
     /**
      * Restore a file to a specific version
@@ -238,7 +229,7 @@ export class SemanticVersioning {
         }
         // Delete excess versions
         for (const id of toDelete.slice(0, versions.length - this.config.maxVersions)) {
-            await this.brain.delete(id);
+            await this.deleteEntity(id);
         }
         // Update cache
         this.versionCache.set(path, versions.filter(v => !toDelete.includes(v.id)));

package/dist/vfs/VirtualFileSystem.js

@@ -1364,37 +1364,29 @@ export class VirtualFileSystem {
         await this.ensureInitialized();
         const entityId = await this.pathResolver.resolve(path);
         const results = [];
-        // Get all relationships involving this entity (both from and to)
+        // Use proper Brainy relationship API to get all relationships
         const [fromRelations, toRelations] = await Promise.all([
-            this.brain.find({
-                connected: {
-                    from: entityId
-                },
-                limit: 1000
-            }),
-            this.brain.find({
-                connected: {
-                    to: entityId
-                },
-                limit: 1000
-            })
+            this.brain.getRelations({ from: entityId }),
+            this.brain.getRelations({ to: entityId })
         ]);
         // Add outgoing relationships
         for (const rel of fromRelations) {
-            if (rel.entity.metadata?.path) {
+            const targetEntity = await this.brain.get(rel.to);
+            if (targetEntity && targetEntity.metadata?.path) {
                 results.push({
-                    path: rel.entity.metadata.path,
-                    relationship: 'related',
+                    path: targetEntity.metadata.path,
+                    relationship: rel.type || 'related',
                     direction: 'from'
                 });
             }
         }
         // Add incoming relationships
         for (const rel of toRelations) {
-            if (rel.entity.metadata?.path) {
+            const sourceEntity = await this.brain.get(rel.from);
+            if (sourceEntity && sourceEntity.metadata?.path) {
                 results.push({
-                    path: rel.entity.metadata.path,
-                    relationship: 'related',
+                    path: sourceEntity.metadata.path,
+                    relationship: rel.type || 'related',
                     direction: 'to'
                 });
             }
@@ -1405,49 +1397,37 @@ export class VirtualFileSystem {
         await this.ensureInitialized();
         const entityId = await this.pathResolver.resolve(path);
         const relationships = [];
-        // Get all relationships involving this entity (both from and to)
+        // Use proper Brainy relationship API
         const [fromRelations, toRelations] = await Promise.all([
-            this.brain.find({
-                connected: {
-                    from: entityId
-                },
-                limit: 1000
-            }),
-            this.brain.find({
-                connected: {
-                    to: entityId
-                },
-                limit: 1000
-            })
+            this.brain.getRelations({ from: entityId }),
+            this.brain.getRelations({ to: entityId })
         ]);
-        // Add outgoing relationships (exclude parent-child relationships)
+        // Process outgoing relationships (excluding Contains for parent-child)
         for (const rel of fromRelations) {
-            if (rel.entity.metadata?.path && rel.entity.metadata?.vfsType) {
-                // Skip parent-child relationships to focus on user-defined relationships
-                const parentPath = this.getParentPath(rel.entity.metadata.path);
-                if (parentPath !== path) { // Not a direct child
+            if (rel.type !== VerbType.Contains) { // Skip filesystem hierarchy
+                const targetEntity = await this.brain.get(rel.to);
+                if (targetEntity && targetEntity.metadata?.path) {
                     relationships.push({
-                        id: crypto.randomUUID(),
-                        from: path,
-                        to: rel.entity.metadata.path,
-                        type: VerbType.References,
-                        createdAt: Date.now()
+                        id: rel.id || crypto.randomUUID(),
+                        from: entityId,
+                        to: rel.to,
+                        type: rel.type,
+                        createdAt: rel.createdAt || Date.now()
                     });
                 }
             }
         }
-        // Add incoming relationships (exclude parent-child relationships)
+        // Process incoming relationships (excluding Contains for parent-child)
         for (const rel of toRelations) {
-            if (rel.entity.metadata?.path && rel.entity.metadata?.vfsType) {
-                // Skip parent-child relationships to focus on user-defined relationships
-                const parentPath = this.getParentPath(path);
-                if (rel.entity.metadata.path !== parentPath) { // Not the parent
+            if (rel.type !== VerbType.Contains) { // Skip filesystem hierarchy
+                const sourceEntity = await this.brain.get(rel.from);
+                if (sourceEntity && sourceEntity.metadata?.path) {
                     relationships.push({
-                        id: crypto.randomUUID(),
-                        from: rel.entity.metadata.path,
-                        to: path,
-                        type: VerbType.References,
-                        createdAt: Date.now()
+                        id: rel.id || crypto.randomUUID(),
+                        from: rel.from,
+                        to: entityId,
+                        type: rel.type,
+                        createdAt: rel.createdAt || Date.now()
                     });
                 }
             }
@@ -1734,7 +1714,7 @@ export class VirtualFileSystem {
                         case 'mkdir':
                             await this.mkdir(op.path, op.options);
                             break;
-                        case 'update':
+                        case 'update': {
                             // Update only metadata without changing content
                             const entityId = await this.pathResolver.resolve(op.path);
                             await this.brain.update({
@@ -1742,6 +1722,7 @@ export class VirtualFileSystem {
                                 metadata: op.options?.metadata
                             });
                             break;
+                        }
                     }
                     result.successful++;
                 }

package/package.json

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