fix(memory): rebind qmd collections when a collection root changes

sasan1200 · vincentkoc · commit 22bda60cbe15 · 2026-06-09T01:10:19.000+09:00
ensureCollections() never rebound a managed collection after its root path changed (e.g. an agent workspace repoint): listCollectionsBestEffort() read `qmd collection list`, whose output carries no filesystem path, so listed.path was always undefined and shouldRebindCollection took its defensive branch and skipped the rebind. The collection stayed pinned to the stale root and recall kept resolving the old location. Enrich the listed collections with their path via `qmd collection show` so path-change detection works and the rebind fires. Closes #91251 (cherry picked from commit 4a22501)
diff --git a/extensions/memory-core/src/memory/qmd-manager.test.ts b/extensions/memory-core/src/memory/qmd-manager.test.ts
@@ -5848,6 +5848,170 @@ describe("QmdMemoryManager", () => {
       }
     });
   });
+
+  it("rebinds a managed collection when its root path changed (show reveals old path)", async () => {
+    // Regression: listCollectionsBestEffort gets only the name from `collection list`
+    // (no path). The fix enriches path via `collection show`; without it shouldRebindCollection
+    // hits the `!listed.path` branch and skips the rebind, leaving the old path pinned.
+    const oldWorkspaceDir = path.join(tmpRoot, "old-workspace");
+    const newWorkspaceDir = workspaceDir; // the manager is configured for this new path
+
+    cfg = {
+      ...cfg,
+      memory: {
+        backend: "qmd",
+        qmd: {
+          includeDefaultMemory: false,
+          update: { interval: "0s", debounceMs: 60_000, onBoot: false },
+          paths: [{ path: newWorkspaceDir, pattern: "**/*.md", name: "workspace" }],
+        },
+      },
+    } as OpenClawConfig;
+
+    const collectionName = `workspace-${agentId}`;
+
+    spawnMock.mockImplementation((_cmd: string, args: string[]) => {
+      if (args[0] === "collection" && args[1] === "list") {
+        // Real qmd: names only, no path/pattern in list output.
+        const child = createMockChild({ autoClose: false });
+        emitAndClose(child, "stdout", JSON.stringify([collectionName]));
+        return child;
+      }
+      if (args[0] === "collection" && args[1] === "show" && args[2] === collectionName) {
+        // Real qmd `collection show` output — exposes the stale (old) path.
+        const child = createMockChild({ autoClose: false });
+        emitAndClose(
+          child,
+          "stdout",
+          [
+            `Collection: ${collectionName}`,
+            `  Path:     ${oldWorkspaceDir}`,
+            `  Pattern:  **/*.md`,
+            `  Include:  yes (default)`,
+          ].join("\n"),
+        );
+        return child;
+      }
+      return createMockChild();
+    });
+
+    const { manager } = await createManager({ mode: "full" });
+    await manager.close();
+
+    const commands = spawnMock.mock.calls.map((call: unknown[]) => call[1] as string[]);
+
+    const removeCall = commands.find(
+      (args) => args[0] === "collection" && args[1] === "remove" && args[2] === collectionName,
+    );
+    expect(removeCall).toBeDefined(); // rebind must remove the stale collection
+
+    const addCall = commands.find((args) => {
+      if (args[0] !== "collection" || args[1] !== "add") {
+        return false;
+      }
+      const nameIdx = args.indexOf("--name");
+      return nameIdx >= 0 && args[nameIdx + 1] === collectionName;
+    });
+    expect(addCall).toBeDefined();
+    // The new add must target the NEW workspace path, not the old one.
+    expect(addCall?.[2]).toBe(newWorkspaceDir);
+  });
+
+  it("rebinds a stale in-container collection root to the host workspace (sandbox-mode transition)", async () => {
+    // Sandbox coverage: an agent that previously ran with its workspace bind-mounted under
+    // /home/node/.openclaw/... stored that in-container path as the collection root. Resolved
+    // with host paths, `collection show` reveals the stale container path; the rebind is
+    // path-namespace-agnostic and re-binds to the current host root.
+    const containerRoot = "/home/node/.openclaw/teams/x/workspace";
+    const newWorkspaceDir = workspaceDir; // host path the manager is configured for
+
+    cfg = {
+      ...cfg,
+      memory: {
+        backend: "qmd",
+        qmd: {
+          includeDefaultMemory: false,
+          update: { interval: "0s", debounceMs: 60_000, onBoot: false },
+          paths: [{ path: newWorkspaceDir, pattern: "**/*.md", name: "workspace" }],
+        },
+      },
+    } as OpenClawConfig;
+
+    const collectionName = `workspace-${agentId}`;
+
+    spawnMock.mockImplementation((_cmd: string, args: string[]) => {
+      if (args[0] === "collection" && args[1] === "list") {
+        const child = createMockChild({ autoClose: false });
+        emitAndClose(child, "stdout", JSON.stringify([collectionName]));
+        return child;
+      }
+      if (args[0] === "collection" && args[1] === "show" && args[2] === collectionName) {
+        const child = createMockChild({ autoClose: false });
+        emitAndClose(
+          child,
+          "stdout",
+          [
+            `Collection: ${collectionName}`,
+            `  Path:     ${containerRoot}`,
+            `  Pattern:  **/*.md`,
+            `  Include:  yes (default)`,
+          ].join("\n"),
+        );
+        return child;
+      }
+      return createMockChild();
+    });
+
+    const { manager } = await createManager({ mode: "full" });
+    await manager.close();
+
+    const commands = spawnMock.mock.calls.map((call: unknown[]) => call[1] as string[]);
+    const removeCall = commands.find(
+      (args) => args[0] === "collection" && args[1] === "remove" && args[2] === collectionName,
+    );
+    expect(removeCall).toBeDefined();
+    const addCall = commands.find((args) => {
+      if (args[0] !== "collection" || args[1] !== "add") {
+        return false;
+      }
+      const nameIdx = args.indexOf("--name");
+      return nameIdx >= 0 && args[nameIdx + 1] === collectionName;
+    });
+    expect(addCall).toBeDefined();
+    // Re-added at the host workspace root, not the stale container path.
+    expect(addCall?.[2]).toBe(newWorkspaceDir);
+  });
+
+  it("parseShownCollection extracts path and pattern from qmd collection show output", async () => {
+    // Unit test for the private parser — accessed via type cast to avoid exporting internals.
+    const { manager } = await createManager({ mode: "status" });
+    type WithParser = {
+      parseShownCollection: (output: string) => { path?: string; pattern?: string };
+    };
+    const parser = (manager as unknown as WithParser).parseShownCollection.bind(manager);
+
+    const sampleOutput = [
+      "Collection: memory-dir-example",
+      "  Path:     /home/node/.openclaw/teams/example-team/workspace-example/memory",
+      "  Pattern:  **/*.md",
+      "  Include:  yes (default)",
+    ].join("\n");
+
+    const result = parser(sampleOutput);
+    expect(result.path).toBe("/home/node/.openclaw/teams/example-team/workspace-example/memory");
+    expect(result.pattern).toBe("**/*.md");
+
+    // Tolerant of missing fields.
+    expect(parser("")).toEqual({});
+    expect(parser("Collection: no-path-here\n  Include:  yes")).toEqual({});
+
+    // Path-only (no pattern line).
+    const pathOnly = parser("Collection: x\n  Path:  /some/path\n");
+    expect(pathOnly.path).toBe("/some/path");
+    expect(pathOnly.pattern).toBeUndefined();
+
+    await manager.close();
+  });
 });
 
 function createDeferred<T>() {
diff --git a/extensions/memory-core/src/memory/qmd-manager.ts b/extensions/memory-core/src/memory/qmd-manager.ts
@@ -657,6 +657,36 @@ export class QmdMemoryManager implements MemorySearchManager {
     } catch {
       // ignore; older qmd versions might not support list --json.
     }
+
+    // `qmd collection list` never emits the filesystem path, so `shouldRebindCollection`
+    // cannot detect a workspace move. Enrich the path for managed collections only
+    // (bounded subprocess count) via `qmd collection show`, which does expose it.
+    for (const collection of this.qmd.collections) {
+      const entry = existing.get(collection.name);
+      if (!entry || entry.path) {
+        // Not listed, or path already present (future-proof qmd version or text parser).
+        continue;
+      }
+      try {
+        const showResult = await this.runQmd(["collection", "show", collection.name], {
+          timeoutMs: this.qmd.update.commandTimeoutMs,
+        });
+        const shown = this.parseShownCollection(showResult.stdout);
+        if (shown.path) {
+          entry.path = shown.path;
+        }
+        // Only backfill pattern when the list parse left it absent; never overwrite a
+        // pattern already extracted from `collection list` output (e.g. a changed pattern
+        // detected via qmd text output would be lost if we clobber it here).
+        if (shown.pattern && !entry.pattern) {
+          entry.pattern = shown.pattern;
+        }
+      } catch {
+        // If show fails (old qmd, timeout, missing collection), leave path undefined.
+        // shouldRebindCollection preserves the safe defensive behavior in that case.
+      }
+    }
+
     return existing;
   }
 
@@ -981,6 +1011,28 @@ export class QmdMemoryManager implements MemorySearchManager {
     return listed;
   }
 
+  // Parses the output of `qmd collection show <name>`, which emits:
+  //   Collection: <name>
+  //     Path:     <absolute-path>
+  //     Pattern:  <glob>
+  //     Include:  yes (default)
+  // This is the only qmd command that reliably surfaces the filesystem path.
+  private parseShownCollection(output: string): { path?: string; pattern?: string } {
+    const result: { path?: string; pattern?: string } = {};
+    for (const rawLine of output.split(/\r?\n/)) {
+      const pathMatch = /^\s*Path\s*:\s*(.+?)\s*$/.exec(rawLine);
+      if (pathMatch) {
+        result.path = pathMatch[1].trim();
+        continue;
+      }
+      const patternMatch = /^\s*Pattern\s*:\s*(.+?)\s*$/.exec(rawLine);
+      if (patternMatch) {
+        result.pattern = patternMatch[1].trim();
+      }
+    }
+    return result;
+  }
+
   private shouldRebindCollection(collection: ManagedCollection, listed: ListedCollection): boolean {
     if (!listed.path) {
       if (typeof listed.pattern === "string" && listed.pattern !== collection.pattern) {
