vektor-slipstream 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vektor-slipstream",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Hardware-accelerated persistent memory for AI agents. Local-first, zero cloud dependency, $0 embedding cost.",
   "main": "slipstream-core.js",
   "exports": {
@@ -51,6 +51,7 @@
     "detect-hardware.js",
     "vektor-licence.js",
     "sovereign.js",
+    "visualize.js",
     "TENETS.md",
     "models/model_quantized.onnx",
     "examples/",

package/slipstream-core.js

@@ -23,6 +23,7 @@
 const path = require('path');
 const fs   = require('fs');
 const { validateLicence } = require('./vektor-licence');
+const { startVisualizer } = require('./visualize');
 
 // ─── SQLite loader — better-sqlite3 with clear error ─────────────────────────
 function loadSQLite(dbPath) {
@@ -623,6 +624,13 @@ class SlipstreamMemory {
   remove(id) {
     try { this.db.prepare("DELETE FROM memories WHERE id=? AND agent_id=?").run(id, this.agentId); } catch (_) {}
   }
+
+  // ── visualize(opts) ───────────────────────────────────────────────────────
+  // Opens a local D3 graph in the browser showing the agent's memory graph.
+  // Returns the server instance so the caller can close it programmatically.
+  async visualize(opts = {}) {
+    return startVisualizer(this, opts);
+  }
 }
 
 // ─── Boot Banner ──────────────────────────────────────────────────────────────

package/vektor-licence.js

@@ -2,39 +2,43 @@
 /**
  * vektor-licence.js — Polar Licence Enforcement
  * ─────────────────────────────────────────────────────────────────────────────
- * Validates a Polar licence key before allowing createMemory() to proceed.
+ * Validates a Polar licence key and enforces 3-machine activation limit.
  *
  * Flow:
  *   1. Customer calls createMemory({ licenceKey: 'VEKTOR-XXXX-...' })
- *   2. We check ~/.vektor/licence.json for a cached validation (30-day TTL)
- *   3. If cache miss or expired → call Polar validate API
- *   4. Valid → cache result, proceed
- *   5. Invalid/missing → throw with purchase link
+ *   2. Check ~/.vektor/licence.json for cached activation (30-day TTL)
+ *   3. Cache hit + activation_id present → proceed silently
+ *   4. Cache miss → call Polar /activate (counts against 3-machine limit)
+ *   5. Success → cache activation_id + proceed
+ *   6. Limit reached → clear error with deactivation instructions
+ *   7. Invalid key → throw with purchase link
  *
- * Polar validate endpoint requires no auth token — safe for client-side use.
+ * Machine deactivation (free up a slot):
+ *   node -e "require('vektor-slipstream/vektor-licence').deactivateMachine('VEKTOR-XXXX')"
+ *   Or customer manages activations at: https://polar.sh
  * ─────────────────────────────────────────────────────────────────────────────
  */
 
-const fs   = require('fs');
-const path = require('path');
-const os   = require('os');
+const fs     = require('fs');
+const path   = require('path');
+const os     = require('os');
 const crypto = require('crypto');
 
 // ── Config ────────────────────────────────────────────────────────────────────
-// Replace POLAR_ORG_ID with your actual Polar organisation ID from
-// polar.sh → Settings → Organisation ID
 
-const POLAR_ORG_ID    = 'a922049c-3049-41e8-9b20-b18890576b6f';
-const POLAR_API       = 'https://api.polar.sh/v1/customer-portal/license-keys/validate';
-const CACHE_TTL_MS    = 30 * 24 * 60 * 60 * 1000; // 30 days
-const CACHE_DIR       = path.join(os.homedir(), '.vektor');
-const CACHE_FILE      = path.join(CACHE_DIR, 'licence.json');
-const PURCHASE_URL    = 'https://vektormemory.com/#pricing';
+const POLAR_ORG_ID     = 'a922049c-3049-41e8-9b20-b18890576b6f';
+const POLAR_VALIDATE   = 'https://api.polar.sh/v1/customer-portal/license-keys/validate';
+const POLAR_ACTIVATE   = 'https://api.polar.sh/v1/customer-portal/license-keys/activate';
+const POLAR_DEACTIVATE = 'https://api.polar.sh/v1/customer-portal/license-keys/deactivate';
+const CACHE_TTL_MS     = 30 * 24 * 60 * 60 * 1000; // 30 days
+const CACHE_DIR        = path.join(os.homedir(), '.vektor');
+const CACHE_FILE       = path.join(CACHE_DIR, 'licence.json');
+const PURCHASE_URL     = 'https://vektormemory.com/#pricing';
+const MACHINE_LABEL    = `${os.hostname()} (${os.platform()}/${os.arch()})`;
 
 // ── Cache helpers ─────────────────────────────────────────────────────────────
 
 function _cacheKey(licenceKey) {
-  // Hash the key so we don't store it in plaintext
   return crypto.createHash('sha256').update(licenceKey).digest('hex').slice(0, 16);
 }
 
@@ -58,134 +62,247 @@ function _getCached(licenceKey) {
   const cache = _readCache();
   const entry = cache[_cacheKey(licenceKey)];
   if (!entry) return null;
-  if (Date.now() - entry.cached_at > CACHE_TTL_MS) return null; // expired
+  if (Date.now() - entry.cached_at > CACHE_TTL_MS) return null;
   return entry;
 }
 
-// ── Polar validation ──────────────────────────────────────────────────────────
+function _clearCache(licenceKey) {
+  try {
+    const cache = _readCache();
+    delete cache[_cacheKey(licenceKey)];
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2));
+  } catch(_) {}
+}
 
