moflo 4.10.7 → 4.10.9

package/dist/src/cli/mcp-tools/memory-tools.js

@@ -1,17 +1,16 @@
 /**
- * Memory MCP Tools for CLI - V3 with sql.js/HNSW Backend
+ * Memory MCP Tools for CLI — node:sqlite + HNSW backend
  *
- * UPGRADED: Now uses the advanced sql.js + HNSW backend for:
- * - 150x-12,500x faster semantic search
- * - Vector embeddings with cosine similarity
- * - Persistent SQLite storage (WASM)
- * - Backward compatible with legacy JSON storage (auto-migrates)
+ * Backed by Node's built-in `node:sqlite` engine (Phase 4 #1083 flipped the
+ * default; Phase 5 #1084 deleted the prior sql.js path) plus an HNSW vector
+ * index for semantic search. Auto-migrates legacy JSON stores on first use.
  *
  * @module v3/cli/mcp-tools/memory-tools
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { GateService } from '../services/spell-gate.js';
+import { BACKEND_LABEL } from '../memory/database-provider.js';
 // Paths
 const MEMORY_DIR = '.moflo/memory';
 const LEGACY_MEMORY_FILE = 'store.json';
@@ -108,7 +107,7 @@ function shapeRetrievedEntry(entry) {
         hasEmbedding: entry.hasEmbedding,
         navigation: parseNavigation(entry.metadata, 'full'),
         found: true,
-        backend: 'sql.js + HNSW',
+        backend: BACKEND_LABEL,
     };
 }
 function validateMemoryInput(key, value, query) {
@@ -185,7 +184,7 @@ async function ensureInitialized() {
     if (hasLegacyStore()) {
         const legacyStore = loadLegacyStore();
         if (legacyStore && Object.keys(legacyStore.entries).length > 0) {
-            console.error('[MCP Memory] Migrating legacy JSON store to sql.js...');
+            console.error('[MCP Memory] Migrating legacy JSON store to node:sqlite...');
             let migrated = 0;
             for (const [key, entry] of Object.entries(legacyStore.entries)) {
                 try {
@@ -211,7 +210,7 @@ async function ensureInitialized() {
 export const memoryTools = [
     {
         name: 'memory_store',
-        description: 'Store a value in memory with vector embedding for semantic search (sql.js + HNSW backend). Upserts by default — pass upsert:false to fail on duplicate keys. Optional `metadata` lets chunk-row producers set the navigation fields (parentDoc, prevChunk, nextChunk, siblings, …) that `memory_get_neighbors` reads.',
+        description: 'Store a value in memory with vector embedding for semantic search (node:sqlite + HNSW backend). Upserts by default — pass upsert:false to fail on duplicate keys. Optional `metadata` lets chunk-row producers set the navigation fields (parentDoc, prevChunk, nextChunk, siblings, …) that `memory_get_neighbors` reads.',
         category: 'memory',
         inputSchema: {
             type: 'object',
@@ -268,7 +267,7 @@ export const memoryTools = [
                     storedAt: new Date().toISOString(),
                     hasEmbedding: !!result.embedding,
                     embeddingDimensions: result.embedding?.dimensions || null,
-                    backend: 'sql.js + HNSW',
+                    backend: BACKEND_LABEL,
                     storeTime: `${duration.toFixed(2)}ms`,
                     error: result.error,
                 };
@@ -387,7 +386,7 @@ export const memoryTools = [
                     query,
                     results,
                     total: results.length,
-                    backend: 'HNSW + sql.js',
+                    backend: BACKEND_LABEL,
                 };
             }
             catch (error) {
@@ -479,7 +478,7 @@ export const memoryTools = [
                     include,
                     neighbors,
                     total: neighbors.length,
-                    backend: 'sql.js + HNSW',
+                    backend: BACKEND_LABEL,
                 };
             }
             catch (error) {
@@ -524,7 +523,7 @@ export const memoryTools = [
                     key,
                     namespace,
                     deleted,
-                    backend: 'sql.js + HNSW',
+                    backend: BACKEND_LABEL,
                     ...(errorReason ? { error: errorReason } : {}),
                 };
             }
@@ -577,7 +576,7 @@ export const memoryTools = [
                     total: result.total,
                     limit,
                     offset,
-                    backend: 'sql.js + HNSW',
+                    backend: BACKEND_LABEL,
                 };
             }
             catch (error) {
@@ -601,27 +600,47 @@ export const memoryTools = [
         },
         handler: async () => {
             await ensureInitialized();
-            const { checkMemoryInitialization, listEntries } = await getMemoryFunctions();
+            const { checkMemoryInitialization } = await getMemoryFunctions();
             try {
                 const status = await checkMemoryInitialization();
-                const allEntries = await listEntries({ limit: 100000 });
-                // Count by namespace
-                const namespaces = {};
-                let withEmbeddings = 0;
-                for (const entry of allEntries.entries) {
-                    namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;
-                    if (entry.hasEmbedding)
-                        withEmbeddings++;
+                // #1149 — server-side aggregation. The pre-fix path iterated every
+                // namespace via listEntries({limit:100000}) and tripped the daemon's
+                // `limit ≤ 10 000` cap → 400 → tryDaemonList defaulted total to 0 →
+                // the MCP tool silently reported zero entries on populated DBs.
+                // Route through the dedicated stats endpoint; on routed:false, run
+                // the same GROUP BY in-process so users always see real counts; on
+                // a daemon error, surface it rather than masking it as zero.
+                const { tryDaemonStats } = await import('../memory/daemon-write-client.js');
+                const routed = await tryDaemonStats();
+                let namespaces;
+                let totalEntries;
+                let withEmbeddings;
+                if (routed.routed && routed.data) {
+                    ({ namespaces, totalEntries, withEmbeddings } = routed.data);
+                }
+                else if (routed.routed && routed.error) {
+                    return {
+                        initialized: status.initialized,
+                        error: `daemon memory_stats failed: ${routed.error}`,
+                        backend: BACKEND_LABEL,
+                    };
+                }
+                else {
+                    const { getNamespaceCounts } = await import('../memory/memory-initializer.js');
+                    const direct = await getNamespaceCounts();
+                    namespaces = direct.namespaces;
+                    totalEntries = direct.total;
+                    withEmbeddings = direct.withEmbeddings;
                 }
                 return {
                     initialized: status.initialized,
-                    totalEntries: allEntries.total,
+                    totalEntries,
                     entriesWithEmbeddings: withEmbeddings,
-                    embeddingCoverage: allEntries.total > 0
-                        ? `${((withEmbeddings / allEntries.total) * 100).toFixed(1)}%`
+                    embeddingCoverage: totalEntries > 0
+                        ? `${((withEmbeddings / totalEntries) * 100).toFixed(1)}%`
                         : '0%',
                     namespaces,
-                    backend: 'sql.js + HNSW',
+                    backend: BACKEND_LABEL,
                     version: status.version || '3.0.0',
                     features: status.features || {
                         vectorEmbeddings: true,

package/dist/src/cli/memory/auto-memory-bridge.js

@@ -3,7 +3,7 @@
  *
  * Per ADR-048: Bridges Claude Code's auto memory (markdown files at
  * ~/.claude/projects/<project>/memory/) with claude-flow's unified memory
- * system (MofloDb: sql.js + HNSW).
+ * system (MofloDb: node:sqlite + HNSW).
  *
  * Auto memory files are human-readable markdown that Claude loads into its
  * system prompt. MEMORY.md (first 200 lines) is the entrypoint; topic files

package/dist/src/cli/memory/controllers/attestation-log.js

@@ -2,7 +2,7 @@
  * AttestationLog — moflo-owned append-only audit log (epic #464 Phase C2).
  *
  * Replaces `agentdb.AttestationLog`. Writes observability records into a
- * sql.js-backed table with a hash chain so tampering can be detected.
+ * SQLite table with a hash chain so tampering can be detected.
  *
  * Consumer surface (from src/cli/memory/memory-bridge.ts):
  *   - record({ operation, entryId, timestamp?, ...metadata })

package/dist/src/cli/memory/controllers/causal-graph.js

@@ -2,7 +2,7 @@
  * CausalGraph — moflo-owned causal edge store.
  *
  * Replaces `agentdb.CausalGraph.addEdge`. Stores typed edges between
- * memory-entry IDs in a sql.js-backed table with composite indexes so
+ * memory-entry IDs in a SQLite table with composite indexes so
  * CausalRecall's BFS walks don't hit a full scan on the relation filter.
  */
 import { clamp01, clampInt, parseJsonSafe } from './_shared.js';

