mixdog 1.4.1 → 1.4.3

package/src/runtime/explore/explorer.mjs

@@ -0,0 +1,88 @@
+// One explorer: the agent loop driven directly with one fixed system prompt
+// and the read-only filesystem tools — no session record, rules, skills,
+// profile context or persistence.
+import { agentLoop } from '../agent/orchestrator/session/agent-loop.mjs';
+import { readOnlyFilesystemTools } from '../agent/orchestrator/session/manager/tool-resolution.mjs';
+import { sharedPrefixProviderCacheOpts } from '../agent/orchestrator/agent-runtime/cache-strategy.mjs';
+import { partialHandoffTextFromSession } from '../agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs';
+
+// Tool-calling responses before the explorer must answer from what it has.
+export const EXPLORER_MAX_TOOL_ROUNDS = 10;
+
+export const EXPLORER_SYSTEM_PROMPT = [
+  'You explore the working directory read-only to answer one question. You cannot edit, run commands or delegate.',
+  '',
+  'Search:',
+  `- You have ${EXPLORER_MAX_TOOL_ROUNDS} tool rounds: batch independent searches in one turn (parallel calls or array arguments).`,
+  "- Search the question's own nouns, and match the subsystem it names, not a similarly named one.",
+  '- Locate first, then read only that window.',
+  '- A location a tool returned is final; never reconfirm it.',
+  '- Before answering, list the parts the question asks about; each needs its own tool-returned `path:line`.',
+  '- Cite implementation, not tests, docs or changelogs, unless asked.',
+  '- A part without a `path:line`: search again with different terms, or use `code_graph` on a found symbol (definition, callers, writers). Call it missing only after that search, and name what you searched.',
+  '- Stop once every part has its location.',
+  '',
+  'Answer shape, hard limit 1,500 characters, nothing else:',
+  '- One short answer line.',
+  '- One evidence line per hop of each part (entry, callee, writer, reader), at most 10 lines: `path:line` from tool output, the exact function or symbol name there, a few words.',
+  '- No intro, summary, extra locations, notes about unread code or "Open:" lines.',
+].join('\n');
+
+// One list for the process: identical schema bytes for every explorer.
+const EXPLORER_TOOLS = readOnlyFilesystemTools();
+export const EXPLORER_TOOL_NAMES = Object.freeze(EXPLORER_TOOLS.map((tool) => tool.name));
+
+/**
+ * Answer `query` on `route` with `provider`. Resolves the answer text (on a
+ * salvage-flagged abort, the text written so far); rejects on failure.
+ */
+export async function runExplorer({ query, route, provider, cwd = null, signal, ownerSessionId = null }) {
+  const tools = EXPLORER_TOOLS.slice();
+  const messages = [
+    { role: 'system', content: EXPLORER_SYSTEM_PROMPT },
+    { role: 'user', content: query },
+  ];
+  // In-memory policy only: the schema allowlist is also the execution
+  // allowlist (pre-dispatch-deny.mjs), and the owner ids attribute spend in
+  // the usage ledger. No session id, so nothing session-keyed is created.
+  const policy = {
+    provider: route.provider,
+    model: route.model,
+    cwd,
+    tools,
+    schemaAllowedTools: EXPLORER_TOOL_NAMES,
+    compaction: { auto: false },
+    ownerSessionId,
+    parentSessionId: ownerSessionId,
+  };
+  // Text of the request in flight, for salvage when the deadline cuts it.
+  let streamed = '';
+  try {
+    const response = await agentLoop(provider, messages, route.model, tools, null, cwd, {
+      signal,
+      session: policy,
+      ...(route.effort ? { effort: route.effort } : {}),
+      fast: route.fast === true,
+      modelParameters: route.modelParameters || {},
+      turnLimits: { maxToolRounds: EXPLORER_MAX_TOOL_ROUNDS },
+      ...sharedPrefixProviderCacheOpts(route.provider),
+      onProviderSendStarted: () => {
+        streamed = '';
+      },
+      onTextDelta: (chunk) => {
+        streamed += typeof chunk === 'string' ? chunk : '';
+      },
+      onTextReset: ({ chars } = {}) => {
+        streamed = streamed.slice(0, Math.max(0, streamed.length - (Number(chars) || 0)));
+        return true;
+      },
+    });
+    return String(response?.content || '').trim();
+  } catch (error) {
+    if (signal?.reason?.salvagePartial === true) {
+      const partial = [partialHandoffTextFromSession({ messages }, 2), streamed.trim()].filter(Boolean).join('\n\n');
+      if (partial) return partial;
+    }
+    throw error;
+  }
+}

