fix(memory): bound per-keyword hybrid FTS recall

vincentkoc · vincentkoc · commit 8ad671b64b9c · 2026-04-28T07:54:16.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Memory: bound provider-backed hybrid keyword fan-out while still recalling split multi-word matches from separate chunks. Carries forward #39555; refs #57711. Thanks @yangzi33 and @ckybit.
 - Control UI/WebChat: keep large attachment payloads out of Lit state and optimistic chat messages, using object URL previews plus send-time payload serialization so PDF/image uploads no longer trigger `RangeError: Maximum call stack size exceeded`. Fixes #73360; refs #54378 and #63432. Thanks @hejunhui-73, @Ansub, and @christianhernandez3-afk.
 - Agents/models: keep per-agent primary models strict when `fallbacks` is omitted, so probe-only custom providers are not tried as hidden fallback candidates unless the agent explicitly opts in. Fixes #73332. Thanks @haumanto.
 - Gateway/models: add `models.pricing.enabled` so offline or restricted-network installs can skip startup OpenRouter and LiteLLM pricing-catalog fetches while keeping explicit model costs working. Fixes #53639. Thanks @callebtc, @palewire, and @rjdjohnston.
diff --git a/extensions/memory-core/src/memory/index.test.ts b/extensions/memory-core/src/memory/index.test.ts
@@ -406,6 +406,16 @@ describe("memory index", () => {
     await fs.mkdir(memoryDir, { recursive: true });
     await fs.writeFile(path.join(memoryDir, "alpha-note.md"), "# Alpha\nAlpha protocol notes.");
     await fs.writeFile(path.join(memoryDir, "beta-note.md"), "# Beta\nBeta release notes.");
+    await fs.writeFile(path.join(memoryDir, "gamma-note.md"), "# Gamma\nGamma rollout notes.");
+    await fs.writeFile(path.join(memoryDir, "delta-note.md"), "# Delta\nDelta incident notes.");
+    await fs.writeFile(
+      path.join(memoryDir, "epsilon-note.md"),
+      "# Epsilon\nEpsilon roadmap notes.",
+    );
+    await fs.writeFile(path.join(memoryDir, "zeta-note.md"), "# Zeta\nZeta archive notes.");
+    await fs.writeFile(path.join(memoryDir, "eta-note.md"), "# Eta\nEta integration notes.");
+    await fs.writeFile(path.join(memoryDir, "theta-note.md"), "# Theta\nTheta release notes.");
+    await fs.writeFile(path.join(memoryDir, "iota-note.md"), "# Iota\nIota migration notes.");
 
     const manager = await getFreshManager(
       createCfg({
@@ -420,11 +430,34 @@ describe("memory index", () => {
       }
 
       await manager.sync({ reason: "test" });
-      const results = await manager.search("alpha beta", { maxResults: 10 });
+      let ftsMatchQueries = 0;
+      const db = (
+        manager as unknown as {
+          db: { prepare: (sql: string) => unknown };
+        }
+      ).db;
+      const prepare = db.prepare.bind(db);
+      db.prepare = ((sql: string) => {
+        if (sql.includes("FROM chunks_fts") && sql.includes("MATCH ?")) {
+          ftsMatchQueries += 1;
+        }
+        return prepare(sql);
+      }) as typeof db.prepare;
+
+      const results = await (async () => {
+        try {
+          return await manager.search("alpha beta gamma delta epsilon zeta eta theta iota", {
+            maxResults: 10,
+          });
+        } finally {
+          db.prepare = prepare;
+        }
+      })();
       const resultPaths = results.map((result) => result.path);
 
       expect(resultPaths.some((entry) => entry.endsWith("memory/alpha-note.md"))).toBe(true);
       expect(resultPaths.some((entry) => entry.endsWith("memory/beta-note.md"))).toBe(true);
+      expect(ftsMatchQueries).toBeLessThanOrEqual(8);
     } finally {
       await manager.close?.();
     }
diff --git a/extensions/memory-core/src/memory/manager.ts b/extensions/memory-core/src/memory/manager.ts
@@ -552,13 +552,12 @@ export class MemoryIndexManager extends MemoryManagerEmbeddingOps implements Mem
     return results.map((entry) => entry as MemorySearchResult & { id: string; textScore: number });
   }
 
-  private resolveHybridKeywordTerms(query: string): string[] {
+  private resolveHybridKeywordTerms(query: string, limit = HYBRID_KEYWORD_FANOUT_LIMIT): string[] {
+    const keywordLimit = Math.max(1, Math.floor(limit));
     const keywords = extractKeywords(query, {
       ftsTokenizer: this.settings.store.fts.tokenizer,
     });
-    const ranked = keywords
-      .toSorted((a, b) => b.length - a.length)
-      .slice(0, HYBRID_KEYWORD_FANOUT_LIMIT);
+    const ranked = keywords.toSorted((a, b) => b.length - a.length).slice(0, keywordLimit);
     return ranked.length > 0 ? ranked : [query];
   }
 
@@ -568,8 +567,11 @@ export class MemoryIndexManager extends MemoryManagerEmbeddingOps implements Mem
     options?: { boostFallbackRanking?: boolean; includeFullQuery?: boolean },
     sourceFilterList?: MemorySource[],
   ): Promise<Array<MemorySearchResult & { id: string; textScore: number }>> {
-    const terms = this.resolveHybridKeywordTerms(query);
     const includeFullQuery = options?.includeFullQuery ?? true;
+    const keywordLimit = includeFullQuery
+      ? HYBRID_KEYWORD_FANOUT_LIMIT - 1
+      : HYBRID_KEYWORD_FANOUT_LIMIT;
+    const terms = this.resolveHybridKeywordTerms(query, keywordLimit);
     const searchTerms = includeFullQuery
       ? [query, ...terms.filter((term) => term !== query)]
       : terms;
diff --git a/src/memory/manager.hybrid-keyword-multi.test.ts b/src/memory/manager.hybrid-keyword-multi.test.ts