package/dist/src/cli/memory/daemon-write-client.js

@@ -37,11 +37,18 @@
  * @module cli/memory/daemon-write-client
  */
 import * as http from 'node:http';
+import { findProjectRoot } from '../services/project-root.js';
+import { resolveClientPort, LEGACY_DEFAULT_PORT, probeDaemonHealth as probeDaemonHealthIdentity, normalizeProjectRoot, } from '../services/daemon-port.js';
 // ============================================================================
 // Constants
 // ============================================================================
-/** Default daemon HTTP port. Mirrors `DEFAULT_DASHBOARD_PORT` in daemon-dashboard.ts. */
-const DEFAULT_DAEMON_PORT = 3117;
+/**
+ * Read-only legacy default exported for tests; the actual port comes from
+ * `getDaemonPort()` which delegates to `resolveClientPort(findProjectRoot())`.
+ * Routes through `LEGACY_DEFAULT_PORT` so no literal port number lives in
+ * this file — see `daemon-port.ts` and the no-fixed-port regression guard.
+ */
+const DEFAULT_DAEMON_PORT = LEGACY_DEFAULT_PORT;
 /** HTTP timeout for ALL daemon requests (probe + write). Bounds the worst-case CLI hang. */
 const DAEMON_HTTP_TIMEOUT_MS = 100;
 /** Health-probe cache TTL. Probe at most once per 5s in either direction. */