-async function _validateWithPolar(licenceKey) {
-  const body = JSON.stringify({
-    key:             licenceKey,
-    organization_id: POLAR_ORG_ID,
-  });
+// ── Polar API calls ───────────────────────────────────────────────────────────
 
-  const res = await fetch(POLAR_API, {
+async function _polarPost(url, body) {
+  const res = await fetch(url, {
     method:  'POST',
     headers: { 'Content-Type': 'application/json' },
-    body,
+    body:    JSON.stringify(body),
     signal:  AbortSignal.timeout(10000),
   });
+  return { status: res.status, data: res.ok ? await res.json() : null };
+}
 
-  if (res.status === 404) {
-    return { valid: false, reason: 'Key not found' };
-  }
-  if (res.status === 422) {
-    return { valid: false, reason: 'Invalid key format' };
-  }
-  if (!res.ok) {
-    // Network/server error — allow offline grace period
-    return { valid: null, reason: `Polar API error: ${res.status}` };
-  }
+async function _activateMachine(licenceKey) {
+  const { status, data } = await _polarPost(POLAR_ACTIVATE, {
+    key:             licenceKey,
+    organization_id: POLAR_ORG_ID,
+    label:           MACHINE_LABEL,
+  });
 
-  const data = await res.json();
+  if (status === 403) return { valid: false, reason: 'LIMIT_REACHED' };
+  if (status === 404) return { valid: false, reason: 'KEY_NOT_FOUND' };
+  if (status === 422) return { valid: false, reason: 'INVALID_FORMAT' };
+  if (!data)          return { valid: null,  reason: `API_ERROR_${status}` };
 
-  // Polar returns status: 'granted' | 'revoked' | 'disabled'
-  if (data.status !== 'granted') {
-    return { valid: false, reason: `Licence ${data.status}` };
+  const lk = data.license_key || data;
+  if (lk.status !== 'granted') {
+    return { valid: false, reason: `LICENCE_${(lk.status || 'UNKNOWN').toUpperCase()}` };
   }
 
   return {
-    valid:      true,
-    status:     data.status,
-    expires_at: data.expires_at || null,
-    key_id:     data.id,
+    valid:         true,
+    activation_id: data.id,
+    key_id:        lk.id,
+    expires_at:    lk.expires_at || null,
+    usage:         lk.usage,
+    limit:         lk.limit_activations,
   };
 }
 
-// ── Main export ───────────────────────────────────────────────────────────────
+async function _validateKey(licenceKey) {
+  const { status, data } = await _polarPost(POLAR_VALIDATE, {
+    key:             licenceKey,
+    organization_id: POLAR_ORG_ID,
+  });
+
+  if (status === 404) return { valid: false, reason: 'KEY_NOT_FOUND' };
+  if (status === 422) return { valid: false, reason: 'INVALID_FORMAT' };
+  if (!data)          return { valid: null,  reason: `API_ERROR_${status}` };
+  if (data.status !== 'granted') {
+    return { valid: false, reason: `LICENCE_${(data.status || 'UNKNOWN').toUpperCase()}` };
+  }
+  return { valid: true };
+}
+
+async function _deactivateMachine(licenceKey, activationId) {
+  const { status } = await _polarPost(POLAR_DEACTIVATE, {
+    key:             licenceKey,
+    organization_id: POLAR_ORG_ID,
+    activation_id:   activationId,
+  });
+  return status === 200 || status === 204;
+}
+
+// ── Error messages ────────────────────────────────────────────────────────────
+
+function _missingKeyError() {
+  return new Error(
+    '\n' +
+    '  ╔══════════════════════════════════════════════════════╗\n' +
+    '  ║         VEKTOR SLIPSTREAM — LICENCE REQUIRED         ║\n' +
+    '  ╚══════════════════════════════════════════════════════╝\n' +
+    '\n' +
+    '  A valid licence key is required to use Vektor Slipstream.\n' +
+    '\n' +
+    '  Purchase at: ' + PURCHASE_URL + '\n' +
+    '\n' +
+    '  Usage:\n' +
+    '    const memory = await createMemory({\n' +
+    '      agentId:    \'my-agent\',\n' +
+    '      licenceKey: \'VEKTOR-XXXX-XXXX-XXXX\',\n' +
+    '    });\n'
+  );
+}
+
+function _invalidKeyError(reason) {
+  return new Error(
+    '\n' +
+    '  ╔══════════════════════════════════════════════════════╗\n' +
+    '  ║       VEKTOR SLIPSTREAM — LICENCE INVALID            ║\n' +
+    '  ╚══════════════════════════════════════════════════════╝\n' +
+    '\n' +
+    '  Reason: ' + reason + '\n' +
+    '\n' +
+    '  Purchase a valid licence at: ' + PURCHASE_URL + '\n' +
+    '  Already purchased? Check your email for the key.\n'
+  );
+}
+
+function _limitReachedError() {
+  return new Error(
+    '\n' +
+    '  ╔══════════════════════════════════════════════════════╗\n' +
+    '  ║     VEKTOR SLIPSTREAM — ACTIVATION LIMIT REACHED     ║\n' +
+    '  ╚══════════════════════════════════════════════════════╝\n' +
+    '\n' +
+    '  Your licence is active on 3 machines (the maximum).\n' +
+    '\n' +
+    '  To activate on this machine, deactivate another first:\n' +
+    '\n' +
+    '  Option A — run on the machine you want to remove:\n' +
+    '    node -e "require(\'vektor-slipstream/vektor-licence\')\n' +
+    '      .deactivateMachine(\'YOUR_KEY\')"\n' +
+    '\n' +
+    '  Option B — manage activations at:\n' +
+    '    https://polar.sh (your customer portal)\n' +
+    '\n' +
+    '  Need more machines? Enterprise (10 seats) coming soon.\n' +
+    '  Contact: hello@vektormemory.com\n'
+  );
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
 
 /**
  * validateLicence(licenceKey)
  *
- * Call before createMemory(). Throws if the key is invalid.
- * Caches valid keys for 30 days so it doesn't call Polar on every run.
+ * Call before createMemory(). Activates this machine on first run,
+ * validates on subsequent runs. Enforces 3-machine limit via Polar.
  *
- * @param {string} licenceKey  — the customer's Polar licence key
+ * @param {string} licenceKey
  * @returns {Promise<void>}
- * @throws {Error} if key is invalid, revoked, or missing
+ * @throws {Error} if key invalid, revoked, missing, or limit reached
  */
 async function validateLicence(licenceKey) {
   if (!licenceKey || typeof licenceKey !== 'string' || licenceKey.trim().length < 8) {
-    throw new Error(
-      '\n' +
-      '  ╔══════════════════════════════════════════════════════╗\n' +
-      '  ║         VEKTOR SLIPSTREAM — LICENCE REQUIRED         ║\n' +
-      '  ╚══════════════════════════════════════════════════════╝\n' +
-      '\n' +
-      '  A valid licence key is required to use Vektor Slipstream.\n' +
-      '\n' +
-      '  Purchase at: ' + PURCHASE_URL + '\n' +
-      '\n' +
-      '  Usage:\n' +
-      '    const memory = await createMemory({\n' +
-      '      agentId:    \'my-agent\',\n' +
-      '      licenceKey: \'VEKTOR-XXXX-XXXX-XXXX\',\n' +
-      '    });\n'
-    );
+    throw _missingKeyError();
   }
 
-  // Check cache first
-  const cached = _getCached(licenceKey);
-  if (cached?.valid === true) {
-    // Cache hit — valid, proceed silently
-    return;
+  const key = licenceKey.trim();
+
+  // Cache hit — this machine is already activated
+  const cached = _getCached(key);
+  if (cached?.valid === true && cached?.activation_id) {
+    return; // proceed silently
   }
 
-  // Cache miss or expired — validate with Polar
+  // Cache miss or expired — activate this machine
   let result;
   try {
-    result = await _validateWithPolar(licenceKey.trim());
+    result = await _activateMachine(key);
   } catch(e) {
-    // Network failure — check if we have any cached entry (even expired) as grace period
-    const staleCache = _readCache()[_cacheKey(licenceKey)];
-    if (staleCache?.valid === true) {
-      console.warn('[SLIPSTREAM] Could not reach licence server — using cached validation (grace period).');
+    // Network failure — grace period using stale cache
+    const stale = _readCache()[_cacheKey(key)];
+    if (stale?.valid === true) {
+      console.warn('[vektor] Could not reach licence server — using cached activation (grace period).');
       return;
     }
     throw new Error(
-      '[SLIPSTREAM] Licence validation failed — could not reach Polar.\n' +
-      'Check your internet connection and try again.\n' +
-      'Error: ' + e.message
+      '[vektor] Licence validation failed — could not reach Polar.\n' +
+      'Check your internet connection.\nError: ' + e.message
     );
   }
 
   if (result.valid === null) {
-    // Polar API error — use stale cache as grace period
-    const staleCache = _readCache()[_cacheKey(licenceKey)];
-    if (staleCache?.valid === true) {
-      console.warn('[SLIPSTREAM] Licence server error — using cached validation (grace period).');
+    const stale = _readCache()[_cacheKey(key)];
+    if (stale?.valid === true) {
+      console.warn('[vektor] Licence server error — using cached activation (grace period).');
       return;
     }
-    throw new Error('[SLIPSTREAM] Licence server temporarily unavailable. Try again in a moment.');
+    throw new Error('[vektor] Licence server temporarily unavailable. Try again in a moment.');
   }
 
   if (!result.valid) {
-    throw new Error(
-      '\n' +
-      '  ╔══════════════════════════════════════════════════════╗\n' +
-      '  ║       VEKTOR SLIPSTREAM — LICENCE INVALID            ║\n' +
-      '  ╚══════════════════════════════════════════════════════╝\n' +
-      '\n' +
-      '  Reason: ' + result.reason + '\n' +
-      '\n' +
-      '  Purchase a valid licence at: ' + PURCHASE_URL + '\n' +
-      '  Already purchased? Check your email for the key.\n'
-    );
+    if (result.reason === 'LIMIT_REACHED') throw _limitReachedError();
+    throw _invalidKeyError(result.reason);
+  }
+
+  // Cache the activation
+  _writeCache(key, {
+    valid:         true,
+    activation_id: result.activation_id,
+    key_id:        result.key_id,
+    expires_at:    result.expires_at,
+    machine:       MACHINE_LABEL,
+  });
+
+  console.log(`[vektor] Licence activated — ${MACHINE_LABEL} (${result.usage}/${result.limit} seats used)`);
+}
+
+/**
+ * deactivateMachine(licenceKey)
+ *
+ * Frees this machine's activation slot. Call before switching machines
+ * or uninstalling. Removes one of the 3 used slots from Polar.
+ *
+ * CLI usage:
+ *   node -e "require('vektor-slipstream/vektor-licence').deactivateMachine('VEKTOR-XXXX')"
+ *
+ * @param {string} licenceKey
+ * @returns {Promise<void>}
+ */
+async function deactivateMachine(licenceKey) {
+  if (!licenceKey || licenceKey.trim().length < 8) {
+    console.error('[vektor] No licence key provided.');
+    return;
+  }
+
+  const key    = licenceKey.trim();
+  const cached = _readCache()[_cacheKey(key)];
+
+  if (!cached?.activation_id) {
+    console.log('[vektor] No active activation found on this machine.');
+    _clearCache(key);
+    return;
   }
 
-  // Valid — cache it
-  _writeCache(licenceKey, result);
+  console.log(`[vektor] Deactivating: ${MACHINE_LABEL}`);
+
+  try {
+    const ok = await _deactivateMachine(key, cached.activation_id);
+    if (ok) {
+      _clearCache(key);
+      console.log('[vektor] Deactivation successful — slot is now free for another machine.');
+    } else {
+      console.warn('[vektor] Deactivation failed. Manage activations at: https://polar.sh');
+    }
+  } catch(e) {
+    console.error('[vektor] Deactivation error:', e.message);
+  }
 }
 
-module.exports = { validateLicence };
+module.exports = { validateLicence, deactivateMachine };

package/visualize.js

@@ -0,0 +1,235 @@
+'use strict';
+/**
+ * visualize.js — memory.visualize()
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Opens a local HTTP server serving a D3 force graph of the agent's memory.
+ * Launched by memory.visualize() — opens browser automatically.
+ * Runs until the user closes the browser tab or calls server.close().
+ *
+ * No external dependencies beyond what's already in the SDK.
+ * Pure Node.js http + inline HTML/CSS/JS with D3 from CDN.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+const http = require('http');
+const os   = require('os');
+
+// ── D3 Graph HTML ─────────────────────────────────────────────────────────────
+
+function buildHTML(agentId) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Vektor Memory Graph — ${agentId}</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { background: #0c0d0e; color: #e2e8f0; font-family: 'IBM Plex Mono', monospace; overflow: hidden; }
+  #header { position: absolute; top: 0; left: 0; right: 0; padding: 12px 20px; display: flex; align-items: center; justify-content: space-between; background: rgba(12,13,14,0.9); border-bottom: 1px solid rgba(255,255,255,0.08); z-index: 10; }
+  #header h1 { font-size: 13px; font-weight: 500; letter-spacing: 0.06em; color: rgba(242,242,242,0.7); }
+  #stats { font-size: 11px; color: rgba(242,242,242,0.38); letter-spacing: 0.04em; }
+  #graph { width: 100vw; height: 100vh; }
+  .node circle { stroke-width: 1.5; cursor: pointer; }
+  .node text { font-size: 10px; fill: rgba(242,242,242,0.6); pointer-events: none; }
+  .link { stroke: rgba(255,255,255,0.12); stroke-width: 1; }
+  .link.semantic  { stroke: rgba(99,153,34,0.4); }
+  .link.causal    { stroke: rgba(255,107,0,0.4); }
+  .link.temporal  { stroke: rgba(59,139,212,0.4); }
+  .link.entity    { stroke: rgba(127,119,221,0.4); }
+  #tooltip { position: absolute; background: rgba(12,13,14,0.95); border: 1px solid rgba(255,255,255,0.12); border-radius: 6px; padding: 10px 14px; font-size: 11px; max-width: 300px; line-height: 1.6; pointer-events: none; display: none; z-index: 20; }
+  #tooltip .t-content { color: rgba(242,242,242,0.8); margin-bottom: 4px; }
+  #tooltip .t-meta { color: rgba(242,242,242,0.38); font-size: 10px; }
+  #legend { position: absolute; bottom: 16px; left: 20px; font-size: 10px; color: rgba(242,242,242,0.38); line-height: 2; }
+  .leg { display: flex; align-items: center; gap: 6px; }
+  .leg-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
+  #controls { position: absolute; bottom: 16px; right: 20px; display: flex; gap: 8px; }
+  #controls button { background: rgba(255,255,255,0.05); border: 1px solid rgba(255,255,255,0.1); color: rgba(242,242,242,0.6); font-size: 11px; font-family: inherit; padding: 4px 12px; border-radius: 4px; cursor: pointer; }
+  #controls button:hover { background: rgba(255,255,255,0.1); }
+</style>
+</head>
+<body>
+<div id="header">
+  <h1>VEKTOR MEMORY GRAPH &mdash; ${agentId}</h1>
+  <span id="stats">loading...</span>
+</div>
+<svg id="graph"></svg>
+<div id="tooltip"><div class="t-content" id="tt-content"></div><div class="t-meta" id="tt-meta"></div></div>
+<div id="legend">
+  <div class="leg"><div class="leg-dot" style="background:#639922"></div> semantic</div>
+  <div class="leg"><div class="leg-dot" style="background:#ff6b00"></div> causal</div>
+  <div class="leg"><div class="leg-dot" style="background:#378add"></div> temporal</div>
+  <div class="leg"><div class="leg-dot" style="background:#7f77dd"></div> entity</div>
+</div>
+<div id="controls">
+  <button onclick="restart()">Reset</button>
+  <button onclick="window.location.reload()">Refresh</button>
+</div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/d3/7.8.5/d3.min.js"></script>
+<script>
+const W = window.innerWidth, H = window.innerHeight;
+const svg = d3.select('#graph').attr('width', W).attr('height', H);
+const g   = svg.append('g');
+const tooltip = document.getElementById('tooltip');
+
+svg.call(d3.zoom().scaleExtent([0.1, 4]).on('zoom', e => g.attr('transform', e.transform)));
+
+const COLOR = { semantic: '#639922', causal: '#ff6b00', temporal: '#378add', entity: '#7f77dd', default: '#888780' };
+
+async function load() {
+  const data = await fetch('/data').then(r => r.json());
+  const nodes = data.nodes;
+  const links = data.edges.map(e => ({ ...e, source: e.source_id, target: e.target_id }));
+
+  document.getElementById('stats').textContent =
+    nodes.length + ' nodes · ' + links.length + ' edges · agent: ${agentId}';
+
+  g.selectAll('*').remove();
+
+  const sim = d3.forceSimulation(nodes)
+    .force('link', d3.forceLink(links).id(d => d.id).distance(80))
+    .force('charge', d3.forceManyBody().strength(-120))
+    .force('center', d3.forceCenter(W / 2, H / 2))
+    .force('collision', d3.forceCollide(20));
+
+  const link = g.append('g').selectAll('line')
+    .data(links).join('line')
+    .attr('class', d => 'link ' + (d.edge_type || 'semantic'));
+
+  const node = g.append('g').selectAll('g')
+    .data(nodes).join('g').attr('class', 'node')
+    .call(d3.drag()
+      .on('start', (e, d) => { if (!e.active) sim.alphaTarget(0.3).restart(); d.fx = d.x; d.fy = d.y; })
+      .on('drag',  (e, d) => { d.fx = e.x; d.fy = e.y; })
+      .on('end',   (e, d) => { if (!e.active) sim.alphaTarget(0); d.fx = null; d.fy = null; }));
+
+  node.append('circle')
+    .attr('r', d => 4 + Math.min((d.importance || 1) * 2, 10))
+    .attr('fill', d => COLOR[d.edge_type] || COLOR.default)
+    .attr('fill-opacity', 0.8)
+    .attr('stroke', d => COLOR[d.edge_type] || COLOR.default)
+    .on('mouseover', (e, d) => {
+      document.getElementById('tt-content').textContent = d.content ? d.content.slice(0, 200) : d.id;
+      document.getElementById('tt-meta').textContent =
+        'importance: ' + (d.importance || 1) + ' · type: ' + (d.edge_type || 'semantic') + ' · id: ' + d.id;
+      tooltip.style.display = 'block';
+      tooltip.style.left = (e.pageX + 12) + 'px';
+      tooltip.style.top  = (e.pageY + 12) + 'px';
+    })
+    .on('mousemove', e => {
+      tooltip.style.left = (e.pageX + 12) + 'px';
+      tooltip.style.top  = (e.pageY + 12) + 'px';
+    })
+    .on('mouseout', () => tooltip.style.display = 'none');
+
+  node.append('text')
+    .attr('dx', 10).attr('dy', 4)
+    .text(d => d.content ? d.content.slice(0, 30) + (d.content.length > 30 ? '…' : '') : '');
+
+  sim.on('tick', () => {
+    link.attr('x1', d => d.source.x).attr('y1', d => d.source.y)
+        .attr('x2', d => d.target.x).attr('y2', d => d.target.y);
+    node.attr('transform', d => 'translate(' + d.x + ',' + d.y + ')');
+  });
+
+  window._sim = sim;
+}
+
+function restart() { if (window._sim) { window._sim.alpha(1).restart(); } }
+
+load().catch(e => {
+  document.getElementById('stats').textContent = 'Error loading graph: ' + e.message;
+});
+</script>
+</body>
+</html>`;
+}
+
+// ── HTTP Server ───────────────────────────────────────────────────────────────
+
+/**
+ * startVisualizer(memory, opts)
+ *
+ * Starts a local HTTP server serving a D3 memory graph.
+ * Opens the browser automatically.
+ *
+ * @param {SlipstreamMemory} memory  — the memory instance to visualize
+ * @param {object} opts
+ * @param {number} opts.port         — port (default: random available)
+ * @param {boolean} opts.open        — auto-open browser (default: true)
+ * @returns {Promise<http.Server>}
+ */
+async function startVisualizer(memory, opts = {}) {
+  const { open = true } = opts;
+  const agentId = memory.agentId || 'agent';
+
+  const server = http.createServer(async (req, res) => {
+    const cors = { 'Access-Control-Allow-Origin': '*' };
+
+    if (req.url === '/') {
+      res.writeHead(200, { 'Content-Type': 'text/html', ...cors });
+      res.end(buildHTML(agentId));
+      return;
+    }
+
+    if (req.url === '/data') {
+      try {
+        // Pull all memories as nodes
+        const nodes = memory.db.prepare(
+          'SELECT id, content, edge_type, importance FROM memories WHERE agent_id = ? ORDER BY importance DESC LIMIT 500'
+        ).all(agentId);
+
+        // Pull edges
+        const edges = memory.db.prepare(
+          'SELECT source_id, target_id, edge_type, weight FROM memory_edges WHERE agent_id = ? LIMIT 2000'
+        ).all(agentId);
+
+        res.writeHead(200, { 'Content-Type': 'application/json', ...cors });
+        res.end(JSON.stringify({ nodes, edges }));
+      } catch(e) {
+        res.writeHead(500, { 'Content-Type': 'application/json', ...cors });
+        res.end(JSON.stringify({ error: e.message }));
+      }
+      return;
+    }
+
+    res.writeHead(404); res.end();
+  });
+
+  // Find an available port
+  await new Promise((resolve, reject) => {
+    const port = opts.port || 0; // 0 = OS picks available port
+    server.listen(port, '127.0.0.1', () => resolve());
+    server.on('error', reject);
+  });
+
+  const { port } = server.address();
+  const url = `http://localhost:${port}`;
+
+  console.log('');
+  console.log('  ╔══════════════════════════════════════════════════════╗');
+  console.log('  ║          VEKTOR MEMORY GRAPH — VISUALIZER            ║');
+  console.log('  ╚══════════════════════════════════════════════════════╝');
+  console.log('');
+  console.log(`  Agent:  ${agentId}`);
+  console.log(`  URL:    ${url}`);
+  console.log('');
+  console.log('  Close this process (Ctrl+C) to stop the visualizer.');
+  console.log('');
+
+  // Auto-open browser
+  if (open) {
+    const platform = os.platform();
+    const { exec } = require('child_process');
+    const cmd = platform === 'win32'  ? `start ${url}`
+              : platform === 'darwin' ? `open ${url}`
+              : `xdg-open ${url}`;
+    exec(cmd, err => {
+      if (err) console.log(`  Open manually: ${url}`);
+    });
+  }
+
+  return server;
+}
+
+module.exports = { startVisualizer };