Skip to content

Commit b1645c6

Browse files
fix(memory): open AgentDB with our better-sqlite3 so Node 24 does not abort
On Node 24.19+, `memory search`, `memory_store` and the AgentDB MCP tools abort intermittently with `Assertion failed: (env) != nullptr` in node::RemoveEnvironmentCleanupHook, from Statement::~Statement() in agentdb/node_modules/better-sqlite3 (exit 134 / "Connection closed"). agentdb 3.0.0-alpha.x pins better-sqlite3 ^11.8.1. 11.x has no Node 24 prebuild, so npm compiles it against the local Node headers, and 24.19+ headers carry a partial ObjectWrap cleanup-hook backport (nodejs/node#65446) that aborts when a Statement is collected outside an Environment. Our own better-sqlite3 12.x ships a Node 24 prebuild built before that header change. The `better-sqlite3` override in the published package.json files does not reach agentdb: npm ignores overrides in a dependency, and `npm i -g ruflo` still installs the nested 11.10.0. ControllerRegistry and AgentDBBackend now replace the AgentDB instance's initializeDatabase() so its handle is opened with this package's better-sqlite3; AgentDB's own loader stays as the fallback and forceWasm is untouched.
1 parent 6c04654 commit b1645c6

4 files changed

Lines changed: 146 additions & 0 deletions

File tree

‎v3/@claude-flow/memory/src/agentdb-backend.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
import { withAgentdbLockRecovery, closeWithAgentdbLockRecovery } from './agentdb-lock-guard.js';
1414
import { EventEmitter } from 'node:events';
1515
import { safeJsonParse } from './json-security.js';
16+
import { useHostSqliteDriver } from './agentdb-native-driver.js';
1617
import {
1718
IMemoryBackend,
1819
MemoryEntry,
@@ -222,6 +223,8 @@ export class AgentDBBackend extends EventEmitter implements IMemoryBackend {
222223
vectorBackend: this.config.vectorBackend,
223224
vectorDimension: this.config.vectorDimension,
224225
});
226+
// Keep agentdb's nested better-sqlite3 11.x out of the process (Node 24 abort).
227+
useHostSqliteDriver(this.agentdb);
225228
await this.agentdb.initialize();
226229
});
227230
} finally {
Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
/**
2+
* Node 24 abort in agentdb's nested better-sqlite3 11.x
3+
* (`Assertion failed: (env) != nullptr` in Statement::~Statement).
4+
*
5+
* useHostSqliteDriver() must make AgentDB open its handle with this
6+
* package's better-sqlite3, so the source-built 11.x addon is never loaded.
7+
*/
8+
9+
import { describe, it, expect } from 'vitest';
10+
import { mkdtempSync, rmSync } from 'node:fs';
11+
import { tmpdir } from 'node:os';
12+
import { join } from 'node:path';
13+
import Database from 'better-sqlite3';
14+
import { useHostSqliteDriver } from './agentdb-native-driver.js';
15+
16+
function fakeAgentDB(config: { forceWasm?: boolean } = {}) {
17+
const calls: string[] = [];
18+
const own = { own: true };
19+
const agentdb: {
20+
config: { forceWasm?: boolean };
21+
usingWasm: boolean;
22+
initializeDatabase: (dbPath: string) => Promise<any>;
23+
} = {
24+
config,
25+
usingWasm: true,
26+
async initializeDatabase(dbPath: string) {
27+
calls.push(dbPath);
28+
return own;
29+
},
30+
};
31+
return { agentdb, calls, own };
32+
}
33+
34+
describe('useHostSqliteDriver', () => {
35+
it('opens the AgentDB handle with our better-sqlite3, not agentdb\'s', async () => {
36+
const dir = mkdtempSync(join(tmpdir(), 'cf-agentdb-driver-'));
37+
const { agentdb, calls } = fakeAgentDB();
38+
try {
39+
useHostSqliteDriver(agentdb);
40+
const db = await agentdb.initializeDatabase(join(dir, 'agentdb-memory.db'));
41+
42+
expect(db).toBeInstanceOf(Database);
43+
expect(calls).toEqual([]);
44+
expect(agentdb.usingWasm).toBe(false);
45+
expect(db.pragma('journal_mode', { simple: true })).toBe('wal');
46+
db.close();
47+
} finally {
48+
rmSync(dir, { recursive: true, force: true });
49+
}
50+
});
51+
52+
it('falls back to AgentDB\'s own loader when ours cannot open the path', async () => {
53+
const { agentdb, calls, own } = fakeAgentDB();
54+
useHostSqliteDriver(agentdb);
55+
const missingDir = join(tmpdir(), 'cf-agentdb-driver-missing', 'nested', 'x.db');
56+
57+
await expect(agentdb.initializeDatabase(missingDir)).resolves.toBe(own);
58+
expect(calls).toEqual([missingDir]);
59+
});
60+
61+
it('leaves forceWasm instances on AgentDB\'s own loader', async () => {
62+
const { agentdb, calls, own } = fakeAgentDB({ forceWasm: true });
63+
useHostSqliteDriver(agentdb);
64+
65+
await expect(agentdb.initializeDatabase(':memory:')).resolves.toBe(own);
66+
expect(calls).toEqual([':memory:']);
67+
});
68+
69+
it('ignores objects without initializeDatabase', () => {
70+
expect(() => useHostSqliteDriver(null)).not.toThrow();
71+
expect(() => useHostSqliteDriver({})).not.toThrow();
72+
});
73+
74+
it('hands the real AgentDB.initialize() a working handle', async () => {
75+
const { AgentDB } = (await import('agentdb')) as any;
76+
const agentdb = new AgentDB({ dbPath: ':memory:' });
77+
useHostSqliteDriver(agentdb);
78+
let opened: unknown;
79+
const wrapped = agentdb.initializeDatabase.bind(agentdb);
80+
agentdb.initializeDatabase = async (p: string) => (opened = await wrapped(p));
81+
try {
82+
await agentdb.initialize();
83+
} catch {
84+
// Embedder/vector-backend setup may fail offline; the handle is what matters.
85+
}
86+
87+
expect(opened).toBeInstanceOf(Database);
88+
(opened as Database.Database | undefined)?.close();
89+
}, 60_000);
90+
});
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
/**
2+
* Open AgentDB's native SQLite handle with this package's better-sqlite3.
3+
*
4+
* agentdb 3.0.0-alpha.x declares `better-sqlite3: ^11.8.1`, so npm gives it a
5+
* nested 11.x copy next to our 12.x one. better-sqlite3 11.x ships no prebuilt
6+
* binary for Node 24 (ABI 137), so on Node 24 that copy is compiled from
7+
* source against the local headers. Node 24.19+ headers carry a partial
8+
* backport of `node::ObjectWrap` cleanup hooks (nodejs/node#65446): a
9+
* Statement collected by an allocation-driven GC calls
10+
* RemoveEnvironmentCleanupHook() with no Environment and the process aborts
11+
* with `Assertion failed: (env) != nullptr` — exit 134 for the CLI, "Connection
12+
* closed" for the MCP server.
13+
*
14+
* The 12.x copy we depend on ships a Node 24 prebuild, so routing AgentDB's
15+
* handle through it keeps the source-built 11.x addon out of the process.
16+
* `overrides` cannot do this: npm ignores them in a dependency's package.json,
17+
* which is where ours sit for anyone installing ruflo.
18+
*/
19+
20+
type AgentDBLike = {
21+
config?: { forceWasm?: boolean };
22+
usingWasm?: boolean;
23+
initializeDatabase?: (dbPath: string) => Promise<unknown>;
24+
};
25+
26+
/**
27+
* Replace `agentdb.initializeDatabase` so `initialize()` opens the database
28+
* with our better-sqlite3. Must be called before `agentdb.initialize()`.
29+
* Falls back to AgentDB's own loader when ours cannot open the file, and
30+
* leaves `forceWasm` instances alone.
31+
*/
32+
export function useHostSqliteDriver(agentdb: AgentDBLike | null | undefined): void {
33+
if (!agentdb || typeof agentdb.initializeDatabase !== 'function') return;
34+
if (agentdb.config?.forceWasm) return;
35+
36+
const agentdbLoader = agentdb.initializeDatabase.bind(agentdb);
37+
agentdb.initializeDatabase = async (dbPath: string) => {
38+
let db: { pragma(sql: string): unknown };
39+
try {
40+
const Database = (await import('better-sqlite3')).default;
41+
db = new Database(dbPath);
42+
} catch {
43+
return agentdbLoader(dbPath);
44+
}
45+
// Same setup as AgentDB.initializeDatabase()'s native branch.
46+
db.pragma('journal_mode = WAL');
47+
agentdb.usingWasm = false;
48+
return db;
49+
};
50+
}

‎v3/@claude-flow/memory/src/controller-registry.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import type { MemoryGraphConfig } from './memory-graph.js';
2727
import { TieredCacheManager } from './cache-manager.js';
2828
import type { CacheConfig } from './types.js';
2929
import { TieredMemoryStore } from './tiered-memory.js';
30+
import { useHostSqliteDriver } from './agentdb-native-driver.js';
3031

3132
// ===== Types =====
3233

@@ -579,6 +580,8 @@ export class ControllerRegistry extends EventEmitter {
579580
// stale) and init retried once with a fresh instance.
580581
await withAgentdbLockRecovery(dbPath, async () => {
581582
this.agentdb = new AgentDBClass({ dbPath });
583+
// Keep agentdb's nested better-sqlite3 11.x out of the process (Node 24 abort).
584+
useHostSqliteDriver(this.agentdb);
582585
await this.agentdb.initialize();
583586
});
584587
} finally {

0 commit comments

Comments
 (0)