@@ -55,18 +62,35 @@ let configCache = null;
 export function _resetForTest() {
     healthCache = null;
     configCache = null;
+    identityCache = null;
+    _portCache = null;
+    _identityWarnedFor.clear();
 }
 // ============================================================================
 // Resolve daemon port (env override → moflo.yaml unused for v1 → default)
 // ============================================================================
+/**
+ * Resolve the daemon HTTP port for this project.
+ *
+ * Delegates to `resolveClientPort(findProjectRoot())`:
+ *   1. `MOFLO_DAEMON_PORT` env override (consumer pin)
+ *   2. `port` field in `<projectRoot>/.moflo/daemon.lock` (server records
+ *      the actual bound port after startup — #1145)
+ *   3. Deterministic per-project port `33000 + sha256(path)%1000`
+ *
+ * Cached per-process — the lock-file path doesn't change once a process is
+ * up. On a routed-failure the health cache is invalidated (which triggers
+ * the next port resolve), keeping the client honest about daemon location
+ * after a recycle.
+ */
+let _portCache = null;
 function getDaemonPort() {
-    const fromEnv = process.env.MOFLO_DAEMON_PORT;
-    if (fromEnv) {
-        const n = parseInt(fromEnv, 10);
-        if (Number.isFinite(n) && n > 0 && n < 65536)
-            return n;
-    }
-    return DEFAULT_DAEMON_PORT;
+    const projectRoot = findProjectRoot();
+    if (_portCache && _portCache.projectRoot === projectRoot)
+        return _portCache.port;
+    const port = resolveClientPort(projectRoot);
+    _portCache = { port, projectRoot };
+    return port;
 }
 // ============================================================================
 // Daemon-disabled check (cached) — reads `daemon.auto_start` from moflo.yaml
