kodelyth-ecc 2.24.11 → 2.29.0

package/scripts/codebase/index.js

@@ -22,6 +22,52 @@ function getVersion() {
   catch { return null; }
 }
 
+// The binary's `--version` string has proven unreliable: builds have reported an
+// old number (e.g. 0.8.1) while exposing much newer tools and the `--ui` (CBM
+// Lens) flag. So detect what the binary can actually DO from its own help text
+// rather than trusting the version. Pure parser (unit-tested) + a thin probe.
+const KNOWN_CAPABILITIES = {
+  lens:       /--ui\b/,                  // CBM Lens UI (v0.12+)
+  traces:     /\bingest_traces\b/,       // runtime-trace ingestion
+  cypher:     /\bquery_graph\b/,         // Cypher + complexity/hot-path metrics
+  smart_ci:   /\bdetect_changes\b/,      // Smart CI test selection
+  adr:        /\bmanage_adr\b/,          // ADR nodes
+  cross_repo: /cross[-_]repo/,           // cross-repo intelligence
+};
+
+function parseCapabilities(helpText) {
+  const h = String(helpText || '');
+  const caps = {};
+  for (const [name, re] of Object.entries(KNOWN_CAPABILITIES)) caps[name] = re.test(h);
+  return caps;
+}
+
+// When the binary exposes clearly-newer capabilities but reports an old version,
+// the version string is not trustworthy — say so rather than displaying a number
+// ECC would otherwise treat as fact. Returns a note string, or null.
+function versionNote(reportedVersion, caps) {
+  const hasNew   = !!(caps && (caps.lens || caps.traces || caps.cross_repo));
+  const looksOld = !!(reportedVersion && /\b0\.[0-8]\./.test(reportedVersion));
+  if (hasNew && looksOld) {
+    return `binary reports "${reportedVersion}" but exposes newer capabilities — the version string is unreliable; capability detection is authoritative. Run \`kodelythecc codebase install\` to refresh.`;
+  }
+  return null;
+}
+
+// Probe the binary's help (different builds print tools under `--help` or
+// `cli --help`) and parse once. Returns the detected capability map, or all-false
+// if the binary is absent.
+function capabilities() {
+  if (!isInstalled()) return parseCapabilities('');
+  let help = '';
+  for (const argv of [['--help'], ['cli', '--help']]) {
+    try {
+      help += '\n' + execFileSync(BIN, argv, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch { /* try the next help surface */ }
+  }
+  return parseCapabilities(help);
+}
+
 function install({ log = () => {} } = {}) {
   if (isInstalled()) return { installed: false, skipped: true, reason: 'already installed', version: getVersion() };
   if (os.platform() === 'win32') {
@@ -95,7 +141,15 @@ function status() {
   const home = os.homedir();
   const c = path.join(home, '.cache', 'codebase-memory-mcp');
   if (fs.existsSync(c)) cacheDir = c;
-  return { installed: true, version, indexed_projects, cache_dir: cacheDir };
+  const caps = capabilities();
+  return {
+    installed: true,
+    version,
+    version_note: versionNote(version, caps),
+    capabilities: caps,
+    indexed_projects,
+    cache_dir: cacheDir,
+  };
 }
 
 // ── Structural query proxy (thin wrapper over `codebase-memory-mcp cli`) ────
@@ -140,4 +194,7 @@ function dashboardSnapshot() {
   return out;
 }
 
-module.exports = { isInstalled, getVersion, install, autoConfigureAgents, status, query, dashboardSnapshot };
+module.exports = {
+  isInstalled, getVersion, install, autoConfigureAgents, status, query, dashboardSnapshot,
+  capabilities, parseCapabilities, versionNote,
+};

package/scripts/hooks/post-bash-command-log.js

@@ -4,6 +4,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { redact } = require('../lib/redact');
 
 const MAX_STDIN = 1024 * 1024;
 let raw = '';
@@ -20,17 +21,9 @@ const MODE_CONFIG = {
 };
 
 function sanitizeCommand(command) {
-  return String(command || '')
-    .replace(/\n/g, ' ')
-    .replace(/--token[= ][^ ]*/g, '--token=<REDACTED>')
-    .replace(/Authorization:[: ]*[^ ]*[: ]*[^ ]*/gi, 'Authorization:<REDACTED>')
-    .replace(/\bAKIA[A-Z0-9]{16}\b/g, '<REDACTED>')
-    .replace(/\bASIA[A-Z0-9]{16}\b/g, '<REDACTED>')
-    .replace(/password[= ][^ ]*/gi, 'password=<REDACTED>')
-    .replace(/\bghp_[A-Za-z0-9_]+\b/g, '<REDACTED>')
-    .replace(/\bgho_[A-Za-z0-9_]+\b/g, '<REDACTED>')
-    .replace(/\bghs_[A-Za-z0-9_]+\b/g, '<REDACTED>')
-    .replace(/\bgithub_pat_[A-Za-z0-9_]+\b/g, '<REDACTED>');
+  // Flatten to one log line, then run the shared credential redactor (which now
+  // covers more token formats than this hook's old inline list did).
+  return redact(String(command || '').replace(/\n/g, ' '));
 }
 
 function appendLine(filePath, line) {

package/scripts/hooks/session-start.js

@@ -22,6 +22,7 @@ const {
   log
 } = require('../lib/utils');
 const { resolveProjectContext, writeSessionLease, resolveSessionId } = require('../lib/observer-sessions');
+const { summarizeStructuredInstincts } = require('../memory/instinct-inject');
 const { getPackageManager, getSelectionPrompt } = require('../lib/package-manager');
 const { listAliases } = require('../lib/session-aliases');
 const { detectProjectType } = require('../lib/project-detect');
@@ -380,6 +381,30 @@ async function main() {
     additionalContextParts.push(instinctSummary);
   }
 
+  // Also inject from the structured instinct store (scripts/memory/instincts.js).
+  // It was written on every correction but never read — this activates the
+  // dormant self-learning loop. Fully fail-safe: never breaks session start.
+  const structuredInstinctSummary = summarizeStructuredInstincts(
+    (observerContext && observerContext.projectRoot) || process.cwd(),
+    { log }
+  );
+  if (structuredInstinctSummary) {
+    additionalContextParts.push(structuredInstinctSummary);
+  }
+
+  // Surface the auto-capture review queue so candidates the last session proposed
+  // are discoverable now, not just at the end of that session. Consent-first:
+  // this only points at the review command; nothing is stored without the user
+  // running promote-pending.
+  try {
+    const n = require('../memory/pending').countPending();
+    if (n > 0) {
+      additionalContextParts.push(
+        `${n} memory candidate(s) await review — list with "kodelythecc memory list-pending", confirm with "promote-pending <id|all>".`
+      );
+    }
+  } catch { /* never block session start */ }
+
   // Check for recent session files (last 7 days)
   const recentSessions = dedupeRecentSessions(sessionSearchDirs);
 

package/scripts/lib/redact.js

@@ -0,0 +1,58 @@
+// scripts/lib/redact.js
+//
+// One place to scrub credentials out of text before it is stored or logged.
+// Used by the memory capture path (so a leaked key is never written into
+// memories.jsonl, where it would then be surfaced by recall and injected into a
+// future session) and by the bash-command logger.
+//
+// Two rule families:
+//   - High-confidence provider token FORMATS, matched anywhere (prose or a
+//     command line) — AWS, GitHub, OpenAI/Anthropic, Stripe, Slack, Google, npm,
+//     JWTs, PEM private-key blocks.
+//   - Assignment / header forms — `--token=`, `Authorization:`, `password=`,
+//     `api_key=`, etc.
+//
+// Every pattern is linear (no nested quantifiers, no adjacent `\s*\s*`) so none
+// can backtrack catastrophically on hostile input — the ReDoS lesson from the
+// prompt-injection guard applies here too.
+'use strict';
+
+const RULES = [
+  // ── Provider token formats (match anywhere) ──
+  [/-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g, '<REDACTED:private-key>'],
+  [/\bAKIA[0-9A-Z]{16}\b/g, '<REDACTED:aws-key>'],
+  [/\bASIA[0-9A-Z]{16}\b/g, '<REDACTED:aws-temp-key>'],
+  [/\bghp_[A-Za-z0-9]{20,}\b/g, '<REDACTED:github-token>'],
+  [/\bgho_[A-Za-z0-9]{20,}\b/g, '<REDACTED:github-token>'],
+  [/\bghs_[A-Za-z0-9]{20,}\b/g, '<REDACTED:github-token>'],
+  [/\bghr_[A-Za-z0-9]{20,}\b/g, '<REDACTED:github-token>'],
+  [/\bgithub_pat_[A-Za-z0-9_]{22,}\b/g, '<REDACTED:github-pat>'],
+  [/\bsk-ant-[A-Za-z0-9_-]{20,}/g, '<REDACTED:anthropic-key>'],
+  [/\bsk-[A-Za-z0-9_-]{20,}/g, '<REDACTED:openai-key>'],
+  [/\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g, '<REDACTED:stripe-key>'],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, '<REDACTED:slack-token>'],
+  [/\bAIza[0-9A-Za-z_-]{35}\b/g, '<REDACTED:google-key>'],
+  [/\bnpm_[A-Za-z0-9]{36}\b/g, '<REDACTED:npm-token>'],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, '<REDACTED:jwt>'],
+  // ── Assignment / header forms ──
+  [/(--token[= ])\S+/g, '$1<REDACTED>'],
+  [/(Authorization:\s*)(?:Bearer\s+)?\S+/gi, '$1<REDACTED>'],
+  [/(\bpassword\s*[=:]\s*)\S+/gi, '$1<REDACTED>'],
+  [/(\b(?:api[_-]?key|secret|access[_-]?token|auth[_-]?token)\s*[=:]\s*)["']?[A-Za-z0-9\-_.]{8,}["']?/gi, '$1<REDACTED>'],
+];
+
+// Replace any credentials in `text` with labelled placeholders. Non-strings pass
+// through unchanged (null/undefined stay as they are).
+function redact(text) {
+  if (typeof text !== 'string') return text;
+  let out = text;
+  for (const [re, repl] of RULES) out = out.replace(re, repl);
+  return out;
+}
+
+// True when redaction would change the text — i.e. a credential is present.
+function hasSecret(text) {
+  return typeof text === 'string' && redact(text) !== text;
+}
+
+module.exports = { redact, hasSecret, RULES };

package/scripts/lib/state-store/index.js

@@ -3,7 +3,6 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const initSqlJs = require('sql.js');
 
 const { applyMigrations, getAppliedMigrations } = require('./migrations');
 const { createQueryApi } = require('./queries');
@@ -11,6 +10,40 @@ const { assertValidEntity, validateEntity } = require('./schema');
 
 const DEFAULT_STATE_STORE_RELATIVE_PATH = path.join('.claude', 'ecc', 'state.db');
 
+// sql.js is OPTIONAL. It powers the session store, the status DB, and the
+// skill-evolution tracker — not the core (memory, RTK, Terse, codebase graph),
+// which stay pure-JS and need nothing. It used to be required at module load, so
+// importing state-store threw "Cannot find module 'sql.js'" for every install
+// that did not have it (which, since it was never a declared dependency, was all
+// of them) — before any caller's try/catch could run. Load it lazily and turn a
+// missing module into a clean, catchable error instead of an import-time crash.
+function loadSqlJs() {
+  try {
+    return require('sql.js');
+  } catch (cause) {
+    const err = new Error(
+      'SQLite support is unavailable: the optional dependency "sql.js" is not installed. ' +
+      'Install it (npm i sql.js, or reinstall kodelyth-ecc) to enable the session store, ' +
+      'status DB, and skill-evolution tracker. Core memory, RTK, Terse, and the codebase ' +
+      'graph do not need it.'
+    );
+    err.code = 'ECC_SQLITE_UNAVAILABLE';
+    err.cause = cause;
+    throw err;
+  }
+}
+
+// Non-throwing probe for callers and `doctor`: is the optional SQLite layer
+// usable on this install?
+function isSqliteAvailable() {
+  try {
+    require.resolve('sql.js');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function resolveStateStorePath(options = {}) {
   if (options.dbPath) {
     if (options.dbPath === ':memory:') {
@@ -163,6 +196,7 @@ async function openDatabase(SQL, dbPath) {
 
 async function createStateStore(options = {}) {
   const dbPath = resolveStateStorePath(options);
+  const initSqlJs = loadSqlJs();
   const SQL = await initSqlJs();
   const db = await openDatabase(SQL, dbPath);
   const appliedMigrations = applyMigrations(db);
@@ -188,4 +222,5 @@ module.exports = {
   DEFAULT_STATE_STORE_RELATIVE_PATH,
   createStateStore,
   resolveStateStorePath,
+  isSqliteAvailable,
 };

package/scripts/lib/state-store/schema.js

@@ -2,7 +2,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const Ajv = require('ajv');
+// `ajv` is loaded lazily inside getAjv(), NOT at module top. It is an OPTIONAL
+// dependency (it validates the optional SQLite state-store's entities), and
+// requiring it here eagerly made importing state-store throw "Cannot find module
+// 'ajv'" on any install without it — which is every default install, and which
+// broke the pre-publish test step in CI. Same bug class as the sql.js one.
 
 const SCHEMA_PATH = path.join(__dirname, '..', '..', '..', 'schemas', 'state-store.schema.json');
 
@@ -33,6 +37,19 @@ function getAjv() {
     return cachedAjv;
   }
 
+  let Ajv;
+  try {
+    Ajv = require('ajv');
+  } catch (cause) {
+    const err = new Error(
+      'state-store schema validation needs the optional dependency "ajv", which is not installed. ' +
+      'Install it (or reinstall kodelyth-ecc) to enable session-store / status-DB validation.'
+    );
+    err.code = 'ECC_AJV_UNAVAILABLE';
+    err.cause = cause;
+    throw err;
+  }
+
   cachedAjv = new Ajv({
     allErrors: true,
     strict: false,

package/scripts/mcp/register-self.js

@@ -25,6 +25,108 @@ function claudeDesktopConfigPath() {
   return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
 }
 
+// MCP config paths for the non-Claude IDEs ECC can auto-wire via JSON. Every
+// target below uses the SAME `{ mcpServers: { <name>: {...} } }` shape as Claude
+// Code (Kiro included — it is MCP-native), so the hardened readConfig +
+// registerInFile merge works unchanged; only the file location differs. Codex is
+// TOML and handled separately (registerCodexToml).
+//
+// Still manual (fragile, editor-version-specific path): Cline / Roo Code store
+// MCP settings in VS Code globalStorage, so ECC does not guess that path.
+function mcpPathsForTarget(target, cwd = process.cwd()) {
+  const home = os.homedir();
+  switch (target) {
+    case 'claude-code':
+    case 'claude-home':
+      return [claudeCodeConfigPath()];
+    case 'cursor':
+    case 'cursor-project':
+      return [path.join(cwd, '.cursor', 'mcp.json')];
+    case 'windsurf':
+    case 'windsurf-home':
+    case 'windsurf-project':
+      return [path.join(home, '.codeium', 'windsurf', 'mcp_config.json')];
+    case 'gemini-cli':
+    case 'gemini-home':
+    case 'gemini-project':
+      return [path.join(home, '.gemini', 'settings.json')];
+    case 'kiro':
+    case 'kiro-project':
+      return [path.join(cwd, '.kiro', 'settings', 'mcp.json')];
+    case 'kiro-home':
+      return [path.join(home, '.kiro', 'settings', 'mcp.json')];
+    default:
+      return [];
+  }
+}
+
+function codexConfigPath() {
+  return path.join(os.homedir(), '.codex', 'config.toml');
+}
+
+// Codex CLI stores MCP servers in TOML as [mcp_servers.<name>] tables. Without
+// pulling in a TOML parser, add our table only when it is absent (idempotent),
+// and otherwise leave the file exactly as it is. Appending a table is
+// order-independent in TOML, so this never clobbers existing servers or settings.
+function registerCodexToml(file, { dryRun = false } = {}) {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      return { file, action: 'error', error: `cannot read ${file}: ${err.message}` };
+    }
+  }
+  if (/\[mcp_servers\.(?:"?kodelyth-ecc"?)\]/.test(raw)) {
+    return { file, action: 'unchanged' };
+  }
+  const table = `\n[mcp_servers."${SERVER_NAME}"]\ncommand = "kodelythecc"\nargs = ["mcp"]\n`;
+  const next = raw.length && !raw.endsWith('\n') ? `${raw}\n${table}` : `${raw}${table}`;
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    safeFs.replaceFilePreservingMode(file, next);
+  }
+  return { file, action: 'added' };
+}
+
+// Returns the list of targets this module can auto-wire (for help text / docs).
+function supportedMcpTargets() {
+  return ['claude-code', 'cursor', 'windsurf', 'gemini-cli', 'kiro', 'codex'];
+}
+
+// Register ECC's MCP server for one install target. JSON targets reuse the same
+// merge that protects ~/.claude.json (absent → created, present → merged without
+// clobbering, unparseable → refused); Codex uses the TOML writer above. Never
+// throws — a bad config for one IDE must not fail an install.
+function registerForTarget(target, { cwd = process.cwd(), log = () => {}, dryRun = false } = {}) {
+  if (target === 'codex' || target === 'codex-home') {
+    try {
+      const r = registerCodexToml(codexConfigPath(), { dryRun });
+      log(`  ${r.action}: ${r.file}`);
+      return [{ target, ...r }];
+    } catch (e) {
+      log(`  skipped codex: ${e.message}`);
+      return [{ target, file: codexConfigPath(), action: 'error', error: e.message }];
+    }
+  }
+  const paths = mcpPathsForTarget(target, cwd);
+  if (paths.length === 0) {
+    return [{ target, action: 'unsupported', reason: `no known MCP config path for "${target}"` }];
+  }
+  const results = [];
+  for (const p of paths) {
+    try {
+      const r = registerInFile(p, { dryRun });
+      log(`  ${r.action}: ${r.file}`);
+      results.push({ target, ...r });
+    } catch (e) {
+      log(`  skipped ${p}: ${e.message}`);
+      results.push({ target, file: p, action: 'error', error: e.message });
+    }
+  }
+  return results;
+}
+
 // Reading this file has THREE outcomes, and collapsing them is destructive.
 //
 // readJson used to return null for every failure, and the caller did
@@ -145,9 +247,19 @@ function unregisterAll({ log = () => {} } = {}) {
 function statusAll() {
   const rows = [];
   for (const p of [claudeCodeConfigPath(), claudeDesktopConfigPath()]) {
-    const cfg = readJson(p);
-    const present = !!(cfg && cfg.mcpServers && cfg.mcpServers[SERVER_NAME]);
-    rows.push({ file: p, present, exists: !!cfg });
+    // Was `readJson(p)` — a function that no longer exists after the
+    // absent/present/unreadable refactor, so statusAll() threw
+    // "readJson is not defined" and took `kodelythecc doctor` and the `mcp`
+    // status command down with it. Use the real reader and its tri-state result.
+    const cfg = readConfig(p);
+    const data = (cfg && cfg.data) || {};
+    const present = !!(data.mcpServers && data.mcpServers[SERVER_NAME]);
+    rows.push({
+      file: p,
+      present,
+      exists: cfg.state !== 'absent',
+      readable: cfg.state !== 'unreadable',
+    });
   }
   return rows;
 }
@@ -157,6 +269,11 @@ module.exports = {
   serverEntry,
   claudeCodeConfigPath,
   claudeDesktopConfigPath,
+  mcpPathsForTarget,
+  supportedMcpTargets,
+  registerForTarget,
+  registerCodexToml,
+  codexConfigPath,
   registerAll,
   unregisterAll,
   statusAll,

package/scripts/memory/cli.js

@@ -19,6 +19,7 @@ const path = require('path');
 const store   = require('./store');
 const { buildContextBlock } = require('./inject');
 const { extractCandidates } = require('./extract');
+const pending = require('./pending');
 
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -190,6 +191,40 @@ function main() {
       return;
     }
 
+    // ── Auto-capture review queue ────────────────────────────────────────────
+    // The Stop hook auto-extracts candidates from each session into the queue;
+    // these three commands are the consent gate that turns them into memories.
+    case 'list-pending':
+    case 'review-pending': {
+      const items = pending.listPending();
+      if (items.length === 0) { console.log('No memory candidates pending review.'); return; }
+      console.log(`${items.length} candidate(s) pending review:\n`);
+      items.forEach((c) => {
+        console.log(`[${c.id}] (score ${c.score ?? '-'})  ${c.problem}`);
+        console.log(`    tags:     ${(c.tags || []).join(', ') || '-'}`);
+        console.log(`    approach: ${String(c.approach).slice(0, 200)}`);
+        console.log('');
+      });
+      console.log('Confirm with: memory promote-pending <id|all>   ·   drop with: memory discard-pending <id|all>');
+      return;
+    }
+
+    case 'promote-pending': {
+      const sel = positional[0] || 'all';
+      const stored = pending.promotePending(sel === 'all' ? 'all' : sel);
+      if (stored.length === 0) { console.log('Nothing promoted (no matching pending candidate).'); return; }
+      console.log(`Stored ${stored.length} memor${stored.length === 1 ? 'y' : 'ies'}:`);
+      stored.forEach(m => console.log(`  ${m.id}  ${m.problem}`));
+      return;
+    }
+
+    case 'discard-pending': {
+      const sel = positional[0] || 'all';
+      const n = pending.discardPending(sel === 'all' ? 'all' : sel);
+      console.log(`Discarded ${n} pending candidate(s).`);
+      return;
+    }
+
     default:
       console.error(`Unknown command: ${cmd}`);
       help();

package/scripts/memory/embedding-providers/local-transformers.js

@@ -0,0 +1,44 @@
+// scripts/memory/embedding-providers/local-transformers.js
+//
+// Local, on-device embedding provider. Runs a small sentence-embedding model
+// through the OPTIONAL `@xenova/transformers` dependency (WASM/ONNX — no native
+// build). After the model is cached once, inference is fully on-device, so the
+// "100% local, zero-network" property holds at recall time; only the first-ever
+// load fetches the model.
+//
+// This module is required ONLY when the user has opted into embeddings
+// (KODELYTH_MEMORY_EMBEDDINGS=on). If the optional dependency is not installed,
+// the require throws and embeddings.getProvider() catches it and falls back to
+// BM25 — so a default install never needs this and never loads it.
+//
+// Not exercised by the CI suite (it needs the heavy optional dependency and a
+// model download); the fusion/gating logic it feeds IS covered, via a stub
+// provider, in tests/memory/embeddings.test.js.
+'use strict';
+
+const MODEL = process.env.KODELYTH_EMBEDDING_MODEL || 'Xenova/all-MiniLM-L6-v2';
+
+let _pipelinePromise = null;
+
+async function createProvider() {
+  // require is inside the function so a missing optional dependency surfaces to
+  // the caller (embeddings.getProvider) as a catchable error, not an import-time
+  // crash of the memory module.
+  const { pipeline } = require('@xenova/transformers');
+  if (!_pipelinePromise) {
+    _pipelinePromise = pipeline('feature-extraction', MODEL);
+  }
+  const extractor = await _pipelinePromise;
+  return {
+    model: MODEL,
+    async embed(text) {
+      if (!text) return null;
+      // Mean-pooled, L2-normalized sentence embedding — the standard recipe for
+      // all-MiniLM-style models. output.data is a Float32Array.
+      const output = await extractor(String(text), { pooling: 'mean', normalize: true });
+      return Array.from(output.data);
+    },
+  };
+}
+
+module.exports = { createProvider, MODEL };

package/scripts/memory/embeddings.js

@@ -0,0 +1,98 @@
+// scripts/memory/embeddings.js
+//
+// OPTIONAL, OFF BY DEFAULT semantic layer for memory recall. The default recall
+// path stays pure BM25 — sync, zero-dependency, zero-network — exactly as
+// advertised. This module only does anything when a user opts in
+// (KODELYTH_MEMORY_EMBEDDINGS=on) AND a local embedding provider is actually
+// available. If either is false, every function here degrades to "no semantics",
+// and recall falls back to BM25 unchanged.
+//
+// The provider is pluggable: the real one (scripts/memory/embedding-providers/
+// local-transformers.js) runs a local model via the optional `@xenova/
+// transformers` dependency, so inference is on-device. Tests inject a
+// deterministic stub instead, so the fusion/gating logic is verified without the
+// heavy dependency or a model download.
+'use strict';
+
+// Test seam: when set (including to null), overrides provider resolution.
+let _providerOverride;
+let _hasOverride = false;
+
+function _setProviderForTest(provider) { _providerOverride = provider; _hasOverride = true; }
+function _clearProviderForTest() { _providerOverride = undefined; _hasOverride = false; }
+
+// Off unless explicitly enabled. Keeps the default session zero-network/zero-dep.
+function isEnabled() {
+  const v = String(process.env.KODELYTH_MEMORY_EMBEDDINGS || '').trim().toLowerCase();
+  return v === '1' || v === 'on' || v === 'true' || v === 'yes';
+}
+
+// Resolve the embedding provider, or null. Null means "no semantics" — a
+// disabled flag, a missing optional dependency, or a load failure all collapse
+// to the same safe BM25-only behaviour.
+async function getProvider() {
+  if (_hasOverride) return _providerOverride;
+  if (!isEnabled()) return null;
+  try {
+    const { createProvider } = require('./embedding-providers/local-transformers');
+    return await createProvider();
+  } catch {
+    return null; // optional dep not installed, or model load failed
+  }
+}
+
+// Cosine similarity of two equal-length numeric vectors. Returns 0 for missing,
+// mismatched, or zero-magnitude vectors rather than NaN, so it is always safe to
+// sort by.
+function cosineSim(a, b) {
+  if (!a || !b || a.length === 0 || a.length !== b.length) return 0;
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+// Fuse BM25 relevance with semantic similarity and re-rank. Pure function.
+//
+//   results:  BM25 results, each { id, score, ... }, already relevance-ranked
+//   queryVec: the query embedding (or null → returns results unchanged)
+//   vecById:  { [id]: vector } for whichever results have a stored embedding
+//   weight:   semantic weight in [0,1] (default 0.5). final =
+//             weight*semantic + (1-weight)*bm25norm, with BM25 min-max normalized
+//             across this result set. A result with no stored vector keeps its
+//             BM25-normalized score (semantic contribution 0), so missing
+//             embeddings never push a relevant memory down unfairly.
+function fuseHybrid(results, { queryVec, vecById = {}, weight = 0.5 } = {}) {
+  if (!Array.isArray(results) || results.length === 0) return results || [];
+  if (!queryVec) return results;
+
+  const scores = results.map(r => r.score || 0);
+  const min = Math.min(...scores);
+  const max = Math.max(...scores);
+  const span = max - min;
+  const norm = (s) => (span === 0 ? 1 : (s - min) / span);
+
+  const w = Math.min(1, Math.max(0, weight));
+  return results
+    .map(r => {
+      const vec = vecById[r.id];
+      const bm25n = norm(r.score || 0);
+      const sem = vec ? Math.max(0, cosineSim(queryVec, vec)) : bm25n;
+      const fused = w * sem + (1 - w) * bm25n;
+      return { ...r, _bm25norm: bm25n, _semantic: vec ? sem : null, _hybrid: fused };
+    })
+    .sort((a, b) => b._hybrid - a._hybrid);
+}
+
+module.exports = {
+  isEnabled,
+  getProvider,
+  cosineSim,
+  fuseHybrid,
+  _setProviderForTest,
+  _clearProviderForTest,
+};