fix(memory-core): skip forced sync for healthy zero-hit search

AllysonAI · AllysonAI · commit 925495a4187c · 2026-06-21T20:27:38.000-04:00
diff --git a/extensions/memory-core/src/memory-tool-manager.test-mocks.ts b/extensions/memory-core/src/memory-tool-manager.test-mocks.ts
@@ -24,6 +24,7 @@ type MemoryBackend = "builtin" | "qmd";
 let backend: MemoryBackend = "builtin";
 let workspaceDir = "/workspace";
 let customStatus: Record<string, unknown> | undefined;
+let statusOverrides: Record<string, unknown> | undefined;
 let searchImpl: SearchImpl = async () => [];
 let getManagerImpl:
   | ((params: { cfg?: unknown; agentId?: string; purpose?: string }) => Promise<{
@@ -54,6 +55,7 @@ const stubManager = {
     sources: ["memory" as const],
     sourceCounts: [{ source: "memory" as const, files: 1, chunks: 1 }],
     custom: customStatus,
+    ...statusOverrides,
   }),
   sync: vi.fn(),
   probeVectorAvailability: vi.fn(async () => true),
@@ -93,6 +95,10 @@ export function setMemoryCustomStatus(next: Record<string, unknown> | undefined)
   customStatus = next;
 }
 
+export function setMemoryStatusOverrides(next: Record<string, unknown> | undefined): void {
+  statusOverrides = next;
+}
+
 export function setMemorySearchImpl(next: SearchImpl): void {
   searchImpl = next;
 }
@@ -120,6 +126,7 @@ export function resetMemoryToolMockState(overrides?: {
   backend = overrides?.backend ?? "builtin";
   workspaceDir = "/workspace";
   customStatus = undefined;
+  statusOverrides = undefined;
   getManagerImpl = undefined;
   searchImpl = overrides?.searchImpl ?? (async () => []);
   readFileImpl =
diff --git a/extensions/memory-core/src/tools.test.ts b/extensions/memory-core/src/tools.test.ts
@@ -11,6 +11,7 @@ import {
   setMemoryCustomStatus,
   setMemorySearchImpl,
   setMemorySearchManagerImpl,
+  setMemoryStatusOverrides,
 } from "./memory-tool-manager.test-mocks.js";
 import { createMemorySearchTool, testing as memoryToolsTesting } from "./tools.js";
 import { MemoryGetSchema, MemorySearchSchema } from "./tools.shared.js";
@@ -58,6 +59,67 @@ describe("memory tool schemas", () => {
   });
 });
 
