moflo 4.9.36 → 4.10.0

package/.claude/guidance/shipped/moflo-agent-rules.md

@@ -24,6 +24,18 @@
 
 **Search `tests` when looking for test coverage** of a function, module, or behavior — it indexes the test tree separately so you can pinpoint specs without grepping the whole repo.
 
+### Traverse Chunks, Don't Bulk-Retrieve
+
+Search returns chunked guidance with a compact `navigation` crumb (`parentDoc`, `prevChunk`, `nextChunk`, `chunkTitle`). Use it:
+
+| Want | Use |
+|------|-----|
+| Adjacent / sibling / hierarchical context | `mcp__moflo__memory_get_neighbors` |
+| Full content of one chunk | `mcp__moflo__memory_retrieve` (returns full nav for further traversal) |
+| Whole source doc | `Read` `parentPath` from any chunk's nav |
+
+Full protocol: `.claude/guidance/moflo-memory-protocol.md`. Don't retrieve every search hit blindly.
+
 ### Tool Selection (MCP-first)
 
 | Tool | Purpose |

package/.claude/guidance/shipped/moflo-memory-protocol.md

@@ -0,0 +1,34 @@
+# MoFlo Memory Protocol — Search, Traverse, Retrieve
+
+**Purpose:** How to use moflo's chunked memory effectively. Search returns navigable chunks — traverse the chunk graph, do not bulk-retrieve every hit.
+
+---
+
+## Rule (MUST)
+
+When a search hit carries a non-null `navigation`, you MUST call `mcp__moflo__memory_get_neighbors` to traverse — not `mcp__moflo__memory_retrieve`. `memory_retrieve` is for fetching one specific chunk in full, or for non-chunk entries where `navigation` is null. Bulk-retrieving search hits defeats the chunking architecture.
+
+## Decision Table
+
+| You want | Use | Why |
+|----------|-----|-----|
+| Find an entry-point | `mcp__moflo__memory_search` | Returns chunk hits with compact `navigation` (parentDoc, prev/next, chunkTitle) |
+| Adjacent context (1 chunk over) | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, returns shaped entries with full nav |
+| Same-section peers (h2/h3 family) | `memory_get_neighbors` `{ include: ['siblings'] }` or `['parent','children']` | Hierarchical traversal — cheaper than re-searching |
+| Full content of one chunk | `mcp__moflo__memory_retrieve` `{ key }` | Returns full nav object for further traversal |
+| Whole source doc when truly needed | `Read` `parentPath` from any chunk's nav | Disk read is cheaper than re-indexed `doc-*` |
+
+## Anti-Patterns
+
+| Don't | Do instead |
+|-------|-----------|
+| Retrieve every search hit blindly | Traverse via `memory_get_neighbors` when `navigation` is present — bulk `memory_retrieve` per hit is a protocol violation |
+| Open the source file when a chunk would do | Stay in the chunk graph; `Read` `parentPath` only for the rare full-doc case |
+| Search again for a key you already have | `memory_retrieve` or `memory_get_neighbors` directly |
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — namespaces, query examples, MCP-first tool selection
+- `.claude/guidance/moflo-memory-strategy.md` — How chunking, embeddings, and the RAG index work

package/.claude/guidance/shipped/moflo-memorydb-maintenance.md

@@ -7,10 +7,26 @@
 ## Database Location
 
 - **Path:** `.moflo/moflo.db` — canonical location
-- **Engine:** sql.js (WASM-based SQLite — no native binaries needed)
+- **Engine:** `node:sqlite` (built into Node 22+) running in WAL mode — multi-process safe via POSIX/Windows file locks. The sql.js (WASM) backend is no longer used and the npm dep is being removed.
 - **Single table:** `memory_entries` — stores content, embeddings, and metadata in one table
+- **WAL sidecars:** `.moflo/moflo.db-wal` + `.moflo/moflo.db-shm` appear next to `moflo.db` after the first write. Don't commit them; don't manually delete them while moflo is running.
 - **Legacy path:** `.swarm/memory.db` — older consumers may still have this. The launcher migrates it to `.moflo/moflo.db` automatically on session start. After migration the legacy file is renamed `.swarm/memory.db.bak` and is safe to delete once you've verified the canonical DB is healthy (`flo doctor`).
 
