ruvector 0.2.1 → 0.2.2

package/bin/cli.js

@@ -9,6 +9,52 @@ const chalk = _chalk.default || _chalk;
 const fs = require('fs');
 const path = require('path');
 
+// Load .env from current directory (if exists)
+try {
+  const envPath = path.join(process.cwd(), '.env');
+  if (fs.existsSync(envPath)) {
+    const envContent = fs.readFileSync(envPath, 'utf8');
+    for (const line of envContent.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eqIdx = trimmed.indexOf('=');
+      if (eqIdx > 0) {
+        const key = trimmed.slice(0, eqIdx).trim();
+        let value = trimmed.slice(eqIdx + 1).trim();
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+          value = value.slice(1, -1);
+        }
+        // Don't override existing env vars
+        if (!process.env[key]) {
+          process.env[key] = value;
+        }
+      }
+    }
+  }
+} catch {}
+
+// Load global config from ~/.ruvector/config.json (if exists)
+try {
+  const os = require('os');
+  const configPath = path.join(os.homedir(), '.ruvector', 'config.json');
+  if (fs.existsSync(configPath)) {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    // Map config keys to env vars (don't override existing)
+    const configMap = {
+      brain_url: 'BRAIN_URL',
+      pi_key: 'PI',
+      edge_genesis_url: 'EDGE_GENESIS_URL',
+      edge_relay_url: 'EDGE_RELAY_URL',
+    };
+    for (const [configKey, envKey] of Object.entries(configMap)) {
+      if (config[configKey] && !process.env[envKey]) {
+        process.env[envKey] = config[configKey];
+      }
+    }
+  }
+} catch {}
+
 // Lazy load ora (spinner) - only needed for commands with progress indicators
 let _oraModule = null;
 function ora(text) {
@@ -45,59 +91,72 @@ function requireRuvector() {
   }
 }
 
-// Import GNN (optional - graceful fallback if not available)
+// Lazy load GNN (optional - loaded on first use, not at startup)
+let _gnnModule = undefined;
 let RuvectorLayer, TensorCompress, differentiableSearch, getCompressionLevel, hierarchicalForward;
 let gnnAvailable = false;
