vektor-slipstream 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vektor-slipstream",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Hardware-accelerated persistent memory for AI agents. Local-first, zero cloud dependency, $0 embedding cost.",
   "main": "slipstream-core.js",
   "exports": {

package/slipstream-core.js

@@ -2,50 +2,191 @@
 
 /**
  * VEKTOR SLIPSTREAM
- * slipstream-core.js — Main Entry Point
+ * slipstream-core.js — Resilient Self-Contained Build
  * ─────────────────────────────────────────────────────────────────────────────
- * The hardware-accelerated memory engine. Parallel to vektor-core.js but
- * with native ONNX embeddings, Hyper-PRAGMA SQLite, and the pre-warmed
- * inference pipeline.
+ * Drop-in replacement for the ONNX-dependent version.
+ * Same public API: createMemory({ agentId, dbPath, silent })
  *
- * Drop-in API replacement for vektor-core.js:
- *   const { createMemory } = require('./slipstream-core');
+ * Embedding strategy (best available, in order):
+ *   1. @xenova/transformers  — full transformer embeddings, pure JS, no ONNX native
+ *   2. Hash-projection       — deterministic 384-dim vector, zero deps, instant boot
  *
- * Same methods. Faster engine underneath.
+ * SQLite strategy (best available, in order):
+ *   1. better-sqlite3        — native, fast
+ *   2. Falls back with clear error message
+ *
+ * All other files (slipstream-db, slipstream-embedder, detect-hardware) are
+ * inlined here — nothing to require().
  * ─────────────────────────────────────────────────────────────────────────────
  */
 
-const { initSlipstreamDB, getDBStats }  = require('./slipstream-db');
-const { SlipstreamEmbedder }            = require('./slipstream-embedder');
-const { getEPLabel }                    = require('./detect-hardware');
-const { validateLicence }               = require('./vektor-licence');
+const path = require('path');
+const fs   = require('fs');
+
+// ─── SQLite loader — better-sqlite3 with clear error ─────────────────────────
+function loadSQLite(dbPath) {
+  try {
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath);
+
+    // Hyper-PRAGMAs — same as original slipstream-db.js
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous  = NORMAL');
+    db.pragma('cache_size   = -65536');   // 64 MB
+    db.pragma('mmap_size    = 1073741824'); // 1 GB
+    db.pragma('temp_store   = MEMORY');
+    db.pragma('page_size    = 4096');
+
+    return db;
+  } catch (e) {
+    if (e.code === 'ERR_DLOPEN_FAILED' || e.message.includes('NODE_MODULE_VERSION')) {
+      console.error('');
+      console.error('  ✗ better-sqlite3 binary mismatch (compiled for different Node version)');
+      console.error('  → Fix: npm rebuild better-sqlite3');
+      console.error('  → Then restart the server');
+      console.error('');
+      throw new Error('better-sqlite3 rebuild required: npm rebuild better-sqlite3');
+    }
+    throw e;
+  }
+}
 
-// ─── Boot Banner ──────────────────────────────────────────────────────────────
+// ─── Embedding Engine ─────────────────────────────────────────────────────────
+// Strategy 1: @xenova/transformers (pure JS, no native deps)
+// Strategy 2: Hash-projection (zero deps, deterministic, always works)
+
+const EMBED_DIM = 384;
+
+// Hash-projection embedder — deterministic 384-dim float32 vector
+// Uses FNV-1a family of hashes over character n-grams
+// Sufficient for keyword recall; upgrade to xenova for semantic search
+function hashEmbed(text) {
+  const vec    = new Float32Array(EMBED_DIM);
+  const tokens = text.toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length > 1);
+
+  // Add character bigrams and trigrams for sub-word coverage
+  const allGrams = [...tokens];
+  for (const tok of tokens) {
+    for (let i = 0; i < tok.length - 1; i++) allGrams.push(tok.slice(i, i + 2));
+    for (let i = 0; i < tok.length - 2; i++) allGrams.push(tok.slice(i, i + 3));
+  }
 
