fix(memory-core): skip qmd zero-hit search sync

sahibzada-allahyar · vincentkoc · commit 5b3b116e4944 · 2026-07-01T03:55:57.000-07:00
diff --git a/extensions/memory-core/src/tools.test.ts b/extensions/memory-core/src/tools.test.ts
@@ -382,57 +382,75 @@ describe("memory_search unavailable payloads", () => {
     expect(searchCalls).toBe(2);
   });
 
-  it("merges qmd runtime debug across zero-hit retry attempts", async () => {
+  it("keeps the zero-hit bootstrap retry for one-shot qmd searches", async () => {
     setMemoryBackend("qmd");
     let searchCalls = 0;
-    setMemorySearchImpl(async (opts) => {
+    setMemorySearchImpl(async () => {
       searchCalls += 1;
       if (searchCalls === 1) {
-        opts?.onDebug?.({
-          backend: "qmd",
-          configuredMode: "search",
-          effectiveMode: "search",
-          qmd: {
-            collectionValidation: {
-              cacheState: "hit",
-              elapsedMs: 2,
-              collectionCount: 2,
-              listCalls: 0,
-              showCalls: 0,
-            },
-            multiCollectionProbe: {
-              cacheState: "hit",
-              elapsedMs: 1,
-              supported: true,
-            },
-          },
-        });
         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: { backend: "qmd", citations: "off" },
+      },
+      oneShotCliRun: true,
+    });
+    const result = await tool.execute("qmd-zero-hit-cli", {
+      query: "hidden thread codename",
+    });
+
+    expect((result.details as { results?: Array<{ path: string }> }).results?.[0]?.path).toBe(
+      "MEMORY.md",
+    );
+    expect(searchCalls).toBe(2);
+    expect(getMemorySyncMockCalls()).toBe(1);
+  });
+
+  it("returns qmd runtime debug without forcing a zero-hit retry", async () => {
+    setMemoryBackend("qmd");
+    let searchCalls = 0;
+    setMemorySearchImpl(async (opts) => {
+      searchCalls += 1;
       opts?.onDebug?.({
         backend: "qmd",
         configuredMode: "search",
-        effectiveMode: "query",
-        fallback: "unsupported-search-flags",
+        effectiveMode: "search",
         qmd: {
+          collectionValidation: {
+            cacheState: "hit",
+            elapsedMs: 2,
+            collectionCount: 2,
+            listCalls: 0,
+            showCalls: 0,
+          },
+          multiCollectionProbe: {
+            cacheState: "hit",
+            elapsedMs: 1,
+            supported: true,
+          },
           searchPlan: {
-            command: "query",
+            command: "search",
             collectionCount: 2,
             groupCount: 2,
             sources: ["memory", "sessions"],
           },
         },
       });
-      return [
-        {
-          path: "MEMORY.md",
-          startLine: 1,
-          endLine: 1,
-          score: 0.9,
-          snippet: "Thread-hidden codename: ORBIT-22.",
-          source: "memory" as const,
-        },
-      ];
+      return [];
     });
 
     const tool = createMemorySearchToolOrThrow({
@@ -441,7 +459,7 @@ describe("memory_search unavailable payloads", () => {
         memory: { backend: "qmd", citations: "off" },
       },
     });
-    const result = await tool.execute("zero-hit-debug-retry", {
+    const result = await tool.execute("zero-hit-debug-single", {
       query: "hidden thread codename",
     });
     const details = result.details as {
@@ -452,9 +470,11 @@ describe("memory_search unavailable payloads", () => {
       };
     };
 
-    expect(searchCalls).toBe(2);
-    expect(details.debug?.effectiveMode).toBe("query");
-    expect(details.debug?.fallback).toBe("unsupported-search-flags");
+    expect((result.details as { results?: Array<unknown> }).results).toEqual([]);
+    expect(searchCalls).toBe(1);
+    expect(getMemorySyncMockCalls()).toBe(0);
+    expect(details.debug?.effectiveMode).toBe("search");
+    expect(details.debug?.fallback).toBeUndefined();
     expect(details.debug?.qmd?.collectionValidation).toMatchObject({
       cacheState: "hit",
       collectionCount: 2,
@@ -464,7 +484,7 @@ describe("memory_search unavailable payloads", () => {
       supported: true,
     });
     expect(details.debug?.qmd?.searchPlan).toEqual({
-      command: "query",
+      command: "search",
       collectionCount: 2,
       groupCount: 2,
       sources: ["memory", "sessions"],
diff --git a/extensions/memory-core/src/tools.ts b/extensions/memory-core/src/tools.ts
@@ -566,7 +566,13 @@ export function createMemorySearchTool(options: {
                   if (pausedIndexIdentityReason) {
                     return;
                   }
-                  if (rawResults.length === 0 && activeMemory.manager.sync) {
+                  // One-shot CLI managers have no background lifecycle, so keep their bootstrap
+                  // retry. Long-lived QMD managers must not run update work in the tool hot path.
+                  if (
+                    rawResults.length === 0 &&
+                    activeMemory.manager.sync &&
+                    (statusBeforeRetry.backend !== "qmd" || options.oneShotCliRun === true)
+                  ) {
                     await activeMemory.manager.sync({ reason: "search", force: true });
                     rawResults = await activeMemory.manager.search(query, searchOptions);
                     pausedIndexIdentityReason = resolvePausedMemoryIndexIdentityReason(