package/src/runtime/explore/tool-defs.mjs

@@ -0,0 +1,35 @@
+import { TOOL_SYNC_EXECUTION_CONTRACT } from '../shared/tool-execution-contract.mjs';
+
+export const EXPLORE_MAX_QUERIES = 8;
+
+export const TOOL_DEFS = [
+  {
+    name: 'explore',
+    title: 'Explore',
+    annotations: {
+      title: 'Explore',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+    description:
+      'Read-only code search in parallel explorers outside your context; returns one merged answer with path:line evidence. ' +
+      'Use when locating needs 3+ searches, spans 2+ files or areas, or covers independent questions; a known file or one lookup: read/grep. ' +
+      TOOL_SYNC_EXECUTION_CONTRACT,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          anyOf: [
+            { type: 'string', minLength: 1 },
+            { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1, maxItems: EXPLORE_MAX_QUERIES },
+          ],
+          description: 'One self-contained question, or an array of independent ones (one explorer each).',
+        },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+  },
+];

package/src/runtime/explore/tool.mjs

@@ -0,0 +1,123 @@
+// The explore tool: one read-only explorer loop per query (explorer.mjs), all
+// in parallel, merged into one bounded answer within the same tool call.
+import { resolveMaintenanceRoute } from '../agent/orchestrator/agent-runtime/maintenance-route.mjs';
+import { loadConfig } from '../agent/orchestrator/config.mjs';
+import { getProvider, initProviders } from '../agent/orchestrator/providers/registry.mjs';
+import { EXPLORE_MAX_QUERIES } from './tool-defs.mjs';
+import { runExplorer } from './explorer.mjs';
+
+// Hidden ids are reserved from user agents, so this one keeps the `-agent`
+// suffix: a plain `explorer` would hide a user's own Explorer agent.
+const EXPLORER_AGENT = 'explore-agent';
+const EXPLORE_TIMEOUT_MS = 120_000;
+export const EXPLORE_OUTPUT_CAP = 24_000;
+const TRUNCATED = '\n[explore: answer truncated]';
+
+function result(text, isError = false) {
+  return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+}
+
+function normalizeExploreQueries(raw) {
+  const list = Array.isArray(raw) ? raw : [raw];
+  return list.map((q) => (typeof q === 'string' ? q.trim() : '')).filter(Boolean);
+}
+
+function capped(text, budget) {
+  return text.length <= budget ? text : text.slice(0, Math.max(0, budget - TRUNCATED.length)) + TRUNCATED;
+}
+
+// Headings and error lines are labels, not answers: the truncation marker
+// would tell the caller that evidence was lost when none was.
+function shortened(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+/**
+ * @param {{ query: string|string[] }} args
+ * @param {{ cwd?: string, signal?: AbortSignal, callerSessionId?: string }} ctx
+ * @param {object} [deps] injectable for tests
+ */
+export async function runExplore(args = {}, ctx = {}, deps = {}) {
+  const {
+    load = () => loadConfig({ secrets: false }),
+    initialize = initProviders,
+    providerFor = getProvider,
+    timeoutMs = EXPLORE_TIMEOUT_MS,
+  } = deps;
+  const queries = normalizeExploreQueries(args.query);
+  if (!queries.length) return result('[explore error] query is required', true);
+  if (queries.length > EXPLORE_MAX_QUERIES) {
+    return result(`[explore error] at most ${EXPLORE_MAX_QUERIES} queries per call`, true);
+  }
+  const config = load();
+  const route = resolveMaintenanceRoute({ agent: EXPLORER_AGENT, config, includeDefault: false });
+  if (!route || typeof route !== 'object') {
+    return result('[explore error] Explore has no model; pick one under Workflows → Built-in agents → Explore', true);
+  }
+
+  // One controller per call: caller cancellation and the deadline both abort
+  // every explorer, and the call waits for each loop to settle.
+  const controller = new AbortController();
+  const parent = ctx.signal;
+  const onParentAbort = () => controller.abort(parent.reason);
+  if (parent?.aborted) return result('[explore error] cancelled', true);
+  parent?.addEventListener('abort', onParentAbort, { once: true });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    const reason = new Error(`explore timed out after ${Math.round(timeoutMs / 1000)}s`);
+    // Lets an explorer return the answer text it already wrote.
+    reason.salvagePartial = true;
+    controller.abort(reason);
+  }, timeoutMs);
+
+  try {
+    await initialize(config.providers || {}, { signal: controller.signal });
+    const provider = providerFor(route.provider);
+    if (!provider || typeof provider.send !== 'function') {
+      return result(`[explore error] provider "${route.provider}" is not ready`, true);
+    }
+    const settled = await Promise.all(
+      queries.map((query) =>
+        runExplorer({
+          query,
+          route,
+          provider,
+          cwd: ctx.cwd || null,
+          signal: controller.signal,
+          ownerSessionId: ctx.callerSessionId || null,
+        }).then(
+          (text) => {
+            const answer = String(text || '').trim();
+            return { ok: Boolean(answer), text: answer, late: timedOut };
+          },
+          (error) => ({ ok: false, error, late: timedOut })
+        )
+      )
+    );
+    if (parent?.aborted) return result('[explore error] cancelled', true);
+    const budget = Math.floor(EXPLORE_OUTPUT_CAP / queries.length);
+    const bodies = settled.map((entry) => {
+      if (entry.ok) return capped(entry.late ? `${entry.text}\n[explore: partial, timed out]` : entry.text, budget);
+      if (entry.late) return `[explore error] timed out after ${Math.round(timeoutMs / 1000)}s with no answer`;
+      if (entry.error) return `[explore error] ${shortened(String(entry.error?.message || entry.error), 500)}`;
+      return '[explore error] explorer returned no answer';
+    });
+    const text =
+      queries.length === 1
+        ? bodies[0]
+        : bodies
+            .map((body, i) => `## Q${i + 1}: ${shortened(queries[i].replace(/\s+/g, ' '), 100)}\n${body}`)
+            .join('\n\n');
+    return result(
+      text,
+      settled.every((entry) => !entry.ok)
+    );
+  } catch (error) {
+    if (parent?.aborted) return result('[explore error] cancelled', true);
+    return result(`[explore error] ${error?.message || error}`, true);
+  } finally {
+    clearTimeout(timer);
+    parent?.removeEventListener('abort', onParentAbort);
+  }
+}