@@ -90,12 +114,18 @@ async function isDaemonEnabledInConfig() {
     configCache = { daemonEnabled: enabled, checkedAt: now };
     return enabled;
 }
-// ============================================================================
-// Health probe (cached) — GET /api/status
-// ============================================================================
+let identityCache = null;
+/**
+ * Ports we've already warned about during this process — bounded by the
+ * number of distinct daemon ports a single client process can see in its
+ * lifetime (usually 1). Keeps the stderr noise to a single line per
+ * mismatched daemon per process.
+ */
+const _identityWarnedFor = new Set();
 /**
  * Cached daemon health probe. Returns true iff the daemon's HTTP server
- * is reachable on `127.0.0.1:<port>` within {@link DAEMON_HTTP_TIMEOUT_MS}.
+ * is reachable on `127.0.0.1:<port>` within {@link DAEMON_HTTP_TIMEOUT_MS}
+ * AND its `/api/health` reports a `projectRoot` matching ours (#1145).
  *
  * Cache survives 5s in either direction — so a daemon that just came up
  * is missed for ≤5s, and a daemon that just died is incorrectly assumed
@@ -113,9 +143,74 @@ export async function isDaemonAvailable() {
     if (healthCache && (now - healthCache.checkedAt) < HEALTH_CACHE_TTL_MS) {
         return healthCache.available;
     }
-    const available = await probeDaemonHealth(getDaemonPort());
-    healthCache = { available, checkedAt: now };
-    return available;
+    const port = getDaemonPort();
+    const reachable = await probeDaemonHealth(port);
+    if (!reachable) {
+        healthCache = { available: false, checkedAt: now };
+        return false;
+    }
+    // 4) Identity check — daemon reachable but is it OUR daemon?
+    const identityOk = await isDaemonIdentityMatch(port);
+    healthCache = { available: identityOk, checkedAt: now };
+    return identityOk;
+}
+/**
+ * Probe `/api/health` and confirm the daemon's reported `projectRoot`
+ * matches ours. Caches the result for {@link HEALTH_CACHE_TTL_MS}.
+ *
+ * Mismatch consequence: this function returns `false`, the caller falls
+ * through to the direct-SQL path (the path that is provably correct, see
+ * the `MOFLO_DISABLE_DAEMON_ROUTING=1` reproducer in
+ * `docs/internal/1145-daemon-port-collision-analysis.md`), and we emit
+ * ONE stderr line per port per process so the user can see the wrong-
+ * project daemon is the problem.
+ *
+ * Tolerant of legacy daemons that don't expose `/api/health`: a 404 means
+ * the daemon predates #1145, so we trust the legacy port resolution (the
+ * client is presumably hitting the same project's daemon anyway) and
+ * return `true`. The lock-file port-discovery path is the primary
+ * collision defence; identity check is the safety net.
+ */
+async function isDaemonIdentityMatch(port) {
+    const now = Date.now();
+    const ourProjectRoot = findProjectRoot();
+    if (identityCache &&
+        identityCache.ourProjectRoot === ourProjectRoot &&
+        (now - identityCache.checkedAt) < HEALTH_CACHE_TTL_MS) {
+        return identityCache.matches;
+    }
+    const probe = await probeDaemonHealthIdentity(port, DAEMON_HTTP_TIMEOUT_MS);
+    if (probe.kind === 'legacy' || probe.kind === 'unreachable') {
+        // No identity to compare — daemon either predates #1145 or the probe
+        // itself failed transport-side. Fall open: rely on port-discovery
+        // (lock file + deterministic hash) as the primary defence. Only a
+        // CONFIRMED mismatch blocks routing — that's the conservative safety
+        // net that doesn't break upgraded-client-against-legacy-daemon.
+        //
+        // Asymmetry with doctor's `checkDaemonIdentity`: the healer probes
+        // LEGACY_DEFAULT_PORT explicitly and flags a foreign legacy daemon
+        // as `fail`, while this hot path lets it through. That's intentional
+        // — the doctor runs on-demand for diagnostics, and live writes must
+        // not block when the cluster is mid-upgrade. The CHANGELOG migration
+        // window is the agreed remediation surface.
+        identityCache = { matches: true, checkedAt: now, ourProjectRoot };
+        return true;
+    }
+    const matches = normalizeProjectRoot(probe.projectRoot) === normalizeProjectRoot(ourProjectRoot);
+    identityCache = {
+        matches,
+        checkedAt: now,
+        ourProjectRoot,
+        daemonProjectRoot: probe.projectRoot,
+    };
+    if (!matches && !_identityWarnedFor.has(port)) {
+        _identityWarnedFor.add(port);
+        // One stderr line per mismatched daemon, ever. Quiet enough that scripts
+        // don't drown but loud enough that healer-class diagnostics surface it.
+        process.stderr.write(`[moflo] daemon at 127.0.0.1:${port} claims project '${probe.projectRoot}' but cwd is '${ourProjectRoot}' — ` +
+            `using direct DB. Run flo healer --fix to repair daemon binding (#1145).\n`);
+    }
+    return matches;
 }
 function probeDaemonHealth(port) {
     return new Promise((resolve) => {
@@ -212,6 +307,31 @@ export async function tryDaemonList(opts) {
         total: typeof data?.total === 'number' ? data.total : 0,
     }));
 }
