# ADR-0008: Native modules ship with a pinned Node runtime - Status: Accepted - Date: 2026-10-24 ## Context The community edition runs on Windows x64, macOS arm64 and x64, and Linux x64 (glibc). Three dependencies carry native code: - `better-sqlite3` holds `waggle.db`, mem0's vector and history stores, telemetry and the marketplace catalogue. mem0 3.3.1 requires it; it has no `node:sqlite` backend. - `onnxruntime-node` (through `@huggingface/transformers`) runs the in-process embedding model that memory depends on. - `sqlite-vec` loaded vector search into the legacy memory engine only. `better-sqlite3` publishes prebuilt binaries per Node ABI. When the installed Node does not match a prebuild, npm falls back to node-gyp, which needs Python and a compiler. That is the failure the audit found on clean machines. ## Decision 1. **Pin the Node runtime.** Installers and the desktop sidecar ship Node 22.23.2 (`scripts/bundle-node.mjs`), so the prebuilt `better-sqlite3` and `onnxruntime-node` binaries always match. Developers need Node 20.19+ or 22.12+ (`engines`); Node 22 is recommended because the managed Ollama runtime on Linux uses its built-in zstd. 2. **Not `node:sqlite`.** It is still experimental in Node 22 and mem0 cannot use it. 3. **No CUDA download.** `onnxruntime-node` downloads CUDA libraries on every Linux x64 install unless `ONNXRUNTIME_NODE_INSTALL_CUDA=skip` is set. The installer script sets it; the embedding and reranking models run on CPU. 4. **No sqlite-vec.** mem0 keeps its own vector store in SQLite and needs no extension. It left with the legacy memory engine: the launcher no longer depends on it, the desktop build no longer copies `vec0` and the installer checks plain SQLite. 5. **Local models on Linux.** The managed Ollama runtime now has pinned Linux x64 and arm64 artifacts (`ollama-linux-*.tar.zst`, SHA-256 and size from the Ollama release). ## Consequences - A clean install needs no Python and no compiler on the supported platforms. - Updating Node, `better-sqlite3` or `onnxruntime-node` is one coordinated change, checked on all three systems in the release smoke run (P1.3d). - The Linux Ollama archive is about 1.4 GB because Ollama bundles its GPU libraries. - The `npx @waggle-ai/waggle` path runs dependency install scripts on the user's Node; there the CUDA skip and the Puppeteer download skip cannot be set by us (ADR-0005). The installer (P1.3c) avoids that path.