open-memex 0.7.0 → 0.7.1

package/AGENTS.md

@@ -16,6 +16,8 @@ via `prepublishOnly` — Node refuses `--experimental-strip-types` for files und
 
 `src/store/db.ts` picks the backend at runtime by sniffing `globalThis.Bun`. Both backends share the same surface (`new Database(path)`, `.exec`, `.prepare().run/all/get`, `.close`). Any DB code you write must stay on that common subset — do not import `better-sqlite3` or `bun:sqlite` directly outside `db.ts`. The Node driver is pinned to the `better-sqlite3` 13 N-API line (D72): the pre-13 `node::ObjectWrap` build aborts intermittently on Node 24.19+ when a prepared statement is finalized by GC.
 
+D74 — the Node floor is **22.14**, not 22.6. `better-sqlite3` 13 is compiled against Node-API 10, which Node gained in 22.14.0; below that floor `require()` succeeds and `new Database()` segfaults the process with no diagnostic (measured: Node 22.12.0 dies with `0xC0000005` on win32-x64, Node 22.23.3 / 24.20.0 are fine; upstream WiseLibs/better-sqlite3#1514). The gate lives in `src/runtime-floor.ts` (pure, unit-tested) and is enforced in `loadDatabase` (`src/store/db.ts`) so every entry point fails with an actionable message instead of a silent crash; `doctor` reports the floor plus a live driver probe run in a child process (a segfault cannot be caught in-process, so the probe must be spawned, and it must resolve the driver from this package's directory, not the caller's cwd). `engines.node` is `>=22.14.0`. Never lower it back to the `--experimental-strip-types` floor of 22.6 — that number is a different constraint and predates the driver bump.
+
 Tool logic is host-agnostic and lives in `src/tools/ops.ts` (plain functions + shared zod arg shapes + `TOOL_DESCRIPTIONS`). `src/tools/memory.ts` (opencode) and `src/mcp.ts` are thin adapters — when adding or changing a tool, change `ops.ts` once and both hosts pick it up.
 
 **Plugin code must not runtime-import a host SDK package** (D58, extended by D60): `@opencode-ai/plugin` (v1) and `@opencode/plugin` (v2) are devDependencies, and neither host resolves them for plugins loaded from a global npm install — the import fails and the host silently skips the plugin (no error, no tools). Type-only imports are fine. `src/tools/memory.ts` carries a local stand-in for the v1 SDK's `tool()` (a runtime identity), and `src/opencode-v2.ts` duck-types the v2 context, for exactly this reason. The plugin entry is a dual export (`{ id, setup, server }`, D60): v1 ≥1.18.29 calls `server`, opencode 2 calls `setup`; both adapt `src/plugin-core.ts`.
@@ -170,9 +172,9 @@ Context injection happens exactly once per session in `experimental.chat.system.
 
 ## Design constraints — read the frozen design first
 
-`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D73; open questions tracked at the end of the doc). Per its §12:
+`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D74; open questions tracked at the end of the doc). Per its §12:
 AGENTS.md answers "how should AI work here"; the design doc answers "why is it
-built this way" (principles, iron rules, the append-only decision log, currently D1–D73). Before changing
+built this way" (principles, iron rules, the append-only decision log, currently D1–D74). Before changing
 architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
 schema, MCP tools, CLI contract), read the relevant design section — the decision
 log records what was already considered and rejected.

package/CHANGELOG.md

@@ -9,6 +9,17 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-10-04
+
+## The Node floor is 22.14, because the driver says so (D74)
+
+- **Fixed: every command could die with no output on Node older than 22.14.** `better-sqlite3` 13 (the D72 N-API line) is compiled against Node-API 10, which Node only gained in **22.14.0**. Below that, `require()` succeeds and the first `new Database()` segfaults the process - no message, no stack, exit 139 on macOS/Linux and `0xC0000005` on Windows. Reproduced on win32-x64 with Node 22.12.0; Node 22.23.3 and 24.20.0 are fine, and Node 20 can never work with v13 (upstream [WiseLibs/better-sqlite3#1514](https://github.com/WiseLibs/better-sqlite3/issues/1514), open). open-memex now refuses to load the driver below the floor and says exactly what to do (upgrade Node, or pin `better-sqlite3@^12.11.1`) instead of dying.
+- **`engines.node` corrected to `>=22.14.0`.** It claimed `>=22.6`, which was the `--experimental-strip-types` floor - a different constraint that predates the driver bump, and wrong for the driver.
+- **`open-memex doctor` gained a `sqlite driver` check** that loads the driver and opens an in-memory database in a **child process** (a segfault cannot be caught in-process) and reports the exit code or signal. It resolves the driver from this package's own directory, so it works when `doctor` runs with cwd set to a user project.
+- Both READMEs gained a troubleshooting entry for the crash signature (`exit 139` / `0xC0000005` / "Segmentation fault"). No protocol, schema, or data change.
+
+## [0.7.0] - 2026-10-04
+
 ## One thing you said is one memory (D73)
 
 Saying "remember ." used to save the same statement up to three times: the keyword hook stored your sentence verbatim with no agent in the loop, then the agent - which could see the chat but not the store - saved its own paraphrase beside it, and `memory_add`'s near-duplicate check scored the two too far apart (0.21-0.38 against a 0.80 bar) to notice. `open-memex audit` reported zero near-duplicates while three copies sat in the folder, and search returned all of them.

package/README.md

@@ -53,7 +53,7 @@ depth once you're up and running.
 
 ## Quick start
 
-You need **Node.js ≥ 22.6** (check with `node -v`). Then:
+You need **Node.js ≥ 22.14** (check with `node -v`). Then:
 
 ```sh
 npm install -g open-memex
