@dex-ai/memory 0.3.4 → 0.3.5

package/README.md

@@ -104,7 +104,7 @@ interface MemoryExtensionOptions {
   userId: string;                    // owner for episodic + semantic memory
 
   vecPath?: string;                  // optional explicit sqlite-vec extension path
-  sqlitePath?: string;               // optional SQLite dylib with extension loading enabled
+  sqlitePath?: string;               // advanced: override auto-detected Homebrew SQLite dylib
 
   llm?: { provider?: Provider; model?: string };
   embed?: (texts: string[]) => Promise<number[][]>; // 384-dim vectors
@@ -143,12 +143,10 @@ This message is **not** persisted to `actx.messages` — it is a per-turn rewrit
 ## Requirements + gotchas
 
 - **sqlite-vec**: loaded via the `sqlite-vec` npm package, which ships prebuilt binaries for macOS, Linux, and Windows. Extension construction throws if the binary is not loadable for your platform.
-- **Bun + macOS SQLite**: Bun uses Apple SQLite on macOS by default, and Apple SQLite disables loadable extensions. The extension automatically uses Homebrew SQLite when it exists at `/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib` or `/usr/local/opt/sqlite/lib/libsqlite3.dylib`. If needed, install it with `brew install sqlite`, set `DEX_SQLITE_DYLIB=/path/to/libsqlite3.dylib`, or pass `sqlitePath` to `memoryExtension()`.
+- **Bun + macOS SQLite**: Bun uses Apple SQLite on macOS by default, and Apple SQLite disables loadable extensions. The extension automatically uses Homebrew SQLite when it exists at `/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib` or `/usr/local/opt/sqlite/lib/libsqlite3.dylib`. If needed, install it and restart Dex:
 
   ```bash
   brew install sqlite
-  export DEX_SQLITE_DYLIB="$(brew --prefix sqlite)/lib/libsqlite3.dylib"
-  bun test
   ```
 
 - **Transformers.js first-run download**: the default local embedder downloads an ONNX model and caches it in `~/.cache/huggingface`. Initial `embed()` may take 10-30s; subsequent calls are faster.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dex-ai/memory",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "SQLite-backed memory Extension for @dex-ai/sdk — episodic, semantic, and procedural memory in one package.",
   "type": "module",
   "exports": {

package/src/db.test.ts

@@ -1,4 +1,6 @@
+import { Database } from 'bun:sqlite';
 import { describe, expect, test } from 'bun:test';
+import { fileURLToPath } from 'node:url';
 import { MemoryDb, EMBED_DIMS } from './db';
 
 describe('MemoryDb', () => {
@@ -40,6 +42,16 @@ describe('MemoryDb', () => {
     }
   });
 
+  test('tolerates SQLite being loaded before custom sqlite configuration', () => {
+    const alreadyOpen = new Database(':memory:');
+    try {
+      const db = new MemoryDb({ path: ':memory:', sqlitePath: fileURLToPath(import.meta.url) });
+      db.close();
+    } finally {
+      alreadyOpen.close();
+    }
+  });
+
   test('EMBED_DIMS is 384', () => {
     expect(EMBED_DIMS).toBe(384);
   });

package/src/db.ts

@@ -96,6 +96,7 @@ const MIGRATIONS: Array<{ name: string; sql: string }> = [
 	},
 ];
 
+const PACKAGE_NAME = "@dex-ai/memory";
 const SQLITE_DYLIB_ENV = "DEX_SQLITE_DYLIB";
 
 const HOMEBREW_SQLITE_DYLIBS = [
@@ -104,9 +105,16 @@ const HOMEBREW_SQLITE_DYLIBS = [
 ];
 
 let customSqliteConfigured = false;
+let customSqliteAttempted = false;
+
+function isSQLiteAlreadyLoadedError(err: unknown): boolean {
+	return err instanceof Error && /SQLite already loaded/i.test(err.message);
+}
 
 function configureCustomSQLite(sqlitePath?: string): void {
 	if (customSqliteConfigured || platform !== "darwin") return;
+	if (sqlitePath === undefined && customSqliteAttempted) return;
+	customSqliteAttempted = true;
 
 	const candidate =
 		sqlitePath ??
@@ -116,23 +124,37 @@ function configureCustomSQLite(sqlitePath?: string): void {
 
 	if (!existsSync(candidate)) {
 		throw new Error(
-			`@dex-ai/memory-sqlite: configured SQLite dylib does not exist: ${candidate}`,
+			`${PACKAGE_NAME}: configured SQLite dylib does not exist: ${candidate}`,
 		);
 	}
 
-	if (!Database.setCustomSQLite(candidate)) {
+	try {
+		if (!Database.setCustomSQLite(candidate)) {
+			throw new Error(`failed to configure custom SQLite dylib: ${candidate}`);
+		}
+		customSqliteConfigured = true;
+	} catch (err) {
+		// Bun only allows setCustomSQLite() before SQLite is loaded anywhere in
+		// the process. Dex may load another SQLite-backed extension first. In
+		// that case, keep using the already-loaded SQLite and let sqlite-vec
+		// loading below determine whether the current build supports extensions.
+		if (isSQLiteAlreadyLoadedError(err)) return;
 		throw new Error(
-			`@dex-ai/memory-sqlite: failed to configure custom SQLite dylib: ${candidate}`,
+			`${PACKAGE_NAME}: ${err instanceof Error ? err.message : String(err)}`,
 		);
 	}
-	customSqliteConfigured = true;
 }
 
 function customSQLiteHelp(): string {
 	if (platform !== "darwin") return "";
-	return ` On macOS, Bun uses Apple SQLite by default, which disables loadable extensions. Install SQLite with \`brew install sqlite\`, then either set ${SQLITE_DYLIB_ENV}=/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib or pass sqlitePath.`;
+	return " On macOS, Bun uses Apple SQLite by default, which disables loadable extensions. Install SQLite with `brew install sqlite`, then restart Dex.";
 }
 
+// Configure Bun to use Homebrew SQLite as soon as this module is imported.
+// Users should only need to install SQLite; no environment variables are
+// required for the common Homebrew locations.
+configureCustomSQLite();
+
 function applyMigrations(db: Database): void {
 	db.exec(`
     CREATE TABLE IF NOT EXISTS _schema_migrations (
@@ -179,7 +201,7 @@ export class MemoryDb {
 		} catch (err) {
 			this.db.close();
 			throw new Error(
-				`@dex-ai/memory-sqlite: failed to load sqlite-vec extension. ` +
+				`${PACKAGE_NAME}: failed to load sqlite-vec extension. ` +
 					`Ensure the sqlite-vec npm package's prebuilt binary is available for this platform.` +
 					customSQLiteHelp() +
 					` Original error: ${err instanceof Error ? err.message : String(err)}`,