@yeaft/webchat-agent 0.1.656 → 0.1.658

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.656",
+  "version": "0.1.658",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/config.js

@@ -219,6 +219,8 @@ function loadLegacyConfig(dir, overrides) {
     unify: normaliseUnifySection(null),
     // DESIGN-v2 feature flag. Default true (PR-E flipped). Override wins.
     memoryV2: overrides.memoryV2 !== undefined ? !!overrides.memoryV2 : true,
+    // GC.1: FTS pre-flow flag (legacy fallback config — defaults true).
+    memoryPreflow: overrides.memoryPreflow !== undefined ? !!overrides.memoryPreflow : true,
     providers: null,
     primaryModel: null,
     fastModel: null,
@@ -323,6 +325,14 @@ export function loadConfig(overrides = {}) {
     memoryV2: overrides.memoryV2 !== undefined ? !!overrides.memoryV2
       : (jsonConfig.memoryV2 !== undefined ? !!jsonConfig.memoryV2 : true),
 
+    // GC.1 feature flag — route pre-turn memory recall through
+    // memory/preflow.js (SQLite FTS5) instead of memory/recall-v2.js
+    // (per-scope file reads). When OFF the engine falls back to v2.
+    // Default ON. Users can opt out via `"memoryPreflow": false` in
+    // ~/.yeaft/config.json. Only applies when memoryV2 is also ON.
+    memoryPreflow: overrides.memoryPreflow !== undefined ? !!overrides.memoryPreflow
+      : (jsonConfig.memoryPreflow !== undefined ? !!jsonConfig.memoryPreflow : true),
+
     // Legacy fields (null when using config.json)
     apiKey: overrides.apiKey || null,
     openaiApiKey: null,

package/unify/engine.js

@@ -22,6 +22,7 @@ import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
 import { LLMContextError, LLMAbortError } from './llm/adapter.js';
 import { recallR6, formatForInjection } from './memory/recall-r6.js';
 import { recallV2 } from './memory/recall-v2.js';
+import { runMemoryPreflow } from './groups/pre-flow.js';
 import { shouldConsolidate, consolidate, partitionMessages } from './memory/consolidate.js';
 import { extractMemories } from './memory/extract.js';
 import { runCompact as runCompactOrchestrator } from './compact/orchestrator.js';
@@ -152,6 +153,9 @@ export class Engine {
   /** @type {object|null} — R6 memory shard store (task-334f) */
   #memoryShardStore;
 
+  /** @type {import('./memory/index-db.js').SegmentIndex|null} — GC.1: SQLite FTS5 segment index */
+  #memoryIndex;
+
   /** @type {import('./tools/registry.js').ToolRegistry|null} */
   #toolRegistry;
 
@@ -223,13 +227,14 @@ export class Engine {
    *   config: object,
    *   conversationStore?: import('./conversation/persist.js').ConversationStore,
    *   memoryStore?: import('./memory/store.js').MemoryStore,
+   *   memoryIndex?: import('./memory/index-db.js').SegmentIndex,
    *   toolRegistry?: import('./tools/registry.js').ToolRegistry,
    *   skillManager?: import('./skills.js').SkillManager,
    *   mcpManager?: import('./mcp.js').MCPManager,
    *   yeaftDir?: string,
    * }} params
    */
-  constructor({ adapter, trace, config, conversationStore, memoryStore, memoryShardStore, toolRegistry, skillManager, mcpManager, yeaftDir }) {
+  constructor({ adapter, trace, config, conversationStore, memoryStore, memoryShardStore, memoryIndex, toolRegistry, skillManager, mcpManager, yeaftDir }) {
     this.#adapter = adapter;
     this.#trace = trace;
     this.#config = config;
@@ -238,6 +243,7 @@ export class Engine {
     this.#conversationStore = conversationStore || null;
     this.#memoryStore = memoryStore || null;
     this.#memoryShardStore = memoryShardStore || null;
+    this.#memoryIndex = memoryIndex || null;
     this.#toolRegistry = toolRegistry || null;
     this.#skillManager = skillManager || null;
     this.#mcpManager = mcpManager || null;
@@ -505,6 +511,27 @@ export class Engine {
   async #recallMemory(prompt, ctx = {}) {
     const memory = { profile: '', entries: [], formatted: '' };
 
+    // ─── GC.1: FTS5 pre-flow path ──────────────────────────────
+    // When the SegmentIndex is wired and the feature flag is on,
+    // route recall through groups/pre-flow.js → memory/preflow.js
+    // (SQLite FTS5). On any failure fall through to v2.
+    if (this.#memoryIndex && this.#config && this.#config.memoryPreflow) {
+      try {
+        const result = runMemoryPreflow(this.#memoryIndex, {
+          userMsg: prompt,
+          groupId: ctx.groupId,
+          vpId: ctx.vpId,
+          featureId: ctx.featureId,
+        });
+        memory.profile = result.profile || '';
+        memory.entries = result.entries || [];
+        memory.formatted = result.formatted || '';
+        return memory;
+      } catch {
+        // Fall through to v2 / R6 paths.
+      }
+    }
+
     // ─── v2 path (DESIGN-v2) ───────────────────────────────────
     if (this.#config && this.#config.memoryV2 && this.#yeaftDir) {
       try {

package/unify/groups/coordinator.js

@@ -2,55 +2,28 @@
  * coordinator.js — Group Coordinator (task-334b).
  *
  * Consumes user/VP messages, persists them to the group's 334o jsonl-log,
- * parses @-mentions (user-posted only), and dispatches to target RoleInstances'
- * `inputQueue`. Aligned with architecture §5 / §6:
+ * and dispatches user-text turns to target RoleInstances'
+ * `inputQueue`.
  *
- *   - Text @-mentions trigger routing ONLY for `role === 'user'` messages.
- *     VP-authored @ mentions are surface noise; VPs dispatch via the
- *     route_forward tool (334d), not free text.
- *   - `@all` fans out to every roster member except the sender (perGroupFanOut
- *     cap honoured via options).
- *   - Unknown @-targets return `{ error: 'not_in_roster' }` in the dispatch
- *     report; coordinator does not mutate roster on stranger mentions.
- *   - No @-mention on a user message → falls back to `defaultVpId` via
- *     resolveFallbackVp (architecture G2).
- *   - taskId: if the inbound message carries `taskId`, dispatch is scoped to
- *     task.members — passed in via `options.taskMembers` (task storage lives
- *     in 334n; coordinator only enforces the filter when the caller provides
- *     the member list).
+ * As of GC.1 Commit B, VP-selection (parseMentions + dispatch matrix:
+ * mention / @all / fallback / vp-author no-op) lives in
+ * `groups/pre-flow.js` so the same logic can be invoked directly by
+ * the parallel fan-out path in web-bridge.js. Coordinator's job is now
+ * narrower: persist the message and translate the selection result
+ * into deliver() calls.
  *
  * This module DOES NOT run the engine. It only:
  *   1. Persists the message (via GroupHandle.appendMessage)
- *   2. Resolves the list of target vpIds
+ *   2. Asks pre-flow for the list of target vpIds
  *   3. Calls a user-supplied deliver(vpId, envelope) per target
- *
- * That lets 334c (RoleInstance/Engine) own how a target is actually woken up
- * (inputQueue push, status transition, etc) without coordinator owning it.
  */
 
-import { isMember, resolveFallbackVp } from './roster.js';
+import { parseMentions, selectRespondingVps } from './pre-flow.js';
 
-/** Matches `@vp-id` where id is [A-Za-z0-9_-]+. Captures the id. */
-const MENTION_RE = /(^|\s)@([A-Za-z0-9_][A-Za-z0-9_-]*)/g;
-
-/**
- * Extract an ordered, unique list of @-mentions from a text string.
- * Recognises the literal token `@all` as broadcast.
- */
-export function parseMentions(text) {
-  if (!text || typeof text !== 'string') return [];
-  const out = [];
-  const seen = new Set();
-  MENTION_RE.lastIndex = 0;
-  let m;
-  while ((m = MENTION_RE.exec(text))) {
-    const id = m[2];
-    if (seen.has(id)) continue;
-    seen.add(id);
-    out.push(id);
-  }
-  return out;
-}
+// Re-export so existing importers (`createCoordinator(...).parseMentions`,
+// or modules importing `parseMentions` from coordinator) keep working
+// without churn. New code should import from `./pre-flow.js` directly.
+export { parseMentions };
 
 /**
  * Build a Group Coordinator bound to a single GroupHandle.
@@ -101,8 +74,18 @@ export function createCoordinator(group, options = {}) {
       role: input.role || (fromUser ? 'user' : 'assistant'),
     });
 
-    // VP-authored messages: persist but do NOT dispatch (§6: no text @ routing)
-    if (!fromUser) {
+    // Ask pre-flow which VPs (if any) should respond.
+    const selection = selectRespondingVps({
+      meta,
+      fromUser,
+      mentions,
+      sender: input.from,
+      fanOutCap,
+      taskMembers: opts.taskMembers,
+    });
+
+    // VP-authored: persist but no dispatch.
+    if (selection.reason === 'vp-author-no-text-routing') {
       return {
         message: stored,
         dispatched: [],
@@ -112,63 +95,48 @@ export function createCoordinator(group, options = {}) {
       };
     }
 
-    // @all broadcast
-    if (mentions.includes('all')) {
-      const roster = meta.roster.filter((v) => v !== input.from).slice(0, fanOutCap);
-      const scoped = opts.taskMembers
-        ? roster.filter((v) => opts.taskMembers.includes(v))
-        : roster;
+    if (selection.reason === 'broadcast') {
       const envelope = makeEnvelope(stored, meta, 'broadcast');
-      for (const vpId of scoped) deliver(vpId, envelope);
+      for (const vpId of selection.dispatched) deliver(vpId, envelope);
       return {
         message: stored,
-        dispatched: scoped,
+        dispatched: selection.dispatched,
         fallback: null,
-        errors: [],
+        errors: selection.errors,
         broadcast: true,
-        truncatedAtFanOutCap: meta.roster.length - 1 > fanOutCap,
+        truncatedAtFanOutCap: !!selection.truncatedAtFanOutCap,
       };
     }
 
-    // Explicit @-mentions
-    if (mentions.length > 0) {
-      const dispatched = [];
-      const errors = [];
-      for (const vpId of mentions) {
-        if (!isMember(meta, vpId)) {
-          errors.push({ vpId, error: 'not_in_roster' });
-          continue;
-        }
-        if (opts.taskMembers && !opts.taskMembers.includes(vpId)) {
-          errors.push({ vpId, error: 'not_in_task_members' });
-          continue;
-        }
-        dispatched.push(vpId);
+    if (selection.reason === 'mention') {
+      for (const vpId of selection.dispatched) {
         deliver(vpId, makeEnvelope(stored, meta, 'mention'));
       }
-      return { message: stored, dispatched, fallback: null, errors };
-    }
-
-    // No @-mention → fallback
-    const fallback = resolveFallbackVp(meta);
-    if (!fallback) {
       return {
         message: stored,
-        dispatched: [],
+        dispatched: selection.dispatched,
         fallback: null,
-        errors: [{ error: 'no_default_vp' }],
+        errors: selection.errors,
       };
     }
-    if (opts.taskMembers && !opts.taskMembers.includes(fallback)) {
+
+    if (selection.reason === 'fallback' && selection.fallback) {
+      deliver(selection.fallback, makeEnvelope(stored, meta, 'fallback'));
       return {
         message: stored,
-        dispatched: [],
-        fallback: null,
-        errors: [{ vpId: fallback, error: 'not_in_task_members' }],
+        dispatched: selection.dispatched,
+        fallback: selection.fallback,
+        errors: selection.errors,
       };
     }
-    deliver(fallback, makeEnvelope(stored, meta, 'fallback'));
-    return { message: stored, dispatched: [fallback], fallback, errors: [] };
+
+    // no-default / nothing to dispatch
+    return {
+      message: stored,
+      dispatched: [],
+      fallback: null,
+      errors: selection.errors,
+    };
   }
 
   return {
@@ -204,3 +172,4 @@ function makeEnvelope(msg, meta, trigger) {
  * @property {boolean=}  truncatedAtFanOutCap
  * @property {string=}   skipped
  */
+

package/unify/groups/pre-flow.js

@@ -0,0 +1,308 @@
+/**
+ * groups/pre-flow.js — explicit pre-flow stage for Unify.
+ *
+ * Pre-flow is the "before any VP runs" stage. It owns:
+ *
+ *   (1) VP selection — which VP(s) respond to this user turn?
+ *       Pure function `selectRespondingVps({meta, fromUser, mentions,
+ *       sender, taskMembers, fanOutCap})` that mirrors the legacy
+ *       coordinator dispatch matrix: mention → broadcast → fallback to
+ *       defaultVpId, with VP-authored messages routed via the explicit
+ *       route_forward tool instead of free-text @-mentions.
+ *
+ *   (2) Memory recall — what memory gets pre-injected into each
+ *       responding VP's prompt? Thin wrapper around
+ *       memory/preflow.js's FTS5 recall.
+ *
+ * Commit C will flip the caller (web-bridge.js) to fan out responding
+ * VPs in parallel via Promise.all.
+ *
+ * Why one module: a single import surface for the full pre-flow stage,
+ * a stable seam for the engine, and a place to format FTS hits into the
+ * {profile, entries, formatted} shape the engine already consumes.
+ */
+
+import { runPreflow as runFtsPreflow } from '../memory/preflow.js';
+import { isMember, resolveFallbackVp } from './roster.js';
+
+/** Matches `@vp-id` where id is [A-Za-z0-9_-]+. Captures the id. */
+const MENTION_RE = /(^|\s)@([A-Za-z0-9_][A-Za-z0-9_-]*)/g;
+
+/**
+ * Extract an ordered, unique list of @-mentions from a text string.
+ * Recognises the literal token `@all` as broadcast.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function parseMentions(text) {
+  if (!text || typeof text !== 'string') return [];
+  const out = [];
+  const seen = new Set();
+  MENTION_RE.lastIndex = 0;
+  let m;
+  while ((m = MENTION_RE.exec(text))) {
+    const id = m[2];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * @typedef {object} SelectionInput
+ * @property {object}   meta          GroupHandle meta (roster + defaultVpId)
+ * @property {boolean}  fromUser      true = user-authored; false = VP-authored
+ * @property {string[]} mentions      Already-parsed @-mentions
+ * @property {string=}  sender        VP id when fromUser=false
+ * @property {number}   [fanOutCap=16]
+ * @property {string[]=} taskMembers  When set, restricts dispatch to this list
+ */
+
+/**
+ * @typedef {object} SelectionResult
+ * @property {string[]} dispatched              VP ids that should respond
+ * @property {string|null} fallback             The fallback vp, if any
+ * @property {Array<{vpId?:string,error:string}>} errors
+ * @property {'mention'|'broadcast'|'fallback'|'vp-author-no-text-routing'|'no-default'} reason
+ * @property {boolean=} truncatedAtFanOutCap
+ */
+
+/**
+ * Pure VP-selection step of pre-flow. Returns ids only — caller owns
+ * persistence + envelope construction + deliver().
+ *
+ * @param {SelectionInput} input
+ * @returns {SelectionResult}
+ */
+export function selectRespondingVps(input) {
+  const meta = input.meta;
+  if (!meta) {
+    return { dispatched: [], fallback: null, errors: [{ error: 'no_group_meta' }], reason: 'no-default' };
+  }
+  const fanOutCap = Number.isFinite(input.fanOutCap) ? input.fanOutCap : 16;
+  const taskMembers = Array.isArray(input.taskMembers) ? input.taskMembers : null;
+  const mentions = Array.isArray(input.mentions) ? input.mentions : [];
+
+  // VP-authored messages: never auto-route through @-mentions; VPs hand
+  // off through the explicit route_forward tool instead.
+  if (!input.fromUser) {
+    return {
+      dispatched: [],
+      fallback: null,
+      errors: [],
+      reason: 'vp-author-no-text-routing',
+    };
+  }
+
+  // @all broadcast — fan out to every roster member except the sender,
+  // honouring fanOutCap and taskMembers.
+  if (mentions.includes('all')) {
+    const roster = meta.roster.filter((v) => v !== input.sender).slice(0, fanOutCap);
+    const scoped = taskMembers ? roster.filter((v) => taskMembers.includes(v)) : roster;
+    return {
+      dispatched: scoped,
+      fallback: null,
+      errors: [],
+      reason: 'broadcast',
+      truncatedAtFanOutCap: meta.roster.length - 1 > fanOutCap,
+    };
+  }
+
+  // Explicit @-mentions
+  if (mentions.length > 0) {
+    const dispatched = [];
+    const errors = [];
+    for (const vpId of mentions) {
+      if (!isMember(meta, vpId)) {
+        errors.push({ vpId, error: 'not_in_roster' });
+        continue;
+      }
+      if (taskMembers && !taskMembers.includes(vpId)) {
+        errors.push({ vpId, error: 'not_in_task_members' });
+        continue;
+      }
+      dispatched.push(vpId);
+    }
+    return { dispatched, fallback: null, errors, reason: 'mention' };
+  }
+
+  // No @-mention → fallback to defaultVpId (architecture G2)
+  const fallback = resolveFallbackVp(meta);
+  if (!fallback) {
+    return {
+      dispatched: [],
+      fallback: null,
+      errors: [{ error: 'no_default_vp' }],
+      reason: 'no-default',
+    };
+  }
+  if (taskMembers && !taskMembers.includes(fallback)) {
+    return {
+      dispatched: [],
+      fallback: null,
+      errors: [{ vpId: fallback, error: 'not_in_task_members' }],
+      reason: 'no-default',
+    };
+  }
+  return {
+    dispatched: [fallback],
+    fallback,
+    errors: [],
+    reason: 'fallback',
+  };
+}
+
+
+/**
+ * Build the heading for a single scope's formatted memory block.
+ *
+ * Mirrors recall-v2's formatRecallV2 heading style so the system
+ * prompt looks the same to the LLM whether recall came from FTS
+ * (here) or from per-scope file reads (recall-v2).
+ *
+ * @param {string} scope
+ * @returns {string}
+ */
+function scopeHeading(scope) {
+  if (scope === 'user') return '## Memory: User';
+  if (scope.startsWith('group/')) return `## Memory: Group ${scope.slice(6)}`;
+  if (scope.startsWith('vp/')) return `## Memory: VP ${scope.slice(3)}`;
+  if (scope.startsWith('feature/')) return `## Memory: Feature ${scope.slice(8)}`;
+  if (scope.startsWith('topic/')) return `## Memory: Topic ${scope.slice(6)}`;
+  return `## Memory: ${scope}`;
+}
+
+/**
+ * Format FTS picked segments into the prompt-ready string.
+ *
+ * Picked segments are grouped by scope (preserving the FTS rerank
+ * order within each scope group), then rendered as markdown blocks
+ * with one heading per scope.
+ *
+ * @param {Array<{scope: string, body: string, tags?: string[], kind?: string}>} picked
+ * @returns {string}
+ */
+export function formatPickedForInjection(picked) {
+  if (!picked || picked.length === 0) return '';
+  const byScope = new Map();
+  // Preserve insertion order (which is rerank order within each scope).
+  for (const seg of picked) {
+    const scope = seg.scope || 'unknown';
+    if (!byScope.has(scope)) byScope.set(scope, []);
+    byScope.get(scope).push(seg);
+  }
+  const parts = [];
+  for (const [scope, segs] of byScope.entries()) {
+    parts.push(scopeHeading(scope));
+    for (const s of segs) {
+      const body = (s.body || '').trim();
+      if (body) parts.push(body);
+    }
+    parts.push('');   // blank line between scopes
+  }
+  return parts.join('\n').trim();
+}
+
+/**
+ * @typedef {object} MemoryPreflowOptions
+ * @property {string}         userMsg              The user's message
+ * @property {string}         [groupId]            Active group, if any
+ * @property {string}         [vpId]               Responding VP id, if any
+ * @property {string}         [featureId]          Active feature, if any
+ * @property {string[]}       [extraScopes]        Additional scopes to include
+ * @property {string[]}       [currentTags]        Contextual tags for rerank
+ * @property {number}         [topK]               Max FTS rows fetched (default 50)
+ * @property {number}         [budgetTokens]       Token budget for picked segments
+ */
+
+/**
+ * @typedef {object} MemoryPreflowResult
+ * @property {string}                   profile      User-scope summary (best-effort)
+ * @property {object[]}                 entries      Picked segments (raw)
+ * @property {string}                   formatted    Prompt-ready string
+ * @property {object}                   meta         Raw FTS preflow metadata
+ */
+
+/**
+ * Build the canonical scope list for a given (groupId, vpId, featureId).
+ * Always includes 'user'. The order is significant — preflow.js's scope
+ * filter accepts/rejects by membership, and the formatter renders in
+ * order.
+ *
+ * @param {{groupId?: string, vpId?: string, featureId?: string, extra?: string[]}} ctx
+ * @returns {string[]}
+ */
+export function buildRelevantScopes({ groupId, vpId, featureId, extra } = {}) {
+  const scopes = ['user'];
+  if (groupId) scopes.push(`group/${groupId}`);
+  if (vpId) scopes.push(`vp/${vpId}`);
+  if (featureId) scopes.push(`feature/${featureId}`);
+  if (Array.isArray(extra)) {
+    for (const s of extra) {
+      if (s && !scopes.includes(s)) scopes.push(s);
+    }
+  }
+  return scopes;
+}
+
+/**
+ * Run memory pre-flow for one VP turn. Thin wrapper around
+ * `memory/preflow.js::runPreflow` that:
+ *
+ *   - resolves canonical scope list from {groupId, vpId, featureId},
+ *   - invokes FTS5 recall,
+ *   - formats picked segments for prompt injection.
+ *
+ * Returns the engine-consumable {profile, entries, formatted, meta}
+ * shape so the existing recall pipeline can swap in without changes.
+ *
+ * @param {import('../memory/index-db.js').SegmentIndex} index
+ * @param {MemoryPreflowOptions} opts
+ * @returns {MemoryPreflowResult}
+ */
+export function runMemoryPreflow(index, opts) {
+  if (!index) {
+    return { profile: '', entries: [], formatted: '', meta: { skipped: 'no-index' } };
+  }
+  const userMsg = (opts?.userMsg || '').trim();
+  if (!userMsg) {
+    return { profile: '', entries: [], formatted: '', meta: { skipped: 'no-user-msg' } };
+  }
+
+  const relevantScopes = buildRelevantScopes({
+    groupId: opts.groupId,
+    vpId: opts.vpId,
+    featureId: opts.featureId,
+    extra: opts.extraScopes,
+  });
+
+  const result = runFtsPreflow(index, {
+    userMsg,
+    relevantScopes,
+    ownVpId: opts.vpId || null,
+    currentTags: opts.currentTags || [],
+    topK: opts.topK,
+    budgetTokens: opts.budgetTokens,
+  });
+
+  // Best-effort profile: pick any user-scope segment body.
+  const userSeg = (result.picked || []).find(p => p.scope === 'user');
+  const profile = userSeg ? (userSeg.body || '').trim() : '';
+
+  const formatted = formatPickedForInjection(result.picked || []);
+
+  return {
+    profile,
+    entries: result.picked || [],
+    formatted,
+    meta: {
+      keywords: result.keywords,
+      ftsQuery: result.ftsQuery,
+      pickedTokens: result.pickedTokens,
+      droppedCount: result.droppedCount,
+      hitCount: (result.hits || []).length,
+    },
+  };
+}

package/unify/session.js

@@ -26,13 +26,22 @@ import { createFullRegistry } from './tools/index.js';
 import { initFeatureStore } from './tools/feature-tools.js';
 import { Engine } from './engine.js';
 // H2.f.5: threads/, pipeline/dispatcher and input-queue retired. The
-// session now exposes a single Engine. Memory recall runs through
-// pre-flow (memory/preflow.js) + post-turn adjustMemory (memory/adjust.js).
+// session now exposes a single Engine.
+//
+// GC.1 Commit A: when config.memoryV2 && config.memoryPreflow, the
+// session opens a SegmentIndex (SQLite FTS5 over memory.md) and
+// passes it to the Engine. The Engine's #recallMemory then routes
+// pre-turn recall through groups/pre-flow.js → memory/preflow.js
+// instead of the per-scope file reader (memory/recall-v2.js).
+// Post-turn adjustMemory (memory/adjust.js) wiring lands in a later
+// commit.
 import { ensureDefaultGroupIfEmpty } from './groups/group-crud.js';
 import { seedDefaultVps } from './vp/seed-defaults.js';
 import { createDreamScheduler } from './memory/dream-scheduler.js';
 import { createV2DreamScheduler } from './dream-v2/session-wiring.js';
 import { getUserMemoryStore } from './memory/user-memory-store.js';
+import { openSegmentIndex } from './memory/index-db.js';
+import { syncAll as syncSegmentIndex } from './memory/segment-sync.js';
 import { migrateR6toV2 } from './memory/migrate-r6-to-v2.js';
 import { join } from 'path';
 import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe, writeFileSync as writeFileSyncSafe } from 'fs';
@@ -213,6 +222,35 @@ export async function loadSession(options = {}) {
     console.warn(`[Yeaft] Failed to open R6 memory shard store: ${err?.message || err}`);
   }
 
+  // ─── 5-fts. (GC.1) Open SegmentIndex for FTS pre-flow ────
+  //     When config.memoryV2 && config.memoryPreflow, build a SQLite
+  //     FTS5 index over ~/.yeaft/memory/<scope>/memory.md and pass it
+  //     to the Engine. Engine.#recallMemory uses it via
+  //     groups/pre-flow.js → memory/preflow.js. Disk is the source of
+  //     truth; on boot we reconcile disk → index via syncAll.
+  //     Failure to open the index is non-fatal: the Engine falls back
+  //     to recall-v2 transparently.
+  let memoryIndex = null;
+  if (config.memoryV2 && config.memoryPreflow && !config._readOnly) {
+    try {
+      const indexPath = join(yeaftDir, 'memory', 'index.db');
+      memoryIndex = openSegmentIndex(indexPath);
+      const memoryRoot = join(yeaftDir, 'memory');
+      try {
+        syncSegmentIndex(memoryRoot, memoryIndex);
+      } catch (syncErr) {
+        // Sync is best-effort; an empty / partial index just produces
+        // empty recall results, never an error.
+        if (config.debug) {
+          console.warn(`[Yeaft] FTS index sync warning: ${syncErr?.message || syncErr}`);
+        }
+      }
+    } catch (err) {
+      console.warn(`[Yeaft] Failed to open FTS segment index (preflow disabled): ${err?.message || err}`);
+      memoryIndex = null;
+    }
+  }
+
   // ─── 5a. Initialize feature store ──────────────────────
   initFeatureStore(yeaftDir, { readOnly: config._readOnly || false });
 
@@ -277,6 +315,7 @@ export async function loadSession(options = {}) {
     conversationStore,
     memoryStore,
     memoryShardStore,
+    memoryIndex,
     toolRegistry,
     skillManager,
     mcpManager,
@@ -355,6 +394,11 @@ export async function loadSession(options = {}) {
     } catch {
       // Trace might not have close() (NullTrace)
     }
+    try {
+      if (memoryIndex) memoryIndex.close();
+    } catch {
+      // Best-effort cleanup
+    }
   }
 
   return {