@@ -163,7 +163,9 @@ no one remembers to write down.
 
 ### Requirements
 
-- **Node.js ≥ 22.6** (`open-memex doctor` verifies this for you)
+- **Node.js ≥ 22.14** (`open-memex doctor` verifies this for you). The floor is
+  the SQLite driver's: `better-sqlite3` 13 is built against Node-API 10, which
+  Node gained in 22.14.0 — older Node segfaults on the first database open.
 
 ### Install the CLI
 
@@ -805,6 +807,18 @@ walks through the mental model end to end.
 
 ## Troubleshooting
 
+**Every command dies with no output, or the process crashes (`exit 139`,
+`0xC0000005`, "Segmentation fault").**
+Your Node is older than **22.14** and the bundled SQLite driver cannot load on
+it. `better-sqlite3` 13 is compiled against Node-API 10, which Node only gained
+in 22.14.0; on anything older `require()` succeeds and then the first database
+open segfaults the process with no diagnostic. open-memex now refuses to load
+the driver and says so, but anything already crashing was almost certainly this.
+Check with `node -v`, then either upgrade Node (`nvm install 22.14 && nvm use
+22.14`, or any current 22.x/24.x) or pin the driver down with `npm install
+better-sqlite3@^12.11.1`. `open-memex doctor` reports both the Node floor and a
+live driver probe. Known upstream: WiseLibs/better-sqlite3#1514.
+
 **`open-memex` is not recognized / command not found.**
 A global `npm install -g` puts the `open-memex` launcher in npm's global bin
 folder. If your terminal can't find it, that folder isn't on your `PATH`:
@@ -915,6 +929,14 @@ the Copilot instructions. With no `--client` it cleans up every detected
 editor; `--global` limits the cleanup to user-level wiring. Your memories are
 never touched.
 
+**I upgraded Node, or switched versions with nvm. Do I need to reinstall?**
+The package itself doesn't care: its SQLite driver is a Node-API prebuild, so
+it loads on any supported Node (≥ 22.14) with no recompiling, and your
+memories live outside the install. But version managers (nvm and friends)
+keep a separate global package folder per Node version, so after a switch
+`open-memex` may simply be "not found". Run `npm install -g open-memex` once
+under the new Node, then `open-memex doctor` to confirm the driver loads.
+
 ## Project status
 
 open-memex is stable and in daily use; the current stable line is published on

package/README.zh-CN.md

@@ -42,7 +42,7 @@
 
 ## 快速开始
 