+/**
+ * Route a memory-stats query through the daemon (#1149). Single GROUP BY
+ * query server-side — replaces the list-and-iterate path in the MCP
+ * `memory_stats` handler that fetched up to 100 000 rows just to count
+ * them and tripped the daemon's `limit ≤ 10 000` cap.
+ *
+ * Returns `{ routed: false }` when the daemon is unavailable or any 5xx /
+ * transport fault fires — caller falls back to a direct
+ * `getNamespaceCounts()` so users never see a fake zero.
+ */
+export async function tryDaemonStats() {
+    if (!(await isDaemonAvailable()))
+        return { routed: false };
+    return requestReadJson('GET', '/api/memory/stats', undefined, (data) => {
+        if (typeof data?.totalEntries !== 'number')
+            return null;
+        return {
+            namespaces: (data?.namespaces && typeof data.namespaces === 'object')
+                ? data.namespaces
+                : {},
+            totalEntries: data.totalEntries,
+            withEmbeddings: typeof data?.withEmbeddings === 'number' ? data.withEmbeddings : 0,
+        };
+    });
+}
 // ============================================================================
 // Internal HTTP poster — never throws, bounded timeout
 // ============================================================================
@@ -261,8 +381,14 @@ function postJson(path, body) {
             // On routed-failure, invalidate the health cache so the next call
             // re-probes and trips back to direct-write quickly when the daemon
             // is dying.
-            if (result.routed === false)
+            if (result.routed === false) {
+                // Daemon recycled to a different port (post #1145 server restart)
+                // → invalidate the port cache too so the next call re-reads
+                // .moflo/daemon.lock. Otherwise we'd keep hammering a stale port.
                 healthCache = null;
+                identityCache = null;
+                _portCache = null;
+            }
             resolve(result);
         };
         const payload = JSON.stringify(body);
