Files
waggle-os/docs/oss/adr/0008-native-modules.md
shumeiko.it 4dbab2cb8b docs: describe the community edition after the move to mem0 and the unified build
AGENTS.md no longer describes memory as half-migrated or asks for
build:packages before running the sidecar, lists the tsc -b build and the
test typecheck among the checks, and drops the removed weaver package.
ADR-0007 and ADR-0008 record that core no longer re-exports the legacy
substrate and that sqlite-vec is gone.
2026-10-24 17:56:20 +02:00

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. 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.