+## Network filesystem caveat
+
+SQLite's multi-process safety relies on POSIX/Windows file locking and on shared-memory WAL sidecars. **Neither works reliably on network-mounted filesystems** — NFS, SMB/CIFS, sshfs, and some FUSE mounts silently break advisory locks and refuse to map the `.db-shm` shared-memory region. If `.moflo/moflo.db` lives on a network mount, two moflo processes can clobber each other's writes and you may see partial-row corruption.
+
+On first open against a non-WAL-capable filesystem moflo emits a one-line stderr warning naming the path:
+
+```
+[moflo] WARNING: SQLite journal_mode=delete on /mnt/network/proj/.moflo/moflo.db (WAL not active).
+If this directory is on NFS/SMB or another network filesystem, POSIX advisory locks are unreliable
+and concurrent moflo processes can corrupt the database. Move the project to a local disk to
+restore multi-process safety.
+```
+
+The warning is deduplicated per path per process. If you see it: move the project (or just the `.moflo/` directory) onto a local disk. There is no in-product workaround — single-machine SQLite cannot be made safe over a remote filesystem.
+
 ## Schema
 
 ```sql
@@ -73,33 +89,28 @@ node bin/build-embeddings.mjs
 
 ## Purging a Namespace
 
-Use sql.js directly (no sqlite3 binary required):
+Use the backend factory so you get the same engine + WAL semantics every other writer uses:
 
 ```js
 node --input-type=module -e "
-import initSqlJs from 'sql.js';
-import { readFileSync, writeFileSync } from 'fs';
+import { openBackend } from 'moflo/bin/lib/get-backend.mjs';
 
-const SQL = await initSqlJs();
-const buf = readFileSync('.moflo/moflo.db');
-const db = new SQL.Database(buf);
+const db = await openBackend(process.cwd(), { create: false });
 
-// Check counts before
 const before = db.exec('SELECT namespace, COUNT(*) FROM memory_entries GROUP BY namespace');
 console.log('BEFORE:', JSON.stringify(before[0]?.values));
 
