@lotargo/memory_plugin 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to `@lotargo/memory_plugin` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.1] - 2026-08-10
+
+### Fixed
+
+- **Cryptic crash on Node.js < 22.5.0** (`No such built-in module: node:sqlite`).
+  ESM static imports are hoisted, so the `node:sqlite` import in `database.js`
+  crashed before any user code could run.  Three layers of protection are now in
+  place:
+  1. **Boot guard** (`boot.js` / `cli_boot.js`): new lightweight entry points
+     that check `process.versions.node` *before* loading the ESM module graph.
+     On incompatible versions they print a clear boxed error with upgrade
+     instructions (`nvm install 22` / `brew install node@22`) and exit.
+  2. **`engine-strict`** (`.npmrc`): `npm install` now **fails** instead of
+     merely warning when `engines.node >= 22.5.0` is not satisfied.
+  3. **Preinstall warning** (`preinstall.js`): a prominent `stderr` message is
+     printed during installation on unsupported Node versions, explaining that
+     the server will not start.
+- Process-kill patterns in `preinstall.js` now match the new `boot.js` entry
+  point in addition to `index.js`, so global updates correctly terminate running
+  server instances.
+
+### Changed
+
+- All `bin` entry points (`memory_plugin`, `memory-agent`, `memory-cli`) now
+  route through `boot.js` / `cli_boot.js` instead of directly to `index.js` /
+  `cli.js`.
+- `.npmrc` is no longer git-ignored; it contains only the project-level
+  `engine-strict=true` setting (npm never publishes `.npmrc` to the tarball).
+
 ## [1.6.0] - 2026-08-10
 
 This release is the outcome of a full five-part audit (publishing, security, code
@@ -105,4 +134,5 @@ a critical retrieval regression introduced after `v1.5.3`.
 - `BENCHMARKS.md` tables were re-derived from the stored JSON artifacts; the
   bge-m3 section had carried e5-small numbers shifted by a column.
 
+[1.6.1]: https://github.com/Lotargo/memory_pugin/releases/tag/v1.6.1
 [1.6.0]: https://github.com/Lotargo/memory_pugin/releases/tag/v1.6.0

package/README.md

@@ -334,18 +334,41 @@ The engine is configured through `<memory-dir>/config.json` (created with defaul
 
 ## Testing & Benchmarking
 
-To run the automated test suite and benchmarks locally:
+To run the automated test suite and benchmarks locally, from the repository root:
 
 ```bash
-cd mcp-server
-
-# Run unit and integration tests
+# Unit + integration + cloud suites (12 files) — fast and fully offline
 npm test
 
-# Run search quality & ingestion benchmarks
+# End-to-end smoke test with REAL ONNX embeddings — run before a release
+npm run smoke
+
+# Search quality & ingestion benchmarks
 npm run benchmark
 ```
 
+### Two testing modes, and why both exist
+
+`npm test` runs every suite with `generateEmbeddings: false`. That keeps it fast
+and offline (no model download, no network), but it means the **dense-vector half
+of the engine is never exercised** — retrieval falls back to BM25-only.
+
+`npm run smoke` covers exactly that blind spot: it ingests a document with real
+ONNX vectors and asserts that hybrid retrieval returns a non-zero cosine
+similarity, plus that a Russian query still reaches an English document
+(something BM25 cannot do). It also walks the full user journey — remember →
+recall → ingest → query → link → update → get → forget — and checks the ingest
+path guard.
+
+This split is not academic: a regression in `v1.5.3+` disabled vector search
+entirely (`node:sqlite` returns BLOBs as `Uint8Array`, and a `Buffer.isBuffer()`
+guard discarded every stored vector) while all offline suites stayed green. The
+smoke test exists so that class of failure cannot ship unnoticed again.
+
+The smoke test reuses the model weights already cached in your data directory, so
+it does not re-download them. Point `MEMORY_MODEL_CACHE` at a cache directory to
+override the lookup; without any cache the weights are fetched once.
+
 For complete methodology details and search quality evaluation metrics, see [`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md).
 
 ### Empirical Search Quality Results

package/mcp-server/boot.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+// ── Boot Guard ──────────────────────────────────────────────────────────────
+// This file is the true entry point for both `memory_plugin` and `memory-agent`
+// binaries.  Its sole purpose is to verify the Node.js version BEFORE the ESM
+// module graph is evaluated — because `mcp-server/index.js` transitively
+// imports `node:sqlite` (a built-in available only from Node 22.5.0), and ESM
+// static imports are hoisted, so a version check inside that file would never
+// execute.
+//
+// By keeping this file free of any `node:sqlite` dependency we can print a
+// clear, actionable error message instead of the cryptic
+//   "No such built-in module: node:sqlite"
+// that users on Node 18/20/21 would otherwise see.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MIN_MAJOR = 22;
+const MIN_MINOR = 5;
+
+const [major, minor] = process.versions.node.split(".").map(Number);
+
+if (major < MIN_MAJOR || (major === MIN_MAJOR && minor < MIN_MINOR)) {
+  process.stderr.write(
+    `\n` +
+    `  ╔══════════════════════════════════════════════════════════════════╗\n` +
+    `  ║  @lotargo/memory_plugin requires Node.js >= 22.5.0             ║\n` +
+    `  ║                                                                ║\n` +
+    `  ║  Detected: Node.js ${process.versions.node.padEnd(44)}║\n` +
+    `  ║                                                                ║\n` +
+    `  ║  The built-in node:sqlite module used by this plugin was       ║\n` +
+    `  ║  introduced in Node.js 22.5.0.  Please upgrade your           ║\n` +
+    `  ║  Node.js installation:                                        ║\n` +
+    `  ║                                                                ║\n` +
+    `  ║    nvm install 22   # or: brew install node@22                 ║\n` +
+    `  ║                                                                ║\n` +
+    `  ╚══════════════════════════════════════════════════════════════════╝\n` +
+    `\n`
+  );
+  process.exit(1);
+}
+
+// Version is OK — hand off to the real entry point.
+import("./index.js");

package/mcp-server/cli_boot.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+// ── CLI Boot Guard ──────────────────────────────────────────────────────────
+// Same version check as boot.js — see that file for the rationale.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MIN_MAJOR = 22;
+const MIN_MINOR = 5;
+
+const [major, minor] = process.versions.node.split(".").map(Number);
+
+if (major < MIN_MAJOR || (major === MIN_MAJOR && minor < MIN_MINOR)) {
+  process.stderr.write(
+    `\n` +
+    `  ╔══════════════════════════════════════════════════════════════════╗\n` +
+    `  ║  @lotargo/memory_plugin requires Node.js >= 22.5.0             ║\n` +
+    `  ║                                                                ║\n` +
+    `  ║  Detected: Node.js ${process.versions.node.padEnd(44)}║\n` +
+    `  ║                                                                ║\n` +
+    `  ║  The built-in node:sqlite module used by this plugin was       ║\n` +
+    `  ║  introduced in Node.js 22.5.0.  Please upgrade your           ║\n` +
+    `  ║  Node.js installation:                                        ║\n` +
+    `  ║                                                                ║\n` +
+    `  ║    nvm install 22   # or: brew install node@22                 ║\n` +
+    `  ║                                                                ║\n` +
+    `  ╚══════════════════════════════════════════════════════════════════╝\n` +
+    `\n`
+  );
+  process.exit(1);
+}
+
+// Version is OK — hand off to the real CLI.
+import("./cli.js").then(m => {
+  if (process.argv[1] && process.argv[1].includes("cli_boot.js")) {
+    m.runCli().catch((err) => console.error("CLI error:", err));
+  }
+});

package/mcp-server/preinstall.js

@@ -5,6 +5,27 @@ if (process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.DEBIAN_F
   process.exit(0);
 }
 
+// ── Node version warning ────────────────────────────────────────────────────
+// engines.node >= 22.5.0 is set in package.json but npm only warns by default.
+// Print a loud, actionable message so the user notices before the server crashes.
+{
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (major < 22 || (major === 22 && minor < 5)) {
+    console.error(
+      `\n` +
+      `  ⚠️  @lotargo/memory_plugin requires Node.js >= 22.5.0\n` +
+      `     Detected: Node.js ${process.versions.node}\n` +
+      `\n` +
+      `     The built-in node:sqlite module used by this plugin was\n` +
+      `     introduced in Node.js 22.5.0.  The server WILL NOT START\n` +
+      `     on your current version.\n` +
+      `\n` +
+      `     Please upgrade:  nvm install 22   (or: brew install node@22)\n`
+    );
+  }
+}
+
+
 // Only run graceful process termination during explicit global npm updates
 if (process.env.npm_config_global === "true" || process.env.MEMORY_PREINSTALL_FORCE === "true") {
   try {
@@ -13,7 +34,7 @@ if (process.env.npm_config_global === "true" || process.env.MEMORY_PREINSTALL_FO
 
     if (process.platform === "win32") {
       try {
-        const psCmd = `Get-CimInstance Win32_Process | Where-Object { ($_.CommandLine -like '*mcp-server/index.js*' -or $_.CommandLine -like '*mcp-server\\\\index.js*') -and $_.CommandLine -notlike '*install*' -and $_.ProcessId -ne ${currentPid} -and $_.ProcessId -ne ${ppid} } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }`;
+        const psCmd = `Get-CimInstance Win32_Process | Where-Object { ($_.CommandLine -like '*mcp-server/boot.js*' -or $_.CommandLine -like '*mcp-server\\\\boot.js*' -or $_.CommandLine -like '*mcp-server/index.js*' -or $_.CommandLine -like '*mcp-server\\\\index.js*') -and $_.CommandLine -notlike '*install*' -and $_.ProcessId -ne ${currentPid} -and $_.ProcessId -ne ${ppid} } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }`;
         execSync(`powershell -NoProfile -NonInteractive -Command "${psCmd}"`, { stdio: "ignore" });
       } catch {}
     } else {
@@ -30,7 +51,7 @@ if (process.env.npm_config_global === "true" || process.env.MEMORY_PREINSTALL_FO
 
           if (!pid || pid === currentPid || pid === ppid || parentPid === currentPid) continue;
 
-          const isServer = cmd.includes("mcp-server/index.js") || cmd.includes("mcp-server/index.js");
+          const isServer = cmd.includes("mcp-server/boot.js") || cmd.includes("mcp-server/index.js");
           const isInstaller = /npm|npx|yarn|pnpm|preinstall|install/i.test(cmd);
 
           if (isServer && !isInstaller) {

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@lotargo/memory_plugin",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "100% local hybrid RAG memory for AI coding agents (OpenCode, Claude Code, Codex, Antigravity). MCP server + plugin: persistent user facts, document ingestion, vector + SQLite FTS5 retrieval across sessions.",
   "type": "module",
   "main": "opencode-plugin/index.js",
   "scripts": {
     "preinstall": "node mcp-server/preinstall.js || true",
     "test": "node tests/run_all.js",
+    "smoke": "node tests/smoke/e2e_real_embeddings.test.js",
     "benchmark": "node mcp-server/benchmarks/run_benchmarks.js"
   },
   "bin": {
-    "memory_plugin": "mcp-server/index.js",
-    "memory-agent": "mcp-server/index.js",
-    "memory-cli": "mcp-server/cli.js"
+    "memory_plugin": "mcp-server/boot.js",
+    "memory-agent": "mcp-server/boot.js",
+    "memory-cli": "mcp-server/cli_boot.js"
   },
   "files": [
     "CHANGELOG.md",
@@ -28,6 +29,8 @@
     "mcp-server/security",
     "mcp-server/storage",
     "mcp-server/tools",
+    "mcp-server/boot.js",
+    "mcp-server/cli_boot.js",
     "mcp-server/cli.js",
     "mcp-server/index.js",
     "mcp-server/fact_format.js",