46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
# 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.
|