-function printBanner(embedder, dbStats, bootMs) {
-  const stats = embedder.getStats();
-  const ep    = stats.epLabel;
-  const icon  = stats.ep === 'cpu' ? '⚙️ ' : '🚀';
+  for (const gram of allGrams) {
+    // FNV-1a 32-bit over the gram characters
+    let h = 2166136261;
+    for (let i = 0; i < gram.length; i++) {
+      h ^= gram.charCodeAt(i);
+      h = (h * 16777619) >>> 0;
+    }
+    // Project into two dimensions for richer coverage
+    const idx1 = h % EMBED_DIM;
+    const idx2 = (h >>> 16) % EMBED_DIM;
+    const sign = (h & 1) ? 1 : -1;
+    vec[idx1] += sign;
+    vec[idx2] += sign * 0.5;
+  }
 
-  console.log('');
-  console.log('  ╔══════════════════════════════════════════════════════╗');
-  console.log('  ║            VEKTOR SLIPSTREAM — ACTIVE                ║');
-  console.log('  ╚══════════════════════════════════════════════════════╝');
-  console.log('');
-  console.log(`  ${icon} EP:        ${ep}`);
-  console.log(`  🧠  Model:     all-MiniLM-L6-v2 INT8 quantized`);
-  console.log(`  ⚡  Embed:     ${stats.avgMs}ms (post-warmup)`);
-  console.log(`  💾  DB:        WAL | mmap:1GB | cache:64MB`);
-  console.log(`  🔥  Warm:      ✓`);
-  console.log(`  ⏱  Boot:      ${bootMs}ms total`);
-  console.log('');
+  // L2 normalize
+  let norm = 0;
+  for (let i = 0; i < EMBED_DIM; i++) norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm) + 1e-10;
+  for (let i = 0; i < EMBED_DIM; i++) vec[i] /= norm;
+
+  return vec;
+}
+
+// Xenova embedder — lazy-loaded, falls back to hash if unavailable
+let _xenovaPipeline = null;
+let _xenovaFailed   = false;
+let _xenovaLoading  = false;
+let _xenovaQueue    = [];
+
+async function xenovaEmbed(text) {
+  if (_xenovaFailed) return null;
+
+  // If pipeline is ready, use it
+  if (_xenovaPipeline) {
+    try {
+      const output = await _xenovaPipeline(text, { pooling: 'mean', normalize: true });
+      return new Float32Array(output.data);
+    } catch (e) {
+      console.warn('[slipstream] xenova embed failed:', e.message);
+      return null;
+    }
+  }
+
+  // If loading, queue this call
+  if (_xenovaLoading) {
+    return new Promise((resolve) => {
+      _xenovaQueue.push({ text, resolve });
+    });
+  }
+
+  // Start loading
+  _xenovaLoading = true;
+  try {
+    const { pipeline, env } = require('@xenova/transformers');
+    // Use local cache, don't require internet
+    env.allowLocalModels   = true;
+    env.allowRemoteModels  = true;
+    env.cacheDir           = path.join(require('os').homedir(), '.cache', 'xenova');
+
+    console.log('[slipstream] Loading @xenova/transformers (first run may download model ~25MB)...');
+    _xenovaPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
+      quantized: true,  // INT8 — matches original slipstream spec
+    });
+    console.log('[slipstream] ✓ Semantic embeddings active (all-MiniLM-L6-v2 INT8)');
+
+    // Drain the queue
+    _xenovaLoading = false;
+    const queued = [..._xenovaQueue];
+    _xenovaQueue  = [];
+    for (const item of queued) {
+      try {
+        const out = await _xenovaPipeline(item.text, { pooling: 'mean', normalize: true });
+        item.resolve(new Float32Array(out.data));
+      } catch (_) { item.resolve(null); }
+    }
+
+    // Now embed the original text
+    const output = await _xenovaPipeline(text, { pooling: 'mean', normalize: true });
+    return new Float32Array(output.data);
+
+  } catch (e) {
+    _xenovaFailed  = true;
+    _xenovaLoading = false;
+    // Drain queue with null
+    for (const item of _xenovaQueue) item.resolve(null);
+    _xenovaQueue = [];
+    if (e.code !== 'MODULE_NOT_FOUND') {
+      console.warn('[slipstream] @xenova/transformers failed:', e.message);
+    }
+    return null;
+  }
+}
+
+// Unified embed — tries xenova, falls back to hash
+async function embed(text) {
+  const xVec = await xenovaEmbed(text);
+  if (xVec) return xVec;
+  return hashEmbed(text);
+}
+
+function getEmbedderStats() {
+  const mode = _xenovaPipeline ? 'xenova/all-MiniLM-L6-v2 INT8' : 'hash-projection (384-dim)';
+  const ep   = _xenovaPipeline ? 'CPU·ONNX' : 'CPU·Hash';
+  return { mode, ep, epLabel: ep, avgMs: _xenovaPipeline ? '~20' : '<1', dim: EMBED_DIM };
 }
 
 // ─── Vector Utilities ─────────────────────────────────────────────────────────
 
 function cosineSimilarity(a, b) {
   let dot = 0, normA = 0, normB = 0;
-  for (let i = 0; i < a.length; i++) {
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
     dot   += a[i] * b[i];
     normA += a[i] * a[i];
     normB += b[i] * b[i];
@@ -58,7 +199,10 @@ function serializeVector(float32Array) {
 }
 
 function deserializeVector(buffer) {
-  return new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
+  if (!buffer || buffer.length < 4) return new Float32Array(0);
+  return new Float32Array(
+    buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength)
+  );
 }
 
 // ─── Schema ───────────────────────────────────────────────────────────────────
@@ -67,9 +211,12 @@ function initSchema(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS memories (
       id          INTEGER PRIMARY KEY AUTOINCREMENT,
-      agent_id    TEXT    NOT NULL,
+      agent_id    TEXT    NOT NULL DEFAULT 'default',
       content     TEXT    NOT NULL,
+      edge_type   TEXT    DEFAULT 'semantic',
       summary     TEXT,
+      tags        TEXT    DEFAULT '',
+      source_agent TEXT   DEFAULT 'system',
       importance  REAL    DEFAULT 1.0,
       vector      BLOB,
       created_at  INTEGER DEFAULT (strftime('%s', 'now')),
@@ -78,262 +225,483 @@ function initSchema(db) {
 
     CREATE INDEX IF NOT EXISTS idx_memories_agent
       ON memories(agent_id);
-
+    CREATE INDEX IF NOT EXISTS idx_memories_type
+      ON memories(edge_type);
     CREATE INDEX IF NOT EXISTS idx_memories_importance
       ON memories(agent_id, importance DESC);
+    CREATE INDEX IF NOT EXISTS idx_memories_created
+      ON memories(created_at DESC);
 
     CREATE TABLE IF NOT EXISTS memory_edges (
       id          INTEGER PRIMARY KEY AUTOINCREMENT,
-      agent_id    TEXT    NOT NULL,
+      agent_id    TEXT    NOT NULL DEFAULT 'default',
       source_id   INTEGER NOT NULL,
       target_id   INTEGER NOT NULL,
-      edge_type   TEXT    NOT NULL,
+      edge_type   TEXT    NOT NULL DEFAULT 'related',
       weight      REAL    DEFAULT 1.0,
       created_at  INTEGER DEFAULT (strftime('%s', 'now')),
-      FOREIGN KEY (source_id) REFERENCES memories(id),
-      FOREIGN KEY (target_id) REFERENCES memories(id)
+      FOREIGN KEY (source_id) REFERENCES memories(id) ON DELETE CASCADE,
+      FOREIGN KEY (target_id) REFERENCES memories(id) ON DELETE CASCADE
     );
 
     CREATE INDEX IF NOT EXISTS idx_edges_agent
       ON memory_edges(agent_id, edge_type);
+
+    CREATE TABLE IF NOT EXISTS agent_capabilities (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id    TEXT    NOT NULL,
+      engine_id   TEXT    NOT NULL,
+      label       TEXT,
+      created_at  TEXT    DEFAULT (datetime('now')),
+      UNIQUE(agent_id, engine_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS directives (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      title       TEXT    NOT NULL,
+      description TEXT    DEFAULT '',
+      status      TEXT    DEFAULT 'BACKLOG',
+      priority    TEXT    DEFAULT 'MED',
+      agent       TEXT    DEFAULT '',
+      project_id  INTEGER DEFAULT NULL,
+      result      TEXT,
+      created_at  INTEGER DEFAULT (strftime('%s','now')*1000),
+      updated_at  INTEGER DEFAULT (strftime('%s','now')*1000)
+    );
+
+    CREATE TABLE IF NOT EXISTS hitl_queue (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      directive_id TEXT,
+      agent       TEXT,
+      action      TEXT,
+      status      TEXT    DEFAULT 'PENDING',
+      result      TEXT,
+      meta        TEXT,
+      created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
   `);
+
+  // Safe migrations — add columns that may not exist in older DBs
+  const migrations = [
+    "ALTER TABLE memories   ADD COLUMN edge_type   TEXT    DEFAULT 'semantic'",
+    "ALTER TABLE memories   ADD COLUMN tags        TEXT    DEFAULT ''",
+    "ALTER TABLE memories   ADD COLUMN source_agent TEXT   DEFAULT 'system'",
+    "ALTER TABLE directives ADD COLUMN result      TEXT",
+    "ALTER TABLE directives ADD COLUMN description TEXT DEFAULT ''",
+    "ALTER TABLE hitl_queue ADD COLUMN action      TEXT",
+  ];
+  for (const m of migrations) {
+    try { db.exec(m); } catch (_) { /* column already exists — safe */ }
+  }
+}
+
+// ─── AUDN Contradiction Detector ─────────────────────────────────────────────
+// Returns true if newText likely contradicts existingText.
+// Three signals: negation words, opposing numeric values, reversal phrases.
+
+const NEGATION_WORDS = new Set([
+  'not','no','never','none','cannot','cant',"can't",'wont',"won't",
+  'isnt',"isn't",'arent',"aren't",'wasnt',"wasn't",'doesnt',"doesn't",
+  'didnt',"didn't",'shouldnt',"shouldn't",'false','incorrect','wrong',
+  'opposite','contrary','denied','declined','rejected',
+]);
+
+const REVERSAL_PHRASES = [
+  /no longer/i, /used to/i, /changed (to|from)/i, /now (is|are|was)\b/i,
+  /instead of/i, /rather than/i, /replaced by/i, /switched (to|from)/i,
+  /corrected to/i, /updated to/i, /actually/i, /in fact/i,
+];
+
+function _tokenize(text) {
+  return text.toLowerCase().replace(/[^\w\s]/g, ' ').split(/\s+/).filter(t => t.length > 1);
+}
+
+function _extractNumbers(text) {
+  return (text.match(/-?\d+(?:\.\d+)?/g) || []).map(Number);
+}
+
+function _isContradiction(newText, existingText) {
+  const newTok = _tokenize(newText);
+  const exTok  = _tokenize(existingText);
+
+  // Signal 1: shared keywords + negation polarity mismatch
+  const sharedKeywords = newTok.filter(t => exTok.includes(t) && t.length > 3);
+  if (sharedKeywords.length > 0) {
+    const newNegated = newTok.some(t => NEGATION_WORDS.has(t));
+    const exNegated  = exTok.some(t => NEGATION_WORDS.has(t));
+    if (newNegated !== exNegated) return true;
+  }
+
+  // Signal 2: opposing numeric values on same subject (>20% change)
+  const newNums = _extractNumbers(newText);
+  const exNums  = _extractNumbers(existingText);
+  if (newNums.length && exNums.length && sharedKeywords.length > 0) {
+    const exVal = exNums[0];
+    if (exVal !== 0 && Math.abs(newNums[0] - exVal) / Math.abs(exVal) > 0.20) return true;
+  }
+
+  // Signal 3: explicit reversal language in new text
+  if (REVERSAL_PHRASES.some(p => p.test(newText))) return true;
+
+  return false;
 }
 
 // ─── SlipstreamMemory ─────────────────────────────────────────────────────────
 
 class SlipstreamMemory {
-  constructor(db, embedder, agentId) {
-    this.db       = db;
-    this.embedder = embedder;
-    this.agentId  = agentId;
+  constructor(db, agentId) {
+    this.db      = db;
+    this.agentId = agentId;
+    // Expose embedder stats for boot banner
+    this.embedder = { getStats: getEmbedderStats };
+    this.ep       = getEmbedderStats().ep;
+    this.model    = getEmbedderStats().mode;
   }
 
-  /**
-   * remember(text)
-   * Stores a memory with its vector embedding.
-   * Synchronous write path — no batching, full durability guaranteed.
-   *
-   * @param {string} text
-   * @returns {Promise<{id: number}>}
-   */
+  // ── remember(text, opts) — AUDN router ───────────────────────────────────
+  // Routes each incoming memory through:
+  //   NO_OP  — exact duplicate, discard
+  //   UPDATE — high similarity + contradiction signal, update existing
+  //   ADD    — genuinely new, insert
+  //
+  // Thresholds (tunable via opts):
+  //   NO_OP  : cosine >= 0.98  (near-identical wording)
+  //   UPDATE : cosine >= 0.82 AND contradiction score > 0
+  //   ADD    : everything else
+
   async remember(text, opts = {}) {
-    const vector     = await this.embedder.embed(text);
-    const vectorBlob = serializeVector(vector);
-    const importance = Number(opts.importance) || 1;
+    const NO_OP_THRESHOLD  = opts.noop_threshold   ?? 0.98;
+    const UPDATE_THRESHOLD = opts.update_threshold ?? 0.82;
+
+    const vec         = await embed(text);
+    const vectorBlob  = serializeVector(vec);
+    const importance  = Number(opts.importance) || 1;
+    const edgeType    = opts.type || opts.edge_type || 'semantic';
+    const tags        = Array.isArray(opts.tags) ? opts.tags.join(',') : (opts.tags || '');
+    const sourceAgent = opts.agent || opts.source_agent || this.agentId;
+
+    // ── Pull top candidates by cosine similarity ──────────────────────────
+    const candidates = this.db.prepare(`
+      SELECT id, content, edge_type, importance, vector
+      FROM   memories
+      WHERE  agent_id = ? AND vector IS NOT NULL
+      ORDER  BY importance DESC, created_at DESC
+      LIMIT  200
+    `).all(this.agentId);
 
-    const stmt = this.db.prepare(`
-      INSERT INTO memories (agent_id, content, vector, importance)
-      VALUES (?, ?, ?, ?)
-    `);
+    let bestScore = 0;
+    let bestRow   = null;
 
-    const result = stmt.run(this.agentId, text, vectorBlob, importance);
-    return { id: result.lastInsertRowid };
+    for (const row of candidates) {
+      const rowVec = deserializeVector(row.vector);
+      if (!rowVec.length) continue;
+      const score = cosineSimilarity(vec, rowVec);
+      if (score > bestScore) { bestScore = score; bestRow = row; }
+    }
+
+    // ── NO_OP — near-identical wording ───────────────────────────────────
+    if (bestScore >= NO_OP_THRESHOLD) {
+      return { action: 'NO_OP', id: bestRow.id, score: bestScore, reason: 'exact duplicate' };
+    }
+
+    // ── UPDATE — similar + contradiction detected ─────────────────────────
+    if (bestScore >= UPDATE_THRESHOLD && bestRow && _isContradiction(text, bestRow.content)) {
+      const newImportance = Math.max(bestRow.importance, importance);
+      this.db.prepare(`
+        UPDATE memories
+        SET    content = ?, vector = ?, importance = ?, source_agent = ?,
+               updated_at = strftime('%s','now')
+        WHERE  id = ?
+      `).run(text, vectorBlob, newImportance, sourceAgent, bestRow.id);
+
+      return {
+        action:   'UPDATE',
+        id:       bestRow.id,
+        score:    bestScore,
+        previous: bestRow.content.slice(0, 120),
+        reason:   'contradiction detected',
+      };
+    }
+
+    // ── DELETE — high confidence contradiction + low importance ──────────────
+    // When the old memory is low-importance AND the contradiction is strong,
+    // it's safer to delete and re-add than to update in place.
+    // Threshold: score >= 0.90 AND importance <= 1 AND contradiction detected.
+    const DELETE_THRESHOLD = opts.delete_threshold ?? 0.90;
+    if (
+      bestScore >= DELETE_THRESHOLD &&
+      bestRow &&
+      (bestRow.importance || 1) <= 1 &&
+      _isContradiction(text, bestRow.content)
+    ) {
+      this.db.prepare('DELETE FROM memories WHERE id = ?').run(bestRow.id);
+      // Remove from HNSW index
+      _hnswRemoveVector(this.agentId, bestRow.id);
+
+      // Re-insert as new with elevated importance (it replaced something)
+      const result = this.db.prepare(`
+        INSERT INTO memories (agent_id, content, edge_type, tags, source_agent, vector, importance)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(this.agentId, text, edgeType, tags, sourceAgent, vectorBlob, Math.max(importance, 2));
+
+      _hnswAddVector(this.db, this.agentId, result.lastInsertRowid, vec);
+
+      return {
+        action:   'DELETE',
+        id:       result.lastInsertRowid,
+        deleted:  bestRow.id,
+        score:    bestScore,
+        previous: bestRow.content.slice(0, 120),
+        reason:   'high-confidence contradiction — old memory removed',
+      };
+    }
+
+    // ── ADD — genuinely new ───────────────────────────────────────────────
+    const result = this.db.prepare(`
+      INSERT INTO memories (agent_id, content, edge_type, tags, source_agent, vector, importance)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(this.agentId, text, edgeType, tags, sourceAgent, vectorBlob, importance);
+
+    return { action: 'ADD', id: result.lastInsertRowid };
   }
 
-  /**
-   * recall(query, topK = 5)
-   * Semantic recall using cosine similarity over stored vectors.
-   * Runs entirely inside SQLite — no external vector DB required.
-   *
-   * @param {string}  query
-   * @param {number}  topK
-   * @returns {Promise<Array<{id, content, importance, score}>>}
-   */
+  // ── recall(query, topK) ────────────────────────────────────────────────────
+  // Semantic cosine similarity + keyword fallback
   async recall(query, topK = 5) {
-    const queryVector = await this.embedder.embed(query);
+    const queryVec = await embed(query);
 
-    // Pull all memories for this agent (mmap makes this fast)
+    // Pull top 500 by importance (mmap makes this fast)
     const rows = this.db.prepare(`
-      SELECT id, content, summary, importance, vector
+      SELECT id, content, summary, edge_type, importance, vector
       FROM   memories
       WHERE  agent_id = ?
         AND  vector IS NOT NULL
-      ORDER  BY importance DESC
+      ORDER  BY importance DESC, created_at DESC
       LIMIT  500
     `).all(this.agentId);
 
-    // Score in JS — cosine sim over Float32Arrays
+    if (!rows.length) {
+      // Nothing stored yet — try keyword fallback
+      return this._keywordRecall(query, topK);
+    }
+
+    // Score: cosine × importance
     const scored = rows
       .map(row => {
         const vec   = deserializeVector(row.vector);
-        const score = cosineSimilarity(queryVector, vec);
-        return {
-          id         : row.id,
-          content    : row.content,
-          summary    : row.summary,
-          importance : row.importance,
-          score      : Math.round(score * 100) / 100,
-        };
+        const score = vec.length > 0 ? cosineSimilarity(queryVec, vec) : 0;
+        return { id: row.id, content: row.content, summary: row.summary, edge_type: row.edge_type, importance: row.importance, score: Math.round(score * 100) / 100 };
       })
       .sort((a, b) => (b.score * b.importance) - (a.score * a.importance))
       .slice(0, topK);
 
+    // If top scores are very low, blend in keyword results
+    if (scored[0]?.score < 0.15) {
+      const kw = this._keywordRecall(query, topK);
+      const seen = new Set(scored.map(r => r.id));
+      for (const r of kw) { if (!seen.has(r.id)) scored.push(r); }
+      return scored.slice(0, topK);
+    }
+
     return scored;
   }
 
-  /**
-   * graph(concept, opts)
-   * Breadth-first traversal from a concept node.
-   *
-   * @param {string} concept
-   * @param {{ hops?: number }} opts
-   * @returns {Promise<{nodes: Array, edges: Array}>}
-   */
+  // Keyword fallback — used when vectors are cold or similarity is weak
+  _keywordRecall(query, limit = 5) {
+    const STOP = new Set(['the','and','for','are','was','has','its','you','your','just','also','more','some','any','all','can','get','this','that','with','from','have','will','what','when','where','which','there','their','about','would','could','should']);
+    const words = query.toLowerCase().replace(/[^\w\s]/g,' ').split(/\s+/).filter(w => w.length > 2 && !STOP.has(w));
+
+    if (!words.length) {
+      // Return most recent
+      return this.db.prepare('SELECT id, content, edge_type, importance, 0.5 as score FROM memories WHERE agent_id=? ORDER BY created_at DESC LIMIT ?').all(this.agentId, limit);
+    }
+
+    // Search each keyword, merge and deduplicate
+    const seen    = new Set();
+    const results = [];
+    for (const word of words.slice(0, 5)) {
+      const rows = this.db.prepare("SELECT id, content, edge_type, importance, 0.5 as score FROM memories WHERE agent_id=? AND content LIKE ? ORDER BY importance DESC LIMIT 5").all(this.agentId, '%' + word + '%');
+      for (const r of rows) { if (!seen.has(r.id)) { seen.add(r.id); results.push(r); } }
+    }
+    return results.slice(0, limit);
+  }
+
+  // ── graph(concept, opts) ──────────────────────────────────────────────────
   async graph(concept, opts = {}) {
-    const hops    = opts.hops ?? 2;
-    const topK    = opts.topK ?? 3;
-
-    // Find seed nodes via recall
-    const seeds   = await this.recall(concept, topK);
-    const visited = new Set(seeds.map(s => s.id));
-    const nodes   = [...seeds];
-    const edges   = [];
+    const hops     = opts.hops ?? 2;
+    const topK     = opts.topK ?? 3;
+    const seeds    = await this.recall(concept, topK);
+    const visited  = new Set(seeds.map(s => s.id));
+    const nodes    = [...seeds];
+    const edges    = [];
     let   frontier = seeds.map(s => s.id);
 
-    for (let hop = 0; hop < hops; hop++) {
-      if (!frontier.length) break;
-
-      const placeholders = frontier.map(() => '?').join(',');
+    for (let hop = 0; hop < hops && frontier.length; hop++) {
+      const ph      = frontier.map(() => '?').join(',');
       const edgeRows = this.db.prepare(`
-        SELECT source_id, target_id, edge_type, weight
-        FROM   memory_edges
-        WHERE  agent_id = ?
-          AND  (source_id IN (${placeholders}) OR target_id IN (${placeholders}))
+        SELECT source_id, target_id, edge_type, weight FROM memory_edges
+        WHERE  agent_id = ? AND (source_id IN (${ph}) OR target_id IN (${ph}))
       `).all(this.agentId, ...frontier, ...frontier);
 
       const nextIds = [];
       for (const edge of edgeRows) {
         edges.push(edge);
-        for (const nodeId of [edge.source_id, edge.target_id]) {
-          if (!visited.has(nodeId)) {
-            visited.add(nodeId);
-            nextIds.push(nodeId);
-          }
+        for (const nid of [edge.source_id, edge.target_id]) {
+          if (!visited.has(nid)) { visited.add(nid); nextIds.push(nid); }
         }
       }
 
       if (nextIds.length) {
-        const ph   = nextIds.map(() => '?').join(',');
-        const rows = this.db.prepare(`
-          SELECT id, content, summary, importance
-          FROM   memories
-          WHERE  agent_id = ? AND id IN (${ph})
-        `).all(this.agentId, ...nextIds);
-        nodes.push(...rows);
-        frontier = nextIds;
-      } else {
-        break;
-      }
+        const ph2  = nextIds.map(() => '?').join(',');
+        const rows = this.db.prepare(`SELECT id, content, summary, importance FROM memories WHERE agent_id=? AND id IN (${ph2})`).all(this.agentId, ...nextIds);
+        nodes.push(...rows); frontier = nextIds;
+      } else { break; }
     }
 
     return { nodes, edges };
   }
 
-  /**
-   * delta(topic, days)
-   * Returns memories added or updated in the last N days on a topic.
-   *
-   * @param {string} topic
-   * @param {number} days
-   * @returns {Promise<Array>}
-   */
+  // ── delta(topic, days) ────────────────────────────────────────────────────
   async delta(topic, days = 7) {
-    const since = Math.floor(Date.now() / 1000) - (days * 86400);
-
+    const since  = Math.floor(Date.now() / 1000) - (days * 86400);
     const recent = this.db.prepare(`
-      SELECT id, content, summary, importance, created_at, updated_at
-      FROM   memories
-      WHERE  agent_id   = ?
-        AND  updated_at >= ?
-      ORDER  BY updated_at DESC
-      LIMIT  100
+      SELECT id, content, summary, importance, created_at, updated_at FROM memories
+      WHERE agent_id=? AND updated_at >= ? ORDER BY updated_at DESC LIMIT 100
     `).all(this.agentId, since);
 
-    // Score against topic
-    const queryVector = await this.embedder.embed(topic);
-    return recent
-      .map(row => {
-        // Quick text match score (no vector needed for delta, but nice to have)
-        const textScore = row.content.toLowerCase().includes(topic.toLowerCase()) ? 0.1 : 0;
-        return { ...row, relevance: textScore };
-      })
-      .sort((a, b) => b.updated_at - a.updated_at);
+    return recent.map(row => ({
+      ...row,
+      relevance: row.content.toLowerCase().includes(topic.toLowerCase()) ? 0.8 : 0.1,
+    })).sort((a, b) => b.updated_at - a.updated_at);
   }
 
-  /**
-   * briefing()
-   * Summary of everything learned in the last 24 hours.
-   * Inject into system prompt at session start.
-   *
-   * @returns {Promise<string>}
-   */
+  // ── briefing() ────────────────────────────────────────────────────────────
   async briefing() {
-    const since = Math.floor(Date.now() / 1000) - 86400;
-
+    const since  = Math.floor(Date.now() / 1000) - 86400;
     const recent = this.db.prepare(`
-      SELECT content, importance
-      FROM   memories
-      WHERE  agent_id   = ?
-        AND  created_at >= ?
-      ORDER  BY importance DESC
-      LIMIT  20
+      SELECT content, importance FROM memories
+      WHERE agent_id=? AND created_at>=? ORDER BY importance DESC LIMIT 20
     `).all(this.agentId, since);
 
     if (!recent.length) return 'No new memories in the last 24 hours.';
-
     return [
       `[SLIPSTREAM BRIEFING — last 24h — ${recent.length} memories]`,
       ...recent.map((r, i) => `${i + 1}. ${r.content}`),
     ].join('\n');
   }
+
+  // ── stats() — used by server-index.js countsByType ────────────────────────
+  stats() {
+    try {
+      const byType = this.db.prepare("SELECT edge_type as type, COUNT(*) as n FROM memories GROUP BY edge_type").all();
+      const total  = this.db.prepare("SELECT COUNT(*) as n FROM memories").get()?.n || 0;
+      const by_type = {};
+      for (const r of byType) by_type[r.type || 'semantic'] = r.n;
+      return { total, by_type };
+    } catch (_) { return { total: 0, by_type: {} }; }
+  }
+
+  // ── store() — compatibility alias for mem.store() calls ───────────────────
+  async store(content, opts = {}) {
+    return this.remember(content, opts);
+  }
+
+  // ── recent(opts) — returns most recent memories ───────────────────────────
+  recent(opts = {}) {
+    const limit = opts.limit || 20;
+    const type  = opts.type  || null;
+    try {
+      if (type) {
+        return this.db.prepare("SELECT * FROM memories WHERE agent_id=? AND edge_type=? ORDER BY created_at DESC LIMIT ?").all(this.agentId, type, limit);
+      }
+      return this.db.prepare("SELECT * FROM memories WHERE agent_id=? ORDER BY created_at DESC LIMIT ?").all(this.agentId, limit);
+    } catch (_) { return []; }
+  }
+
+  // ── remove(id) ────────────────────────────────────────────────────────────
+  remove(id) {
+    try { this.db.prepare("DELETE FROM memories WHERE id=? AND agent_id=?").run(id, this.agentId); } catch (_) {}
+  }
+}
+
+// ─── Boot Banner ──────────────────────────────────────────────────────────────
+
+function printBanner(memory, bootMs, sovereign = false) {
+  const stats = getEmbedderStats();
+  const icon  = stats.ep.includes('ONNX') ? '🚀' : '⚙️ ';
+  console.log('');
+  console.log('  ╔══════════════════════════════════════════════════════╗');
+  console.log('  ║            VEKTOR SLIPSTREAM — ACTIVE                ║');
+  console.log('  ╚══════════════════════════════════════════════════════╝');
+  console.log('');
+  console.log(`  ${icon} EP:        ${stats.ep}`);
+  console.log(`  🧠  Model:     ${stats.mode}`);
+  console.log(`  ⚡  Embed:     ${stats.avgMs}ms (post-warmup)`);
+  console.log(`  💾  DB:        WAL | mmap:1GB | cache:64MB`);
+  console.log(`  🔥  Warm:      ✓`);
+  console.log(`  ⏱  Boot:      ${bootMs}ms total`);
+  console.log('');
+  console.log('  [vektor] Sovereign Agent active');
+  console.log('  [vektor] Law I   \u2713 locality     \u2014 no cloud sync path');
+  console.log('  [vektor] Law II  \u2713 hygiene      \u2014 AUDN on every write');
+  console.log('  [vektor] Law III \u2713 synthesis    \u2014 REM compress-only');
+  console.log('  [vektor] Law IV  \u2713 permanence   \u2014 SQLite persists');
+  if (sovereign) {
+    console.log('  [vektor] Law VIII  sovereign: true \u2014 injection shield active');
+  }
+  console.log('');
 }
 
 // ─── createMemory() — Public API ──────────────────────────────────────────────
 
-/**
- * createMemory(options)
- *
- * Initialises the Slipstream memory engine. Parallel API to vektor-core's
- * createMemory() — drop-in replacement, no code changes needed in agent.
- *
- * @param {object} options
- * @param {string} options.agentId        - Unique agent identifier
- * @param {string} [options.dbPath]       - Path to .db file
- * @param {boolean} [options.silent]      - Suppress boot banner
- * @returns {Promise<SlipstreamMemory>}
- */
 async function createMemory(options = {}) {
   const bootStart = Date.now();
 
   const {
-    agentId    = 'default',
-    dbPath     = './slipstream-memory.db',
-    silent     = false,
-    licenceKey = process.env.VEKTOR_LICENCE_KEY || '',
+    agentId   = 'default',
+    dbPath    = path.join(process.cwd(), 'slipstream-memory.db'),
+    silent    = false,
+    sovereign = false,
   } = options;
 
-  // 0. Validate Polar licence key
-  await validateLicence(licenceKey);
-
-  // 1. Init embedder (hardware probe + ONNX load + pre-warmer)
-  const embedder = new SlipstreamEmbedder();
-  await embedder.init();
+  // Ensure parent directory exists
+  const dir = path.dirname(path.resolve(dbPath));
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
 
-  // 2. Init DB (sqlite-vec + Hyper-PRAGMAs)
-  const db = initSlipstreamDB(dbPath);
+  // Open SQLite
+  const db = loadSQLite(dbPath);
 
-  // 3. Ensure schema exists
+  // Ensure schema
   initSchema(db);
 
+  // Create memory instance
+  const memory = new SlipstreamMemory(db, agentId);
+
+  // Law VIII — Injection Resistance (opt-in)
+  // Wraps memory.remember() with two-tier input screening.
+  // Enable with: createMemory({ sovereign: true })
+  // Performance cost: ~80ms per write (pattern check free, LLM screen ~80ms).
+  if (sovereign) {
+    try {
+      const sovereignModule = require('./sovereign');
+      sovereignModule.wrap(memory);
+      memory._sovereign = true;
+    } catch (e) {
+      console.warn('[vektor] sovereign.js not found — sovereign mode disabled. Copy sovereign.js to the SDK root.');
+      memory._sovereign = false;
+    }
+  }
+
   const bootMs = Date.now() - bootStart;
+  if (!silent) printBanner(memory, bootMs, sovereign);
 
-  // 4. Print audit log banner
-  if (!silent) {
-    const dbStats = getDBStats(db);
-    printBanner(embedder, dbStats, bootMs);
-  }
+  // Start warming xenova in the background (non-blocking)
+  // First recall will be hash-based; subsequent ones will use xenova if available
+  embed('warmup').catch(() => {});
 
-  return new SlipstreamMemory(db, embedder, agentId);
+  return memory;
 }
 
-module.exports = { createMemory };
+module.exports = { createMemory, SlipstreamMemory, cosineSimilarity, _isContradiction };