@soulcraft/brainy 6.1.0 → 6.2.1

package/dist/vfs/KnowledgeLayer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Knowledge Layer for VFS
+ *
+ * This is the REAL integration that makes VFS intelligent.
+ * It wraps VFS operations and adds Knowledge Layer processing.
+ */
+import { VirtualFileSystem } from './VirtualFileSystem.js';
+import { Brainy } from '../brainy.js';
+export declare class KnowledgeLayer {
+    private vfs;
+    private brain;
+    private eventRecorder;
+    private semanticVersioning;
+    private entitySystem;
+    private conceptSystem;
+    private gitBridge;
+    private enabled;
+    constructor(vfs: VirtualFileSystem, brain: Brainy);
+    /**
+     * Enable Knowledge Layer by wrapping VFS methods
+     */
+    enable(): Promise<void>;
+    /**
+     * Add Knowledge Layer query methods to VFS
+     */
+    private addKnowledgeMethods;
+    /**
+     * Disable Knowledge Layer
+     */
+    disable(): Promise<void>;
+}
+/**
+ * Enable Knowledge Layer on a VFS instance
+ */
+export declare function enableKnowledgeLayer(vfs: VirtualFileSystem, brain: Brainy): Promise<KnowledgeLayer>;

package/dist/vfs/KnowledgeLayer.js

