From 61ea8bbabf5a22c97ceff9f4b4af9f201eb6b2e0 Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Sat, 24 Oct 2026 12:06:32 +0200 Subject: [PATCH] docs(oss): record the native-module strategy (ADR-0008, P1.3b) --- docs/oss/adr/0008-native-modules.md | 45 +++++++++++++++++++++++++++++ docs/oss/adr/README.md | 1 + 2 files changed, 46 insertions(+) create mode 100644 docs/oss/adr/0008-native-modules.md diff --git a/docs/oss/adr/0008-native-modules.md b/docs/oss/adr/0008-native-modules.md new file mode 100644 index 0000000..1138492 --- /dev/null +++ b/docs/oss/adr/0008-native-modules.md @@ -0,0 +1,45 @@ +# 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. diff --git a/docs/oss/adr/README.md b/docs/oss/adr/README.md index e303f71..c1751bb 100644 --- a/docs/oss/adr/README.md +++ b/docs/oss/adr/README.md @@ -13,6 +13,7 @@ decision, add a new record that supersedes the old one. | [0005](0005-whatsapp-web-js.md) | The WhatsApp channel uses `whatsapp-web.js` | Accepted, one open item | | [0006](0006-opt-in-analytics.md) | Analytics are opt-in | Accepted, one open item | | [0007](0007-memory-contract.md) | The memory contract and how it maps onto mem0 | Accepted | +| [0008](0008-native-modules.md) | Native modules ship with a pinned Node runtime | Accepted | ## Pending decisions