docs(oss): record the native-module strategy (ADR-0008, P1.3b)
This commit is contained in:
45
docs/oss/adr/0008-native-modules.md
Normal file
45
docs/oss/adr/0008-native-modules.md
Normal file
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user