@@ -0,0 +1,443 @@
+/**
+ * Knowledge Layer for VFS
+ *
+ * This is the REAL integration that makes VFS intelligent.
+ * It wraps VFS operations and adds Knowledge Layer processing.
+ */
+import { EventRecorder } from './EventRecorder.js';
+import { SemanticVersioning } from './SemanticVersioning.js';
+import { PersistentEntitySystem } from './PersistentEntitySystem.js';
+import { ConceptSystem } from './ConceptSystem.js';
+import { GitBridge } from './GitBridge.js';
+export class KnowledgeLayer {
+    constructor(vfs, brain) {
+        this.vfs = vfs;
+        this.brain = brain;
+        this.enabled = false;
+        // Initialize all 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);
+    }
+    /**
+     * Enable Knowledge Layer by wrapping VFS methods
+     */
+    async enable() {
+        if (this.enabled)
+            return;
+        this.enabled = true;
+        // Save original methods
+        const originalWriteFile = this.vfs.writeFile.bind(this.vfs);
+        const originalUnlink = this.vfs.unlink.bind(this.vfs);
+        const originalRename = this.vfs.rename.bind(this.vfs);
+        const originalMkdir = this.vfs.mkdir.bind(this.vfs);
+        const originalRmdir = this.vfs.rmdir.bind(this.vfs);
+        // Wrap writeFile to add intelligence
+        this.vfs.writeFile = async (path, data, options) => {
+            // Call original VFS method first
+            const result = await originalWriteFile(path, data, options);
+            // Process in background (non-blocking)
+            setImmediate(async () => {
+                try {
+                    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+                    // 1. Record the event
+                    await this.eventRecorder.recordEvent({
+                        type: 'write',
+                        path,
+                        content: buffer,
+                        size: buffer.length,
+                        author: options?.author || 'system'
+                    });
+                    // 2. Check for semantic versioning
+                    try {
+                        const existingContent = await this.vfs.readFile(path).catch(() => null);
+                        if (existingContent) {
+                            const shouldVersion = await this.semanticVersioning.shouldVersion(existingContent, buffer);
+                            if (shouldVersion) {
+                                await this.semanticVersioning.createVersion(path, buffer, {
+                                    message: options?.message || 'Automatic semantic version'
+                                });
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.debug('Versioning check failed:', err);
+                    }
+                    // 3. Extract entities
+                    if (options?.extractEntities !== false) {
+                        await this.entitySystem.extractEntities(path, buffer);
+                    }
+                    // 4. Extract concepts
+                    if (options?.extractConcepts !== false) {
+                        await this.conceptSystem.extractAndLinkConcepts(path, buffer);
+                    }
+                }
+                catch (error) {
+                    console.debug('Knowledge Layer processing error:', error);
+                }
+            });
+            return result;
+        };
+        // Wrap unlink to record deletion
+        this.vfs.unlink = async (path) => {
+            const result = await originalUnlink(path);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'delete',
+                    path,
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Wrap rename to track moves
+        this.vfs.rename = async (oldPath, newPath) => {
+            const result = await originalRename(oldPath, newPath);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'rename',
+                    path: oldPath,
+                    metadata: { newPath },
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Wrap mkdir to track directory creation
+        this.vfs.mkdir = async (path, options) => {
+            const result = await originalMkdir(path, options);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'mkdir',
+                    path,
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Wrap rmdir to track directory deletion
+        this.vfs.rmdir = async (path, options) => {
+            const result = await originalRmdir(path, options);
+            setImmediate(async () => {
+                await this.eventRecorder.recordEvent({
+                    type: 'rmdir',
+                    path,
+                    author: 'system'
+                });
+            });
+            return result;
+        };
+        // Add Knowledge Layer methods to VFS
+        this.addKnowledgeMethods();
+        console.log('✨ Knowledge Layer enabled on VFS');
+    }
+    /**
+     * Add Knowledge Layer query methods to VFS
+     */
+    addKnowledgeMethods() {
+        // Event history
+        this.vfs.getHistory = async (path, options) => {
+            return await this.eventRecorder.getHistory(path, options);
+        };
+        this.vfs.reconstructAtTime = async (path, timestamp) => {
+            return await this.eventRecorder.reconstructFileAtTime(path, timestamp);
+        };
+        // Semantic versioning
+        this.vfs.getVersions = async (path) => {
+            return await this.semanticVersioning.getVersions(path);
+        };
+        this.vfs.getVersion = async (path, versionId) => {
+            return await this.semanticVersioning.getVersion(path, versionId);
+        };
+        this.vfs.restoreVersion = async (path, versionId) => {
+            const content = await this.semanticVersioning.getVersion(path, versionId);
+            if (content) {
+                await this.vfs.writeFile(path, content);
+            }
+        };
+        // Entity system
+        this.vfs.createEntity = async (config) => {
+            return await this.entitySystem.createEntity(config);
+        };
+        this.vfs.findEntity = async (query) => {
+            return await this.entitySystem.findEntity(query);
+        };
+        this.vfs.getEntityEvolution = async (entityId) => {
+            return await this.entitySystem.getEvolution(entityId);
+        };
+        // Concept system
+        this.vfs.createConcept = async (config) => {
+            return await this.conceptSystem.createConcept(config);
+        };
+        this.vfs.findConcepts = async (query) => {
+            return await this.conceptSystem.findConcepts(query);
+        };
+        this.vfs.getConceptGraph = async (options) => {
+            return await this.conceptSystem.getConceptGraph(options);
+        };
+        // Git bridge
+        this.vfs.exportToGit = async (vfsPath, gitPath) => {
+            return await this.gitBridge.exportToGit(vfsPath, gitPath);
+        };
+        this.vfs.importFromGit = async (gitPath, vfsPath) => {
+            return await this.gitBridge.importFromGit(gitPath, vfsPath);
+        };
+        // Temporal coupling
+        this.vfs.findTemporalCoupling = async (path, windowMs) => {
+            return await this.eventRecorder.findTemporalCoupling(path, windowMs);
+        };
+        // Entity convenience methods that wrap Brainy's core API
+        this.vfs.linkEntities = async (fromEntity, toEntity, relationship) => {
+            // Handle both entity IDs and entity objects
+            const fromId = typeof fromEntity === 'string' ? fromEntity : fromEntity.id;
+            const toId = typeof toEntity === 'string' ? toEntity : toEntity.id;
+            // Use brain.relate to create the relationship
+            return await this.brain.relate({
+                from: fromId,
+                to: toId,
+                type: relationship // VerbType or string
+            });
+        };
+        // Find where an entity appears across files
+        this.vfs.findEntityOccurrences = async (entityId) => {
+            const occurrences = [];
+            // Search for files that contain references to this entity
+            // First, get all relationships where this entity is involved
+            const relations = await this.brain.getRelations({ from: entityId });
+            const toRelations = await this.brain.getRelations({ to: entityId });
+            // Find file entities that relate to this entity
+            for (const rel of [...relations, ...toRelations]) {
+                try {
+                    // Check if the related entity is a file
+                    const relatedId = rel.from === entityId ? rel.to : rel.from;
+                    const entity = await this.brain.get(relatedId);
+                    if (entity?.metadata?.vfsType === 'file' && entity?.metadata?.path) {
+                        occurrences.push({
+                            path: entity.metadata.path,
+                            context: entity.data ? entity.data.toString().substring(0, 200) : undefined
+                        });
+                    }
+                }
+                catch (error) {
+                    // Entity might not exist, continue
+                }
+            }
+            // Also search for files that mention the entity name in their content
+            const entityData = await this.brain.get(entityId);
+            if (entityData?.metadata?.name) {
+                const searchResults = await this.brain.find({
+                    query: entityData.metadata.name,
+                    where: { vfsType: 'file' },
+                    limit: 20
+                });
+                for (const result of searchResults) {
+                    if (result.entity?.metadata?.path && !occurrences.some(o => o.path === result.entity.metadata.path)) {
+                        occurrences.push({
+                            path: result.entity.metadata.path,
+                            context: result.entity.data ? result.entity.data.toString().substring(0, 200) : undefined
+                        });
+                    }
+                }
+            }
+            return occurrences;
+        };
+        // Update an entity (convenience wrapper)
+        this.vfs.updateEntity = async (entityId, updates) => {
+            // Get current entity from brain
+            const currentEntity = await this.brain.get(entityId);
+            if (!currentEntity) {
+                throw new Error(`Entity ${entityId} not found`);
+            }
+            // Merge updates
+            const updatedMetadata = {
+                ...currentEntity.metadata,
+                ...updates,
+                lastUpdated: Date.now(),
+                version: (currentEntity.metadata?.version || 0) + 1
+            };
+            // Update via brain
+            await this.brain.update({
+                id: entityId,
+                data: JSON.stringify(updatedMetadata),
+                metadata: updatedMetadata
+            });
+            return entityId;
+        };
+        // Get entity graph (convenience wrapper)
+        this.vfs.getEntityGraph = async (entityId, options) => {
+            const depth = options?.depth || 2;
+            const graph = { nodes: new Map(), edges: [] };
+            const visited = new Set();
+            const traverse = async (id, currentDepth) => {
+                if (visited.has(id) || currentDepth > depth)
+                    return;
+                visited.add(id);
+                // Add node
+                const entity = await this.brain.get(id);
+                if (entity) {
+                    graph.nodes.set(id, entity);
+                }
+                // Get relationships
+                const relations = await this.brain.getRelations({ from: id });
+                const toRelations = await this.brain.getRelations({ to: id });
+                for (const rel of [...relations, ...toRelations]) {
+                    graph.edges.push(rel);
+                    // Traverse connected nodes
+                    if (currentDepth < depth) {
+                        const nextId = rel.from === id ? rel.to : rel.from;
+                        await traverse(nextId, currentDepth + 1);
+                    }
+                }
+            };
+            await traverse(entityId, 0);
+            return {
+                nodes: Array.from(graph.nodes.values()),
+                edges: graph.edges
+            };
+        };
+        // List all entities of a specific type
+        this.vfs.listEntities = async (query) => {
+            return await this.entitySystem.findEntity(query || {});
+        };
+        // Find files by concept
+        this.vfs.findByConcept = async (conceptName) => {
+            const paths = [];
+            // First find the concept
+            const concepts = await this.conceptSystem.findConcepts({ name: conceptName });
+            if (concepts.length === 0) {
+                return paths;
+            }
+            const concept = concepts[0];
+            // Search for files that contain concept keywords
+            const searchTerms = [conceptName, ...(concept.keywords || [])].join(' ');
+            const searchResults = await this.brain.find({
+                query: searchTerms,
+                where: { vfsType: 'file' },
+                limit: 50
+            });
+            // Get unique paths
+            const pathSet = new Set();
+            for (const result of searchResults) {
+                if (result.entity?.metadata?.path) {
+                    pathSet.add(result.entity.metadata.path);
+                }
+            }
+            // Also check concept manifestations if stored
+            if (concept.manifestations) {
+                for (const manifestation of concept.manifestations) {
+                    if (manifestation.filePath) {
+                        pathSet.add(manifestation.filePath);
+                    }
+                }
+            }
+            return Array.from(pathSet);
+        };
+        // Get timeline of events
+        this.vfs.getTimeline = async (options) => {
+            const fromTime = options?.from ? new Date(options.from).getTime() : Date.now() - 30 * 24 * 60 * 60 * 1000; // 30 days ago
+            const toTime = options?.to ? new Date(options.to).getTime() : Date.now();
+            const limit = options?.limit || 100;
+            // Get events from event recorder
+            const events = await this.eventRecorder.getEvents({
+                since: fromTime,
+                until: toTime,
+                types: options?.types,
+                limit
+            });
+            // Transform to timeline format
+            return events.map(event => ({
+                timestamp: new Date(event.timestamp),
+                type: event.type,
+                path: event.path,
+                user: event.author,
+                description: `${event.type} ${event.path}${event.oldPath ? ` (from ${event.oldPath})` : ''}`
+            }));
+        };
+        // Get collaboration history for a file
+        this.vfs.getCollaborationHistory = async (path) => {
+            // Get all events for this path
+            const history = await this.eventRecorder.getHistory(path, { limit: 100 });
+            return history.map(event => ({
+                user: event.author || 'system',
+                timestamp: new Date(event.timestamp),
+                action: event.type,
+                size: event.size
+            }));
+        };
+        // Export to markdown format
+        this.vfs.exportToMarkdown = async (path) => {
+            const markdown = [];
+            const traverse = async (currentPath, depth = 0) => {
+                const indent = '  '.repeat(depth);
+                try {
+                    const stats = await this.vfs.stat(currentPath);
+                    if (stats.isDirectory()) {
+                        // Add directory header
+                        const name = currentPath.split('/').pop() || currentPath;
+                        markdown.push(`${indent}## ${name}/`);
+                        markdown.push('');
+                        // List and traverse children
+                        const children = await this.vfs.readdir(currentPath);
+                        for (const child of children.sort()) {
+                            const childPath = currentPath === '/' ? `/${child}` : `${currentPath}/${child}`;
+                            await traverse(childPath, depth + 1);
+                        }
+                    }
+                    else {
+                        // Add file content
+                        const name = currentPath.split('/').pop() || currentPath;
+                        const extension = name.split('.').pop() || 'txt';
+                        try {
+                            const content = await this.vfs.readFile(currentPath);
+                            const textContent = content.toString('utf8');
+                            markdown.push(`${indent}### ${name}`);
+                            markdown.push('');
+                            // Add code block for code files
+                            if (['js', 'ts', 'jsx', 'tsx', 'py', 'java', 'cpp', 'go', 'rs', 'json'].includes(extension)) {
+                                markdown.push(`${indent}\`\`\`${extension}`);
+                                markdown.push(textContent.split('\n').map(line => `${indent}${line}`).join('\n'));
+                                markdown.push(`${indent}\`\`\``);
+                            }
+                            else if (extension === 'md') {
+                                // Include markdown directly
+                                markdown.push(textContent);
+                            }
+                            else {
+                                // Plain text in quotes
+                                markdown.push(`${indent}> ${textContent.split('\n').join(`\n${indent}> `)}`);
+                            }
+                            markdown.push('');
+                        }
+                        catch (error) {
+                            markdown.push(`${indent}*Binary or unreadable file*`);
+                            markdown.push('');
+                        }
+                    }
+                }
+                catch (error) {
+                    // Skip inaccessible paths
+                }
+            };
+            await traverse(path);
+            return markdown.join('\n');
+        };
+    }
+    /**
+     * Disable Knowledge Layer
+     */
+    async disable() {
+        // Would restore original methods here
+        this.enabled = false;
+    }
+}
+/**
+ * Enable Knowledge Layer on a VFS instance
+ */
+export async function enableKnowledgeLayer(vfs, brain) {
+    const knowledgeLayer = new KnowledgeLayer(vfs, brain);
+    await knowledgeLayer.enable();
+    return knowledgeLayer;
+}
+//# sourceMappingURL=KnowledgeLayer.js.map

package/dist/vfs/PersistentEntitySystem.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Persistent Entity System for VFS
+ *
+ * Manages entities that evolve across files and time
+ * Not just story characters - any evolving entity: APIs, customers, services, models
+ * 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 extends ManagedEntity {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    aliases: string[];
+    appearances: EntityAppearance[];
+    attributes: Record<string, any>;
+    created: number;
+    lastUpdated: number;
+    version: number;
+    entityType?: string;
+}
+/**
+ * An appearance of an entity in a specific file/location
+ */
+export interface EntityAppearance extends ManagedEntity {
+    id: string;
+    entityId: string;
+    filePath: string;
+    context: string;
+    position?: {
+        line?: number;
+        column?: number;
+        offset?: number;
+    };
+    timestamp: number;
+    version: number;
+    changes?: EntityChange[];
+    confidence: number;
+    eventType?: string;
+}
+/**
+ * A change/evolution to an entity
+ */
+export interface EntityChange {
+    field: string;
+    oldValue: any;
+    newValue: any;
+    timestamp: number;
+    source: string;
+    reason?: string;
+}
+/**
+ * Configuration for persistent entities
+ */
+export interface PersistentEntityConfig {
+    autoExtract?: boolean;
+    similarityThreshold?: number;
+    maxAppearances?: number;
+    evolutionTracking?: boolean;
+}
+/**
+ * Persistent Entity System
+ *
+ * Tracks entities that exist across multiple files and evolve over time
+ * Examples:
+ * - Story characters that appear in multiple chapters
+ * - API endpoints that evolve across documentation
+ * - Business entities that appear in multiple reports
+ * - Code classes/functions that span multiple files
+ */
+export declare class PersistentEntitySystem extends EntityManager {
+    private config;
+    private entityCache;
+    constructor(brain: Brainy, config?: PersistentEntityConfig);
+    /**
+     * Create a new persistent entity
+     */
+    createEntity(entity: Omit<PersistentEntity, 'id' | 'created' | 'lastUpdated' | 'version' | 'appearances'>): Promise<string>;
+    /**
+     * Find an existing entity by name or attributes
+     */
+    findEntity(query: {
+        name?: string;
+        type?: string;
+        attributes?: Record<string, any>;
+        similar?: string;
+    }): Promise<PersistentEntity[]>;
+    /**
+     * Record an appearance of an entity in a file
+     */
+    recordAppearance(entityId: string, filePath: string, context: string, options?: {
+        position?: EntityAppearance['position'];
+        confidence?: number;
+        extractChanges?: boolean;
+    }): Promise<string>;
+    /**
+     * Get entity evolution history
+     */
+    getEvolution(entityId: string): Promise<{
+        entity: PersistentEntity;
+        timeline: Array<{
+            timestamp: number;
+            version: number;
+            changes: EntityChange[];
+            appearance?: EntityAppearance;
+        }>;
+    }>;
+    /**
+     * Find all appearances of an entity
+     */
+    findAppearances(entityId: string, options?: {
+        filePath?: string;
+        since?: number;
+        until?: number;
+        minConfidence?: number;
+    }): Promise<EntityAppearance[]>;
+    /**
+     * Evolve an entity with new information
+     */
+    evolveEntity(entityId: string, updates: Partial<Pick<PersistentEntity, 'name' | 'description' | 'aliases' | 'attributes'>>, source: string, reason?: string): Promise<void>;
+    /**
+     * Extract entities from content (auto-extraction)
+     */
+    extractEntities(filePath: string, content: Buffer): Promise<string[]>;
+    /**
+     * Update references when a file moves
+     */
+    updateReferences(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Get persistent entity by ID
+     */
+    getPersistentEntity(entityId: string): Promise<PersistentEntity | null>;
+    /**
+     * Update stored entity (rename to avoid parent method conflict)
+     */
+    private updatePersistentEntity;
+    /**
+     * Detect changes in entity from context
+     */
+    private detectChanges;
+    /**
+     * Generate embedding for entity
+     */
+    private generateEntityEmbedding;
+    /**
+     * Generate embedding for text
+     */
+    private generateTextEmbedding;
+    /**
+     * Detect entity type from name and context
+     */
+    private detectEntityType;
+    /**
+     * Extract context around a position
+     */
+    private extractContext;
+    /**
+     * Clear entity cache
+     */
+    clearCache(entityId?: string): void;
+}