Summary

• Replace sqlite3 with better-sqlite3 in both SQLiteManager (history store) and MemoryVectorStore (in-memory vector store) to fix native binding resolution failures under OpenClaw's jiti loader
• Update all build configs (tsup.config.ts, package.json, src/oss/package.json) so the package builds cleanly
• Add 24 tests covering both migrated modules end-to-end

Problem

The sqlite3 package uses the bindings module to locate its native .node addon at runtime by walking the V8 call stack to find the caller's __dirname. When OpenClaw loads the mem0 plugin through jiti (JIT TypeScript/ESM loader), V8 stack frames have synthetic filenames from jiti's transpiler, causing bindings to resolve the wrong module_root:

Error: Could not locate the bindings file. Tried:
 → /app/node_modules/.pnpm/jiti@2.6.1/node_modules/jiti/build/node_sqlite3.node
 → ...

The actual binary exists in the plugin's extension directory but bindings never searches there. This is architecture-independent — it affects x86_64, ARM64, macOS, and Linux equally.

Additionally, the published dist/oss/index.mjs had two unconditional top-level import sqlite3 from "sqlite3" statements (from SQLiteManager and MemoryVectorStore), so sqlite3 was evaluated eagerly at ESM parse time with no way to conditionally skip it.

Solution

Replace sqlite3 with better-sqlite3 which:

• Ships prebuilt binaries via prebuild-install (no compile step needed)
• Uses a different native loading mechanism that doesn't rely on bindings module path walking
• Is synchronous (simpler API, eliminates the async callback wrapper boilerplate)
• Has broader platform coverage out of the box (x64, ARM64, musl/glibc)

Changes

SQLiteManager.ts

• Rewritten to use better-sqlite3's synchronous API
• Prepared statements cached in constructor (stmtInsert, stmtSelect) for performance
• init() is now synchronous — no more .catch(console.error) race condition
• undefined params explicitly coerced to null for better-sqlite3 compatibility

MemoryVectorStore (memory.ts)

• Rewritten to use better-sqlite3's synchronous API
• Removed run(), all(), getOne() async Promise wrappers
• Batch insert() wrapped in a transaction for atomicity and performance
• Buffer handling updated for better-sqlite3's Uint8Array return type

tsup.config.ts

• External array: sqlite3 → better-sqlite3

package.json

• peerDependencies: sqlite3: 5.1.7 → better-sqlite3: ^11.9.1
• pnpm.onlyBuiltDependencies: sqlite3 → better-sqlite3
• devDependencies: Added @types/better-sqlite3: ^7.6.13
• Removed @types/sqlite3 from peerDependencies

src/oss/package.json

• sqlite3 → better-sqlite3 in dependencies
• Removed @types/sqlite3

Tests (new: better-sqlite3-migration.test.ts)

24 tests covering:

• SQLiteManager: in-memory, file persistence, addHistory, getHistory (DESC order), memory_id isolation, NULL handling, reset, rapid insertions
• MemoryVectorStore: insert/get, search with cosine similarity sorting, filters, limit, dimension mismatch errors, update, delete, deleteCol, list, getUserId/setUserId, upsert behavior, file persistence

Migration

Users of the mem0ai npm package who use the OSS mode with sqlite history will need to:

1. npm uninstall sqlite3 / pnpm remove sqlite3
2. npm install better-sqlite3 / pnpm add better-sqlite3

No code changes required — the API is unchanged.

Test plan

• All 24 new tests pass (npx jest --testPathPattern=better-sqlite3-migration)
• Type-check passes (npx tsc --noEmit — zero new errors)
• tsup build succeeds (ESM, CJS, DTS all generated cleanly)
• better-sqlite3 correctly externalized in build output (verified in dist/oss/index.mjs)
• Pre-existing test failures unchanged (3 suites fail on main with identical errors)
• Test with OpenClaw plugin loading (manual)
• Test on ARM64 (if available)

OpenClaw End-to-End Test Results

Tested the full mem0 OSS plugin lifecycle through OpenClaw's gateway (jiti-based TypeScript plugin loader) to verify the better-sqlite3 migration works in the exact environment that triggered the original sqlite3 binding failures.

Setup

• OpenClaw gateway running as a macOS LaunchAgent (Node v22.22.0 via /usr/local/bin/node)
• Plugin loader: jiti 2.6.1 (JIT TypeScript/ESM transpiler)
• Config: OSS mode with memory vector store (better-sqlite3 backed), OpenAI embedder (text-embedding-3-small), OpenAI LLM (gpt-4o)
• History: Disabled for this test (the historyDbPath config propagation bug is a separate issue — see PR fix(openclaw): propagate historyDbPath into historyStore to prevent SQLITE_CANTOPEN crash loop #4160)

Results

Fixes

• Fixes [@mem0/openclaw-mem0] sqlite3 native binding resolution fails due to jiti path mismatch #4107 — sqlite3 native binding resolution fails due to jiti path mismatch
• Fixes [OpenClaw Plugin] ARM64 sqlite3 binding error on Node v22 #4050 — Same root cause on ARM64
• Fixes @mem0/openclaw-mem0 OSS mode: sqlite3 binding lookup fails under OpenClaw/Jiti loader context #4172 — OSS mode sqlite3 binding lookup fails under OpenClaw/Jiti loader context
• Fixes @mem0/openclaw-mem0 OSS mode fails on Node 25 with sqlite3 binding lookup under jiti #4156 — OSS mode fails on Node 25 with sqlite3 binding lookup under jiti

Related

• PR fix: replace sqlite3 with better-sqlite3 to fix native binding resolution #4123 — Original attempt (only migrated SQLiteManager, missed MemoryVectorStore + build configs)
• PR fix(ts): lazy-load SQLite3 to prevent import time crashes #3919 — Lazy-load sqlite3 (partial mitigation, superseded by this PR)