vektor-slipstream 1.4.4 → 2.0.0

package/cortex.js

@@ -1,221 +0,0 @@
-/**
- * cloak_cortex.js
- * File anatomy scanner — builds a token-aware project index in Vektor's entity graph.
- * Called once on init, then on significant file changes (not per-session).
- *
- * Writes to Vektor as entity nodes:
- *   "file:src/server.ts | purpose: Express HTTP server | tokens: ~520 | last_scanned: <iso>"
- *
- * Architecture: CLOAK layer → Vektor entity graph (MAGMA §3.2)
- * Research: MAGMA arXiv:2601.03236, OpenWolf anatomy pattern
- */
-
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-
-// ---------------------------------------------------------------------------
-// Token estimation (OpenWolf ratios — accurate to ±15%)
-// ---------------------------------------------------------------------------
-const TOKEN_RATIOS = {
-  code : 3.5,   // .js .ts .py .go .rs etc.
-  prose: 4.0,   // .md .txt .rst
-  mixed: 3.75,  // .json .yaml .toml .html
-};
-
-const CODE_EXTS  = new Set(['.js','.ts','.jsx','.tsx','.py','.go','.rs','.rb','.java','.c','.cpp','.cs','.php','.swift','.kt']);
-const PROSE_EXTS = new Set(['.md','.txt','.rst','.mdx']);
-const SKIP_DIRS  = new Set(['node_modules','.git','dist','build','.next','__pycache__','.cache','coverage','.wolf']);
-const SKIP_FILES = new Set(['.DS_Store','package-lock.json','yarn.lock','pnpm-lock.yaml']);
-
-function estimateTokens(filePath, bytes) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (CODE_EXTS.has(ext))  return Math.round(bytes / TOKEN_RATIOS.code);
-  if (PROSE_EXTS.has(ext)) return Math.round(bytes / TOKEN_RATIOS.prose);
-  return Math.round(bytes / TOKEN_RATIOS.mixed);
-}
-
-// ---------------------------------------------------------------------------
-// File scanner
-// ---------------------------------------------------------------------------
-function scanDirectory(dirPath, results = [], rootPath = dirPath, visited = new Set()) {
-  // Only resolve realpath for symlinks — not for every directory.
-  // Running fs.realpathSync on all directories is ~4x slower on large codebases
-  // (especially Windows NTFS) and the visited Set grows unnecessarily large.
-  // Normal directories cannot create cycles; only symlinks can.
-
-  let entries;
-  try {
-    entries = fs.readdirSync(dirPath, { withFileTypes: true });
-  } catch {
-    return results;
-  }
-
-  for (const entry of entries) {
-    if (SKIP_FILES.has(entry.name)) continue;
-
-    const fullPath = path.join(dirPath, entry.name);
-    const relPath  = path.relative(rootPath, fullPath);
-
-    if (entry.isSymbolicLink()) {
-      // Symlinks only: resolve real path and check for cycles
-      let realPath;
-      try { realPath = fs.realpathSync(fullPath); } catch { continue; }
-
-      if (visited.has(realPath)) continue; // cycle detected — skip
-
-      let stat;
-      try { stat = fs.statSync(fullPath); } catch { continue; }
-
-      if (stat.isDirectory()) {
-        if (!SKIP_DIRS.has(entry.name)) {
-          visited.add(realPath); // mark before recursing
-          scanDirectory(fullPath, results, rootPath, visited);
-        }
-      } else if (stat.isFile()) {
-        const ext    = path.extname(entry.name).toLowerCase();
-        const tokens = estimateTokens(fullPath, stat.size);
-        results.push({ relPath, ext, tokens, mtime: stat.mtimeMs, bytes: stat.size });
-      }
-      continue;
-    }
-
-    if (entry.isDirectory()) {
-      // Normal directory — no realpathSync needed, no cycle possible
-      if (!SKIP_DIRS.has(entry.name)) {
-        scanDirectory(fullPath, results, rootPath, visited);
-      }
-      continue;
-    }
-
-    if (!entry.isFile()) continue;
-
-    let stat;
-    try { stat = fs.statSync(fullPath); } catch { continue; }
-
-    const ext    = path.extname(entry.name).toLowerCase();
-    const tokens = estimateTokens(fullPath, stat.size);
-    const mtime  = stat.mtimeMs;
-
-    results.push({ relPath, ext, tokens, mtime, bytes: stat.size });
-  }
-
-  return results;
-}
-
-// isSymlinkDir removed — logic inlined above for clarity
-
-// ---------------------------------------------------------------------------
-// Build Vektor memory strings for entity graph
-// ---------------------------------------------------------------------------
-function buildEntityString(file, projectName) {
-  return [
-    `[CLOAK_CORTEX] project:${projectName}`,
-    `file:${file.relPath}`,
-    `tokens:~${file.tokens}`,
-    `size:${file.bytes}b`,
-    `last_modified:${new Date(file.mtime).toISOString()}`,
-  ].join(' | ');
-}
-
-// ---------------------------------------------------------------------------
-// Load/save scan cache (.wolf/cortex-cache.json) to avoid rescanning unchanged files
-// ---------------------------------------------------------------------------
-function loadCache(projectPath) {
-  const cachePath = path.join(projectPath, '.wolf', 'cortex-cache.json');
-  try {
-    return JSON.parse(fs.readFileSync(cachePath, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-function saveCache(projectPath, cache) {
-  const wolfDir = path.join(projectPath, '.wolf');
-  if (!fs.existsSync(wolfDir)) fs.mkdirSync(wolfDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(wolfDir, 'cortex-cache.json'),
-    JSON.stringify(cache, null, 2)
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Main export
-// ---------------------------------------------------------------------------
-
-/**
- * runCortex({ projectPath, memory, force })
- *
- * @param {string}  projectPath  - Absolute path to project root
- * @param {object}  memory       - Vektor memory instance (vektor-slipstream)
- * @param {boolean} force        - Re-scan all files even if unchanged
- * @returns {object}             - { scanned, skipped, written, totalTokens, anatomy }
- */
-async function runCortex({ projectPath, memory, force = false } = {}) {
-  if (!projectPath) throw new Error('cloak_cortex: projectPath is required');
-  if (!memory)      throw new Error('cloak_cortex: memory instance is required');
-
-  const projectName = path.basename(projectPath);
-  const cache       = force ? {} : loadCache(projectPath);
-  const files       = scanDirectory(projectPath);
-
-  const stats = { scanned: 0, skipped: 0, written: 0, totalTokens: 0 };
-  const anatomy = [];
-
-  for (const file of files) {
-    stats.totalTokens += file.tokens;
-    anatomy.push({ path: file.relPath, tokens: file.tokens });
-
-    // Skip if file hasn't changed since last scan
-    const cacheKey = file.relPath;
-    if (!force && cache[cacheKey] && cache[cacheKey].mtime === file.mtime) {
-      stats.skipped++;
-      continue;
-    }
-
-    stats.scanned++;
-
-    const entityStr = buildEntityString(file, projectName);
-
-    try {
-      await memory.remember(entityStr);
-      cache[cacheKey] = { mtime: file.mtime, tokens: file.tokens };
-      stats.written++;
-    } catch (err) {
-      console.error(`[cloak_cortex] Failed to write entity for ${file.relPath}:`, err.message);
-    }
-  }
-
-  // Write project-level summary node
-  const summaryStr = [
-    `[CLOAK_CORTEX_SUMMARY] project:${projectName}`,
-    `total_files:${files.length}`,
-    `total_tokens:~${stats.totalTokens}`,
-    `scanned_at:${new Date().toISOString()}`,
-  ].join(' | ');
-
-  try {
-    await memory.remember(summaryStr);
-  } catch (err) {
-    console.error('[cloak_cortex] Failed to write summary node:', err.message);
-  }
-
-  saveCache(projectPath, cache);
-
-  return { ...stats, anatomy };
-}
-
-/**
- * getAnatomy({ projectPath })
- * Returns the cached anatomy without hitting Vektor — for fast pre-read hints.
- */
-function getAnatomy(projectPath) {
-  const cache = loadCache(projectPath);
-  return Object.entries(cache).map(([relPath, data]) => ({
-    path: relPath,
-    tokens: data.tokens,
-  })).sort((a, b) => b.tokens - a.tokens);
-}
-
-module.exports = { runCortex, getAnatomy, scanDirectory, estimateTokens };

package/detect-hardware.js

@@ -1,181 +0,0 @@
-'use strict';
-
-/**
- * VEKTOR SLIPSTREAM
- * detect-hardware.js — Execution Provider Probe
- * ─────────────────────────────────────────────────────────────────────────────
- * Probes the host system for hardware acceleration capabilities WITHOUT
- * attempting to load any native binaries. Uses only OS-level CLI tools that
- * ship with the relevant drivers/OS — so this file itself has zero native deps
- * and zero risk of crashing the terminal.
- *
- * Returns: 'cuda' | 'coreml' | 'cpu'
- * Execution time: < 10ms (CLI probe only, no driver load)
- *
- * Consumed by:
- *   - postinstall.js   → to decide which onnxruntime variant to install
- *   - slipstream.js    → to decide which EP to pass to InferenceSession.create()
- * ─────────────────────────────────────────────────────────────────────────────
- */
-
-const os   = require('os');
-const { execSync } = require('child_process');
-
-// ─── Constants ───────────────────────────────────────────────────────────────
-
-const EP = Object.freeze({
-  CUDA   : 'cuda',
-  COREML : 'coreml',
-  CPU    : 'cpu',
-});
-
-// ─── Probe Helpers ───────────────────────────────────────────────────────────
-
-/**
- * macOS: Check for Apple Silicon via sysctl.
- * sysctl is a native macOS syscall utility — always present, zero install.
- * Returns 'coreml' on M-series chips, 'cpu' on Intel Macs.
- */
-function probeDarwin() {
-  try {
-    const cpuBrand = execSync(
-      'sysctl -n machdep.cpu.brand_string 2>/dev/null',
-      { stdio: 'pipe', timeout: 2000 }
-    ).toString().trim();
-
-    if (cpuBrand.includes('Apple')) {
-      return EP.COREML;
-    }
-  } catch (_) {
-    // sysctl unavailable or returned non-zero — safe fallback
-  }
-  return EP.CPU;
-}
-
-/**
- * Linux / Windows: Check for NVIDIA GPU via nvidia-smi.
- * nvidia-smi ships with the NVIDIA driver package.
- * If it exits 0, the GPU is present AND the driver is loaded — both required.
- * stdio: 'ignore' suppresses the full nvidia-smi output table.
- * timeout: 3000ms prevents hangs on misconfigured driver environments.
- */
-function probeNvidia() {
-  try {
-    execSync('nvidia-smi', { stdio: 'ignore', timeout: 3000 });
-    return EP.CUDA;
-  } catch (_) {
-    // nvidia-smi not found, or GPU present but driver not loaded
-    return EP.CPU;
-  }
-}
-
-// ─── Main Export ─────────────────────────────────────────────────────────────
-
-/**
- * detectHardware()
- *
- * Synchronous hardware probe. Returns the highest-performance execution
- * provider available on the current machine. Decision tree:
- *
- *   macOS + Apple Silicon  →  'coreml'   (Neural Engine via CoreML)
- *   macOS + Intel          →  'cpu'      (no CoreML acceleration)
- *   Linux/Win + NVIDIA     →  'cuda'     (GPU via CUDA)
- *   Linux/Win + no GPU     →  'cpu'      (optimised WASM SIMD path)
- *   Any other platform     →  'cpu'      (safe universal fallback)
- *
- * @returns {'cuda'|'coreml'|'cpu'}
- */
-function detectHardware() {
-  const platform = os.platform();
-
-  switch (platform) {
-    case 'darwin':
-      return probeDarwin();
-
-    case 'linux':
-    case 'win32':
-      return probeNvidia();
-
-    default:
-      // FreeBSD, Android, unknown — CPU is always safe
-      return EP.CPU;
-  }
-}
-
-/**
- * detectHardwareAsync()
- *
- * Non-blocking wrapper. Runs the probe in a setImmediate tick so it doesn't
- * stall the event loop during module initialisation. Preferred for use inside
- * slipstream.js createMemory() boot sequence.
- *
- * @returns {Promise<'cuda'|'coreml'|'cpu'>}
- */
-function detectHardwareAsync() {
-  return new Promise((resolve) => {
-    setImmediate(() => resolve(detectHardware()));
-  });
-}
-
-/**
- * getEPLabel()
- * Human-readable label for the audit log banner.
- *
- * @param {'cuda'|'coreml'|'cpu'} ep
- * @returns {string}
- */
-function getEPLabel(ep) {
-  const labels = {
-    [EP.CUDA]   : 'CUDA (NVIDIA GPU)',
-    [EP.COREML] : 'CoreML (Apple Neural Engine)',
-    [EP.CPU]    : 'CPU (WASM SIMD)',
-  };
-  return labels[ep] ?? 'CPU (WASM SIMD)';
-}
-
-module.exports = {
-  detectHardware,
-  detectHardwareAsync,
-  getEPLabel,
-  EP, // export constants so consumers don't hardcode strings
-};
-
-// ─── CLI Self-Test ───────────────────────────────────────────────────────────
-// Run directly to validate the probe on any target machine:
-//   node detect-hardware.js
-//
-// Expected outputs:
-//   Apple M-series  →  [SLIPSTREAM PROBE] EP: CoreML (Apple Neural Engine) ✓
-//   NVIDIA machine  →  [SLIPSTREAM PROBE] EP: CUDA (NVIDIA GPU) ✓
-//   Any other       →  [SLIPSTREAM PROBE] EP: CPU (WASM SIMD) ✓
-
-if (require.main === module) {
-  const start = Date.now();
-  const ep    = detectHardware();
-  const ms    = Date.now() - start;
-
-  const icon = ep === EP.CPU ? '⚙️ ' : '🚀';
-
-  console.log('');
-  console.log('  ╔══════════════════════════════════════════╗');
-  console.log('  ║       VEKTOR SLIPSTREAM — PROBE          ║');
-  console.log('  ╚══════════════════════════════════════════╝');
-  console.log('');
-  console.log(`  ${icon} EP:       ${getEPLabel(ep)}`);
-  console.log(`  ⏱  Probe:    ${ms}ms`);
-  console.log(`  🖥  Platform: ${os.platform()} / ${os.arch()}`);
-  console.log(`  💾  RAM:      ${(os.totalmem() / 1024 ** 3).toFixed(1)} GB`);
-  console.log('');
-
-  if (ep === EP.CPU) {
-    console.log('  ℹ️  No GPU acceleration detected.');
-    console.log('  Slipstream will run on optimised CPU (WASM SIMD).');
-    console.log('  For CUDA: ensure nvidia-smi is accessible in PATH.');
-    console.log('  For CoreML: Apple Silicon Mac required.');
-  } else {
-    console.log(`  ✓ Hardware acceleration confirmed. Slipstream will`);
-    console.log(`    engage ${getEPLabel(ep)} for sub-12ms embeddings.`);
-  }
-
-  console.log('');
-}

package/entity-resolver.js

@@ -1,298 +0,0 @@
-/**
- * VEKTOR EntityResolver
- * Canonical entity resolution layer for vektor-slipstream.
- * Sits between your app and memory.remember() — normalises
- * entity references before they hit the MAGMA graph.
- *
- * Usage:
- *   const resolver = new EntityResolver(memory, db);
- *   await resolver.remember('the CFO approved the budget');
- *   // → stored as "Sarah Chen approved the budget" (entity_0042)
- */
-
-import Database from 'better-sqlite3';
-
-export class EntityResolver {
-  /**
-   * @param {object} memory  - vektor-slipstream memory instance
-   * @param {string} dbPath  - path to your SQLite db (same one vektor uses, or separate)
-   */
-  constructor(memory, dbPath = './vektor-entities.db') {
-    this.memory = memory;
-    this.db = new Database(dbPath);
-    this._init();
-  }
-
-  // ─── Schema ────────────────────────────────────────────────────────────────
-
-  _init() {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS entities (
-        id          TEXT PRIMARY KEY,
-        canonical   TEXT NOT NULL,
-        type        TEXT DEFAULT 'unknown',
-        confidence  REAL DEFAULT 1.0,
-        created_at  INTEGER DEFAULT (unixepoch()),
-        updated_at  INTEGER DEFAULT (unixepoch())
-      );
-
-      CREATE TABLE IF NOT EXISTS aliases (
-        alias       TEXT PRIMARY KEY,
-        entity_id   TEXT NOT NULL,
-        source      TEXT DEFAULT 'manual',
-        created_at  INTEGER DEFAULT (unixepoch()),
-        FOREIGN KEY (entity_id) REFERENCES entities(id)
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_aliases_entity ON aliases(entity_id);
-    `);
-  }
-
-  // ─── Public API ────────────────────────────────────────────────────────────
-
-  /**
-   * Drop-in replacement for memory.remember().
-   * Resolves entity references in text before storing.
-   *
-   * @param {string} text     - raw input text
-   * @param {object} opts     - passed through to memory.remember()
-   * @returns {object}        - { normalised, entityIds, result }
-   */
-  async remember(text, opts = {}) {
-    const { normalised, entityIds } = await this._resolveText(text);
-    const result = await this.memory.remember(normalised, {
-      ...opts,
-      metadata: { ...opts.metadata, entityIds }
-    });
-    return { normalised, entityIds, result };
-  }
-
-  /**
-   * Resolve a single reference string to a canonical entity.
-   * Returns null if no match found above threshold.
-   *
-   * @param {string} ref      - e.g. "the CFO", "Sarah", "S. Chen"
-   * @param {number} threshold - similarity threshold (default 0.88)
-   * @returns {object|null}   - { id, canonical, type } or null
-   */
-  async resolve(ref, threshold = 0.88) {
-    const normalised = ref.trim().toLowerCase();
-
-    // 1. Exact alias lookup (fast path)
-    const exact = this.db
-      .prepare('SELECT e.* FROM entities e JOIN aliases a ON a.entity_id = e.id WHERE lower(a.alias) = ?')
-      .get(normalised);
-    if (exact) return exact;
-
-    // 2. Fuzzy alias lookup (handles minor typos/punctuation)
-    const fuzzy = this._fuzzyAliasLookup(normalised);
-    if (fuzzy) return fuzzy;
-
-    // 3. Semantic similarity via VEKTOR recall
-    const candidates = await this.memory.recall(`entity: ${ref}`, 5);
-    for (const c of candidates) {
-      if (c.score >= threshold && c.metadata?.entityId) {
-        const entity = this.getEntity(c.metadata.entityId);
-        if (entity) {
-          // Auto-learn this alias
-          this.addAlias(ref, entity.id, 'auto');
-          return entity;
-        }
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Register a new canonical entity.
-   *
-   * @param {string} canonical  - e.g. "Sarah Chen"
-   * @param {string} type       - person | org | project | concept
-   * @param {string[]} aliases  - known aliases: ["Sarah", "the CFO", "S. Chen"]
-   * @returns {string}          - entity id
-   */
-  addEntity(canonical, type = 'unknown', aliases = []) {
-    const id = `entity_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
-
-    this.db.prepare(`
-      INSERT INTO entities (id, canonical, type)
-      VALUES (?, ?, ?)
-      ON CONFLICT(id) DO NOTHING
-    `).run(id, canonical, type);
-
-    // Always register canonical name as an alias
-    const allAliases = [canonical, ...aliases];
-    for (const alias of allAliases) {
-      this.addAlias(alias, id, 'manual');
-    }
-
-    return id;
-  }
-
-  /**
-   * Add a new alias to an existing entity.
-   */
-  addAlias(alias, entityId, source = 'manual') {
-    this.db.prepare(`
-      INSERT INTO aliases (alias, entity_id, source)
-      VALUES (?, ?, ?)
-      ON CONFLICT(alias) DO UPDATE SET entity_id = excluded.entity_id
-    `).run(alias.trim(), entityId, source);
-  }
-
-  /**
-   * Get entity by id.
-   */
-  getEntity(id) {
-    return this.db.prepare('SELECT * FROM entities WHERE id = ?').get(id) || null;
-  }
-
-  /**
-   * List all entities (for debugging / UI).
-   */
-  listEntities() {
-    const entities = this.db.prepare('SELECT * FROM entities ORDER BY canonical').all();
-    return entities.map(e => ({
-      ...e,
-      aliases: this.db
-        .prepare('SELECT alias, source FROM aliases WHERE entity_id = ?')
-        .all(e.id)
-        .map(a => a.alias)
-    }));
-  }
-
-  /**
-   * Merge two entities — keeps targetId, moves all aliases.
-   * Use when you discover two entity nodes are the same person/thing.
-   */
-  mergeEntities(sourceId, targetId) {
-    this.db.prepare('UPDATE aliases SET entity_id = ? WHERE entity_id = ?').run(targetId, sourceId);
-    this.db.prepare('DELETE FROM entities WHERE id = ?').run(sourceId);
-    return this.getEntity(targetId);
-  }
-
-  /**
-   * Scan memory graph for likely duplicate entities using
-   * recall similarity — returns candidate pairs for review.
-   *
-   * @param {number} threshold - 0.88 is a good starting point
-   */
-  async findDuplicateCandidates(threshold = 0.88) {
-    const entities = this.listEntities();
-    const candidates = [];
-
-    for (const entity of entities) {
-      const results = await this.memory.recall(`entity: ${entity.canonical}`, 5);
-      for (const r of results) {
-        if (
-          r.score >= threshold &&
-          r.metadata?.entityId &&
-          r.metadata.entityId !== entity.id
-        ) {
-          candidates.push({
-            entity_a: entity,
-            entity_b: this.getEntity(r.metadata.entityId),
-            score: r.score
-          });
-        }
-      }
-    }
-
-    // Deduplicate candidate pairs
-    return candidates.filter((c, i, arr) =>
-      c.entity_b &&
-      arr.findIndex(x =>
-        (x.entity_a.id === c.entity_b.id && x.entity_b?.id === c.entity_a.id)
-      ) < i
-    );
-  }
-
-  // ─── Private ───────────────────────────────────────────────────────────────
-
-  /**
-   * Scan text for known entity aliases and replace with canonical names.
-   * Returns normalised text and a list of resolved entity IDs.
-   */
-  async _resolveText(text) {
-    const allAliases = this.db
-      .prepare('SELECT alias, entity_id FROM aliases ORDER BY length(alias) DESC')
-      .all();
-
-    let normalised = text;
-    const entityIds = new Set();
-
-    for (const { alias, entity_id } of allAliases) {
-      const regex = new RegExp(`\\b${this._escapeRegex(alias)}\\b`, 'gi');
-      if (regex.test(normalised)) {
-        const entity = this.getEntity(entity_id);
-        if (entity) {
-          normalised = normalised.replace(regex, entity.canonical);
-          entityIds.add(entity_id);
-        }
-      }
-    }
-
-    return { normalised, entityIds: [...entityIds] };
-  }
-
-  _fuzzyAliasLookup(input) {
-    const allAliases = this.db
-      .prepare('SELECT alias, entity_id FROM aliases')
-      .all();
-
-    for (const { alias, entity_id } of allAliases) {
-      if (this._levenshtein(input, alias.toLowerCase()) <= 2) {
-        return this.getEntity(entity_id);
-      }
-    }
-    return null;
-  }
-
-  _levenshtein(a, b) {
-    const m = a.length, n = b.length;
-    const dp = Array.from({ length: m + 1 }, (_, i) =>
-      Array.from({ length: n + 1 }, (_, j) => i === 0 ? j : j === 0 ? i : 0)
-    );
-    for (let i = 1; i <= m; i++)
-      for (let j = 1; j <= n; j++)
-        dp[i][j] = a[i-1] === b[j-1]
-          ? dp[i-1][j-1]
-          : 1 + Math.min(dp[i-1][j], dp[i][j-1], dp[i-1][j-1]);
-    return dp[m][n];
-  }
-
-  _escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  }
-}
-
-
-// ─── Example usage ───────────────────────────────────────────────────────────
-//
-// import { createMemory } from 'vektor-slipstream';
-// import { EntityResolver } from './entity-resolver.js';
-//
-// const memory = await createMemory({ provider: 'gemini', apiKey, agentId: 'my-agent' });
-// const resolver = new EntityResolver(memory);
-//
-// // Register known entities once (or load from a config file)
-// resolver.addEntity('Sarah Chen', 'person', ['Sarah', 'the CFO', 'S. Chen', 'Ms Chen']);
-// resolver.addEntity('VEKTOR Memory', 'org', ['Vektor', 'VEKTOR', 'the company']);
-// resolver.addEntity('Project Atlas', 'project', ['Atlas', 'the project', 'our roadmap']);
-//
-// // Drop-in for memory.remember() — resolves aliases automatically
-// await resolver.remember('the CFO approved Project Atlas budget');
-// // → stored as "Sarah Chen approved Project Atlas budget"
-// // → entityIds: ['entity_...sarah', 'entity_...atlas']
-//
-// // Resolve a reference without storing
-// const entity = await resolver.resolve('S. Chen');
-// console.log(entity.canonical); // → "Sarah Chen"
-//
-// // Find likely duplicate nodes for manual review
-// const dupes = await resolver.findDuplicateCandidates(0.88);
-// console.log(dupes); // → [{ entity_a, entity_b, score }]
-//
-// // Merge duplicates once confirmed
-// resolver.mergeEntities('entity_old_id', 'entity_keep_id');