fix(memory): preserve qmd startup errors

mushuiyu886 · mushuiyu886 · commit 152dc8ec21a0 · 2026-06-13T14:47:35.000+08:00
diff --git a/extensions/memory-core/src/memory/search-manager.test.ts b/extensions/memory-core/src/memory/search-manager.test.ts
@@ -368,6 +368,30 @@ describe("getMemorySearchManager caching", () => {
     expect(searchResults).toHaveLength(1);
   });
 
+  it("returns the qmd startup failure when builtin fallback is unavailable", async () => {
+    const cfg = createQmdCfg("missing-qmd-no-builtin");
+    checkQmdBinaryAvailability.mockResolvedValueOnce({
+      available: false,
+      reason: "binary",
+      error: "spawn qmd ENOENT",
+    });
+    mockMemoryIndexGet.mockRejectedValueOnce(
+      new Error(
+        'Memory search unavailable: embedding provider "openai" is configured but unavailable.',
+      ),
+    );
+
+    const result = await getMemorySearchManager({ cfg, agentId: "missing-qmd-no-builtin" });
+
+    expect(result.manager).toBeNull();
+    expect(result.error).toContain("qmd binary unavailable (qmd): spawn qmd ENOENT");
+    expect(result.error).toContain(
+      'builtin fallback unavailable: Memory search unavailable: embedding provider "openai" is configured but unavailable.',
+    );
+    expect(createQmdManagerMock).not.toHaveBeenCalled();
+    expect(mockMemoryIndexGet).toHaveBeenCalledTimes(1);
+  });
+
   it("treats legacy qmd unavailable results without a reason as binary failures", async () => {
     const cfg = createQmdCfg("missing-qmd-legacy");
     checkQmdBinaryAvailability.mockResolvedValueOnce({
diff --git a/extensions/memory-core/src/memory/search-manager.ts b/extensions/memory-core/src/memory/search-manager.ts
@@ -262,16 +262,18 @@ export async function getMemorySearchManager(params: {
     }
 
     if (transient) {
-      const { manager } = await createPrimaryQmdManager(
+      const { manager, failureReason } = await createPrimaryQmdManager(
         params.purpose === "cli" ? "cli" : "status",
       );
-      return manager ? { manager } : await getBuiltinMemorySearchManager(params);
+      return manager
+        ? { manager }
+        : await getBuiltinMemorySearchManagerAfterQmdFailure(params, failureReason);
     }
 
     const recentFailure = getActiveQmdManagerOpenFailure(scopeKey, identityKey);
     if (recentFailure) {
       log.debug?.(`qmd memory unavailable; using builtin during cooldown: ${recentFailure.reason}`);
-      return await getBuiltinMemorySearchManager(params);
+      return await getBuiltinMemorySearchManagerAfterQmdFailure(params, recentFailure.reason);
     }
 
     const pending = PENDING_QMD_MANAGER_CREATES.get(scopeKey);
@@ -280,16 +282,14 @@ export async function getMemorySearchManager(params: {
       return await getMemorySearchManager(params);
     }
 
+    let pendingFailureReason: string | undefined;
     const pendingCreate: PendingQmdManagerCreate = {
       identityKey,
       promise: (async () => {
         const created = await createFullQmdManager(identityKey);
         if (!created.entry) {
-          recordQmdManagerOpenFailure(
-            scopeKey,
-            identityKey,
-            created.failureReason ?? "qmd memory unavailable",
-          );
+          pendingFailureReason = created.failureReason ?? "qmd memory unavailable";
+          recordQmdManagerOpenFailure(scopeKey, identityKey, pendingFailureReason);
           return null;
         }
         QMD_MANAGER_CACHE.set(scopeKey, created.entry);
@@ -308,12 +308,35 @@ export async function getMemorySearchManager(params: {
     };
     PENDING_QMD_MANAGER_CREATES.set(scopeKey, pendingCreate);
     const manager = await pendingCreate.promise;
-    return manager ? { manager } : await getBuiltinMemorySearchManager(params);
+    return manager
+      ? { manager }
+      : await getBuiltinMemorySearchManagerAfterQmdFailure(params, pendingFailureReason);
   }
 
   return await getBuiltinMemorySearchManager(params);
 }
 
+async function getBuiltinMemorySearchManagerAfterQmdFailure(
+  params: {
+    cfg: OpenClawConfig;
+    agentId: string;
+    purpose?: MemorySearchManagerPurpose;
+  },
+  qmdFailureReason: string | undefined,
+): Promise<MemorySearchManagerResult> {
+  const fallback = await getBuiltinMemorySearchManager(params);
+  if (fallback.manager || !qmdFailureReason) {
+    return fallback;
+  }
+  const fallbackError = fallback.error?.trim();
+  return {
+    manager: null,
+    error: fallbackError
+      ? `${qmdFailureReason}; builtin fallback unavailable: ${fallbackError}`
+      : qmdFailureReason,
+  };
+}
+
 async function getBuiltinMemorySearchManager(params: {
   cfg: OpenClawConfig;
   agentId: string;