-try {
-  const gnn = require('@ruvector/gnn');
-  RuvectorLayer = gnn.RuvectorLayer;
-  TensorCompress = gnn.TensorCompress;
-  differentiableSearch = gnn.differentiableSearch;
-  getCompressionLevel = gnn.getCompressionLevel;
-  hierarchicalForward = gnn.hierarchicalForward;
-  gnnAvailable = true;
-} catch (e) {
-  // GNN not available - commands will show helpful message
+
+function loadGnn() {
+  if (_gnnModule !== undefined) return _gnnModule;
+  try {
+    const gnn = require('@ruvector/gnn');
+    RuvectorLayer = gnn.RuvectorLayer;
+    TensorCompress = gnn.TensorCompress;
+    differentiableSearch = gnn.differentiableSearch;
+    getCompressionLevel = gnn.getCompressionLevel;
+    hierarchicalForward = gnn.hierarchicalForward;
+    _gnnModule = gnn;
+    gnnAvailable = true;
+    return gnn;
+  } catch {
+    _gnnModule = null;
+    gnnAvailable = false;
+    return null;
+  }
 }
 
-// Import Attention (optional - graceful fallback if not available)
+// Lazy load Attention (optional - loaded on first use, not at startup)
+let _attentionModule = undefined;
 let DotProductAttention, MultiHeadAttention, HyperbolicAttention, FlashAttention, LinearAttention, MoEAttention;
 let GraphRoPeAttention, EdgeFeaturedAttention, DualSpaceAttention, LocalGlobalAttention;
 let benchmarkAttention, computeAttentionAsync, batchAttentionCompute, parallelAttentionCompute;
 let expMap, logMap, mobiusAddition, poincareDistance, projectToPoincareBall;
 let attentionInfo, attentionVersion;
 let attentionAvailable = false;
-try {
-  const attention = require('@ruvector/attention');
-  // Core mechanisms
-  DotProductAttention = attention.DotProductAttention;
-  MultiHeadAttention = attention.MultiHeadAttention;
-  HyperbolicAttention = attention.HyperbolicAttention;
-  FlashAttention = attention.FlashAttention;
-  LinearAttention = attention.LinearAttention;
-  MoEAttention = attention.MoEAttention;
-  // Graph attention
-  GraphRoPeAttention = attention.GraphRoPeAttention;
-  EdgeFeaturedAttention = attention.EdgeFeaturedAttention;
-  DualSpaceAttention = attention.DualSpaceAttention;
-  LocalGlobalAttention = attention.LocalGlobalAttention;
-  // Utilities
-  benchmarkAttention = attention.benchmarkAttention;
-  computeAttentionAsync = attention.computeAttentionAsync;
-  batchAttentionCompute = attention.batchAttentionCompute;
-  parallelAttentionCompute = attention.parallelAttentionCompute;
-  // Hyperbolic math
-  expMap = attention.expMap;
-  logMap = attention.logMap;
-  mobiusAddition = attention.mobiusAddition;
-  poincareDistance = attention.poincareDistance;
-  projectToPoincareBall = attention.projectToPoincareBall;
-  // Meta
-  attentionInfo = attention.info;
-  attentionVersion = attention.version;
-  attentionAvailable = true;
-} catch (e) {
-  // Attention not available - commands will show helpful message
+
+function loadAttention() {
+  if (_attentionModule !== undefined) return _attentionModule;
+  try {
+    const attention = require('@ruvector/attention');
+    DotProductAttention = attention.DotProductAttention;
+    MultiHeadAttention = attention.MultiHeadAttention;
+    HyperbolicAttention = attention.HyperbolicAttention;
+    FlashAttention = attention.FlashAttention;
+    LinearAttention = attention.LinearAttention;
+    MoEAttention = attention.MoEAttention;
+    GraphRoPeAttention = attention.GraphRoPeAttention;
+    EdgeFeaturedAttention = attention.EdgeFeaturedAttention;
+    DualSpaceAttention = attention.DualSpaceAttention;
+    LocalGlobalAttention = attention.LocalGlobalAttention;
+    benchmarkAttention = attention.benchmarkAttention;
+    computeAttentionAsync = attention.computeAttentionAsync;
+    batchAttentionCompute = attention.batchAttentionCompute;
+    parallelAttentionCompute = attention.parallelAttentionCompute;
+    expMap = attention.expMap;
+    logMap = attention.logMap;
+    mobiusAddition = attention.mobiusAddition;
+    poincareDistance = attention.poincareDistance;
+    projectToPoincareBall = attention.projectToPoincareBall;
+    attentionInfo = attention.attentionInfo;
+    attentionVersion = attention.attentionVersion;
+    _attentionModule = attention;
+    attentionAvailable = true;
+    return attention;
+  } catch {
+    _attentionModule = null;
+    attentionAvailable = false;
+    return null;
+  }
 }
 
 const program = new Command();
@@ -369,7 +428,8 @@ program
 
     // Try to load ruvector for implementation info
     if (loadRuvector()) {
-      const version = typeof getVersion === 'function' ? getVersion() : 'unknown';
+      const versionInfo = typeof getVersion === 'function' ? getVersion() : null;
+      const version = versionInfo && versionInfo.version ? versionInfo.version : 'unknown';
       const impl = typeof getImplementationType === 'function' ? getImplementationType() : 'native';
       console.log(chalk.white(`  Core Version: ${chalk.yellow(version)}`));
       console.log(chalk.white(`  Implementation: ${chalk.yellow(impl)}`));
@@ -377,6 +437,7 @@ program
       console.log(chalk.white(`  Core: ${chalk.gray('Not loaded (install @ruvector/core)')}`));
     }
 
+    loadGnn();
     console.log(chalk.white(`  GNN Module: ${gnnAvailable ? chalk.green('Available') : chalk.gray('Not installed')}`));
     console.log(chalk.white(`  Node Version: ${chalk.yellow(process.version)}`));
     console.log(chalk.white(`  Platform: ${chalk.yellow(process.platform)}`));
@@ -401,6 +462,7 @@ program
     const { execSync } = require('child_process');
 
     // Available optional packages - all ruvector npm packages
+    loadGnn();
     const availablePackages = {
       // Core packages
       core: {
@@ -689,6 +751,7 @@ program
 
 // Helper to check GNN availability
 function requireGnn() {
+  loadGnn();
   if (!gnnAvailable) {
     console.error(chalk.red('Error: GNN module not available.'));
     console.error(chalk.yellow('Install it with: npm install @ruvector/gnn'));
@@ -884,6 +947,7 @@ gnnCmd
   .command('info')
   .description('Show GNN module information')
   .action(() => {
+    loadGnn();
     if (!gnnAvailable) {
       console.log(chalk.yellow('\nGNN Module: Not installed'));
       console.log(chalk.white('Install with: npm install @ruvector/gnn'));
@@ -915,6 +979,7 @@ gnnCmd
 
 // Helper to require attention module
 function requireAttention() {
+  loadAttention();
   if (!attentionAvailable) {
     console.error(chalk.red('Error: @ruvector/attention is not installed'));
     console.error(chalk.yellow('Install it with: npm install @ruvector/attention'));
@@ -1242,6 +1307,7 @@ attentionCmd
   .command('info')
   .description('Show attention module information')
   .action(() => {
+    loadAttention();
     if (!attentionAvailable) {
       console.log(chalk.yellow('\nAttention Module: Not installed'));
       console.log(chalk.white('Install with: npm install @ruvector/attention'));
@@ -1287,6 +1353,7 @@ attentionCmd
   .description('List all available attention mechanisms')
   .option('-v, --verbose', 'Show detailed information')
   .action((options) => {
+    loadAttention();
     console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
     console.log(chalk.cyan('              Available Attention Mechanisms'));
     console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
@@ -1429,6 +1496,7 @@ program
     }
 
     // Check @ruvector/gnn
+    loadGnn();
     if (gnnAvailable) {
       console.log(chalk.green(`  ✓ @ruvector/gnn installed`));
     } else {
@@ -1436,6 +1504,7 @@ program
     }
 
     // Check @ruvector/attention
+    loadAttention();
     if (attentionAvailable) {
       console.log(chalk.green(`  ✓ @ruvector/attention installed`));
     } else {
@@ -2531,6 +2600,7 @@ program
     }
 
     if (options.gnn) {
+      loadGnn();
       if (!gnnAvailable) {
         console.log(chalk.yellow('  @ruvector/gnn not installed.'));
         console.log(chalk.white('  Install with: npm install @ruvector/gnn'));
@@ -7130,165 +7200,356 @@ rvfCmd.command('export <path>')
     } catch (e) { console.error(chalk.red(e.message)); process.exit(1); }
   });
 
-// RVF example download/list commands
-const RVF_EXAMPLES = [
-  { name: 'basic_store', size: '152 KB', desc: '1,000 vectors, dim 128, cosine metric' },
-  { name: 'semantic_search', size: '755 KB', desc: 'Semantic search with HNSW index' },
-  { name: 'rag_pipeline', size: '303 KB', desc: 'RAG pipeline with embeddings' },
-  { name: 'embedding_cache', size: '755 KB', desc: 'Cached embedding store' },
-  { name: 'quantization', size: '1.5 MB', desc: 'PQ-compressed vectors' },
-  { name: 'progressive_index', size: '2.5 MB', desc: 'Large-scale progressive HNSW index' },
-  { name: 'filtered_search', size: '255 KB', desc: 'Metadata-filtered vector search' },
-  { name: 'recommendation', size: '102 KB', desc: 'Recommendation engine vectors' },
-  { name: 'agent_memory', size: '32 KB', desc: 'AI agent episodic memory' },
-  { name: 'swarm_knowledge', size: '86 KB', desc: 'Multi-agent shared knowledge base' },
-  { name: 'experience_replay', size: '27 KB', desc: 'RL experience replay buffer' },
-  { name: 'tool_cache', size: '26 KB', desc: 'MCP tool call cache' },
-  { name: 'mcp_in_rvf', size: '32 KB', desc: 'MCP server embedded in RVF' },
-  { name: 'ruvbot', size: '51 KB', desc: 'Chatbot knowledge store' },
-  { name: 'claude_code_appliance', size: '17 KB', desc: 'Claude Code cognitive appliance' },
-  { name: 'lineage_parent', size: '52 KB', desc: 'COW parent file' },
-  { name: 'lineage_child', size: '26 KB', desc: 'COW child (derived) file' },
-  { name: 'self_booting', size: '31 KB', desc: 'Self-booting with KERNEL_SEG' },
-  { name: 'linux_microkernel', size: '15 KB', desc: 'Embedded Linux microkernel' },
-  { name: 'ebpf_accelerator', size: '153 KB', desc: 'eBPF distance accelerator' },
-  { name: 'browser_wasm', size: '14 KB', desc: 'Browser WASM module embedded' },
-  { name: 'tee_attestation', size: '102 KB', desc: 'TEE attestation with witnesses' },
-  { name: 'zero_knowledge', size: '52 KB', desc: 'ZK-proof witness chain' },
-  { name: 'sealed_engine', size: '208 KB', desc: 'Sealed inference engine' },
-  { name: 'access_control', size: '77 KB', desc: 'Permission-gated vectors' },
-  { name: 'financial_signals', size: '202 KB', desc: 'Financial signal vectors' },
-  { name: 'medical_imaging', size: '302 KB', desc: 'Medical imaging embeddings' },
-  { name: 'legal_discovery', size: '903 KB', desc: 'Legal document discovery' },
-  { name: 'multimodal_fusion', size: '804 KB', desc: 'Multi-modal embedding fusion' },
-  { name: 'hyperbolic_taxonomy', size: '23 KB', desc: 'Hyperbolic space taxonomy' },
-  { name: 'network_telemetry', size: '16 KB', desc: 'Network telemetry vectors' },
-  { name: 'postgres_bridge', size: '152 KB', desc: 'PostgreSQL bridge vectors' },
-  { name: 'ruvllm_inference', size: '133 KB', desc: 'RuvLLM inference cache' },
-  { name: 'serverless', size: '509 KB', desc: 'Serverless deployment bundle' },
-  { name: 'edge_iot', size: '27 KB', desc: 'Edge/IoT lightweight store' },
-  { name: 'dedup_detector', size: '153 KB', desc: 'Deduplication detector' },
-  { name: 'compacted', size: '77 KB', desc: 'Post-compaction example' },
-  { name: 'posix_fileops', size: '52 KB', desc: 'POSIX file operations test' },
-  { name: 'network_sync_a', size: '52 KB', desc: 'Network sync peer A' },
-  { name: 'network_sync_b', size: '52 KB', desc: 'Network sync peer B' },
-  { name: 'agent_handoff_a', size: '31 KB', desc: 'Agent handoff source' },
-  { name: 'agent_handoff_b', size: '11 KB', desc: 'Agent handoff target' },
-  { name: 'reasoning_parent', size: '5.6 KB', desc: 'Reasoning chain parent' },
-  { name: 'reasoning_child', size: '8.1 KB', desc: 'Reasoning chain child' },
-  { name: 'reasoning_grandchild', size: '162 B', desc: 'Minimal derived file' },
+// RVF example catalog - manifest-based with local cache + SHA-256 verification
+const BUILTIN_RVF_CATALOG = [
+  // Minimal fallback if GCS and cache are both unavailable
+  { name: 'basic_store', size_human: '152 KB', description: '1,000 vectors, dim 128, cosine metric', category: 'core' },
+  { name: 'semantic_search', size_human: '755 KB', description: 'Semantic search with HNSW index', category: 'core' },
+  { name: 'rag_pipeline', size_human: '303 KB', description: 'RAG pipeline with embeddings', category: 'core' },
+  { name: 'agent_memory', size_human: '32 KB', description: 'AI agent episodic memory', category: 'ai' },
+  { name: 'swarm_knowledge', size_human: '86 KB', description: 'Multi-agent shared knowledge base', category: 'ai' },
+  { name: 'self_booting', size_human: '31 KB', description: 'Self-booting with KERNEL_SEG', category: 'compute' },
+  { name: 'ebpf_accelerator', size_human: '153 KB', description: 'eBPF distance accelerator', category: 'compute' },
+  { name: 'tee_attestation', size_human: '102 KB', description: 'TEE attestation with witnesses', category: 'security' },
+  { name: 'claude_code_appliance', size_human: '17 KB', description: 'Claude Code cognitive appliance', category: 'integration' },
+  { name: 'lineage_parent', size_human: '52 KB', description: 'COW parent file', category: 'lineage' },
+  { name: 'financial_signals', size_human: '202 KB', description: 'Financial signal vectors', category: 'industry' },
+  { name: 'mcp_in_rvf', size_human: '32 KB', description: 'MCP server embedded in RVF', category: 'integration' },
 ];
 
-const RVF_BASE_URL = 'https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output';
+const GCS_MANIFEST_URL = 'https://storage.googleapis.com/ruvector-examples/manifest.json';
+const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output';
+
+function getRvfCacheDir() {
+  const os = require('os');
+  return path.join(os.homedir(), '.ruvector', 'examples');
+}
+
+async function getRvfManifest(opts = {}) {
+  const cacheDir = getRvfCacheDir();
+  const manifestPath = path.join(cacheDir, 'manifest.json');
+
+  // Check cache (1 hour TTL)
+  if (!opts.refresh && fs.existsSync(manifestPath)) {
+    try {
+      const stat = fs.statSync(manifestPath);
+      const age = Date.now() - stat.mtimeMs;
+      if (age < 3600000) {
+        return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      }
+    } catch {}
+  }
+
+  if (opts.offline) {
+    // Offline mode - use cache even if stale
+    if (fs.existsSync(manifestPath)) {
+      return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    return { examples: BUILTIN_RVF_CATALOG, base_url: GITHUB_RAW_BASE, version: 'builtin', offline: true };
+  }
+
+  // Try GCS
+  try {
+    const resp = await fetch(GCS_MANIFEST_URL);
+    if (resp.ok) {
+      const manifest = await resp.json();
+      fs.mkdirSync(cacheDir, { recursive: true });
+      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+      return manifest;
+    }
+  } catch {}
+
+  // Fallback: stale cache
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      manifest._stale = true;
+      return manifest;
+    } catch {}
+  }
+
+  // Final fallback: builtin catalog with GitHub URLs
+  return { examples: BUILTIN_RVF_CATALOG, base_url: GITHUB_RAW_BASE, version: 'builtin' };
+}
+
+function verifyRvfFile(filePath, expectedSha256) {
+  if (!expectedSha256) return { verified: false, reason: 'No checksum available' };
+  const crypto = require('crypto');
+  const hash = crypto.createHash('sha256');
+  const data = fs.readFileSync(filePath);
+  hash.update(data);
+  const actual = hash.digest('hex');
+  return { verified: actual === expectedSha256, actual, expected: expectedSha256 };
+}
 
 rvfCmd.command('examples')
-  .description('List available example .rvf files')
+  .description('List available example .rvf files from the catalog')
+  .option('--category <cat>', 'Filter by category (core, ai, security, compute, lineage, industry, network, integration)')
+  .option('--refresh', 'Force refresh manifest from server')
+  .option('--offline', 'Use only cached data')
   .option('--json', 'Output as JSON')
-  .action((opts) => {
+  .action(async (opts) => {
+    const manifest = await getRvfManifest({ refresh: opts.refresh, offline: opts.offline });
+    let examples = manifest.examples || [];
+
+    if (opts.category) {
+      examples = examples.filter(e => e.category === opts.category);
+    }
+
     if (opts.json) {
-      console.log(JSON.stringify(RVF_EXAMPLES, null, 2));
+      console.log(JSON.stringify({ version: manifest.version, count: examples.length, examples }, null, 2));
       return;
     }
-    console.log(chalk.bold.cyan('\nAvailable RVF Example Files (45 total)\n'));
-    console.log(chalk.dim(`Download: npx ruvector rvf download <name>\n`));
-    const maxName = Math.max(...RVF_EXAMPLES.map(e => e.name.length));
-    const maxSize = Math.max(...RVF_EXAMPLES.map(e => e.size.length));
-    for (const ex of RVF_EXAMPLES) {
-      const name = chalk.green(ex.name.padEnd(maxName));
-      const size = chalk.yellow(ex.size.padStart(maxSize));
-      console.log(`  ${name}  ${size}  ${chalk.dim(ex.desc)}`);
+
+    console.log(chalk.bold.cyan(`\nRVF Example Files (${examples.length} of ${(manifest.examples || []).length} total)\n`));
+    if (manifest._stale) console.log(chalk.yellow('  (Using stale cached manifest)\n'));
+    if (manifest.version === 'builtin') console.log(chalk.yellow('  (Using built-in catalog -- run without --offline for full list)\n'));
+    console.log(chalk.dim(`  Download: npx ruvector rvf download <name>`));
+    console.log(chalk.dim(`  Filter:   npx ruvector rvf examples --category ai\n`));
+
+    // Group by category
+    const grouped = {};
+    for (const ex of examples) {
+      const cat = ex.category || 'other';
+      if (!grouped[cat]) grouped[cat] = [];
+      grouped[cat].push(ex);
+    }
+
+    for (const [cat, items] of Object.entries(grouped).sort()) {
+      const catDesc = manifest.categories ? manifest.categories[cat] || '' : '';
+      console.log(chalk.bold.yellow(`  ${cat} ${catDesc ? chalk.dim(`-- ${catDesc}`) : ''}`));
+      for (const ex of items) {
+        const name = chalk.green(ex.name.padEnd(28));
+        const size = chalk.yellow((ex.size_human || '').padStart(8));
+        console.log(`    ${name} ${size}  ${chalk.dim(ex.description || '')}`);
+      }
+      console.log();
+    }
+
+    if (manifest.categories && !opts.category) {
+      console.log(chalk.dim(`  Categories: ${Object.keys(manifest.categories).join(', ')}\n`));
     }
-    console.log(chalk.dim(`\nFull catalog: https://github.com/ruvnet/ruvector/tree/main/examples/rvf/output\n`));
   });
 
 rvfCmd.command('download [names...]')
-  .description('Download example .rvf files from GitHub')
-  .option('-a, --all', 'Download all 45 examples (~11 MB)')
+  .description('Download example .rvf files with integrity verification')
+  .option('-a, --all', 'Download all examples')
+  .option('-c, --category <cat>', 'Download all examples in a category')
   .option('-o, --output <dir>', 'Output directory', '.')
+  .option('--verify', 'Re-verify cached files')
+  .option('--no-cache', 'Skip cache, always download fresh')
+  .option('--offline', 'Use only cached files')
+  .option('--refresh', 'Refresh manifest before download')
   .action(async (names, opts) => {
-    const https = require('https');
-    const ALLOWED_REDIRECT_HOSTS = ['raw.githubusercontent.com', 'objects.githubusercontent.com', 'github.com'];
-    const sanitizeFileName = (name) => {
-      // Strip path separators and parent directory references
-      const base = path.basename(name);
-      // Only allow alphanumeric, underscores, hyphens, dots
-      if (!/^[\w\-.]+$/.test(base)) throw new Error(`Invalid filename: ${base}`);
-      return base;
-    };
-    const downloadFile = (url, dest) => new Promise((resolve, reject) => {
-      const file = fs.createWriteStream(dest);
-      https.get(url, (res) => {
-        if (res.statusCode === 302 || res.statusCode === 301) {
-          const redirectUrl = res.headers.location;
-          try {
-            const redirectHost = new URL(redirectUrl).hostname;
-            if (!ALLOWED_REDIRECT_HOSTS.includes(redirectHost)) {
-              file.close();
-              reject(new Error(`Redirect to untrusted host: ${redirectHost}`));
-              return;
-            }
-          } catch { file.close(); reject(new Error('Invalid redirect URL')); return; }
-          https.get(redirectUrl, (res2) => { res2.pipe(file); file.on('finish', () => { file.close(); resolve(); }); }).on('error', reject);
-          return;
-        }
-        if (res.statusCode !== 200) { file.close(); fs.unlinkSync(dest); reject(new Error(`HTTP ${res.statusCode}`)); return; }
-        res.pipe(file);
-        file.on('finish', () => { file.close(); resolve(); });
-      }).on('error', reject);
-    });
+    const manifest = await getRvfManifest({ refresh: opts.refresh, offline: opts.offline });
+    const examples = manifest.examples || [];
+    const baseUrl = manifest.base_url || GITHUB_RAW_BASE;
 
     let toDownload = [];
     if (opts.all) {
-      toDownload = RVF_EXAMPLES.map(e => e.name);
+      toDownload = examples;
+    } else if (opts.category) {
+      toDownload = examples.filter(e => e.category === opts.category);
+      if (!toDownload.length) {
+        console.error(chalk.red(`No examples in category '${opts.category}'`));
+        process.exit(1);
+      }
     } else if (names && names.length > 0) {
-      toDownload = names;
+      for (const name of names) {
+        const cleanName = name.replace(/\.rvf$/, '');
+        const found = examples.find(e => e.name === cleanName);
+        if (found) {
+          toDownload.push(found);
+        } else {
+          console.error(chalk.red(`Unknown example: ${cleanName}. Run 'npx ruvector rvf examples' to list.`));
+        }
+      }
+      if (!toDownload.length) process.exit(1);
     } else {
-      console.error(chalk.red('Specify example names or use --all. Run `npx ruvector rvf examples` to list.'));
+      console.error(chalk.red('Specify example names, --all, or --category. Run `npx ruvector rvf examples` to list.'));
       process.exit(1);
     }
 
     const outDir = path.resolve(opts.output);
     if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+    const cacheDir = getRvfCacheDir();
+    fs.mkdirSync(cacheDir, { recursive: true });
 
     console.log(chalk.bold.cyan(`\nDownloading ${toDownload.length} .rvf file(s) to ${outDir}\n`));
-    let ok = 0, fail = 0;
-    for (const name of toDownload) {
-      const rawName = name.endsWith('.rvf') ? name : `${name}.rvf`;
-      let fileName;
-      try { fileName = sanitizeFileName(rawName); } catch (e) {
-        console.log(chalk.red(`SKIPPED: ${e.message}`));
+
+    const https = require('https');
+    const crypto = require('crypto');
+    const ALLOWED_REDIRECT_HOSTS = ['raw.githubusercontent.com', 'objects.githubusercontent.com', 'github.com', 'storage.googleapis.com'];
+
+    const downloadFile = (url, dest) => new Promise((resolve, reject) => {
+      const doGet = (getUrl) => {
+        const mod = getUrl.startsWith('https') ? https : require('http');
+        mod.get(getUrl, (res) => {
+          if (res.statusCode === 301 || res.statusCode === 302) {
+            const loc = res.headers.location;
+            try {
+              const host = new URL(loc).hostname;
+              if (!ALLOWED_REDIRECT_HOSTS.includes(host)) {
+                reject(new Error(`Redirect to untrusted host: ${host}`));
+                return;
+              }
+            } catch { reject(new Error('Invalid redirect URL')); return; }
+            doGet(loc);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}`));
+            return;
+          }
+          const file = fs.createWriteStream(dest);
+          res.pipe(file);
+          file.on('finish', () => { file.close(); resolve(); });
+          file.on('error', reject);
+        }).on('error', reject);
+      };
+      doGet(url);
+    });
+
+    let ok = 0, cached = 0, fail = 0, verified = 0;
+
+    for (const ex of toDownload) {
+      const fileName = `${ex.name}.rvf`;
+      // Sanitize filename
+      if (!/^[\w\-.]+$/.test(fileName)) {
+        console.log(`  ${chalk.red('SKIP')} ${fileName} (invalid filename)`);
         fail++;
         continue;
       }
-      // Validate against known examples when not using --all
-      if (!opts.all) {
-        const baseName = fileName.replace(/\.rvf$/, '');
-        if (!RVF_EXAMPLES.some(e => e.name === baseName)) {
-          console.log(chalk.red(`SKIPPED: Unknown example '${baseName}'. Run 'npx ruvector rvf examples' to list.`));
-          fail++;
+
+      const destPath = path.join(outDir, fileName);
+      const cachePath = path.join(cacheDir, fileName);
+
+      // Path containment check
+      if (!path.resolve(destPath).startsWith(path.resolve(outDir))) {
+        console.log(`  ${chalk.red('SKIP')} ${fileName} (path traversal)`);
+        fail++;
+        continue;
+      }
+
+      // Check cache first
+      if (opts.cache !== false && fs.existsSync(cachePath) && !opts.verify) {
+        // Verify if checksum available
+        if (ex.sha256) {
+          const check = verifyRvfFile(cachePath, ex.sha256);
+          if (check.verified) {
+            // Copy from cache
+            if (path.resolve(destPath) !== path.resolve(cachePath)) {
+              fs.copyFileSync(cachePath, destPath);
+            }
+            console.log(`  ${chalk.green('CACHED')} ${chalk.cyan(fileName)} ${chalk.dim(ex.size_human || '')}`);
+            cached++;
+            continue;
+          } else {
+            // Cache corrupted, re-download
+            console.log(`  ${chalk.yellow('STALE')} ${fileName} -- re-downloading`);
+          }
+        } else {
+          // Copy from cache (no checksum to verify)
+          if (path.resolve(destPath) !== path.resolve(cachePath)) {
+            fs.copyFileSync(cachePath, destPath);
+          }
+          console.log(`  ${chalk.green('CACHED')} ${chalk.cyan(fileName)} ${chalk.dim(ex.size_human || '')}`);
+          cached++;
           continue;
         }
       }
-      const url = `${RVF_BASE_URL}/${encodeURIComponent(fileName)}`;
-      const dest = path.join(outDir, fileName);
-      // Path containment check
-      if (!path.resolve(dest).startsWith(path.resolve(outDir) + path.sep) && path.resolve(dest) !== path.resolve(outDir)) {
-        console.log(chalk.red(`SKIPPED: Path traversal detected for '${fileName}'`));
+
+      if (opts.offline) {
+        console.log(`  ${chalk.yellow('SKIP')} ${fileName} (offline mode, not cached)`);
         fail++;
         continue;
       }
+
+      // Download
+      const url = `${baseUrl}/${encodeURIComponent(fileName)}`;
       try {
-        process.stdout.write(chalk.dim(`  ${fileName} ... `));
-        await downloadFile(url, dest);
-        const stat = fs.statSync(dest);
-        console.log(chalk.green(`OK (${(stat.size / 1024).toFixed(0)} KB)`));
+        await downloadFile(url, cachePath);
+
+        // SHA-256 verify
+        if (ex.sha256) {
+          const check = verifyRvfFile(cachePath, ex.sha256);
+          if (check.verified) {
+            verified++;
+            console.log(`  ${chalk.green('OK')} ${chalk.cyan(fileName)} ${chalk.dim(ex.size_human || '')} ${chalk.green('SHA-256 verified')}`);
+          } else {
+            console.log(`  ${chalk.red('FAIL')} ${fileName} -- SHA-256 mismatch! Expected ${ex.sha256.slice(0, 12)}... got ${check.actual.slice(0, 12)}...`);
+            fs.unlinkSync(cachePath);
+            fail++;
+            continue;
+          }
+        } else {
+          console.log(`  ${chalk.green('OK')} ${chalk.cyan(fileName)} ${chalk.dim(ex.size_human || '')} ${chalk.yellow('(no checksum)')}`);
+        }
+
+        // Copy to output dir if different from cache
+        if (path.resolve(destPath) !== path.resolve(cachePath)) {
+          fs.copyFileSync(cachePath, destPath);
+        }
         ok++;
       } catch (e) {
-        console.log(chalk.red(`FAILED: ${e.message}`));
+        console.log(`  ${chalk.red('FAIL')} ${fileName}: ${e.message}`);
         fail++;
       }
     }
-    console.log(chalk.bold(`\nDone: ${ok} downloaded, ${fail} failed\n`));
+
+    console.log(chalk.bold(`\n  Downloaded: ${ok}, Cached: ${cached}, Failed: ${fail}${verified ? `, Verified: ${verified}` : ''}\n`));
+  });
+
+// RVF cache management
+rvfCmd.command('cache <action>')
+  .description('Manage local .rvf example cache (status, clear)')
+  .action((action) => {
+    const cacheDir = getRvfCacheDir();
+
+    switch (action) {
+      case 'status': {
+        if (!fs.existsSync(cacheDir)) {
+          console.log(chalk.dim('\n  No cache directory found.\n'));
+          return;
+        }
+        const files = fs.readdirSync(cacheDir).filter(f => f.endsWith('.rvf'));
+        const manifestExists = fs.existsSync(path.join(cacheDir, 'manifest.json'));
+        let totalSize = 0;
+        for (const f of files) {
+          totalSize += fs.statSync(path.join(cacheDir, f)).size;
+        }
+        console.log(chalk.bold.cyan('\nRVF Cache Status\n'));
+        console.log(`  ${chalk.bold('Location:')}  ${cacheDir}`);
+        console.log(`  ${chalk.bold('Files:')}     ${files.length} .rvf files`);
+        console.log(`  ${chalk.bold('Size:')}      ${(totalSize / (1024 * 1024)).toFixed(1)} MB`);
+        console.log(`  ${chalk.bold('Manifest:')} ${manifestExists ? chalk.green('cached') : chalk.dim('not cached')}`);
+        if (manifestExists) {
+          const stat = fs.statSync(path.join(cacheDir, 'manifest.json'));
+          const age = Date.now() - stat.mtimeMs;
+          const fresh = age < 3600000;
+          console.log(`  ${chalk.bold('Age:')}       ${Math.floor(age / 60000)} min ${fresh ? chalk.green('(fresh)') : chalk.yellow('(stale)')}`);
+        }
+        console.log();
+        break;
+      }
+      case 'clear': {
+        if (!fs.existsSync(cacheDir)) {
+          console.log(chalk.dim('\n  No cache to clear.\n'));
+          return;
+        }
+        const files = fs.readdirSync(cacheDir);
+        let cleared = 0;
+        for (const f of files) {
+          fs.unlinkSync(path.join(cacheDir, f));
+          cleared++;
+        }
+        console.log(chalk.green(`\n  Cleared ${cleared} cached files from ${cacheDir}\n`));
+        break;
+      }
+      default:
+        console.error(chalk.red(`Unknown cache action: ${action}. Use: status, clear`));
+        process.exit(1);
+    }
   });
 
 // MCP Server command
@@ -7296,8 +7557,15 @@ const mcpCmd = program.command('mcp').description('MCP (Model Context Protocol)
 
 mcpCmd.command('start')
   .description('Start the RuVector MCP server')
-  .action(() => {
-    // Execute the mcp-server.js directly
+  .option('-t, --transport <type>', 'Transport type: stdio or sse', 'stdio')
+  .option('-p, --port <number>', 'Port for SSE transport', '8080')
+  .option('--host <host>', 'Host to bind for SSE', '0.0.0.0')
+  .action((opts) => {
+    if (opts.transport === 'sse') {
+      process.env.MCP_TRANSPORT = 'sse';
+      process.env.MCP_PORT = opts.port;
+      process.env.MCP_HOST = opts.host;
+    }
     const mcpServerPath = path.join(__dirname, 'mcp-server.js');
     if (!fs.existsSync(mcpServerPath)) {
       console.error(chalk.red('Error: MCP server not found at'), mcpServerPath);
@@ -7813,6 +8081,98 @@ brainCmd.command('sync [direction]')
     } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
   });
 
+brainCmd.command('page <action> [args...]')
+  .description('Brainpedia page management (list, get, create, update, delete)')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
+  .action(async (action, args, opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
+    try {
+      const client = new piBrain.PiBrainClient(config);
+      let result;
+      switch (action) {
+        case 'list':
+          result = await client.listPages ? client.listPages({ limit: 20 }) : { pages: [], message: 'Brainpedia not yet available on this server' };
+          break;
+        case 'get':
+          if (!args[0]) { console.error(chalk.red('Usage: brain page get <slug>')); process.exit(1); }
+          result = await client.getPage ? client.getPage(args[0]) : { error: 'Brainpedia not yet available' };
+          break;
+        case 'create':
+          if (!args[0]) { console.error(chalk.red('Usage: brain page create <title> [--content <text>]')); process.exit(1); }
+          result = await client.createPage ? client.createPage({ title: args[0], content: opts.content || '' }) : { error: 'Brainpedia not yet available' };
+          break;
+        case 'update':
+          if (!args[0]) { console.error(chalk.red('Usage: brain page update <slug> [--content <text>]')); process.exit(1); }
+          result = await client.updatePage ? client.updatePage(args[0], { content: opts.content || '' }) : { error: 'Brainpedia not yet available' };
+          break;
+        case 'delete':
+          if (!args[0]) { console.error(chalk.red('Usage: brain page delete <slug>')); process.exit(1); }
+          result = await client.deletePage ? client.deletePage(args[0]) : { error: 'Brainpedia not yet available' };
+          break;
+        default:
+          console.error(chalk.red(`Unknown page action: ${action}. Use: list, get, create, update, delete`));
+          process.exit(1);
+      }
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(result, null, 2)); return; }
+      if (result.pages) {
+        console.log(chalk.bold.cyan('\nBrainpedia Pages\n'));
+        result.pages.forEach((p, i) => console.log(`  ${chalk.yellow(i + 1 + '.')} ${chalk.bold(p.title || p.slug)} ${chalk.dim(p.updated || '')}`));
+      } else if (result.title) {
+        console.log(chalk.bold.cyan(`\n${result.title}\n`));
+        if (result.content) console.log(result.content);
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
+  });
+
+brainCmd.command('node <action> [args...]')
+  .description('WASM compute node management (publish, list, status)')
+  .option('--url <url>', 'Brain server URL')
+  .option('--key <key>', 'Pi key')
+  .option('--json', 'Output as JSON')
+  .action(async (action, args, opts) => {
+    const piBrain = await requirePiBrain();
+    const config = getBrainConfig(opts);
+    try {
+      const client = new piBrain.PiBrainClient(config);
+      let result;
+      switch (action) {
+        case 'publish':
+          if (!args[0]) { console.error(chalk.red('Usage: brain node publish <wasm-file>')); process.exit(1); }
+          const wasmPath = path.resolve(args[0]);
+          if (!fs.existsSync(wasmPath)) { console.error(chalk.red(`File not found: ${wasmPath}`)); process.exit(1); }
+          const wasmBytes = fs.readFileSync(wasmPath);
+          result = await client.publishNode ? client.publishNode({ wasm: wasmBytes, name: path.basename(wasmPath, '.wasm') }) : { error: 'WASM node publish not yet available on this server' };
+          break;
+        case 'list':
+          result = await client.listNodes ? client.listNodes({ limit: 20 }) : { nodes: [], message: 'WASM node listing not yet available' };
+          break;
+        case 'status':
+          if (!args[0]) { console.error(chalk.red('Usage: brain node status <node-id>')); process.exit(1); }
+          result = await client.nodeStatus ? client.nodeStatus(args[0]) : { error: 'WASM node status not yet available' };
+          break;
+        default:
+          console.error(chalk.red(`Unknown node action: ${action}. Use: publish, list, status`));
+          process.exit(1);
+      }
+      if (opts.json || !process.stdout.isTTY) { console.log(JSON.stringify(result, null, 2)); return; }
+      if (result.nodes) {
+        console.log(chalk.bold.cyan('\nWASM Compute Nodes\n'));
+        result.nodes.forEach((n, i) => console.log(`  ${chalk.yellow(i + 1 + '.')} ${chalk.bold(n.name || n.id)} ${chalk.dim(n.status || '')}`));
+      } else if (result.id) {
+        console.log(chalk.green(`Published node: ${result.id}`));
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+      console.log();
+    } catch (e) { console.error(chalk.red(`Error: ${e.message}`)); process.exit(1); }
+  });
+
 // ============================================================================
 // Edge Commands — Distributed compute via @ruvector/edge-net
 // ============================================================================
@@ -7934,14 +8294,17 @@ identityCmd.command('show')
     hash.update(piKey);
     const pseudonym = hash.digest('hex');
     const mcpToken = crypto.createHmac('sha256', piKey).update('mcp').digest('hex').slice(0, 32);
+    const edgeKeyBuf = crypto.createHash('sha512').update(piKey).update('edge-net').digest().slice(0, 32);
+    const edgeKey = edgeKeyBuf.toString('hex');
     if (opts.json || !process.stdout.isTTY) {
-      console.log(JSON.stringify({ pseudonym, mcp_token: mcpToken, key_prefix: piKey.slice(0, 8) + '...' }, null, 2));
+      console.log(JSON.stringify({ pseudonym, mcp_token: mcpToken, edge_key: edgeKey, key_prefix: piKey.slice(0, 8) + '...' }, null, 2));
       return;
     }
     console.log(chalk.bold.cyan('\nPi Identity\n'));
     console.log(`  ${chalk.bold('Key:')}        ${piKey.slice(0, 8)}...${piKey.slice(-8)}`);
     console.log(`  ${chalk.bold('Pseudonym:')}  ${chalk.green(pseudonym)}`);
     console.log(`  ${chalk.bold('MCP Token:')} ${chalk.dim(mcpToken)}`);
+    console.log(`  ${chalk.bold('Edge Key:')}  ${chalk.dim(edgeKey)}`);
     console.log();
   });
 

package/bin/mcp-server.js

@@ -363,7 +363,7 @@ class Intelligence {
 const server = new Server(
   {
     name: 'ruvector',
-    version: '0.2.1',
+    version: '0.2.2',
   },
   {
     capabilities: {
@@ -1224,11 +1224,12 @@ const TOOLS = [
   },
   {
     name: 'rvf_examples',
-    description: 'List available example .rvf files with download URLs from the ruvector repository',
+    description: 'List available example .rvf files with download URLs. Supports filtering by name, description, or category.',
     inputSchema: {
       type: 'object',
       properties: {
-        filter: { type: 'string', description: 'Filter examples by name or description substring' }
+        filter: { type: 'string', description: 'Filter examples by name or description substring' },
+        category: { type: 'string', description: 'Filter by category (core, ai, security, compute, lineage, industry, network, integration)' }
       },
       required: []
     }
@@ -3022,31 +3023,85 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'rvf_examples': {
-        const BASE_URL = 'https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output';
-        const examples = [
-          { name: 'basic_store', size: '152 KB', desc: '1,000 vectors, dim 128' },
-          { name: 'semantic_search', size: '755 KB', desc: 'Semantic search with HNSW' },
-          { name: 'rag_pipeline', size: '303 KB', desc: 'RAG pipeline embeddings' },
-          { name: 'agent_memory', size: '32 KB', desc: 'AI agent episodic memory' },
-          { name: 'swarm_knowledge', size: '86 KB', desc: 'Multi-agent knowledge base' },
-          { name: 'self_booting', size: '31 KB', desc: 'Self-booting with kernel' },
-          { name: 'ebpf_accelerator', size: '153 KB', desc: 'eBPF distance accelerator' },
-          { name: 'tee_attestation', size: '102 KB', desc: 'TEE attestation + witnesses' },
-          { name: 'lineage_parent', size: '52 KB', desc: 'COW parent file' },
-          { name: 'lineage_child', size: '26 KB', desc: 'COW child (derived)' },
-          { name: 'claude_code_appliance', size: '17 KB', desc: 'Claude Code appliance' },
-          { name: 'progressive_index', size: '2.5 MB', desc: 'Large-scale HNSW index' },
-        ];
-        let filtered = examples;
+        const os = require('os');
+        const GCS_MANIFEST = 'https://storage.googleapis.com/ruvector-examples/manifest.json';
+        const GITHUB_RAW = 'https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output';
+        const cacheDir = path.join(os.homedir(), '.ruvector', 'examples');
+        const manifestPath = path.join(cacheDir, 'manifest.json');
+
+        let manifest;
+        // Try cache first
+        if (fs.existsSync(manifestPath)) {
+          try {
+            const stat = fs.statSync(manifestPath);
+            if (Date.now() - stat.mtimeMs < 3600000) {
+              manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+            }
+          } catch {}
+        }
+
+        // Fetch from GCS if no fresh cache
+        if (!manifest) {
+          try {
+            const resp = await fetch(GCS_MANIFEST);
+            if (resp.ok) {
+              manifest = await resp.json();
+              try {
+                fs.mkdirSync(cacheDir, { recursive: true });
+                fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+              } catch {}
+            }
+          } catch {}
+        }
+
+        // Fallback to hardcoded
+        if (!manifest) {
+          manifest = {
+            version: 'builtin',
+            base_url: GITHUB_RAW,
+            examples: [
+              { name: 'basic_store', size_human: '152 KB', description: '1,000 vectors, dim 128', category: 'core' },
+              { name: 'semantic_search', size_human: '755 KB', description: 'Semantic search with HNSW', category: 'core' },
+              { name: 'rag_pipeline', size_human: '303 KB', description: 'RAG pipeline embeddings', category: 'core' },
+              { name: 'agent_memory', size_human: '32 KB', description: 'AI agent episodic memory', category: 'ai' },
+              { name: 'swarm_knowledge', size_human: '86 KB', description: 'Multi-agent knowledge base', category: 'ai' },
+              { name: 'self_booting', size_human: '31 KB', description: 'Self-booting with kernel', category: 'compute' },
+              { name: 'ebpf_accelerator', size_human: '153 KB', description: 'eBPF distance accelerator', category: 'compute' },
+              { name: 'tee_attestation', size_human: '102 KB', description: 'TEE attestation + witnesses', category: 'security' },
+              { name: 'claude_code_appliance', size_human: '17 KB', description: 'Claude Code appliance', category: 'integration' },
+              { name: 'lineage_parent', size_human: '52 KB', description: 'COW parent file', category: 'lineage' },
+              { name: 'financial_signals', size_human: '202 KB', description: 'Financial signals', category: 'industry' },
+              { name: 'progressive_index', size_human: '2.5 MB', description: 'Large-scale HNSW index', category: 'core' },
+            ]
+          };
+        }
+
+        let examples = manifest.examples || [];
+        const baseUrl = manifest.base_url || GITHUB_RAW;
+
         if (args.filter) {
           const f = args.filter.toLowerCase();
-          filtered = examples.filter(e => e.name.includes(f) || e.desc.toLowerCase().includes(f));
+          examples = examples.filter(e =>
+            e.name.includes(f) ||
+            (e.description || '').toLowerCase().includes(f) ||
+            (e.category || '').includes(f)
+          );
+        }
+
+        if (args.category) {
+          examples = examples.filter(e => e.category === args.category);
         }
+
         return { content: [{ type: 'text', text: JSON.stringify({
           success: true,
-          total: 45,
-          shown: filtered.length,
-          examples: filtered.map(e => ({ ...e, url: `${BASE_URL}/${e.name}.rvf` })),
+          version: manifest.version,
+          total: (manifest.examples || []).length,
+          shown: examples.length,
+          examples: examples.map(e => ({
+            ...e,
+            url: `${baseUrl}/${e.name}.rvf`
+          })),
+          categories: manifest.categories || {},
           catalog: 'https://github.com/ruvnet/ruvector/tree/main/examples/rvf/output'
         }, null, 2) }] };
       }
@@ -3322,9 +3377,173 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 
 // Start server
 async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error('RuVector MCP server running on stdio');
+  const transportType = process.env.MCP_TRANSPORT || 'stdio';
+
+  if (transportType === 'sse') {
+    const http = require('http');
+    const crypto = require('crypto');
+    const port = parseInt(process.env.MCP_PORT || '8080', 10);
+    const host = process.env.MCP_HOST || '0.0.0.0';
+
+    // SSE MCP Transport Implementation
+    // MCP over SSE uses:
+    //   GET /sse - SSE stream for server->client messages
+    //   POST /message - client->server JSON-RPC messages
+
+    const sessions = new Map();
+
+    const httpServer = http.createServer(async (req, res) => {
+      // CORS headers
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url, `http://${req.headers.host}`);
+
+      if (req.method === 'GET' && url.pathname === '/sse') {
+        // SSE endpoint - establish persistent connection
+        const sessionId = crypto.randomUUID();
+
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          'Connection': 'keep-alive',
+        });
+
+        // Send endpoint event so client knows where to POST
+        const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+        const messageUrl = `http://${displayHost}:${port}/message?sessionId=${sessionId}`;
+        res.write(`event: endpoint\ndata: ${messageUrl}\n\n`);
+
+        // Store session
+        sessions.set(sessionId, {
+          res,
+          messageQueue: [],
+        });
+
+        // Create a custom transport for this session
+        const sessionTransport = {
+          _onMessage: null,
+          _onClose: null,
+          _onError: null,
+          _started: false,
+
+          async start() {
+            this._started = true;
+          },
+
+          async close() {
+            sessions.delete(sessionId);
+            if (!res.writableEnded) {
+              res.end();
+            }
+          },
+
+          async send(message) {
+            if (!res.writableEnded) {
+              res.write(`event: message\ndata: ${JSON.stringify(message)}\n\n`);
+            }
+          },
+
+          set onmessage(handler) { this._onMessage = handler; },
+          get onmessage() { return this._onMessage; },
+          set onclose(handler) { this._onClose = handler; },
+          get onclose() { return this._onClose; },
+          set onerror(handler) { this._onError = handler; },
+          get onerror() { return this._onError; },
+        };
+
+        sessions.get(sessionId).transport = sessionTransport;
+
+        // Connect server to this transport
+        await server.connect(sessionTransport);
+
+        // Process any queued messages
+        const session = sessions.get(sessionId);
+        if (session) {
+          for (const msg of session.messageQueue) {
+            if (sessionTransport._onMessage) {
+              sessionTransport._onMessage(msg);
+            }
+          }
+          session.messageQueue = [];
+        }
+
+        // Handle disconnect
+        req.on('close', () => {
+          sessions.delete(sessionId);
+          if (sessionTransport._onClose) {
+            sessionTransport._onClose();
+          }
+        });
+
+      } else if (req.method === 'POST' && url.pathname === '/message') {
+        // Message endpoint - receive client JSON-RPC messages
+        const sessionId = url.searchParams.get('sessionId');
+        const session = sessions.get(sessionId);
+
+        if (!session) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Session not found' }));
+          return;
+        }
+
+        let body = '';
+        req.on('data', chunk => { body += chunk; });
+        req.on('end', () => {
+          try {
+            const message = JSON.parse(body);
+
+            if (session.transport && session.transport._onMessage) {
+              session.transport._onMessage(message);
+            } else {
+              session.messageQueue.push(message);
+            }
+
+            res.writeHead(202, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'accepted' }));
+          } catch (e) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          }
+        });
+
+      } else if (req.method === 'GET' && url.pathname === '/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          status: 'ok',
+          transport: 'sse',
+          sessions: sessions.size,
+          tools: 91,
+          version: '0.2.2'
+        }));
+
+      } else {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found. Use GET /sse for SSE stream, POST /message for JSON-RPC, GET /health for status.' }));
+      }
+    });
+
+    httpServer.listen(port, host, () => {
+      const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+      console.error(`RuVector MCP server running on SSE at http://${host}:${port}`);
+      console.error(`  SSE endpoint:     http://${displayHost}:${port}/sse`);
+      console.error(`  Message endpoint: http://${displayHost}:${port}/message`);
+      console.error(`  Health check:     http://${displayHost}:${port}/health`);
+    });
+
+  } else {
+    // Default: stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('RuVector MCP server running on stdio');
+  }
 }
 
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvector",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "High-performance vector database for Node.js with automatic native/WASM fallback",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",