+describe("memory_search zero-hit sync decisions", () => {
+  it("only forces sync for unavailable or unready index status", () => {
+    const decide = memoryToolsTesting.shouldForceSyncAfterZeroResults;
+    const healthy = {
+      backend: "qmd",
+      dirty: false,
+      files: 27,
+      chunks: 472,
+      vector: { available: true },
+      fts: { available: true },
+      custom: { indexIdentity: { status: "valid" } },
+    };
+
+    expect(decide(healthy)).toEqual({
+      shouldSync: false,
+      reason: "healthy_zero_hit",
+    });
+    expect(decide({ ...healthy, dirty: true })).toEqual({
+      shouldSync: false,
+      reason: "healthy_zero_hit",
+    });
+    expect(decide({ ...healthy, backend: "builtin", dirty: true })).toEqual({
+      shouldSync: true,
+      reason: "dirty_index",
+    });
+    expect(decide({ ...healthy, backend: undefined, dirty: true })).toEqual({
+      shouldSync: true,
+      reason: "dirty_index",
+    });
+    expect(decide({ ...healthy, vector: { enabled: false, available: false } })).toEqual({
+      shouldSync: false,
+      reason: "healthy_zero_hit",
+    });
+    expect(decide({ ...healthy, fts: { enabled: false, available: false } })).toEqual({
+      shouldSync: false,
+      reason: "healthy_zero_hit",
+    });
+    expect(decide({ ...healthy, custom: { indexIdentity: { status: "missing" } } })).toEqual({
+      shouldSync: true,
+      reason: "index_identity_invalid",
+    });
+    expect(decide({ ...healthy, chunks: 0 })).toEqual({
+      shouldSync: true,
+      reason: "no_indexed_chunks",
+    });
+    expect(decide({ ...healthy, files: 0 })).toEqual({
+      shouldSync: true,
+      reason: "no_indexed_files",
+    });
+    expect(decide({ ...healthy, vector: { available: false } })).toEqual({
+      shouldSync: true,
+      reason: "vector_unavailable",
+    });
+    expect(decide({ ...healthy, fts: { available: false } })).toEqual({
+      shouldSync: true,
+      reason: "fts_unavailable",
+    });
+    expect(decide(null)).toEqual({ shouldSync: true, reason: "status_unavailable" });
+  });
+});
+
 describe("memory_search unavailable payloads", () => {
   beforeEach(() => {
     resetMemoryToolMockState({ searchImpl: async () => [] });
@@ -313,8 +375,42 @@ describe("memory_search unavailable payloads", () => {
     expect(getMemoryCloseMockCalls()).toBe(1);
   });
 
-  it("forces a sync and retries once when the first search has zero hits", async () => {
+  it("returns a healthy zero-hit without forcing sync when the index is ready", async () => {
+    let searchCalls = 0;
+    setMemorySearchImpl(async () => {
+      searchCalls += 1;
+      if (searchCalls === 1) {
+        return [];
+      }
+      return [
+        {
+          path: "MEMORY.md",
+          startLine: 1,
+          endLine: 1,
+          score: 0.9,
+          snippet: "Thread-hidden codename: ORBIT-22.",
+          source: "memory" as const,
+        },
+      ];
+    });
+
+    const tool = createMemorySearchToolOrThrow({
+      config: {
+        agents: { list: [{ id: "main", default: true }] },
+        memory: { citations: "off" },
+      },
+    });
+    const result = await tool.execute("zero-hit-retry", { query: "hidden thread codename" });
+    const details = result.details as { results?: Array<{ path: string }> };
+
+    expect(details.results).toEqual([]);
+    expect(searchCalls).toBe(1);
+    expect(getMemorySyncMockCalls()).toBe(0);
+  });
+
+  it("preserves the dirty zero-hit retry for non-qmd backends", async () => {
     let searchCalls = 0;
+    setMemoryStatusOverrides({ dirty: true });
     setMemorySearchImpl(async () => {
       searchCalls += 1;
       if (searchCalls === 1) {
@@ -339,11 +435,11 @@ describe("memory_search unavailable payloads", () => {
       },
     });
     const result = await tool.execute("zero-hit-retry", { query: "hidden thread codename" });
+    const details = result.details as { results?: Array<{ path: string }> };
 
-    expect((result.details as { results?: Array<{ path: string }> }).results?.[0]?.path).toBe(
-      "MEMORY.md",
-    );
+    expect(details.results).toEqual([expect.objectContaining({ path: "MEMORY.md" })]);
     expect(searchCalls).toBe(2);
+    expect(getMemorySyncMockCalls()).toBe(1);
   });
 
   it("returns unavailable metadata when the index identity is paused", async () => {
diff --git a/extensions/memory-core/src/tools.ts b/extensions/memory-core/src/tools.ts
@@ -44,6 +44,15 @@ type MemorySearchToolResult =
   | MemoryCorpusSearchResult;
 type MemoryManagerContext = Awaited<ReturnType<typeof getMemoryManagerContextWithPurpose>>;
 type ActiveMemoryManagerContext = Extract<MemoryManagerContext, { manager: unknown }>;
+type MemorySearchZeroResultStatus = {
+  backend?: unknown;
+  dirty?: unknown;
+  files?: unknown;
+  chunks?: unknown;
+  vector?: unknown;
+  fts?: unknown;
+  custom?: unknown;
+};
 
 const MEMORY_SEARCH_TOOL_TIMEOUT_MS = 15_000;
 const MEMORY_SEARCH_TOOL_COOLDOWN_MS = 60_000;
@@ -76,10 +85,42 @@ function recordMemorySearchToolCooldown(key: string, error: string): void {
   });
 }
 
+function shouldForceSyncAfterZeroResults(status: MemorySearchZeroResultStatus | null | undefined): {
+  shouldSync: boolean;
+  reason: string;
+} {
+  if (!status || typeof status !== "object") {
+    return { shouldSync: true, reason: "status_unavailable" };
+  }
+  const indexIdentity = asRecord(asRecord(status.custom)?.indexIdentity);
+  if (indexIdentity?.status && indexIdentity.status !== "valid") {
+    return { shouldSync: true, reason: "index_identity_invalid" };
+  }
+  if (typeof status.chunks === "number" && status.chunks <= 0) {
+    return { shouldSync: true, reason: "no_indexed_chunks" };
+  }
+  if (typeof status.files === "number" && status.files <= 0) {
+    return { shouldSync: true, reason: "no_indexed_files" };
+  }
+  const vectorStatus = asRecord(status.vector);
+  if (vectorStatus?.available === false && vectorStatus.enabled !== false) {
+    return { shouldSync: true, reason: "vector_unavailable" };
+  }
+  const ftsStatus = asRecord(status.fts);
+  if (ftsStatus?.available === false && ftsStatus.enabled !== false) {
+    return { shouldSync: true, reason: "fts_unavailable" };
+  }
+  if (status.dirty === true && status.backend !== "qmd") {
+    return { shouldSync: true, reason: "dirty_index" };
+  }
+  return { shouldSync: false, reason: "healthy_zero_hit" };
+}
+
 export const testing = {
   resetMemorySearchToolCooldowns() {
     memorySearchToolCooldowns.clear();
   },
+  shouldForceSyncAfterZeroResults,
 } as const;
 
 function isActiveMemoryManagerContext(
@@ -532,13 +573,16 @@ export function createMemorySearchTool(options: {
                     return;
                   }
                   if (rawResults.length === 0 && activeMemory.manager.sync) {
-                    await activeMemory.manager.sync({ reason: "search", force: true });
-                    rawResults = await activeMemory.manager.search(query, searchOptions);
-                    pausedIndexIdentityReason = resolvePausedMemoryIndexIdentityReason(
-                      activeMemory.manager.status(),
-                    );
-                    if (pausedIndexIdentityReason) {
-                      return;
+                    const syncDecision = shouldForceSyncAfterZeroResults(statusBeforeRetry);
+                    if (syncDecision.shouldSync) {
+                      await activeMemory.manager.sync({ reason: "search", force: true });
+                      rawResults = await activeMemory.manager.search(query, searchOptions);
+                      pausedIndexIdentityReason = resolvePausedMemoryIndexIdentityReason(
+                        activeMemory.manager.status(),
+                      );
+                      if (pausedIndexIdentityReason) {
+                        return;
+                      }
                     }
                   }
                   rawResults = await filterMemorySearchHitsBySessionVisibility({
