chore: recovery checkpoint - v3.0 API successfully recovered

CRITICAL CHECKPOINT - DO NOT PUSH TO GITHUB

Recovery Status:
- Successfully recovered brainy.ts from compiled JavaScript
- All core v3.0 API methods functional (add, get, update, delete, relate, find, etc.)
- Neural subsystem intact (562KB embedded patterns, NLP working)
- Augmentation pipeline operational (20+ augmentations)
- HNSW clustering system complete
- Triple Intelligence compiled (needs constructor fix)
- Test suite validates functionality

Changes preserved:
- 898 files with changes from last 3 days
- 144,475 insertions
- All augmentation improvements
- All test coverage enhancements
- Complete v3.0 feature set

This is a LOCAL checkpoint only - contains recovered work after corruption incident.
Created backup in .backups/brainy-full-20250910-151314.tar.gz

Branch: recovery-checkpoint-20250910-151433
Date: Wed Sep 10 03:18:04 PM PDT 2025

.recovery-workspace/dist-backup-20250910-141917/cli/commands/core.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Core CLI Commands - TypeScript Implementation
+ *
+ * Essential database operations: add, search, get, relate, import, export
+ */
+interface CoreOptions {
+    verbose?: boolean;
+    json?: boolean;
+    pretty?: boolean;
+}
+interface AddOptions extends CoreOptions {
+    id?: string;
+    metadata?: string;
+    type?: string;
+}
+interface SearchOptions extends CoreOptions {
+    limit?: string;
+    threshold?: string;
+    metadata?: string;
+}
+interface GetOptions extends CoreOptions {
+    withConnections?: boolean;
+}
+interface RelateOptions extends CoreOptions {
+    weight?: string;
+    metadata?: string;
+}
+interface ImportOptions extends CoreOptions {
+    format?: 'json' | 'csv' | 'jsonl';
+    batchSize?: string;
+}
+interface ExportOptions extends CoreOptions {
+    format?: 'json' | 'csv' | 'jsonl';
+}
+export declare const coreCommands: {
+    /**
+     * Add data to the neural database
+     */
+    add(text: string, options: AddOptions): Promise<void>;
+    /**
+     * Search the neural database
+     */
+    search(query: string, options: SearchOptions): Promise<void>;
+    /**
+     * Get item by ID
+     */
+    get(id: string, options: GetOptions): Promise<void>;
+    /**
+     * Create relationship between items
+     */
+    relate(source: string, verb: string, target: string, options: RelateOptions): Promise<void>;
+    /**
+     * Import data from file
+     */
+    import(file: string, options: ImportOptions): Promise<void>;
+    /**
+     * Export database
+     */
+    export(file: string | undefined, options: ExportOptions): Promise<void>;
+};
+export {};

.recovery-workspace/dist-backup-20250910-141917/cli/commands/core.js