@@ -322,45 +448,49 @@ function postJson(path, body) {
     });
 }
 /**
- * Generic JSON POST that returns a daemon-read envelope. Same transport
- * guarantees as `postJson`: never throws, bounded timeout, invalidates health
- * cache on routed-failure.
+ * Generic JSON read-request that returns a daemon-read envelope. Never
+ * throws, bounded by `DAEMON_HTTP_TIMEOUT_MS`, invalidates the health +
+ * identity + port caches on any routed-failure (daemon-recycle covers).
  *
- * The `shape` callback maps the daemon's parsed JSON payload to the typed
- * data shape the caller expects. Returning `null` from `shape` (or a parse
- * failure) downgrades to `{ routed: false }` so the caller falls back.
+ * Failure-shape contract (#1101):
+ *   2xx                            → routed:true with shape(data)
+ *   4xx                            → routed:true with error (caller propagates)
+ *   5xx / transport / parse-fail   → routed:false (caller falls back)
+ *
+ * `body === undefined` ⇒ GET (no Content-* headers); otherwise POST with
+ * JSON body. The `shape` callback maps parsed JSON to the typed payload;
+ * returning `null` downgrades the response to routed:false so the caller
+ * falls back to bridge-direct.
  */
-function postReadJson(path, body, shape) {
+function requestReadJson(method, path, body, 
+// `data` is a JSON.parse boundary — typed `any` here mirrors JSON.parse's
+// own return type so callers can do safe optional-chaining narrowing.
+shape) {
     return new Promise((resolve) => {
         let done = false;
         const finish = (result) => {
             if (done)
                 return;
             done = true;
-            if (result.routed === false)
+            if (result.routed === false) {
+                // Daemon may have recycled to a new port (post-#1145 restart) →
+                // invalidate the lock-file-port cache and the identity probe so
+                // the next call re-discovers reality.
                 healthCache = null;
+                identityCache = null;
+                _portCache = null;
+            }
             resolve(result);
         };
-        const payload = JSON.stringify(body);
-        const req = http.request({
-            host: '127.0.0.1',
-            port: getDaemonPort(),
-            path,
-            method: 'POST',
-            timeout: DAEMON_HTTP_TIMEOUT_MS,
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': Buffer.byteLength(payload),
-            },
-        }, (res) => {
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        const headers = payload === undefined
+            ? undefined
+            : { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) };
+        const req = http.request({ host: '127.0.0.1', port: getDaemonPort(), path, method, timeout: DAEMON_HTTP_TIMEOUT_MS, headers }, (res) => {
             let buf = '';
             res.setEncoding('utf8');
             res.on('data', (chunk) => { buf += chunk; });
             res.on('end', () => {
-                // #1101 — mirror postJson contract for reads:
-                //   2xx  → routed:true with shaped data
-                //   4xx  → routed:true with error (no data) — caller propagates
-                //   5xx  → routed:false (caller falls back)
                 const status = res.statusCode ?? 0;
                 if (status >= 500 || status < 200) {
                     finish({ routed: false });
@@ -371,13 +501,8 @@ function postReadJson(path, body, shape) {
                     return;
                 }
                 try {
-                    const parsed = JSON.parse(buf);
-                    const shaped = shape(parsed);
-                    if (shaped === null) {
-                        finish({ routed: false });
-                        return;
-                    }
-                    finish({ routed: true, data: shaped });
+                    const shaped = shape(JSON.parse(buf));
+                    finish(shaped === null ? { routed: false } : { routed: true, data: shaped });
                 }
                 catch {
                     finish({ routed: false });
@@ -387,8 +512,12 @@ function postReadJson(path, body, shape) {
         });
         req.on('error', () => finish({ routed: false }));
         req.on('timeout', () => { req.destroy(); finish({ routed: false }); });
-        req.write(payload);
+        if (payload !== undefined)
+            req.write(payload);
         req.end();
     });
 }
+function postReadJson(path, body, shape) {
+    return requestReadJson('POST', path, body, shape);
+}
 //# sourceMappingURL=daemon-write-client.js.map

package/dist/src/cli/memory/database-provider.js

@@ -11,6 +11,13 @@
 import { platform } from 'node:os';
 import { existsSync } from 'node:fs';
 import { SqliteBackend } from './sqlite-backend.js';
+/**
+ * Canonical label returned in MCP `backend` fields and other consumer-visible
+ * surfaces. Single source of truth so a future engine swap is a one-line edit
+ * instead of an 8-site grep. Phase 5 (#1084) finalized node:sqlite as the
+ * only SQLite backend; the HNSW vector index sits on top.
+ */
+export const BACKEND_LABEL = 'node:sqlite + HNSW';
 /**
  * Detect platform and recommend provider
  */
@@ -118,9 +125,15 @@ async function selectProvider(preferred, verbose = false) {
  * ```
  */
 export async function createDatabase(path, options = {}) {
-    const { provider = 'auto', verbose = false, walMode: _walMode = true, optimize = true, defaultNamespace = 'default', maxEntries = 1000000, autoPersistInterval = 5000, wasmPath: _wasmPath, } = options;
-    // Select provider
-    const selectedProvider = await selectProvider(provider, verbose);
+    const { provider, verbose = false, walMode: _walMode = true, optimize = true, defaultNamespace = 'default', maxEntries = 1000000, autoPersistInterval = 5000, wasmPath: _wasmPath, } = options;
+    // When no explicit provider is given, consult moflo.yaml's
+    // `memory.backend` knob (#1144). This is what makes the YAML value
+    // truthful instead of cosmetic — the runtime now actually honours
+    // whatever the consumer put in their config. Falls back to `'auto'` if
+    // the config can't be loaded (e.g. running from a directory with no
+    // `moflo.yaml`), preserving the previous behaviour for raw callers.
+    const effectiveProvider = provider ?? (await preferredProviderFromConfig(verbose)) ?? 'auto';
+    const selectedProvider = await selectProvider(effectiveProvider, verbose);
     if (verbose) {
         console.log(`[DatabaseProvider] Creating database with provider: ${selectedProvider}`);
         console.log(`[DatabaseProvider] Database path: ${path}`);
@@ -178,6 +191,48 @@ export async function createDatabase(path, options = {}) {
 export function getPlatformInfo() {
     return detectPlatform();
 }
+/**
+ * Read `memory.backend` from the project's `moflo.yaml`, resolve any
+ * deprecated aliases (sql.js → node-sqlite), and return a value
+ * `selectProvider()` understands. Returns `null` on any failure so
+ * `createDatabase()` cleanly falls back to platform auto-detection
+ * — config loading must never break the runtime.
+ *
+ * Wrapped in a dynamic import so the memory subtree doesn't pull
+ * `js-yaml` / `fs` into hot paths (e.g. the in-memory test backend).
+ *
+ * Memoised per (cwd, process) — a test suite or daemon that opens many
+ * DBs in sequence parses moflo.yaml once. Keyed on cwd so a test that
+ * `chdir`s into a temp dir gets a fresh resolution.
+ */
+const _resolvedProviderCache = new Map();
+async function preferredProviderFromConfig(verbose) {
+    const key = process.cwd();
+    if (_resolvedProviderCache.has(key)) {
+        return _resolvedProviderCache.get(key) ?? null;
+    }
+    try {
+        const { loadMofloConfig, resolveDatabaseProvider } = await import('../config/moflo-config.js');
+        const cfg = loadMofloConfig();
+        const resolved = resolveDatabaseProvider(cfg.memory.backend);
+        if (verbose) {
+            console.log(`[DatabaseProvider] moflo.yaml memory.backend="${cfg.memory.backend}" → ${resolved}`);
+        }
+        _resolvedProviderCache.set(key, resolved);
+        return resolved;
+    }
+    catch (err) {
+        if (verbose) {
+            console.warn(`[DatabaseProvider] Could not load moflo.yaml backend preference (${err.message}) — falling back to auto-detection`);
+        }
+        _resolvedProviderCache.set(key, null);
+        return null;
+    }
+}
+/** @internal — test hook only; resets the per-cwd cache between cases. */
+export function _resetPreferredProviderCache() {
+    _resolvedProviderCache.clear();
+}
 /**
  * Check which providers are available.
  *