-// Purge a namespace (embeddings are inline — no separate table to clean)
 db.run(\"DELETE FROM memory_entries WHERE namespace = 'code-map'\");
 
 const after = db.exec('SELECT namespace, COUNT(*) FROM memory_entries GROUP BY namespace');
 console.log('AFTER:', JSON.stringify(after[0]?.values));
 
-writeFileSync('.moflo/moflo.db', Buffer.from(db.export()));
+db.save();
 db.close();
 "
 ```
 
-> **Important — sql.js write-back clobbers manual edits.** Long-lived processes (the moflo daemon, MCP servers) read the DB once on startup and dump the entire in-memory state on every flush. Direct `node -e` writes against `.moflo/moflo.db` while the daemon is running will be overwritten the next time it flushes. Run `flo daemon stop` (or stop your editor's MCP session) before purging, then restart afterwards.
+Under node:sqlite the `db.save()` call is a no-op (WAL persists incrementally), but the factory keeps the API parity so the same snippet works against any backend the factory currently knows about. Concurrent writers serialize through WAL — running this while the daemon is up no longer clobbers anything — but if you want to be defensive, `flo daemon stop` before purging is still the cleanest sequence.
 
 After purging, reindex the namespace and rebuild embeddings:
 ```bash

package/.claude/guidance/shipped/moflo-root-cause-discipline.md

@@ -91,6 +91,35 @@ When you find that the test is the actual problem: change the test, document why
 
 ---
 
+## Never Mask a Production Bug with Test-Side Workarounds
+
+**When a test catches a real bug, fix the bug — never the test.** A test that passes by avoiding the broken path is a lie about coverage.
+
+| Symptom test exposed | Right move | Wrong move (firing-offense pattern) |
+|---------------------|-----------|-------------------------------------|
+| Race between writers | Coordinate the writers | Reorder test so the race window closes before the assertion |
+| Data corruption from a known writer | Find and fix the writer | Pre-seed the corrupted state so the assertion no longer fires |
+| Stale cache served to readers | Invalidate the cache properly | Add `sleep` / `refresh()` in test to mask staleness |
+| Cross-process clobber on a shared file | Single-writer ownership or atomic write | Order the test so only one writer runs |
+| Missing precondition guard in prod | Add the guard | Have test setup satisfy the guard's precondition |
+
+**Smell test:** read the test setup as a description of production behavior. If steps appear that production code does not perform, the test is mocking around a real bug.
+
+### Case Study: #1053 Memory Traversal
+
+> "Healer: probeMemoryGetNeighbors() runs first in checkMemoryAccessFunctional so the bridge instantiates after the seed lands (sql.js whole-DB writeback clobbers external file writes once the in-memory snapshot warms)." — PR #1053 commit
+
+Diagnosis correct; fix wrong. The clobber stayed in production. `moflo@4.9.37` shipped two regressions to every consumer (migration-induced embedding loss + `memory_store` silent drop) because the suite was engineered around the failure it had just detected.
+
+### Self-Check Before Merging Any Test-Only Change
+
+1. **Did the test fail first?** Name the production bug it caught.
+2. **Did my fix change only the test?** If yes, the runtime contract must be the bug — document why in the commit message.
+3. **Would a real user still hit this in production?** If yes, fix the bug, not the test.
+4. **Does test code comment *why* it sleeps / reorders / mocks?** That comment usually names a production bug — move the fix to production.
+
+---
+
 ## Concrete Example: #1017 Hive-Mind Shutdown
 
 This is the canonical case study for this guidance — and it has a second-order lesson that makes it even more useful.
@@ -141,11 +170,29 @@ Reviewers should reject — not just question — PRs that show patch-on-patch s
 | New fix adds a layer without removing one | Ask: "what was wrong with the prior layer? why does it stay?" |
 | Comment in new code says "for safety" or "just in case" | Ask: "what specific failure is this preventing? cite the line that produces it" |
 | The PR description says "this should fix the flake" without a deterministic repro | Ask: "what was the actual root cause? the writeup doesn't name it" |
+| Commit message names a production bug, then describes test setup that avoids it | **Reject.** The bug stays live in production. Demand a fix at the production-code locus, not at the test. |
 
 These questions are not pedantic. They are the difference between fixing a bug and growing the surface area of bugs.
 
 ---
 
+## Scoping a Fix Issue — Kill the Class, Not the Instance
+
+**When you file an issue for a bug, scope it to eliminate the bug class, not patch the visible instance.** Partial scope guarantees a follow-up epic.
+
+| Posture | Right | Wrong |
+|---------|-------|-------|
+| Scope | Name the bug class; list every writer / caller / consumer that can produce it | Name only the surface where the symptom showed |
+| Strategy | Commit to one approach in the body — "we will do X" | "Pick one of: option A or option B" |
+| Audit | Enumerate every member of the class (every writer, every caller, every migration) | Patch the one path that broke today |
+| Acceptance | Every original failure mode reproduces today and is gone after the epic; a new violator triggers a loud test | Symptom no longer reproduces |
+| Tests | Mirror the production failure shape (multi-process, cross-writer, time-coupled) | In-process unit tests only |
+| Follow-ups | None — anything that would be a follow-up is added to scope now | "We'll address this in a separate issue" |
+
+If the epic body says "we'll figure out X in a follow-up", the scope is wrong — fold X in or explain why it cannot be in scope (e.g., depends on a release boundary).
+
+---
+
 ## How to Apply When You Are Stuck
 
 If you genuinely cannot find the root cause after stepping back:

package/.claude/guidance/shipped/moflo-subagents.md

@@ -18,6 +18,10 @@ CLI fallback when MCP is unavailable: `npx flo memory search --query "..." --nam
 
 The full namespace reference, query examples by domain, and tool catalog live in `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — read that next.
 
+### Traverse, don't bulk-retrieve
+
+Search hits carry a compact `navigation` crumb. For adjacent/sibling/hierarchical context, call `mcp__moflo__memory_get_neighbors` (one round-trip) instead of retrieving every hit. Full protocol: `.claude/guidance/moflo-memory-protocol.md`.
+
 ---
 
 ## Step 2: Apply Universal Agent Rules

package/.claude/helpers/gate.cjs

@@ -307,7 +307,7 @@ switch (command) {
       process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
     }
     if (config.memory_first && s.memoryRequired && !s.memorySearched) {
-      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents.\n');
+      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     }
     if (s.lastNamespaceHint) {
       // Per-actor single-shot. Each session_id gets the hint at most once per
@@ -376,7 +376,7 @@ switch (command) {
     if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -386,7 +386,7 @@ switch (command) {
     var fp = process.env.TOOL_INPUT_file_path || '';
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'record-task-created': {

package/.claude/helpers/statusline.cjs

@@ -485,58 +485,81 @@ function getHooksStatus() {
 }
 
 // Embeddings stats — reads from cache file written by embedding/memory ops.
-// No subprocess spawning. Falls back to DB file size estimate if cache is missing.
+// No subprocess spawning.
+//
+// Reconciliation (epic #1054.S5 / #1059): the cached vectorCount is only
+// trusted when (a) the daemon owns the lock and (b) the daemon's reported
+// `version` matches the installed package version. Either failing means the
+// cache may have been written by a clobbered or pre-upgrade writer, so the
+// number is flagged `reconciled: false` and the render path shows `?` instead
+// of a value that can't be vouched for. The prior `dbSize / 2` heuristic
+// fallback was exactly the unreconciled fabrication the story prohibits, so
+// it's removed.
 function getEmbeddingsStats() {
   let vectorCount = 0;
   let dbSizeKB = 0;
   let namespaces = 0;
   let hasHnsw = false;
+  let reconciled = false;
+  let staleReason = null;
 
-  // Read cached stats (written by memory store/embed/rebuild commands).
-  // `.moflo/` is the canonical location post-#699; the `.swarm/` parallel
-  // write was retired in #714 because every writer (bridge-core,
-  // memory-initializer, build-embeddings) now writes here, so the legacy
-  // fallback can only ever be stale — exactly the divergence trap that
-  // produced #639.
   const cached = readJSON(path.join(CWD, '.moflo', 'vector-stats.json'));
   if (cached && typeof cached.vectorCount === 'number') {
     vectorCount = cached.vectorCount;
     dbSizeKB = cached.dbSizeKB || 0;
     namespaces = cached.namespaces || 0;
     hasHnsw = cached.hasHnsw || false;
-    return { vectorCount, dbSizeKB, namespaces, hasHnsw };
-  }
 
-  // Fallback: estimate from DB file size (no subprocess). Same probe order
-  // as `getLearningStats` above — see comment there.
-  const dbFiles = [
-    path.join(CWD, '.moflo', 'moflo.db'),
-    path.join(CWD, '.swarm', 'memory.db'),
-    path.join(CWD, 'data', 'memory.db'),
-    path.join(CWD, '.claude', 'memory.db'),
-  ];
-  for (const f of dbFiles) {
-    const stat = safeStat(f);
-    if (stat) {
-      dbSizeKB = Math.floor(stat.size / 1024);
-      vectorCount = Math.floor(dbSizeKB / 2);
-      namespaces = 1;
-      break;
+    // Reconciliation against the daemon (single-writer authority post-#1054).
+    const daemonLock = readJSON(path.join(CWD, '.moflo', 'daemon.lock'));
+    const installedPkg = readJSON(path.join(CWD, 'node_modules', 'moflo', 'package.json'))
+                      || readJSON(path.join(CWD, 'package.json'));
+    if (!daemonLock || typeof daemonLock.pid !== 'number') {
+      staleReason = 'daemon-down';
+    } else if (!installedPkg || typeof installedPkg.version !== 'string') {
+      staleReason = 'pkg-unknown';
+    } else if (daemonLock.version !== installedPkg.version) {
+      staleReason = 'version-skew';
+    } else {
+      reconciled = true;
     }
+  } else {
+    staleReason = 'cache-missing';
   }
 
   const hnswPaths = [
     path.join(CWD, '.moflo', 'hnsw.index'),
     path.join(CWD, '.swarm', 'hnsw.index'), // legacy pre-#727
   ];
-  for (const p of hnswPaths) {
-    if (safeStat(p)) {
-      hasHnsw = true;
-      break;
+  if (!hasHnsw) {
+    for (const p of hnswPaths) {
+      if (safeStat(p)) {
+        hasHnsw = true;
+        break;
+      }
+    }
+  }
+
+  // Fall back to a DB-size probe ONLY for the size display (which has no truth
+  // claim); vectorCount remains 0 when cache is missing rather than fabricating
+  // a divide-by-2 heuristic.
+  if (dbSizeKB === 0) {
+    const dbFiles = [
+      path.join(CWD, '.moflo', 'moflo.db'),
+      path.join(CWD, '.swarm', 'memory.db'),
+      path.join(CWD, 'data', 'memory.db'),
+      path.join(CWD, '.claude', 'memory.db'),
+    ];
+    for (const f of dbFiles) {
+      const stat = safeStat(f);
+      if (stat) {
+        dbSizeKB = Math.floor(stat.size / 1024);
+        break;
+      }
     }
   }
 
-  return { vectorCount, dbSizeKB, namespaces, hasHnsw };
+  return { vectorCount, dbSizeKB, namespaces, hasHnsw, reconciled, staleReason };
 }
 
 // Test stats (count files only — NO reading file contents)
@@ -798,13 +821,20 @@ function generateDashboard() {
   // Embeddings line \u2014 vector store stats from .moflo/vector-stats.json.
   // Reuses `system.embeddings` (already computed by getSystemMetrics()) instead
   // of re-probing the cache file on every render.
+  //
+  // Reconciliation (#1054.S5 / #1059): when `vec.reconciled` is false, render
+  // the count as `?` and tag the reason \u2014 the underlying cache could have been
+  // written by a stale daemon and we refuse to display an unverified number.
   {
     const vec = system.embeddings;
-    if (vec.vectorCount > 0) {
+    if (vec.vectorCount > 0 || !vec.reconciled) {
       const hnswInd = vec.hasHnsw ? `${c.brightGreen}\u26A1${c.reset}` : '';
       const sizeDisp = vec.dbSizeKB >= 1024 ? `${(vec.dbSizeKB / 1024).toFixed(1)}MB` : `${vec.dbSizeKB}KB`;
+      const countDisp = vec.reconciled
+        ? `${c.brightGreen}\u25CF${vec.vectorCount}${c.reset}${hnswInd}`
+        : `${c.brightYellow}?${c.reset} ${c.dim}(${vec.staleReason || 'unreconciled'})${c.reset}`;
       const eParts = [
-        `${c.cyan}Vectors${c.reset} ${c.brightGreen}\u25CF${vec.vectorCount}${c.reset}${hnswInd}`,
+        `${c.cyan}Vectors${c.reset} ${countDisp}`,
         `${c.cyan}Size${c.reset} ${c.brightWhite}${sizeDisp}${c.reset}`,
       ];
       if (vec.namespaces > 0) {
@@ -877,13 +907,19 @@ function generateCompactDashboard() {
   }
   // Embeddings \u2014 always-on when vectorCount > 0; self-hides on a fresh install.
   // Compact doesn't call getSystemMetrics() so this is the only probe per render.
+  // Reconciliation: when the count is unreconciled (#1054.S5 / #1059), render
+  // `?` rather than displaying a value that can't be verified across the
+  // cache + daemon-reported state.
   {
     const vec = getEmbeddingsStats();
-    if (vec.vectorCount > 0) {
+    if (vec.vectorCount > 0 || !vec.reconciled) {
       const hnswInd = vec.hasHnsw ? '\u26A1' : '';
       const sizeDisp = vec.dbSizeKB >= 1024 ? `${(vec.dbSizeKB / 1024).toFixed(1)}MB` : `${vec.dbSizeKB}KB`;
+      const countDisp = vec.reconciled
+        ? `${c.brightGreen}${vec.vectorCount}${hnswInd}${c.reset}`
+        : `${c.brightYellow}?${c.reset}`;
       segments.push(
-        `${c.brightCyan}\uD83D\uDCCA${c.reset} ${c.brightGreen}${vec.vectorCount}${hnswInd}${c.reset} ${c.dim}(${sizeDisp})${c.reset}`
+        `${c.brightCyan}\uD83D\uDCCA${c.reset} ${countDisp} ${c.dim}(${sizeDisp})${c.reset}`
       );
     }
   }

package/.claude/helpers/subagent-bootstrap.json

@@ -1,3 +1,3 @@
 {
-  "directive": "MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol."
+  "directive": "MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol. When a search hit carries `navigation`, you MUST call mcp__moflo__memory_get_neighbors to traverse — calling mcp__moflo__memory_retrieve on every hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`."
 }

package/.claude/helpers/subagent-start.cjs

@@ -22,7 +22,7 @@ const path = require('path');
 // Defense-in-depth copy of the canonical directive in subagent-bootstrap.json.
 // Kept as a single-line literal so the parity test in tests/bin/subagent-start.test.ts
 // can verify it matches the JSON via plain substring containment.
-const FALLBACK_DIRECTIVE = 'MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol.';
+const FALLBACK_DIRECTIVE = 'MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol. When a search hit carries `navigation`, you MUST call mcp__moflo__memory_get_neighbors to traverse — calling mcp__moflo__memory_retrieve on every hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`.';
 
 function loadDirective() {
   const jsonPath = path.join(__dirname, 'subagent-bootstrap.json');

package/.claude/skills/eldar/SKILL.md

@@ -121,6 +121,14 @@ mcp__moflo__memory_stats — { namespace: "learnings" }
 
 Flag empty `learnings` as `info` (project hasn't accumulated decisions yet — fine for new projects). Flag empty `guidance` as `warn` (no indexed guidance means semantic search is degraded).
 
+**Legacy `doc-*` residue (#1053 S4)** — moflo retired whole-document indexing in favor of chunk-only RAG. The `purge-doc-entries` migration runs on session-start; if any `doc-*` rows linger, the migration didn't fire (ran with no DB, errored, or the install is below the migration's introduction).
+
+```
+mcp__moflo__memory_search — { query: "doc-", namespace: "guidance", threshold: 0, limit: 5 }
+```
+
+If any returned `key` starts with `doc-`, flag `info`: "legacy doc-* rows present — `purge-doc-entries` migration did not run; fixable via `flo healer --fix` or manual `node node_modules/moflo/bin/run-migrations.mjs`".
+
 ### 1i. Hooks & MCP Wiring
 
 Read `.claude/settings.json`. Check:

package/bin/build-embeddings.mjs

@@ -16,27 +16,16 @@
  *   flo-embeddings --namespace guidance                       # scope to one namespace
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { resolve, dirname } from 'path';
-import { mofloResolveURL, mofloInternalURL } from './lib/moflo-resolve.mjs';
-import { memoryDbPath, hnswIndexPath } from './lib/moflo-paths.mjs';
-const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
+import { existsSync, readFileSync } from 'fs';
+import { mofloInternalURL } from './lib/moflo-resolve.mjs';
+import { memoryDbPath, hnswIndexPath, findProjectRoot } from './lib/moflo-paths.mjs';
+import { openBackend } from './lib/get-backend.mjs';
 const FASTEMBED_INLINE = 'dist/src/cli/embeddings/fastembed-inline/index.js';
 const BRIDGE_CORE = 'dist/src/cli/memory/bridge-core.js';
 const HNSW_PERSISTENCE = 'dist/src/cli/memory/hnsw-persistence.js';
 const { writeVectorStatsJson } = await import(mofloInternalURL(BRIDGE_CORE));
 const { buildAndWriteHnswSidecar } = await import(mofloInternalURL(HNSW_PERSISTENCE));
 
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
 const projectRoot = findProjectRoot();
 const DB_PATH = memoryDbPath(projectRoot);
 
@@ -100,14 +89,11 @@ async function getDb() {
   if (!existsSync(DB_PATH)) {
     throw new Error(`Database not found: ${DB_PATH}`);
   }
-  const SQL = await initSqlJs();
-  const buffer = readFileSync(DB_PATH);
-  return new SQL.Database(buffer);
+  return openBackend(projectRoot, { create: false });
 }
 
 function saveDb(db) {
-  const data = db.export();
-  writeFileSync(DB_PATH, Buffer.from(data));
+  db.save();
 }
 
 function getEntriesNeedingEmbeddings(db, namespace, forceAll) {

package/bin/cli.js

@@ -13,6 +13,11 @@
 // already ships with correct .js extensions — the patch is unnecessary.
 process.env.SKIP_AGENTDB_PATCH ??= '1';
 
+// MUST run before any `node:sqlite` import in the process tree so the
+// once-per-process ExperimentalWarning never fires. See module header for
+// why we filter rather than `--no-warnings`-style broadly suppressing.
+import './lib/suppress-sqlite-warning.mjs';
+
 import { randomUUID } from 'crypto';
 
 // Check if we should run in MCP server mode

package/bin/gate.cjs

@@ -307,7 +307,7 @@ switch (command) {
       process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
     }
     if (config.memory_first && s.memoryRequired && !s.memorySearched) {
-      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents.\n');
+      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     }
     if (s.lastNamespaceHint) {
       // Per-actor single-shot. Each session_id gets the hint at most once per
@@ -376,7 +376,7 @@ switch (command) {
     if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -386,7 +386,7 @@ switch (command) {
     var fp = process.env.TOOL_INPUT_file_path || '';
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'record-task-created': {

package/bin/generate-code-map.mjs

@@ -29,26 +29,14 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from
 import { resolve, dirname, relative, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync, execFileSync, spawn } from 'child_process';
-import { mofloResolveURL } from './lib/moflo-resolve.mjs';
-import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
+import { memoryDbPath, MOFLO_DIR, findProjectRoot } from './lib/moflo-paths.mjs';
+import { openBackend } from './lib/get-backend.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
-const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Detect project root: walk up from cwd to find a package.json
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
 const projectRoot = findProjectRoot();
 const NAMESPACE = 'code-map';
 const DB_PATH = memoryDbPath(projectRoot);
@@ -110,14 +98,7 @@ function ensureDbDir() {
 
 async function getDb() {
   ensureDbDir();
-  const SQL = await initSqlJs();
-  let db;
-  if (existsSync(DB_PATH)) {
-    const buffer = readFileSync(DB_PATH);
-    db = new SQL.Database(buffer);
-  } else {
-    db = new SQL.Database();
-  }
+  const db = await openBackend(projectRoot, { create: true });
 
   db.run(`
     CREATE TABLE IF NOT EXISTS memory_entries (
@@ -147,8 +128,7 @@ async function getDb() {
 }
 
 function saveDb(db) {
-  const data = db.export();
-  writeFileSync(DB_PATH, Buffer.from(data));
+  db.save();
 }
 
 function countNamespace(db) {

package/bin/hooks.mjs

@@ -26,24 +26,15 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { createProcessManager } from './lib/process-manager.mjs';
 import { shouldDaemonAutoStart } from './lib/daemon-config.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
+import { findProjectRoot } from './lib/moflo-paths.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Detect project root by walking up from cwd to find package.json.
 // IMPORTANT: Do NOT use resolve(__dirname, '..') or '../..' — this script lives
 // in bin/ during development but gets synced to .claude/scripts/ in consumer
-// projects, so __dirname-relative paths break. findProjectRoot() works everywhere.
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
+// projects, so __dirname-relative paths break. findProjectRoot() works
+// everywhere and resolves identically to the TS bridge (see lib/moflo-paths.mjs).
 const projectRoot = findProjectRoot();
 const logFile = resolve(projectRoot, '.swarm/hooks.log');
 const pm = createProcessManager(projectRoot);

package/bin/index-all.mjs

@@ -18,7 +18,7 @@ import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { spawn, spawnSync } from 'child_process';
 import { platform } from 'os';
-import { hnswIndexPath } from './lib/moflo-paths.mjs';
+import { hnswIndexPath, findProjectRoot } from './lib/moflo-paths.mjs';
 import {
   decideStepGate,
   computeStepFingerprint,
@@ -38,20 +38,10 @@ const ONNX_THREAD_CAP = {
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Detect project root by walking up from cwd to find package.json.
 // IMPORTANT: Do NOT use resolve(__dirname, '..') — this script lives in bin/
 // during development but gets synced to .claude/scripts/ in consumer projects,
-// so __dirname-relative paths break. findProjectRoot() works in both locations.
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
+// so __dirname-relative paths break. findProjectRoot() (lib/moflo-paths.mjs)
+// works in both locations and resolves identically to the TS bridge.
 const projectRoot = findProjectRoot();
 const LOG_PATH = resolve(projectRoot, '.swarm/hooks.log');