@@ -0,0 +1,348 @@
+/**
+ * Core CLI Commands - TypeScript Implementation
+ *
+ * Essential database operations: add, search, get, relate, import, export
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { readFileSync, writeFileSync } from 'fs';
+import { BrainyData } from '../../brainyData.js';
+let brainyInstance = null;
+const getBrainy = async () => {
+    if (!brainyInstance) {
+        brainyInstance = new BrainyData();
+        await brainyInstance.init();
+    }
+    return brainyInstance;
+};
+const formatOutput = (data, options) => {
+    if (options.json) {
+        console.log(options.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+    }
+};
+export const coreCommands = {
+    /**
+     * Add data to the neural database
+     */
+    async add(text, options) {
+        const spinner = ora('Adding to neural database...').start();
+        try {
+            const brain = await getBrainy();
+            let metadata = {};
+            if (options.metadata) {
+                try {
+                    metadata = JSON.parse(options.metadata);
+                }
+                catch {
+                    spinner.fail('Invalid metadata JSON');
+                    process.exit(1);
+                }
+            }
+            if (options.id) {
+                metadata.id = options.id;
+            }
+            if (options.type) {
+                metadata.type = options.type;
+            }
+            // Smart detection by default
+            const result = await brain.add(text, metadata);
+            spinner.succeed('Added successfully');
+            if (!options.json) {
+                console.log(chalk.green(`✓ Added with ID: ${result}`));
+                if (options.type) {
+                    console.log(chalk.dim(`  Type: ${options.type}`));
+                }
+                if (Object.keys(metadata).length > 0) {
+                    console.log(chalk.dim(`  Metadata: ${JSON.stringify(metadata)}`));
+                }
+            }
+            else {
+                formatOutput({ id: result, metadata }, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to add data');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Search the neural database
+     */
+    async search(query, options) {
+        const spinner = ora('Searching neural database...').start();
+        try {
+            const brain = await getBrainy();
+            const searchOptions = {
+                limit: options.limit ? parseInt(options.limit) : 10
+            };
+            if (options.threshold) {
+                searchOptions.threshold = parseFloat(options.threshold);
+            }
+            if (options.metadata) {
+                try {
+                    searchOptions.filter = JSON.parse(options.metadata);
+                }
+                catch {
+                    spinner.fail('Invalid metadata filter JSON');
+                    process.exit(1);
+                }
+            }
+            const results = await brain.search(query, searchOptions.limit, searchOptions);
+            spinner.succeed(`Found ${results.length} results`);
+            if (!options.json) {
+                if (results.length === 0) {
+                    console.log(chalk.yellow('No results found'));
+                }
+                else {
+                    results.forEach((result, i) => {
+                        console.log(chalk.cyan(`\n${i + 1}. ${result.content || result.id}`));
+                        if (result.score !== undefined) {
+                            console.log(chalk.dim(`   Similarity: ${(result.score * 100).toFixed(1)}%`));
+                        }
+                        if (result.metadata) {
+                            console.log(chalk.dim(`   Metadata: ${JSON.stringify(result.metadata)}`));
+                        }
+                    });
+                }
+            }
+            else {
+                formatOutput(results, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Search failed');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Get item by ID
+     */
+    async get(id, options) {
+        const spinner = ora('Fetching item...').start();
+        try {
+            const brain = await getBrainy();
+            // Try to get the item
+            const results = await brain.search(id, 1);
+            if (results.length === 0) {
+                spinner.fail('Item not found');
+                console.log(chalk.yellow(`No item found with ID: ${id}`));
+                process.exit(1);
+            }
+            const item = results[0];
+            spinner.succeed('Item found');
+            if (!options.json) {
+                console.log(chalk.cyan('\nItem Details:'));
+                console.log(`  ID: ${item.id}`);
+                console.log(`  Content: ${item.content || 'N/A'}`);
+                if (item.metadata) {
+                    console.log(`  Metadata: ${JSON.stringify(item.metadata, null, 2)}`);
+                }
+                if (options.withConnections) {
+                    // Get verbs/relationships
+                    // Get connections if method exists
+                    const connections = brain.getConnections ? await brain.getConnections(id) : [];
+                    if (connections && connections.length > 0) {
+                        console.log(chalk.cyan('\nConnections:'));
+                        connections.forEach((conn) => {
+                            console.log(`  ${conn.source} --[${conn.type}]--> ${conn.target}`);
+                        });
+                    }
+                }
+            }
+            else {
+                formatOutput(item, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to get item');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Create relationship between items
+     */
+    async relate(source, verb, target, options) {
+        const spinner = ora('Creating relationship...').start();
+        try {
+            const brain = await getBrainy();
+            let metadata = {};
+            if (options.metadata) {
+                try {
+                    metadata = JSON.parse(options.metadata);
+                }
+                catch {
+                    spinner.fail('Invalid metadata JSON');
+                    process.exit(1);
+                }
+            }
+            if (options.weight) {
+                metadata.weight = parseFloat(options.weight);
+            }
+            // Create the relationship
+            const result = await brain.addVerb(source, target, verb, metadata);
+            spinner.succeed('Relationship created');
+            if (!options.json) {
+                console.log(chalk.green(`✓ Created relationship with ID: ${result}`));
+                console.log(chalk.dim(`  ${source} --[${verb}]--> ${target}`));
+                if (metadata.weight) {
+                    console.log(chalk.dim(`  Weight: ${metadata.weight}`));
+                }
+            }
+            else {
+                formatOutput({ id: result, source, verb, target, metadata }, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to create relationship');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Import data from file
+     */
+    async import(file, options) {
+        const spinner = ora('Importing data...').start();
+        try {
+            const brain = await getBrainy();
+            const format = options.format || 'json';
+            const batchSize = options.batchSize ? parseInt(options.batchSize) : 100;
+            // Read file content
+            const content = readFileSync(file, 'utf-8');
+            let items = [];
+            switch (format) {
+                case 'json':
+                    items = JSON.parse(content);
+                    if (!Array.isArray(items)) {
+                        items = [items];
+                    }
+                    break;
+                case 'jsonl':
+                    items = content.split('\n')
+                        .filter(line => line.trim())
+                        .map(line => JSON.parse(line));
+                    break;
+                case 'csv':
+                    // Simple CSV parsing (first line is headers)
+                    const lines = content.split('\n').filter(line => line.trim());
+                    const headers = lines[0].split(',').map(h => h.trim());
+                    items = lines.slice(1).map(line => {
+                        const values = line.split(',').map(v => v.trim());
+                        const obj = {};
+                        headers.forEach((h, i) => {
+                            obj[h] = values[i];
+                        });
+                        return obj;
+                    });
+                    break;
+            }
+            spinner.text = `Importing ${items.length} items...`;
+            // Process in batches
+            let imported = 0;
+            for (let i = 0; i < items.length; i += batchSize) {
+                const batch = items.slice(i, i + batchSize);
+                for (const item of batch) {
+                    if (typeof item === 'string') {
+                        await brain.add(item);
+                    }
+                    else if (item.content || item.text) {
+                        await brain.add(item.content || item.text, item.metadata || item);
+                    }
+                    else {
+                        await brain.add(JSON.stringify(item), { originalData: item });
+                    }
+                    imported++;
+                }
+                spinner.text = `Imported ${imported}/${items.length} items...`;
+            }
+            spinner.succeed(`Imported ${imported} items`);
+            if (!options.json) {
+                console.log(chalk.green(`✓ Successfully imported ${imported} items from ${file}`));
+                console.log(chalk.dim(`  Format: ${format}`));
+                console.log(chalk.dim(`  Batch size: ${batchSize}`));
+            }
+            else {
+                formatOutput({ imported, file, format, batchSize }, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Import failed');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Export database
+     */
+    async export(file, options) {
+        const spinner = ora('Exporting database...').start();
+        try {
+            const brain = await getBrainy();
+            const format = options.format || 'json';
+            // Export all data
+            const data = await brain.export({ format: 'json' });
+            let output = '';
+            switch (format) {
+                case 'json':
+                    output = options.pretty
+                        ? JSON.stringify(data, null, 2)
+                        : JSON.stringify(data);
+                    break;
+                case 'jsonl':
+                    if (Array.isArray(data)) {
+                        output = data.map(item => JSON.stringify(item)).join('\n');
+                    }
+                    else {
+                        output = JSON.stringify(data);
+                    }
+                    break;
+                case 'csv':
+                    if (Array.isArray(data) && data.length > 0) {
+                        // Get all unique keys for headers
+                        const headers = new Set();
+                        data.forEach(item => {
+                            Object.keys(item).forEach(key => headers.add(key));
+                        });
+                        const headerArray = Array.from(headers);
+                        // Create CSV
+                        output = headerArray.join(',') + '\n';
+                        output += data.map(item => {
+                            return headerArray.map(h => {
+                                const value = item[h];
+                                if (typeof value === 'object') {
+                                    return JSON.stringify(value);
+                                }
+                                return value || '';
+                            }).join(',');
+                        }).join('\n');
+                    }
+                    break;
+            }
+            if (file) {
+                writeFileSync(file, output);
+                spinner.succeed(`Exported to ${file}`);
+                if (!options.json) {
+                    console.log(chalk.green(`✓ Successfully exported database to ${file}`));
+                    console.log(chalk.dim(`  Format: ${format}`));
+                    console.log(chalk.dim(`  Items: ${Array.isArray(data) ? data.length : 1}`));
+                }
+                else {
+                    formatOutput({ file, format, count: Array.isArray(data) ? data.length : 1 }, options);
+                }
+            }
+            else {
+                spinner.succeed('Export complete');
+                console.log(output);
+            }
+        }
+        catch (error) {
+            spinner.fail('Export failed');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    }
+};
+//# sourceMappingURL=core.js.map

.recovery-workspace/dist-backup-20250910-141917/cli/commands/neural.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 🧠 Neural Similarity API Commands
+ *
+ * CLI interface for semantic similarity, clustering, and neural operations
+ */
+interface CommandArguments {
+    action?: string;
+    id?: string;
+    query?: string;
+    threshold?: number;
+    format?: string;
+    output?: string;
+    limit?: number;
+    algorithm?: string;
+    dimensions?: number;
+    explain?: boolean;
+    _: string[];
+}
+export declare const neuralCommand: {
+    command: string;
+    describe: string;
+    builder: (yargs: any) => any;
+    handler: (argv: CommandArguments) => Promise<void>;
+};
+export default neuralCommand;

.recovery-workspace/dist-backup-20250910-141917/cli/commands/neural.js

@@ -0,0 +1,508 @@
+/**
+ * 🧠 Neural Similarity API Commands
+ *
+ * CLI interface for semantic similarity, clustering, and neural operations
+ */
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs';
+import path from 'path';
+import { BrainyData } from '../../brainyData.js';
+import { NeuralAPI } from '../../neural/neuralAPI.js';
+export const neuralCommand = {
+    command: 'neural [action]',
+    describe: '🧠 Neural similarity and clustering operations',
+    builder: (yargs) => {
+        return yargs
+            .positional('action', {
+            describe: 'Neural operation to perform',
+            type: 'string',
+            choices: ['similar', 'clusters', 'hierarchy', 'neighbors', 'path', 'outliers', 'visualize']
+        })
+            .option('id', {
+            describe: 'Item ID for similarity operations',
+            type: 'string',
+            alias: 'i'
+        })
+            .option('query', {
+            describe: 'Query text for similarity search',
+            type: 'string',
+            alias: 'q'
+        })
+            .option('threshold', {
+            describe: 'Similarity threshold (0-1)',
+            type: 'number',
+            default: 0.7,
+            alias: 't'
+        })
+            .option('format', {
+            describe: 'Output format',
+            type: 'string',
+            choices: ['json', 'table', 'tree', 'graph'],
+            default: 'table',
+            alias: 'f'
+        })
+            .option('output', {
+            describe: 'Output file path',
+            type: 'string',
+            alias: 'o'
+        })
+            .option('limit', {
+            describe: 'Maximum number of results',
+            type: 'number',
+            default: 10,
+            alias: 'l'
+        })
+            .option('algorithm', {
+            describe: 'Clustering algorithm',
+            type: 'string',
+            choices: ['hierarchical', 'kmeans', 'dbscan', 'auto'],
+            default: 'auto',
+            alias: 'a'
+        })
+            .option('dimensions', {
+            describe: 'Visualization dimensions (2 or 3)',
+            type: 'number',
+            choices: [2, 3],
+            default: 2,
+            alias: 'd'
+        })
+            .option('explain', {
+            describe: 'Include detailed explanations',
+            type: 'boolean',
+            default: false,
+            alias: 'e'
+        });
+    },
+    handler: async (argv) => {
+        console.log(chalk.cyan('\n🧠 NEURAL SIMILARITY API'));
+        console.log(chalk.gray('━'.repeat(50)));
+        // Initialize Brainy and Neural API
+        const brain = new BrainyData();
+        const neural = new NeuralAPI(brain);
+        try {
+            const action = argv.action || await promptForAction();
+            switch (action) {
+                case 'similar':
+                    await handleSimilarCommand(neural, argv);
+                    break;
+                case 'clusters':
+                    await handleClustersCommand(neural, argv);
+                    break;
+                case 'hierarchy':
+                    await handleHierarchyCommand(neural, argv);
+                    break;
+                case 'neighbors':
+                    await handleNeighborsCommand(neural, argv);
+                    break;
+                case 'path':
+                    await handlePathCommand(neural, argv);
+                    break;
+                case 'outliers':
+                    await handleOutliersCommand(neural, argv);
+                    break;
+                case 'visualize':
+                    await handleVisualizeCommand(neural, argv);
+                    break;
+                default:
+                    console.log(chalk.red(`❌ Unknown action: ${action}`));
+                    showHelp();
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('💥 Error:'), error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    }
+};
+async function promptForAction() {
+    const answer = await inquirer.prompt([{
+            type: 'list',
+            name: 'action',
+            message: 'Choose a neural operation:',
+            choices: [
+                { name: '🔗 Calculate similarity between items', value: 'similar' },
+                { name: '🎯 Find semantic clusters', value: 'clusters' },
+                { name: '🌳 Show item hierarchy', value: 'hierarchy' },
+                { name: '🕸️  Find semantic neighbors', value: 'neighbors' },
+                { name: '🛣️  Find semantic path between items', value: 'path' },
+                { name: '🚨 Detect outliers', value: 'outliers' },
+                { name: '📊 Generate visualization data', value: 'visualize' }
+            ]
+        }]);
+    return answer.action;
+}
+async function handleSimilarCommand(neural, argv) {
+    const spinner = ora('🧠 Calculating semantic similarity...').start();
+    try {
+        let itemA, itemB;
+        if (argv.id && argv.query) {
+            itemA = argv.id;
+            itemB = argv.query;
+        }
+        else if (argv._ && argv._.length >= 3) {
+            itemA = argv._[1];
+            itemB = argv._[2];
+        }
+        else {
+            spinner.stop();
+            const answers = await inquirer.prompt([
+                {
+                    type: 'input',
+                    name: 'itemA',
+                    message: 'First item (ID or text):',
+                    validate: (input) => input.length > 0
+                },
+                {
+                    type: 'input',
+                    name: 'itemB',
+                    message: 'Second item (ID or text):',
+                    validate: (input) => input.length > 0
+                }
+            ]);
+            itemA = answers.itemA;
+            itemB = answers.itemB;
+            spinner.start();
+        }
+        const result = await neural.similar(itemA, itemB, {
+            explain: argv.explain,
+            includeBreakdown: argv.explain
+        });
+        spinner.succeed('✅ Similarity calculated');
+        if (typeof result === 'number') {
+            console.log(`\n🔗 Similarity: ${chalk.cyan((result * 100).toFixed(1))}%`);
+        }
+        else {
+            console.log(`\n🔗 Similarity: ${chalk.cyan((result.score * 100).toFixed(1))}%`);
+            if (result.explanation) {
+                console.log(`💭 Explanation: ${result.explanation}`);
+            }
+            if (result.breakdown) {
+                console.log('\n📊 Breakdown:');
+                console.log(`  Semantic: ${chalk.yellow((result.breakdown.semantic * 100).toFixed(1))}%`);
+                if (result.breakdown.taxonomic !== undefined) {
+                    console.log(`  Taxonomic: ${chalk.yellow((result.breakdown.taxonomic * 100).toFixed(1))}%`);
+                }
+                if (result.breakdown.contextual !== undefined) {
+                    console.log(`  Contextual: ${chalk.yellow((result.breakdown.contextual * 100).toFixed(1))}%`);
+                }
+            }
+            if (result.hierarchy) {
+                console.log(`\n🌳 Hierarchy: ${result.hierarchy.sharedParent ?
+                    `Shared parent at distance ${result.hierarchy.distance}` :
+                    'No shared parent found'}`);
+            }
+        }
+        if (argv.output) {
+            await saveToFile(argv.output, result, argv.format);
+        }
+    }
+    catch (error) {
+        spinner.fail('💥 Failed to calculate similarity');
+        throw error;
+    }
+}
+async function handleClustersCommand(neural, argv) {
+    const spinner = ora('🎯 Finding semantic clusters...').start();
+    try {
+        const options = {
+            algorithm: argv.algorithm,
+            threshold: argv.threshold,
+            maxClusters: argv.limit
+        };
+        const clusters = await neural.clusters(argv.query || options);
+        spinner.succeed(`✅ Found ${clusters.length} clusters`);
+        if (argv.format === 'json') {
+            console.log(JSON.stringify(clusters, null, 2));
+        }
+        else {
+            console.log(`\n🎯 ${chalk.cyan(clusters.length)} Semantic Clusters:\n`);
+            clusters.forEach((cluster, index) => {
+                console.log(`${chalk.yellow(`Cluster ${index + 1}:`)} ${cluster.label || cluster.id}`);
+                console.log(`  📊 Confidence: ${chalk.green((cluster.confidence * 100).toFixed(1))}%`);
+                console.log(`  👥 Members: ${cluster.members.length}`);
+                if (cluster.members.length <= 5) {
+                    cluster.members.forEach(member => {
+                        console.log(`    • ${member}`);
+                    });
+                }
+                else {
+                    cluster.members.slice(0, 3).forEach(member => {
+                        console.log(`    • ${member}`);
+                    });
+                    console.log(`    ... and ${cluster.members.length - 3} more`);
+                }
+                console.log();
+            });
+        }
+        if (argv.output) {
+            await saveToFile(argv.output, clusters, argv.format);
+        }
+    }
+    catch (error) {
+        spinner.fail('💥 Failed to find clusters');
+        throw error;
+    }
+}
+async function handleHierarchyCommand(neural, argv) {
+    const spinner = ora('🌳 Building semantic hierarchy...').start();
+    try {
+        const id = argv.id || argv._[1];
+        if (!id) {
+            spinner.stop();
+            const answer = await inquirer.prompt([{
+                    type: 'input',
+                    name: 'id',
+                    message: 'Enter item ID:',
+                    validate: (input) => input.length > 0
+                }]);
+            spinner.start();
+            const hierarchy = await neural.hierarchy(answer.id);
+            displayHierarchy(hierarchy);
+        }
+        else {
+            const hierarchy = await neural.hierarchy(id);
+            spinner.succeed('✅ Hierarchy built');
+            displayHierarchy(hierarchy);
+        }
+        if (argv.output) {
+            const hierarchy = await neural.hierarchy(id || argv._[1]);
+            await saveToFile(argv.output, hierarchy, argv.format);
+        }
+    }
+    catch (error) {
+        spinner.fail('💥 Failed to build hierarchy');
+        throw error;
+    }
+}
+function displayHierarchy(hierarchy) {
+    console.log(`\n🌳 Semantic Hierarchy for ${chalk.cyan(hierarchy.self.id)}:`);
+    if (hierarchy.root) {
+        console.log(`🔝 Root: ${hierarchy.root.id} (${(hierarchy.root.similarity * 100).toFixed(1)}%)`);
+    }
+    if (hierarchy.grandparent) {
+        console.log(`👴 Grandparent: ${hierarchy.grandparent.id} (${(hierarchy.grandparent.similarity * 100).toFixed(1)}%)`);
+    }
+    if (hierarchy.parent) {
+        console.log(`👨 Parent: ${hierarchy.parent.id} (${(hierarchy.parent.similarity * 100).toFixed(1)}%)`);
+    }
+    console.log(`🎯 ${chalk.bold('Self:')} ${hierarchy.self.id}`);
+    if (hierarchy.siblings && hierarchy.siblings.length > 0) {
+        console.log(`👥 Siblings: ${hierarchy.siblings.length}`);
+        hierarchy.siblings.forEach((sibling) => {
+            console.log(`  • ${sibling.id} (${(sibling.similarity * 100).toFixed(1)}%)`);
+        });
+    }
+    if (hierarchy.children && hierarchy.children.length > 0) {
+        console.log(`👶 Children: ${hierarchy.children.length}`);
+        hierarchy.children.forEach((child) => {
+            console.log(`  • ${child.id} (${(child.similarity * 100).toFixed(1)}%)`);
+        });
+    }
+}
+async function handleNeighborsCommand(neural, argv) {
+    const spinner = ora('🕸️ Finding semantic neighbors...').start();
+    try {
+        const id = argv.id || argv._[1];
+        if (!id) {
+            spinner.stop();
+            const answer = await inquirer.prompt([{
+                    type: 'input',
+                    name: 'id',
+                    message: 'Enter item ID:',
+                    validate: (input) => input.length > 0
+                }]);
+            spinner.start();
+        }
+        const targetId = id || (await inquirer.prompt([{
+                type: 'input',
+                name: 'id',
+                message: 'Enter item ID:',
+                validate: (input) => input.length > 0
+            }])).id;
+        const graph = await neural.neighbors(targetId, {
+            limit: argv.limit,
+            includeEdges: true
+        });
+        spinner.succeed(`✅ Found ${graph.neighbors.length} neighbors`);
+        console.log(`\n🕸️ Neighbors of ${chalk.cyan(graph.center)}:`);
+        graph.neighbors.forEach((neighbor, index) => {
+            console.log(`${index + 1}. ${neighbor.id} (${(neighbor.similarity * 100).toFixed(1)}%)`);
+            if (neighbor.type) {
+                console.log(`   Type: ${neighbor.type}`);
+            }
+            if (neighbor.connections) {
+                console.log(`   Connections: ${neighbor.connections}`);
+            }
+        });
+        if (graph.edges && graph.edges.length > 0) {
+            console.log(`\n🔗 ${graph.edges.length} semantic connections found`);
+        }
+        if (argv.output) {
+            await saveToFile(argv.output, graph, argv.format);
+        }
+    }
+    catch (error) {
+        spinner.fail('💥 Failed to find neighbors');
+        throw error;
+    }
+}
+async function handlePathCommand(neural, argv) {
+    const spinner = ora('🛣️ Finding semantic path...').start();
+    try {
+        let fromId, toId;
+        if (argv._ && argv._.length >= 3) {
+            fromId = argv._[1];
+            toId = argv._[2];
+        }
+        else {
+            spinner.stop();
+            const answers = await inquirer.prompt([
+                {
+                    type: 'input',
+                    name: 'from',
+                    message: 'From item ID:',
+                    validate: (input) => input.length > 0
+                },
+                {
+                    type: 'input',
+                    name: 'to',
+                    message: 'To item ID:',
+                    validate: (input) => input.length > 0
+                }
+            ]);
+            fromId = answers.from;
+            toId = answers.to;
+            spinner.start();
+        }
+        const path = await neural.semanticPath(fromId, toId);
+        if (path.length === 0) {
+            spinner.warn('🚫 No semantic path found');
+            console.log(`No path found between ${chalk.cyan(fromId)} and ${chalk.cyan(toId)}`);
+        }
+        else {
+            spinner.succeed(`✅ Found path with ${path.length} hops`);
+            console.log(`\n🛣️ Semantic Path from ${chalk.cyan(fromId)} to ${chalk.cyan(toId)}:`);
+            console.log(`${chalk.cyan(fromId)} (start)`);
+            path.forEach((hop, index) => {
+                console.log(`${'  '.repeat(index + 1)}↓ ${(hop.similarity * 100).toFixed(1)}%`);
+                console.log(`${'  '.repeat(index + 1)}${hop.id} (hop ${hop.hop})`);
+            });
+        }
+        if (argv.output) {
+            await saveToFile(argv.output, path, argv.format);
+        }
+    }
+    catch (error) {
+        spinner.fail('💥 Failed to find path');
+        throw error;
+    }
+}
+async function handleOutliersCommand(neural, argv) {
+    const spinner = ora('🚨 Detecting semantic outliers...').start();
+    try {
+        const outliers = await neural.outliers(argv.threshold);
+        spinner.succeed(`✅ Found ${outliers.length} outliers`);
+        if (outliers.length === 0) {
+            console.log('\n🎉 No outliers detected - all items are well connected!');
+        }
+        else {
+            console.log(`\n🚨 ${chalk.red(outliers.length)} Semantic Outliers:`);
+            outliers.forEach((outlier, index) => {
+                console.log(`${index + 1}. ${outlier}`);
+            });
+            console.log(`\n💡 These items have similarity < ${argv.threshold} to their nearest neighbors`);
+        }
+        if (argv.output) {
+            await saveToFile(argv.output, outliers, argv.format);
+        }
+    }
+    catch (error) {
+        spinner.fail('💥 Failed to detect outliers');
+        throw error;
+    }
+}
+async function handleVisualizeCommand(neural, argv) {
+    const spinner = ora('📊 Generating visualization data...').start();
+    try {
+        const vizData = await neural.visualize({
+            dimensions: argv.dimensions,
+            maxNodes: argv.limit
+        });
+        spinner.succeed('✅ Visualization data generated');
+        console.log(`\n📊 Visualization Data (${vizData.format} layout):`);
+        console.log(`📍 Nodes: ${vizData.nodes.length}`);
+        console.log(`🔗 Edges: ${vizData.edges.length}`);
+        console.log(`🎯 Clusters: ${vizData.clusters?.length || 0}`);
+        console.log(`📐 Dimensions: ${vizData.layout?.dimensions}D`);
+        if (argv.format === 'json') {
+            console.log('\nData:');
+            console.log(JSON.stringify(vizData, null, 2));
+        }
+        else {
+            console.log('\n🎨 Style Settings:');
+            console.log(`  Node Colors: ${vizData.style?.nodeColors}`);
+            console.log(`  Edge Width: ${vizData.style?.edgeWidth}`);
+            console.log(`  Labels: ${vizData.style?.labels}`);
+        }
+        if (argv.output) {
+            await saveToFile(argv.output, vizData, 'json');
+            console.log(`\n💾 Visualization data saved to: ${chalk.green(argv.output)}`);
+        }
+        else {
+            console.log(`\n💡 Use --output to save visualization data for external tools`);
+        }
+    }
+    catch (error) {
+        spinner.fail('💥 Failed to generate visualization');
+        throw error;
+    }
+}
+async function saveToFile(filepath, data, format) {
+    const dir = path.dirname(filepath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    let output;
+    switch (format) {
+        case 'json':
+            output = JSON.stringify(data, null, 2);
+            break;
+        case 'table':
+            output = formatAsTable(data);
+            break;
+        default:
+            output = JSON.stringify(data, null, 2);
+    }
+    fs.writeFileSync(filepath, output, 'utf8');
+    console.log(`💾 Saved to: ${chalk.green(filepath)}`);
+}
+function formatAsTable(data) {
+    // Simple table formatting - could be enhanced with a table library
+    if (Array.isArray(data)) {
+        return data.map((item, index) => `${index + 1}. ${JSON.stringify(item)}`).join('\n');
+    }
+    return JSON.stringify(data, null, 2);
+}
+function showHelp() {
+    console.log('\n🧠 Neural Similarity API Commands:');
+    console.log('');
+    console.log('  brainy neural similar <item1> <item2>    Calculate similarity');
+    console.log('  brainy neural clusters                    Find semantic clusters');
+    console.log('  brainy neural hierarchy <id>              Show item hierarchy');
+    console.log('  brainy neural neighbors <id>              Find semantic neighbors');
+    console.log('  brainy neural path <from> <to>            Find semantic path');
+    console.log('  brainy neural outliers                    Detect outliers');
+    console.log('  brainy neural visualize                   Generate visualization data');
+    console.log('');
+    console.log('Options:');
+    console.log('  --threshold, -t   Similarity threshold (0-1)');
+    console.log('  --format, -f      Output format (json|table|tree|graph)');
+    console.log('  --output, -o      Save to file');
+    console.log('  --limit, -l       Maximum results');
+    console.log('  --explain, -e     Include explanations');
+    console.log('');
+}
+export default neuralCommand;
+//# sourceMappingURL=neural.js.map

.recovery-workspace/dist-backup-20250910-141917/cli/commands/utility.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Utility CLI Commands - TypeScript Implementation
+ *
+ * Database maintenance, statistics, and benchmarking
+ */
+interface UtilityOptions {
+    verbose?: boolean;
+    json?: boolean;
+    pretty?: boolean;
+}
+interface StatsOptions extends UtilityOptions {
+    byService?: boolean;
+    detailed?: boolean;
+}
+interface CleanOptions extends UtilityOptions {
+    removeOrphans?: boolean;
+    rebuildIndex?: boolean;
+}
+interface BenchmarkOptions extends UtilityOptions {
+    operations?: string;
+    iterations?: string;
+}
+export declare const utilityCommands: {
+    /**
+     * Show database statistics
+     */
+    stats(options: StatsOptions): Promise<void>;
+    /**
+     * Clean and optimize database
+     */
+    clean(options: CleanOptions): Promise<void>;
+    /**
+     * Run performance benchmarks
+     */
+    benchmark(options: BenchmarkOptions): Promise<void>;
+};
+export {};

.recovery-workspace/dist-backup-20250910-141917/cli/commands/utility.js

@@ -0,0 +1,276 @@
+/**
+ * Utility CLI Commands - TypeScript Implementation
+ *
+ * Database maintenance, statistics, and benchmarking
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import Table from 'cli-table3';
+import { BrainyData } from '../../brainyData.js';
+let brainyInstance = null;
+const getBrainy = async () => {
+    if (!brainyInstance) {
+        brainyInstance = new BrainyData();
+        await brainyInstance.init();
+    }
+    return brainyInstance;
+};
+const formatBytes = (bytes) => {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+};
+const formatOutput = (data, options) => {
+    if (options.json) {
+        console.log(options.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+    }
+};
+export const utilityCommands = {
+    /**
+     * Show database statistics
+     */
+    async stats(options) {
+        const spinner = ora('Gathering statistics...').start();
+        try {
+            const brain = await getBrainy();
+            const stats = await brain.getStatistics();
+            const memUsage = process.memoryUsage();
+            spinner.succeed('Statistics gathered');
+            if (options.json) {
+                formatOutput(stats, options);
+                return;
+            }
+            console.log(chalk.cyan('\n📊 Database Statistics\n'));
+            // Core stats table
+            const coreTable = new Table({
+                head: [chalk.cyan('Metric'), chalk.cyan('Value')],
+                style: { head: [], border: [] }
+            });
+            coreTable.push(['Total Items', chalk.green(stats.nounCount + stats.verbCount + stats.metadataCount || 0)], ['Nouns', chalk.green(stats.nounCount || 0)], ['Verbs (Relationships)', chalk.green(stats.verbCount || 0)], ['Metadata Records', chalk.green(stats.metadataCount || 0)]);
+            console.log(coreTable.toString());
+            // Service breakdown if available
+            if (options.byService && stats.serviceBreakdown) {
+                console.log(chalk.cyan('\n🔧 Service Breakdown\n'));
+                const serviceTable = new Table({
+                    head: [chalk.cyan('Service'), chalk.cyan('Nouns'), chalk.cyan('Verbs'), chalk.cyan('Metadata')],
+                    style: { head: [], border: [] }
+                });
+                Object.entries(stats.serviceBreakdown).forEach(([service, serviceStats]) => {
+                    serviceTable.push([
+                        service,
+                        serviceStats.nounCount || 0,
+                        serviceStats.verbCount || 0,
+                        serviceStats.metadataCount || 0
+                    ]);
+                });
+                console.log(serviceTable.toString());
+            }
+            // Storage info
+            if (stats.storage) {
+                console.log(chalk.cyan('\n💾 Storage\n'));
+                const storageTable = new Table({
+                    head: [chalk.cyan('Property'), chalk.cyan('Value')],
+                    style: { head: [], border: [] }
+                });
+                storageTable.push(['Type', stats.storage.type || 'Unknown'], ['Size', stats.storage.size ? formatBytes(stats.storage.size) : 'N/A'], ['Location', stats.storage.location || 'N/A']);
+                console.log(storageTable.toString());
+            }
+            // Performance metrics
+            if (stats.performance && options.detailed) {
+                console.log(chalk.cyan('\n⚡ Performance\n'));
+                const perfTable = new Table({
+                    head: [chalk.cyan('Metric'), chalk.cyan('Value')],
+                    style: { head: [], border: [] }
+                });
+                if (stats.performance.avgQueryTime) {
+                    perfTable.push(['Avg Query Time', `${stats.performance.avgQueryTime.toFixed(2)} ms`]);
+                }
+                if (stats.performance.totalQueries) {
+                    perfTable.push(['Total Queries', stats.performance.totalQueries]);
+                }
+                if (stats.performance.cacheHitRate) {
+                    perfTable.push(['Cache Hit Rate', `${(stats.performance.cacheHitRate * 100).toFixed(1)}%`]);
+                }
+                console.log(perfTable.toString());
+            }
+            // Memory usage
+            console.log(chalk.cyan('\n🧠 Memory Usage\n'));
+            const memTable = new Table({
+                head: [chalk.cyan('Type'), chalk.cyan('Size')],
+                style: { head: [], border: [] }
+            });
+            memTable.push(['Heap Used', formatBytes(memUsage.heapUsed)], ['Heap Total', formatBytes(memUsage.heapTotal)], ['RSS', formatBytes(memUsage.rss)], ['External', formatBytes(memUsage.external)]);
+            console.log(memTable.toString());
+            // Index info
+            if (stats.index && options.detailed) {
+                console.log(chalk.cyan('\n🎯 Vector Index\n'));
+                const indexTable = new Table({
+                    head: [chalk.cyan('Property'), chalk.cyan('Value')],
+                    style: { head: [], border: [] }
+                });
+                indexTable.push(['Dimensions', stats.index.dimensions || 'N/A'], ['Indexed Vectors', stats.index.vectorCount || 0], ['Index Size', stats.index.indexSize ? formatBytes(stats.index.indexSize) : 'N/A']);
+                console.log(indexTable.toString());
+            }
+        }
+        catch (error) {
+            spinner.fail('Failed to gather statistics');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Clean and optimize database
+     */
+    async clean(options) {
+        const spinner = ora('Cleaning database...').start();
+        try {
+            const brain = await getBrainy();
+            const tasks = [];
+            if (options.removeOrphans) {
+                spinner.text = 'Removing orphaned items...';
+                tasks.push('Removed orphaned items');
+                // Implementation would go here
+                await new Promise(resolve => setTimeout(resolve, 500)); // Simulate work
+            }
+            if (options.rebuildIndex) {
+                spinner.text = 'Rebuilding search index...';
+                tasks.push('Rebuilt search index');
+                // Implementation would go here
+                await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate work
+            }
+            if (tasks.length === 0) {
+                spinner.text = 'Running general cleanup...';
+                tasks.push('General cleanup completed');
+                // Run general cleanup tasks
+                await new Promise(resolve => setTimeout(resolve, 500)); // Simulate work
+            }
+            spinner.succeed('Database cleaned');
+            if (!options.json) {
+                console.log(chalk.green('\n✓ Cleanup completed:'));
+                tasks.forEach(task => {
+                    console.log(chalk.dim(`  • ${task}`));
+                });
+                // Get new stats
+                const stats = await brain.getStatistics();
+                console.log(chalk.cyan('\nDatabase Status:'));
+                console.log(`  Total items: ${stats.nounCount + stats.verbCount}`);
+                console.log(`  Index status: ${chalk.green('Healthy')}`);
+            }
+            else {
+                formatOutput({ tasks, success: true }, options);
+            }
+        }
+        catch (error) {
+            spinner.fail('Cleanup failed');
+            console.error(chalk.red(error.message));
+            process.exit(1);
+        }
+    },
+    /**
+     * Run performance benchmarks
+     */
+    async benchmark(options) {
+        const operations = options.operations || 'all';
+        const iterations = parseInt(options.iterations || '100');
+        console.log(chalk.cyan(`\n🚀 Running Benchmarks (${iterations} iterations)\n`));
+        const results = {
+            operations: {},
+            summary: {}
+        };
+        try {
+            const brain = await getBrainy();
+            // Benchmark different operations
+            const benchmarks = [
+                { name: 'add', enabled: operations === 'all' || operations.includes('add') },
+                { name: 'search', enabled: operations === 'all' || operations.includes('search') },
+                { name: 'similarity', enabled: operations === 'all' || operations.includes('similarity') },
+                { name: 'cluster', enabled: operations === 'all' || operations.includes('cluster') }
+            ];
+            for (const bench of benchmarks) {
+                if (!bench.enabled)
+                    continue;
+                const spinner = ora(`Benchmarking ${bench.name}...`).start();
+                const times = [];
+                for (let i = 0; i < iterations; i++) {
+                    const start = Date.now();
+                    switch (bench.name) {
+                        case 'add':
+                            await brain.add(`Test item ${i}`, { benchmark: true });
+                            break;
+                        case 'search':
+                            await brain.search('test', 10);
+                            break;
+                        case 'similarity':
+                            const neural = brain.neural;
+                            await neural.similar('test1', 'test2');
+                            break;
+                        case 'cluster':
+                            const neuralApi = brain.neural;
+                            await neuralApi.clusters();
+                            break;
+                    }
+                    times.push(Date.now() - start);
+                }
+                // Calculate statistics
+                const avg = times.reduce((a, b) => a + b, 0) / times.length;
+                const min = Math.min(...times);
+                const max = Math.max(...times);
+                const median = times.sort((a, b) => a - b)[Math.floor(times.length / 2)];
+                results.operations[bench.name] = {
+                    avg: avg.toFixed(2),
+                    min,
+                    max,
+                    median,
+                    ops: (1000 / avg).toFixed(2)
+                };
+                spinner.succeed(`${bench.name}: ${avg.toFixed(2)}ms avg (${(1000 / avg).toFixed(2)} ops/sec)`);
+            }
+            // Calculate summary
+            const totalOps = Object.values(results.operations).reduce((sum, op) => sum + parseFloat(op.ops), 0);
+            results.summary = {
+                totalOperations: Object.keys(results.operations).length,
+                averageOpsPerSec: (totalOps / Object.keys(results.operations).length).toFixed(2)
+            };
+            if (!options.json) {
+                // Display results table
+                console.log(chalk.cyan('\n📊 Benchmark Results\n'));
+                const table = new Table({
+                    head: [
+                        chalk.cyan('Operation'),
+                        chalk.cyan('Avg (ms)'),
+                        chalk.cyan('Min (ms)'),
+                        chalk.cyan('Max (ms)'),
+                        chalk.cyan('Median (ms)'),
+                        chalk.cyan('Ops/sec')
+                    ],
+                    style: { head: [], border: [] }
+                });
+                Object.entries(results.operations).forEach(([op, stats]) => {
+                    table.push([
+                        op,
+                        stats.avg,
+                        stats.min,
+                        stats.max,
+                        stats.median,
+                        chalk.green(stats.ops)
+                    ]);
+                });
+                console.log(table.toString());
+                console.log(chalk.cyan('\n📈 Summary'));
+                console.log(`  Operations tested: ${results.summary.totalOperations}`);
+                console.log(`  Average throughput: ${chalk.green(results.summary.averageOpsPerSec)} ops/sec`);
+            }
+            else {
+                formatOutput(results, options);
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Benchmark failed:'), error.message);
+            process.exit(1);
+        }
+    }
+};
+//# sourceMappingURL=utility.js.map