-需要 **Node.js ≥ 22.6**（用 `node -v` 检查）。然后：
+需要 **Node.js ≥ 22.14**（用 `node -v` 检查）。然后：
 
 ```sh
 npm install -g open-memex
@@ -118,7 +118,7 @@ open-memex 用两种方式接编辑器：原生的 **opencode 插件**，和标
 
 ### 环境要求
 
-- **Node.js ≥ 22.6**（`open-memex doctor` 会替你核查）
+- **Node.js ≥ 22.14**（`open-memex doctor` 会替你核查）。这个下限来自 SQLite 驱动：`better-sqlite3` 13 是按 Node-API 10 编译的，而 Node 直到 22.14.0 才支持它——更老的 Node 在第一次打开数据库时会直接段错误崩溃。
 
 ### 安装 CLI
 
@@ -561,6 +561,9 @@ npx -y open-memex mcp        # 无需安装
 
 ## 故障排查
 
+**每条命令都毫无输出地死掉，或进程直接崩溃（`exit 139`、`0xC0000005`、"Segmentation fault"）。**
+你的 Node 比 **22.14** 老，内置的 SQLite 驱动在它上面加载不了。`better-sqlite3` 13 是按 Node-API 10 编译的，而 Node 直到 22.14.0 才支持；在更老的版本上 `require()` 会成功，然后第一次打开数据库就把进程段错误掉，没有任何诊断信息。open-memex 现在会拒绝加载驱动并明确告诉你，但如果之前就是毫无输出一路崩溃，基本可以确定是这个原因。用 `node -v` 确认后，二选一：升级 Node（`nvm install 22.14 && nvm use 22.14`，或任意当前的 22.x/24.x），或者把驱动降回去：`npm install better-sqlite3@^12.11.1`。`open-memex doctor` 会同时报告 Node 下限和一次真实的驱动探测。上游已知问题：WiseLibs/better-sqlite3#1514。
+
 **`open-memex` 无法识别 / 命令找不到。**
 全局 `npm install -g` 把 `open-memex` 启动器放在 npm 的全局 bin 文件夹里。终端找不到命令，就是这个文件夹不在 PATH 上：
 
@@ -607,6 +610,9 @@ Windows 上已加载的 DLL 是锁定的：如果 open-memex 的 MCP 服务器
 **VS Code——`init` 跑一次还是每个项目跑？**
 跑一次就够。直接 `open-memex init` 会自动检测 VS Code 并把 MCP 服务器条目写进 VS Code 的用户级 `mcp.json`（Windows 在 `%APPDATA%/Code/User/mcp.json`，macOS 在 `~/Library/Application Support/Code/User/mcp.json`，Linux 在 `~/.config/Code/User/mcp.json`），服务器在每个项目都会启动。项目里有项目级 `.vscode/mcp.json` 时仍以它优先，而该条目保留 `cwd=${workspaceFolder}`，所以项目作用域按窗口各自解析。如果你的 用户级 `mcp.json` 里有注释（VS Code 接受 JSONC），`init` 不动它，会打印确切片段让你手动添加。空文件会被当作空白，直接写入。
 
+**我升级了 Node，或者用 nvm 切换了版本，需要重装 open-memex 吗？**
+包本身不用：它的 SQLite 驱动是 Node-API 预编译的，在任何受支持的 Node（≥ 22.14）上都能直接加载、不需要重新编译；你的记忆也不在安装目录里。但 nvm 这类版本管理器会给每个 Node 版本留一份独立的全局包目录，切换之后 `open-memex` 可能就"找不到"了。在新 Node 下跑一次 `npm install -g open-memex`，再用 `open-memex doctor` 确认驱动能正常加载。
+
 **怎么移除编辑器接线？**
 `open-memex uninstall` 撤销 `init`：移除 MCP 服务器条目、opencode 插件行、Agent Skill 目录，以及 Copilot 指令里的 open-memex 段落。不带 `--client` 时清理所有检测到的编辑器；`--global` 把清理限制在用户级接线。你的记忆永不被动。
 

package/dist/.build-stamp

@@ -1 +1 @@
-c84b05d4afadebb4346f31a95ca00c4075a700269fc5019453799d0eeeb8b09e
+f8c82ea850a33c28a396d33675b9d22b1b99cf19cef5e828252fb0400b1154e6

package/dist/doctor.js

@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG, stripJsonComments } from "./config.js";
 import { paths, homeOverride } from "./paths.js";
 import { resolveCwdScope } from "./scope.js";
+import { MIN_NODE_VERSION, nativeDriverFloorMessage, nodeSupportsNativeDriver, } from "./runtime-floor.js";
 import { db, backendName } from "./store/db.js";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.js";
 // D64: the MCP server exposes eleven tools; checking only the five the
@@ -29,12 +30,69 @@ const EXPECTED_TOOLS = [
 ];
 function nodeCheck() {
     const [major, minor] = process.versions.node.split(".").map(Number);
-    const ok = major > 22 || (major === 22 && minor >= 6);
-    return {
-        name: "node",
-        ok,
-        detail: `v${process.versions.node} (need >= 22.6 for --experimental-strip-types)`,
-    };
+    // Two independent floors, and the higher one wins: 22.6 for
+    // --experimental-strip-types, 22.14 for the native SQLite driver (D74).
+    const stripTypesOk = major > 22 || (major === 22 && minor >= 6);
+    const driverOk = nodeSupportsNativeDriver(process.versions.node);
+    const ok = stripTypesOk && driverOk;
+    let detail = `v${process.versions.node}`;
+    if (!stripTypesOk) {
+        detail += ` (need >= 22.6 for --experimental-strip-types)`;
+    }
+    else if (!driverOk) {
+        detail += ` (need >= ${MIN_NODE_VERSION}: better-sqlite3 13 is built against Node-API 10 and segfaults below it)`;
+    }
+    else {
+        detail += " (>= 22.14: ok for type stripping and the SQLite driver)";
+    }
+    return { name: "node", ok, detail };
+}
+/**
+ * D74: the native driver used to fail by segfaulting — invisible to any
+ * in-process try/catch. Now that `loadDatabase` refuses below the floor, the
+ * load is safe to attempt here, so a broken driver reports itself here instead
+ * of killing the first command the user runs.
+ */
+function driverCheck() {
+    if (typeof globalThis.Bun !== "undefined") {
+        return { name: "sqlite driver", ok: true, detail: "bun:sqlite (built-in, no native module)" };
+    }
+    // Resolve the driver from THIS package's directory, not from the caller's
+    // cwd: `doctor` routinely runs with cwd set to a user project, where a bare
+    // `require("better-sqlite3")` would not find our node_modules at all.
+    const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+    try {
+        const probe = execFileSync(process.execPath, [
+            "-e",
+            "const p=process.argv[1];const D=require(require.resolve('better-sqlite3',{paths:[p]}));const db=new D(':memory:');db.exec('create table t(a)');db.close();process.stdout.write('ok')",
+            pkgRoot,
+        ], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30_000 });
+        return {
+            name: "sqlite driver",
+            ok: probe.includes("ok"),
+            detail: probe.includes("ok")
+                ? "better-sqlite3 loaded and opened an in-memory database"
+                : `probe returned ${JSON.stringify(probe)}`,
+        };
+    }
+    catch (err) {
+        const e = err;
+        // A native crash arrives as a huge unsigned status (0xC0000005 on Windows,
+        // 139 via SIGSEGV elsewhere). Print both forms - the hex is the one people
+        // recognize from Event Viewer or a shell's `exit=139`.
+        const how = e.signal
+            ? `signal ${e.signal}`
+            : typeof e.status === "number" && e.status > 255
+                ? `exit code ${e.status} (0x${(e.status >>> 0).toString(16).toUpperCase()})`
+                : `exit code ${e.status}`;
+        return {
+            name: "sqlite driver",
+            ok: false,
+            detail: `better-sqlite3 could not open a database (${how}). ` +
+                (e.stderr ? String(e.stderr).trim().split("\n").slice(-2).join(" ") + " " : "") +
+                nativeDriverFloorMessage(),
+        };
+    }
 }
 function configCheck() {
     try {
@@ -514,7 +572,7 @@ function vscodeMcpCheck() {
 }
 export async function runDoctor() {
     console.log("open-memex doctor");
-    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), opencodePluginCheck(), vscodeMcpCheck()];
+    const checks = [nodeCheck(), configCheck(), driverCheck(), scopeCheck(), storageCheck(), lockingCheck(), opencodePluginCheck(), vscodeMcpCheck()];
     checks.push(await mcpCheck());
     checks.push(legacyCheck());
     let allOk = true;

package/dist/runtime-floor.js

@@ -0,0 +1,47 @@
+/**
+ * Runtime floor for the native SQLite driver (D74).
+ *
+ * `better-sqlite3` 13 is built against Node-API 10, and Node only gained
+ * Node-API 10 in **22.14.0**. On an older Node the module registers and then
+ * dies with a segmentation fault inside `new Database(...)` — no message, no
+ * stack, exit 139 on macOS/Linux and `0xC0000005` on Windows. Upstream:
+ * WiseLibs/better-sqlite3#1514 (open; reproduces on win32-x64 and
+ * darwin-arm64, Node 20 and 22; `v12.11.1` is unaffected). Node 20 can never
+ * work with v13 — Node-API 10 never landed on that line — and it is EoL.
+ *
+ * So the floor is not "whatever `engines` claimed" (it said >=22.6, which was
+ * the `--experimental-strip-types` floor, not the driver's) but the exact
+ * Node-API 10 boundary. Below it we refuse loudly instead of segfaulting.
+ *
+ * Pure module — no imports, no db — so the comparison is unit-testable.
+ */
+export const MIN_NODE_VERSION = "22.14.0";
+export const NODE_FLOOR = { major: 22, minor: 14, patch: 0 };
+/** Parse `major.minor.patch`, ignoring any prerelease suffix (`23.1.0-nightly`). */
+export function parseNodeVersion(version) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+/** True when `version` is at or above the Node-API 10 floor. */
+export function nodeSupportsNativeDriver(version) {
+    const v = parseNodeVersion(version);
+    if (!v)
+        return false;
+    const f = NODE_FLOOR;
+    if (v.major !== f.major)
+        return v.major > f.major;
+    if (v.minor !== f.minor)
+        return v.minor > f.minor;
+    return v.patch >= f.patch;
+}
+/** The actionable message used by the driver guard and `doctor`. */
+export function nativeDriverFloorMessage(version = process.versions.node) {
+    return (`better-sqlite3 13 needs Node >= ${MIN_NODE_VERSION} (it is built against ` +
+        `Node-API 10), but this runtime is v${version}. On older Node the driver ` +
+        `segfaults on the first database open, which is why open-memex refuses to ` +
+        `load it. Upgrade Node (nvm install ${MIN_NODE_VERSION.split(".").slice(0, 2).join(".")} ` +
+        `&& nvm use ${MIN_NODE_VERSION.split(".").slice(0, 2).join(".")}), or pin the driver ` +
+        `down with: npm install better-sqlite3@^12.11.1`);
+}

package/dist/store/db.js

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { paths } from "../paths.js";
+import { nativeDriverFloorMessage, nodeSupportsNativeDriver, } from "../runtime-floor.js";
 // Runtime-agnostic SQLite:
 //   - Inside opencode (Bun runtime): bun:sqlite (built-in, no native module load)
 //   - Under Node CLI: better-sqlite3
@@ -11,6 +12,13 @@ function loadDatabase() {
         // bun:sqlite is a built-in module; only resolvable under the Bun runtime.
         return require("bun:sqlite").Database;
     }
+    // D74: better-sqlite3 13 is built against Node-API 10, which Node gained in
+    // 22.14.0. Below that floor `require` succeeds and `new Database()` then
+    // segfaults the process with no diagnostic — so refuse before we can crash
+    // and say what to do instead (upstream: WiseLibs/better-sqlite3#1514).
+    if (!nodeSupportsNativeDriver(process.versions.node)) {
+        throw new Error(nativeDriverFloorMessage());
+    }
     return require("better-sqlite3");
 }
 let _db = null;

package/docs/V2-DESIGN.md

@@ -1,6 +1,6 @@
 # OpenMemex — Design Document (protocol v0.2)
 
-**Status:** FROZEN — protocol v0.2 (2026-09-26). Decisions D1–D73 are settled; open questions are tracked at the end of this document.
+**Status:** FROZEN — protocol v0.2 (2026-09-26). Decisions D1–D74 are settled; open questions are tracked at the end of this document.
 **Author:** Stone, with 小沐
 **Changelog vs v1:** incorporates round-3 review from Perplexity, Grok, Gemini, ChatGPT, DeepSeek.
 Key changes: Design Principles section; `role` separated from `type`; two iron rules;
@@ -1469,6 +1469,36 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   entry back before deleting. The HTML rendering of the same data layer
   follows as a separate change; auto-draft stays gated on the unlock
   conditions in the design doc.
+- **D74 — the Node floor is 22.14, because the driver sets it, not us.** D72
+  moved the Node driver to `better-sqlite3` 13 (the N-API rewrite) to stop the
+  Node 24.19+ exit-path abort. That upgrade carried an unstated requirement:
+  v13 is compiled against **Node-API 10**, and Node only gained Node-API 10 in
+  **22.14.0**. Below that floor `require("better-sqlite3")` succeeds and then
+  `new Database()` segfaults the process — no message, no stack, exit 139 on
+  macOS/Linux, `0xC0000005` on Windows. Measured on win32-x64: Node 22.12.0
+  dies on the first open, Node 22.23.3 and 24.20.0 work; Node 20 can never work
+  with v13, since Node-API 10 never landed on that line (EoL regardless). This
+  is upstream and still open — WiseLibs/better-sqlite3#1514, plus #1516 for the
+  separate `npm ci` gyp problem on Windows, where `gypfile: false` does not stop
+  npm from shelling out to node-gyp. `engines.node` had been `>=22.6`, which was
+  the `--experimental-strip-types` floor — a real but *different* constraint
+  that predated the driver bump; leaving it would have shipped a package whose
+  declared support window crashes on its own dependency. Three changes:
+  (1) `engines.node` is `>=22.14.0`, and the two floors are documented as two
+  floors rather than merged into one number; (2) `loadDatabase` refuses below
+  the new floor and throws the actionable message (upgrade Node, or pin
+  `better-sqlite3@^12.11.1` — v12 is unaffected), because a crash no in-process
+  `try`/`catch` can report is the worst possible failure mode for a CLI;
+  (3) `doctor` reports the floor *and* probes the driver in a **child process**,
+  since a segfault cannot be caught in-process — the probe resolves the driver
+  from this package's own directory, because `doctor` routinely runs with cwd
+  set to a user project where a bare `require` finds nothing. The version
+  comparison lives in `src/runtime-floor.ts`, pure and unit-tested, because the
+  boundary is a fact to be tested (22.13.9 below, 22.14.0 exactly at, 22.23.3
+  and 24.20.0 above) rather than a constant to be trusted. Deliberately NOT
+  done: pinning back to v12 (that re-opens D72's Node 24 abort), or attempting
+  to fix either upstream bug here.
+
 - **D73 — one user statement, one memory: the keyword hook hands off to the
   agent.** The keyword hook and the agent are two writers for one user turn,
   and only one of them knows the sentence is already stored. Observed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",
@@ -38,6 +38,6 @@
     "open-memex": "dist/cli.js"
   },
   "engines": {
-    "node": ">=22.6"
+    "node": ">=22.14.0"
   }
 }

package/scripts/smoke-pure.ts

@@ -9,6 +9,12 @@ import { resolveProjectScope, resolveCwdScope, pickScopeRoot, PERSONAL_SCOPE } f
 import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { toFtsQuery } from "../src/retrieve/query.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
+import {
+  MIN_NODE_VERSION,
+  nativeDriverFloorMessage,
+  nodeSupportsNativeDriver,
+  parseNodeVersion,
+} from "../src/runtime-floor.ts";
 import {
   TURN_ECHO_THRESHOLD,
   TURN_ECHO_WINDOW_MS,
@@ -608,6 +614,31 @@ console.log("== env var names (D62) ==");
   }
 }
 
+console.log("== runtime floor (native driver, D74) ==");
+// better-sqlite3 13 is built against Node-API 10, which Node gained in 22.14.0.
+// Below that floor `require` succeeds and `new Database()` segfaults the
+// process with no diagnostic, so the version gate is the only thing standing
+// between an old Node and a silent crash. The 22.12.0 / 22.23.3 boundary is
+// the measured one (win32-x64, WiseLibs/better-sqlite3#1514).
+ok("floor is 22.14.0", MIN_NODE_VERSION === "22.14.0");
+ok("22.12.0 is below the floor (segfaults)", !nodeSupportsNativeDriver("22.12.0"));
+ok("22.13.9 is below the floor", !nodeSupportsNativeDriver("22.13.9"));
+ok("22.14.0 is exactly the floor", nodeSupportsNativeDriver("22.14.0"));
+ok("22.14.1 is above", nodeSupportsNativeDriver("22.14.1"));
+ok("22.23.3 is above (measured working)", nodeSupportsNativeDriver("22.23.3"));
+ok("24.20.0 is above (measured working)", nodeSupportsNativeDriver("24.20.0"));
+ok("25.x is above", nodeSupportsNativeDriver("25.3.0"));
+ok("20.x is below (Node-API 10 never landed on 20)", !nodeSupportsNativeDriver("20.19.6"));
+ok("v-prefix tolerated", nodeSupportsNativeDriver("v22.14.0"));
+ok("prerelease suffix tolerated", nodeSupportsNativeDriver("23.1.0-nightly20260101"));
+ok("garbage is below, not a crash", !nodeSupportsNativeDriver("not-a-version"));
+ok("parses major/minor/patch", JSON.stringify(parseNodeVersion("22.14.3")) === '{"major":22,"minor":14,"patch":3}');
+const floorMsg = nativeDriverFloorMessage("22.12.0");
+ok("message names the floor", floorMsg.includes("22.14.0"));
+ok("message names the running version", floorMsg.includes("22.12.0"));
+ok("message offers a fix (upgrade or downgrade)", /Upgrade Node/.test(floorMsg) && /better-sqlite3@\^12/.test(floorMsg));
+ok("message explains the segfault", /segfaults/.test(floorMsg));
+
 console.log("== lifecycle pure: contentHash / similarity ==");
 ok("hash deterministic + whitespace-insensitive", contentHash("hello   world\n") === contentHash("hello world"));
 ok("hash differs on content", contentHash("hello world") !== contentHash("hello mars"));

package/src/doctor.ts

@@ -10,6 +10,11 @@ import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG, stripJsonComments } from "./config.ts";
 import { paths, homeOverride } from "./paths.ts";
 import { resolveCwdScope } from "./scope.ts";
+import {
+  MIN_NODE_VERSION,
+  nativeDriverFloorMessage,
+  nodeSupportsNativeDriver,
+} from "./runtime-floor.ts";
 import { db, backendName } from "./store/db.ts";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.ts";
 
@@ -37,12 +42,72 @@ const EXPECTED_TOOLS = [
 
 function nodeCheck(): Check {
   const [major, minor] = process.versions.node.split(".").map(Number);
-  const ok = major > 22 || (major === 22 && minor >= 6);
-  return {
-    name: "node",
-    ok,
-    detail: `v${process.versions.node} (need >= 22.6 for --experimental-strip-types)`,
-  };
+  // Two independent floors, and the higher one wins: 22.6 for
+  // --experimental-strip-types, 22.14 for the native SQLite driver (D74).
+  const stripTypesOk = major > 22 || (major === 22 && minor >= 6);
+  const driverOk = nodeSupportsNativeDriver(process.versions.node);
+  const ok = stripTypesOk && driverOk;
+  let detail = `v${process.versions.node}`;
+  if (!stripTypesOk) {
+    detail += ` (need >= 22.6 for --experimental-strip-types)`;
+  } else if (!driverOk) {
+    detail += ` (need >= ${MIN_NODE_VERSION}: better-sqlite3 13 is built against Node-API 10 and segfaults below it)`;
+  } else {
+    detail += " (>= 22.14: ok for type stripping and the SQLite driver)";
+  }
+  return { name: "node", ok, detail };
+}
+
+/**
+ * D74: the native driver used to fail by segfaulting — invisible to any
+ * in-process try/catch. Now that `loadDatabase` refuses below the floor, the
+ * load is safe to attempt here, so a broken driver reports itself here instead
+ * of killing the first command the user runs.
+ */
+function driverCheck(): Check {
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== "undefined") {
+    return { name: "sqlite driver", ok: true, detail: "bun:sqlite (built-in, no native module)" };
+  }
+  // Resolve the driver from THIS package's directory, not from the caller's
+  // cwd: `doctor` routinely runs with cwd set to a user project, where a bare
+  // `require("better-sqlite3")` would not find our node_modules at all.
+  const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+  try {
+    const probe = execFileSync(
+      process.execPath,
+      [
+        "-e",
+        "const p=process.argv[1];const D=require(require.resolve('better-sqlite3',{paths:[p]}));const db=new D(':memory:');db.exec('create table t(a)');db.close();process.stdout.write('ok')",
+        pkgRoot,
+      ],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30_000 },
+    );
+    return {
+      name: "sqlite driver",
+      ok: probe.includes("ok"),
+      detail: probe.includes("ok")
+        ? "better-sqlite3 loaded and opened an in-memory database"
+        : `probe returned ${JSON.stringify(probe)}`,
+    };
+  } catch (err) {
+    const e = err as { status?: number | null; signal?: string | null; stderr?: string };
+    // A native crash arrives as a huge unsigned status (0xC0000005 on Windows,
+    // 139 via SIGSEGV elsewhere). Print both forms - the hex is the one people
+    // recognize from Event Viewer or a shell's `exit=139`.
+    const how = e.signal
+      ? `signal ${e.signal}`
+      : typeof e.status === "number" && e.status > 255
+        ? `exit code ${e.status} (0x${(e.status >>> 0).toString(16).toUpperCase()})`
+        : `exit code ${e.status}`;
+    return {
+      name: "sqlite driver",
+      ok: false,
+      detail:
+        `better-sqlite3 could not open a database (${how}). ` +
+        (e.stderr ? String(e.stderr).trim().split("\n").slice(-2).join(" ") + " " : "") +
+        nativeDriverFloorMessage(),
+    };
+  }
 }
 
 function configCheck(): Check {
@@ -540,7 +605,7 @@ function vscodeMcpCheck(): Check {
 
 export async function runDoctor(): Promise<boolean> {
   console.log("open-memex doctor");
-  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), opencodePluginCheck(), vscodeMcpCheck()];
+  const checks: Check[] = [nodeCheck(), configCheck(), driverCheck(), scopeCheck(), storageCheck(), lockingCheck(), opencodePluginCheck(), vscodeMcpCheck()];
   checks.push(await mcpCheck());
   checks.push(legacyCheck());
   let allOk = true;

package/src/runtime-floor.ts

@@ -0,0 +1,56 @@
+/**
+ * Runtime floor for the native SQLite driver (D74).
+ *
+ * `better-sqlite3` 13 is built against Node-API 10, and Node only gained
+ * Node-API 10 in **22.14.0**. On an older Node the module registers and then
+ * dies with a segmentation fault inside `new Database(...)` — no message, no
+ * stack, exit 139 on macOS/Linux and `0xC0000005` on Windows. Upstream:
+ * WiseLibs/better-sqlite3#1514 (open; reproduces on win32-x64 and
+ * darwin-arm64, Node 20 and 22; `v12.11.1` is unaffected). Node 20 can never
+ * work with v13 — Node-API 10 never landed on that line — and it is EoL.
+ *
+ * So the floor is not "whatever `engines` claimed" (it said >=22.6, which was
+ * the `--experimental-strip-types` floor, not the driver's) but the exact
+ * Node-API 10 boundary. Below it we refuse loudly instead of segfaulting.
+ *
+ * Pure module — no imports, no db — so the comparison is unit-testable.
+ */
+
+export const MIN_NODE_VERSION = "22.14.0";
+
+export interface NodeFloor {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+export const NODE_FLOOR: NodeFloor = { major: 22, minor: 14, patch: 0 };
+
+/** Parse `major.minor.patch`, ignoring any prerelease suffix (`23.1.0-nightly`). */
+export function parseNodeVersion(version: string): NodeFloor | null {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+/** True when `version` is at or above the Node-API 10 floor. */
+export function nodeSupportsNativeDriver(version: string): boolean {
+  const v = parseNodeVersion(version);
+  if (!v) return false;
+  const f = NODE_FLOOR;
+  if (v.major !== f.major) return v.major > f.major;
+  if (v.minor !== f.minor) return v.minor > f.minor;
+  return v.patch >= f.patch;
+}
+
+/** The actionable message used by the driver guard and `doctor`. */
+export function nativeDriverFloorMessage(version: string = process.versions.node): string {
+  return (
+    `better-sqlite3 13 needs Node >= ${MIN_NODE_VERSION} (it is built against ` +
+    `Node-API 10), but this runtime is v${version}. On older Node the driver ` +
+    `segfaults on the first database open, which is why open-memex refuses to ` +
+    `load it. Upgrade Node (nvm install ${MIN_NODE_VERSION.split(".").slice(0, 2).join(".")} ` +
+    `&& nvm use ${MIN_NODE_VERSION.split(".").slice(0, 2).join(".")}), or pin the driver ` +
+    `down with: npm install better-sqlite3@^12.11.1`
+  );
+}

package/src/store/db.ts

@@ -1,5 +1,10 @@
 import { createRequire } from "node:module";
 import { paths } from "../paths.ts";
+import {
+  MIN_NODE_VERSION,
+  nativeDriverFloorMessage,
+  nodeSupportsNativeDriver,
+} from "../runtime-floor.ts";
 
 // Runtime-agnostic SQLite:
 //   - Inside opencode (Bun runtime): bun:sqlite (built-in, no native module load)
@@ -18,6 +23,13 @@ function loadDatabase(): AnyDatabaseCtor {
     // bun:sqlite is a built-in module; only resolvable under the Bun runtime.
     return require("bun:sqlite").Database as AnyDatabaseCtor;
   }
+  // D74: better-sqlite3 13 is built against Node-API 10, which Node gained in
+  // 22.14.0. Below that floor `require` succeeds and `new Database()` then
+  // segfaults the process with no diagnostic — so refuse before we can crash
+  // and say what to do instead (upstream: WiseLibs/better-sqlite3#1514).
+  if (!nodeSupportsNativeDriver(process.versions.node)) {
+    throw new Error(nativeDriverFloorMessage());
+  }
   return require("better-sqlite3") as AnyDatabaseCtor;
 }