Files
waggle-os/docs/oss/adr/0008-native-modules.md

2.4 KiB

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. The package leaves with the legacy memory engine; the root sqlite-vec-windows-x64 dependency is already gone.
  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.