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.
2.4 KiB
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-sqlite3holdswaggle.db, mem0's vector and history stores, telemetry and the marketplace catalogue. mem0 3.3.1 requires it; it has nonode:sqlitebackend.onnxruntime-node(through@huggingface/transformers) runs the in-process embedding model that memory depends on.sqlite-vecloaded 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
- Pin the Node runtime. Installers and the desktop sidecar ship Node 22.23.2
(
scripts/bundle-node.mjs), so the prebuiltbetter-sqlite3andonnxruntime-nodebinaries 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. - Not
node:sqlite. It is still experimental in Node 22 and mem0 cannot use it. - No CUDA download.
onnxruntime-nodedownloads CUDA libraries on every Linux x64 install unlessONNXRUNTIME_NODE_INSTALL_CUDA=skipis set. The installer script sets it; the embedding and reranking models run on CPU. - 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
vec0and the installer checks plain SQLite. - 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-sqlite3oronnxruntime-nodeis 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/wagglepath 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.