package/src/runtime/local-provider/hardware.mjs

@@ -19,7 +19,7 @@ export function localProviderPlatformKey(platform = process.platform, arch = pro
  *  RAM — exactly what llama.cpp's Metal backend reports on a 16 GB M4; larger
  *  Macs may allow more, which this leaves unused. Metal reports that whole
  *  working set as free, so free equals total here as it does in llama.cpp. */
-export function appleSiliconGpu({ name, totalBytes, wiredLimitMb }) {
+function appleSiliconGpu({ name, totalBytes, wiredLimitMb }) {
   const memoryBytes = wiredLimitMb > 0 ? wiredLimitMb * 1024 ** 2 : Math.floor((totalBytes * 2) / 3);
   return { index: 0, uuid: 'MTL0', vendor: 'Apple', name, memoryBytes, freeMemoryBytes: memoryBytes };
 }

package/src/runtime/media/adapters/codex-image.mjs

@@ -32,9 +32,9 @@ import {
 
 const REQUEST_TIMEOUT_MS = 400_000;
 const LABEL = 'ChatGPT image';
-export const CODEX_IMAGE_MODEL = 'gpt-image-2';
-export const CODEX_IMAGES_GENERATIONS_URL = new URL('images/generations', CODEX_RESPONSES_URL).href;
-export const CODEX_IMAGES_EDITS_URL = new URL('images/edits', CODEX_RESPONSES_URL).href;
+const CODEX_IMAGE_MODEL = 'gpt-image-2';
+const CODEX_IMAGES_GENERATIONS_URL = new URL('images/generations', CODEX_RESPONSES_URL).href;
+const CODEX_IMAGES_EDITS_URL = new URL('images/edits', CODEX_RESPONSES_URL).href;
 const BACKGROUNDS = new Set(['transparent', 'opaque', 'auto']);
 
 const dataUrl = (ref) => `data:${ref.mime || 'image/png'};base64,${ref.base64}`;

package/src/runtime/media/adapters/gemini-video.mjs

@@ -83,7 +83,7 @@ async function generateViaVeo({ model, prompt, options, references = [], signal,
   if ([4, 6, 8].includes(duration)) parameters.durationSeconds = duration;
 
   // The budget starts at submission, not after it: a hung predictLongRunning
-  // POST used to run without any ceiling of its own.
+  // POST would otherwise run without any ceiling of its own.
   const deadline = Date.now() + TOTAL_TIMEOUT_MS;
   const started = await fetch(`${BASE_URL}/models/${encodeURIComponent(model)}:predictLongRunning`, {
     method: 'POST',

package/src/runtime/media/media-usage.mjs

@@ -91,7 +91,7 @@ export function imageApiUsage(body) {
 }
 
 /** True when the provider reported something billable for the request. */
-export function hasReportedUsage(usage) {
+function hasReportedUsage(usage) {
   if (!usage) return false;
   // Seconds are only attached once a video generation completed (billed per second).
   return (

package/src/runtime/media/store.mjs

@@ -231,7 +231,7 @@ export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime,
   // whose bytes are all NUL.
   writeFileAtomicSync(path, bytes);
   entry.file = file;
-  // The gallery is NOT capped (user). An entry-count trim used to unlink the
+  // The gallery is NOT capped (user). An entry-count trim would unlink the
   // oldest files here, which is data loss nobody asked for: a generated asset
   // leaves this store only through an explicit delete.
   mutateIndex((assets) => [entry, ...assets]);

package/src/runtime/memory/index.mjs

@@ -59,7 +59,8 @@ import {
   resolveCoalesceMaxRetries,
   scheduleCoalescedCycleRetry,
 } from './lib/memory-cycle-requests.mjs';
-import { drainEmbeddingReindex } from './lib/embedding-reindex.mjs';
+import { drainEmbeddingReindex, runRootEmbedSweep } from './lib/embedding-reindex.mjs';
+import { sweepRootEmbedText } from './lib/memory-embed.mjs';
 import { refreshCoreMemoryFile } from './lib/core-memory-file.mjs';
 import { resolveProjectId, resolveProjectScope } from './lib/project-id-resolver.mjs';
 import {
@@ -71,6 +72,7 @@ import {
 } from './lib/trace-store.mjs';
 import { writeJsonAtomicSync } from '../shared/atomic-file.mjs';
 import { safeIpcSend } from '../shared/safe-ipc-send.mjs';
+import { adoptSystemProxy } from '../shared/llm/system-proxy.mjs';
 import { resolvePluginData, mixdogHome } from '../shared/plugin-paths.mjs';
 import { scheduledCycle1Signature } from './lib/cycle-signatures.mjs';
 import { createTranscriptIngest } from './lib/transcript-ingest.mjs';
@@ -96,6 +98,9 @@ import {
 } from './lib/memory-config-flags.mjs';
 const IS_MEMORY_ENTRY = !!process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
 if (IS_MEMORY_ENTRY) {
+  // Runtime and model downloads follow the system proxy the launching daemon
+  // handed over (removed from this env so child processes never see it).
+  adoptSystemProxy();
   // Node's own warning printer stays off in this runtime, but a listener leak
   // is still logged, with the stack that names its source.
   process.removeAllListeners('warning');
@@ -428,6 +433,15 @@ function _startEmbeddingReindex() {
             `ok=${summary.succeeded} failed=${summary.failed}\n`
         );
       }
+      return runRootEmbedSweep({
+        sweepStep: ({ signal }) => sweepRootEmbedText(db, { signal }),
+        signal: controller.signal,
+      });
+    })
+    .then((sweep) => {
+      if (sweep.replaced > 0) {
+        __mixdogMemoryLog(`[memory-service] root text sweep steps=${sweep.steps} replaced=${sweep.replaced}\n`);
+      }
     })
     .catch((error) => {
       if (!controller.signal.aborted) {

package/src/runtime/memory/lib/embedding-provider.mjs

@@ -12,6 +12,7 @@ import { writeProfilePoint } from './model-profile.mjs';
 import { createCompactVectorCache } from './compact-vector-cache.mjs';
 import { EMBED_KEEP_WARM_MS } from './embedding-idle-lease.mjs';
 import { workerExecArgv } from '../../shared/worker-exec-argv.mjs';
+import { systemProxyHandoffEnv } from '../../shared/llm/system-proxy.mjs';
 import {
   getConfiguredEmbeddingModelId,
   getDefaultEmbeddingDtype,
@@ -69,7 +70,9 @@ function ensureWorker() {
   _lastRestartMs = now;
   const execArgv = embeddingWorkerExecArgv();
   const created = new Worker(WORKER_PATH, {
-    env: { ...process.env },
+    // The model download runs in this worker: it gets the system proxy
+    // decision explicitly (and removes it from its own env on start).
+    env: { ...process.env, ...systemProxyHandoffEnv() },
     execArgv,
     workerData: { dtype: _configuredDtype },
   });

package/src/runtime/memory/lib/embedding-reindex.mjs

@@ -46,3 +46,30 @@ export async function drainEmbeddingReindex({
 
   return { passes, attempted, succeeded, failed };
 }
+
+// The root-text sweep replaces vectors that still work, so it has no urgency:
+// small steps with long rests keep a ~62k-root backfill in the background of a
+// working session instead of competing with it.
+const ROOT_SWEEP_PAUSE_MS = 4_000;
+
+export async function runRootEmbedSweep({
+  sweepStep,
+  signal,
+  pauseMs = ROOT_SWEEP_PAUSE_MS,
+  wait = waitForNextPass,
+} = {}) {
+  if (typeof sweepStep !== 'function') {
+    throw new TypeError('runRootEmbedSweep: sweepStep required');
+  }
+  let steps = 0;
+  let replaced = 0;
+  while (true) {
+    throwIfAborted(signal);
+    const result = await sweepStep({ signal });
+    steps += 1;
+    replaced += Number(result?.replaced ?? 0);
+    if (result?.done) break;
+    await wait(pauseMs, signal);
+  }
+  return { steps, replaced };
+}

package/src/runtime/memory/lib/embedding-worker.mjs

@@ -8,6 +8,7 @@ import os from 'node:os';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { resolvePluginData } from '../../shared/plugin-paths.mjs';
+import { adoptSystemProxy } from '../../shared/llm/system-proxy.mjs';
 import { compressEmbeddingModelCache } from './embedding-model-cache-compression.mjs';
 import { createIdleLease } from './embedding-idle-lease.mjs';
 import { ensureModelFile, ensureModelGraph } from './embedding-model-files.mjs';
@@ -24,6 +25,9 @@ import {
   prepareEmbeddingInput,
 } from './embedding-model-config.mjs';
 
+// The model download goes through the system proxy the parent handed over.
+adoptSystemProxy();
+
 const MODEL_ID = getConfiguredEmbeddingModelId();
 
 // Reroute ALL worker-thread stdio through parentPort. Without stdout:true/

package/src/runtime/memory/lib/memory-embed.mjs

@@ -2,7 +2,7 @@ import { __mixdogMemoryLog } from './memory-log.mjs';
 
 import { embedTexts, getEmbeddingModelId, holdEmbeddingWarm } from './embedding-provider.mjs';
 import { onnxRuntimeSupported } from '../../shared/onnx-runtime-support.mjs';
-import { embeddingToSql } from './memory.mjs';
+import { embeddingToSql, ROOT_EMBED_SWEEP_META_KEY } from './memory.mjs';
 import { createHash } from 'node:crypto';
 import { pruneEmbeddingCache, resolveEmbeddingCacheMaxRows } from './embedding-cache-retention.mjs';
 import { throwIfAborted, markStoreFault } from './memory-cycle-shared.mjs';
@@ -524,6 +524,18 @@ async function syncRawBatchEmbeddings(db, ids, options = {}) {
   return writtenIds;
 }
 
+// A chunk root is also the chunk's first message: cycle1 promotes that raw row
+// in place, and every other member keeps its own content vector. Embedding only
+// element/summary left the first message's own words with no vector, so its
+// details were reachable only through the lossy summary. The summary leads so a
+// long message truncated at the model window still keeps it.
+export function rootEmbedText(row) {
+  const head = [row?.element, row?.summary].filter(Boolean).join(' — ').trim();
+  if (!head) return '';
+  const content = isRawEmbeddable(row?.role, row?.content) ? row.content.trim() : '';
+  return content ? `${head}\n\n${content}` : head;
+}
+
 // Batch-embed all ids in one DB round-trip for fetching, one API call per unique text,
 // then one VALUES UPDATE for all results.
 // Returns the list of ids that were actually UPDATEd with a fresh embedding.
@@ -535,9 +547,10 @@ async function syncBatchEmbeddings(db, ids, options = {}) {
   throwIfAborted(signal);
   if (!onnxRuntimeSupported()) return [];
   const rows = (
-    await db.query(`SELECT id, element, summary FROM memory.entries WHERE id = ANY($1::bigint[]) AND is_root = 1`, [
-      ids,
-    ])
+    await db.query(
+      `SELECT id, element, summary, content, role FROM memory.entries WHERE id = ANY($1::bigint[]) AND is_root = 1`,
+      [ids]
+    )
   ).rows;
   throwIfAborted(signal);
   if (rows.length === 0) return [];
@@ -546,8 +559,9 @@ async function syncBatchEmbeddings(db, ids, options = {}) {
   throwIfAborted(signal);
   const expected = Number(dimsRow?.value ?? 0);
 
-  const texts = rows.map((row) => [row.element, row.summary].filter(Boolean).join(' — ').trim());
-  const vectors = await cachedEmbedTextBatch(db, texts.filter(Boolean), { signal });
+  const texts = rows.map(rootEmbedText);
+  const embedBatch = options.embedBatch ?? cachedEmbedTextBatch;
+  const vectors = await embedBatch(db, texts.filter(Boolean), { signal });
   throwIfAborted(signal);
   // Re-map: only non-empty texts were passed to cachedEmbedTextBatch
   let vecIdx = 0;
@@ -562,28 +576,29 @@ async function syncBatchEmbeddings(db, ids, options = {}) {
       __mixdogMemoryLog(`[embed] dim mismatch (id=${row.id} got=${vector.length} expected=${expected})\n`);
       continue;
     }
-    updates.push({ id: Number(row.id), element: row.element, summary: row.summary, vector });
+    updates.push({ id: Number(row.id), element: row.element, summary: row.summary, content: row.content, vector });
   }
 
   if (updates.length === 0) return [];
 
   // The VALUES update is one SQL batch; do not split it with an abort checkpoint.
   const valClauses = updates.map((_u, i) => {
-    const base = i * 4;
-    return `($${base + 1}::bigint, $${base + 2}::halfvec, $${base + 3}::text, $${base + 4}::text)`;
+    const base = i * 5;
+    return `($${base + 1}::bigint, $${base + 2}::halfvec, $${base + 3}::text, $${base + 4}::text, $${base + 5}::text)`;
   });
   const params = [];
   for (const u of updates) {
-    params.push(u.id, embeddingToSql(u.vector), u.element, u.summary);
+    params.push(u.id, embeddingToSql(u.vector), u.element, u.summary, u.content);
   }
   const res = await db.query(
     `UPDATE memory.entries AS e
      SET embedding = t.vector
-     FROM (VALUES ${valClauses.join(',')}) AS t(id, vector, element, summary)
+     FROM (VALUES ${valClauses.join(',')}) AS t(id, vector, element, summary, content)
      WHERE e.id = t.id AND e.is_root = 1
-       AND e.embedding IS NULL
+       AND e.embedding IS ${options.replace ? 'NOT ' : ''}NULL
        AND e.element IS NOT DISTINCT FROM t.element
        AND e.summary IS NOT DISTINCT FROM t.summary
+       AND e.content IS NOT DISTINCT FROM t.content
      RETURNING e.id`,
     params
   );
@@ -596,7 +611,7 @@ async function syncBatchEmbeddings(db, ids, options = {}) {
     const curRows = missedIds.length
       ? (
           await db.query(
-            `SELECT id, embedding IS NOT NULL AS has_embedding, element, summary
+            `SELECT id, embedding IS NOT NULL AS has_embedding, element, summary, content
            FROM memory.entries WHERE id = ANY($1::bigint[]) AND is_root = 1`,
             [missedIds]
           )
@@ -610,7 +625,8 @@ async function syncBatchEmbeddings(db, ids, options = {}) {
       if (!cur) continue;
       const textUnchanged =
         (cur.element === u.element || (cur.element == null && u.element == null)) &&
-        (cur.summary === u.summary || (cur.summary == null && u.summary == null));
+        (cur.summary === u.summary || (cur.summary == null && u.summary == null)) &&
+        (cur.content === u.content || (cur.content == null && u.content == null));
       if (!textUnchanged) {
         staleSkips++;
         continue;
@@ -631,6 +647,59 @@ async function syncBatchEmbeddings(db, ids, options = {}) {
   return writtenIds;
 }
 
+// One paced step of the root-text sweep (startRootEmbedSweep in memory.mjs).
+// Existing vectors stay searchable until replaced: the step claims the next
+// roots below the stored cursor that still HAVE a vector, embeds their current
+// text, replaces each vector only where the text is unchanged, and advances the
+// cursor in the same transaction. The meta row lock serializes concurrent
+// sweepers; any failure rolls back both vectors and cursor. Roots without a
+// vector are left to the ordinary flush, which already uses the new text.
+const ROOT_SWEEP_BATCH = 8;
+export async function sweepRootEmbedText(db, options = {}) {
+  const { batchSize = ROOT_SWEEP_BATCH, signal, embedBatch } = options;
+  throwIfAborted(signal);
+  if (!onnxRuntimeSupported()) return { claimed: 0, replaced: 0, done: true };
+  await ensureEmbCacheTable(db);
+  const client = await db._pool.connect();
+  let committed = false;
+  try {
+    await client.query('BEGIN');
+    const state = await client.query(`SELECT value FROM memory.meta WHERE key = $1 FOR UPDATE`, [
+      ROOT_EMBED_SWEEP_META_KEY,
+    ]);
+    const value = state.rows[0]?.value;
+    const cursor = Number(value?.cursor);
+    if (!value || value.done === true || !Number.isFinite(cursor)) {
+      await client.query('COMMIT');
+      committed = true;
+      return { claimed: 0, replaced: 0, done: true };
+    }
+    const claim = await client.query(
+      `SELECT id FROM memory.entries
+       WHERE is_root = 1 AND id < $1 AND embedding IS NOT NULL
+         AND (element IS NOT NULL OR summary IS NOT NULL)
+       ORDER BY id DESC
+       LIMIT $2
+       FOR UPDATE`,
+      [cursor, batchSize]
+    );
+    const ids = claim.rows.map((r) => Number(r.id));
+    throwIfAborted(signal);
+    const written = ids.length ? await syncBatchEmbeddings(client, ids, { signal, replace: true, embedBatch }) : [];
+    const done = ids.length < batchSize;
+    await client.query(
+      `UPDATE memory.meta SET value = jsonb_build_object('cursor', $2::bigint, 'done', $3::boolean) WHERE key = $1`,
+      [ROOT_EMBED_SWEEP_META_KEY, ids.length ? Math.min(...ids) : cursor, done]
+    );
+    await client.query('COMMIT');
+    committed = true;
+    return { claimed: ids.length, replaced: written.length, done };
+  } finally {
+    if (!committed) await client.query('ROLLBACK').catch(() => {});
+    client.release();
+  }
+}
+
 // Explicit maintenance must propagate partial failures and caller cancellation,
 // including callers sharing a flush that was started without their signal.
 export async function flushSearchEmbeddings(db, options = {}) {