Memory improvements (#1437)

umeshma · web-flow · commit a7b65c5c3fad · 2025-08-08T20:02:04.000Z
* Scope query schema: bug fixes
* Memory: settings flag to allow auto experimentation of natural
language queries with enhanced scope ("where") detection
* Code for fuzzier comparisons of test output
diff --git a/ts/examples/chat/src/memory/knowproDoc.ts b/ts/examples/chat/src/memory/knowproDoc.ts
@@ -70,6 +70,7 @@ export async function createKnowproDocMemoryCommands(
                 ),
                 buildIndex: argBool("Index the imported podcast", true),
                 v2: argBool("Use v2 knowledge extraction", false),
+                scoped: argBool("Use scoped queries", true),
             },
         };
     }
@@ -84,7 +85,7 @@ export async function createKnowproDocMemoryCommands(
             namedArgs.filePath,
             namedArgs.maxCharsPerChunk,
             undefined,
-            kpContext.createMemorySettings(),
+            createDocMemorySettings(namedArgs.scoped),
         );
         kpContext.conversation = context.docMemory;
         writeDocInfo(context.docMemory);
@@ -101,6 +102,7 @@ export async function createKnowproDocMemoryCommands(
             description: "Load existing Doc memory",
             options: {
                 filePath: argSourceFile(),
+                scoped: argBool("Use scoped queries", true),
             },
         };
     }
@@ -118,7 +120,7 @@ export async function createKnowproDocMemoryCommands(
         const docMemory = await cm.DocMemory.readFromFile(
             path.dirname(memoryFilePath),
             getFileName(memoryFilePath),
-            kpContext.createMemorySettings(),
+            createDocMemorySettings(namedArgs.scoped),
         );
         clock.stop();
 
@@ -234,5 +236,13 @@ export async function createKnowproDocMemoryCommands(
             }
         }
     }
+
+    function createDocMemorySettings(useScoped: boolean) {
+        const settings = kpContext.createMemorySettings();
+        if (useScoped !== undefined && useScoped === true) {
+            settings.useScopedSearch = true;
+        }
+        return settings;
+    }
     return;
 }
diff --git a/ts/examples/chat/src/memory/knowproTest.ts b/ts/examples/chat/src/memory/knowproTest.ts
@@ -557,15 +557,7 @@ export async function createKnowproTestCommands(
                 (result, index, total) => {
                     context.printer.writeProgress(index + 1, total);
                     if (result.success) {
-                        const cmp = result.data;
-                        if (cmp.error) {
-                            writeSearchComparison(cmp);
-                        } else {
-                            context.printer.writeLineInColor(
-                                chalk.green,
-                                cmp.query,
-                            );
-                        }
+                        writeSearchComparison(result.data);
                     } else {
                         context.printer.writeError(result.message);
                     }
@@ -690,11 +682,16 @@ export async function createKnowproTestCommands(
     }
 
     function writeSearchComparison(cmp: kpTest.ScopeQueryComparison): void {
-        context.printer.writeJsonInColor(chalk.gray, cmp.expected);
-        context.printer.writeHeading("Scope");
-        context.printer.writeJson(cmp.actual);
         if (cmp.error) {
-            context.printer.writeError(cmp.error);
+            context.printer.writeLineInColor(chalk.redBright, cmp.query);
+            context.printer.writeJsonInColor(chalk.green, cmp.expected);
+            context.printer.writeHeading("Scope");
+            context.printer.writeJsonInColor(chalk.red, cmp.actual);
+            if (cmp.error) {
+                context.printer.writeError(cmp.error);
+            }
+        } else {
+            context.printer.writeLineInColor(chalk.greenBright, cmp.query);
         }
     }
 
diff --git a/ts/examples/examplesLib/src/chalkWriter.ts b/ts/examples/examplesLib/src/chalkWriter.ts
@@ -182,7 +182,7 @@ export class ChalkWriter extends ConsoleWriter {
 
     public writePromptSection(prompt: PromptSection) {
         if (prompt.content) {
-            this.writeLine(prompt.role);
+            this.writeLine(`[Role: ${prompt.role}]`);
             if (typeof prompt.content === "string") {
                 this.writeLine(prompt.content);
             } else {
diff --git a/ts/packages/knowPro/src/searchLang.ts b/ts/packages/knowPro/src/searchLang.ts
@@ -1089,7 +1089,9 @@ export async function searchQueryExprFromLanguage2(
 
 /**
  * Experimental...
- * Allows NLP to specify scoping.
+ * Uses an improved schema to better capture "scope" clauses from natural language queries
+ * Scopes can now be explicitly specified as 'sub-queries'... scope filters. This leads to a more
+ * robust "where" operator
  *
  * Search a conversation using natural language. Returns {@link ConversationSearchResult} containing
  * relevant knowledge and messages.
diff --git a/ts/packages/knowPro/src/searchQuerySchema_v2.ts b/ts/packages/knowPro/src/searchQuerySchema_v2.ts
@@ -27,8 +27,9 @@ export type EntityTerm = {
     facets?: FacetTerm[];
 };
 
+// Use for action verbs only. Ensure nouns are not misinterpreted as verbs
 export type VerbsTerm = {
-    words: string[]; // individual words in single or compound verb
+    words: string[]; // individual words in single verb or compound verb
     tense: "Past" | "Present" | "Future";
 };
 
@@ -46,7 +47,7 @@ export type ActionTerm = {
     additionalEntities?: EntityTerm[];
     // Is the intent of the phrase translated to this ActionTerm to actually get information about a specific entities?
     // Examples:
-    // true: if asking for specific information about an entity, such as "What is Mia's phone number?" or "Where did Jane study?"
+    // true: if asking for specific information about an entity, such as "What did Mia say her phone number was?"
     // false if involves actions and interactions between entities, such as "What phone number did Mia mention in her note to Jane?"
     isInformational: boolean;
 };
@@ -62,10 +63,13 @@ export type ScopeFilter = {
 // Search a search engine using filters:
 // entitySearchTerms cannot contain entities already in actionSearchTerms
 export type SearchFilter = {
+    // Use actionSearchTerm for queries involving actions and interactions between entities.
     actionSearchTerm?: ActionTerm;
+    // Use entitySearchTerms for queries asking for specific information about entities and their attributes.
+    // E.g. "What is Mia's phone number?" or "Where did Jane study?"
     entitySearchTerms?: EntityTerm[];
     // searchTerms:
-    // Concepts, topics or other terms that don't fit ActionTerms or EntityTerms
+    // Concepts, topics or other terms that don't fit (or are not already handled by) ActionTerms or EntityTerms.
     // - Do not use noisy searchTerms like "topic", "topics", "subject", "discussion" etc. even if they are mentioned in the user request
     // - Phrases like 'email address' or 'first name' are a single term
     // - use empty searchTerms array when use asks for summaries
diff --git a/ts/packages/knowProTest/src/common.ts b/ts/packages/knowProTest/src/common.ts
@@ -253,6 +253,7 @@ export function compareStringArray(
     y: string[] | undefined,
     label: string,
     sort = true,
+    cmpFuzzy?: (x: string, y: string) => boolean,
 ): string | undefined {
     if (isUndefinedOrEmpty(x) && isUndefinedOrEmpty(y)) {
         return undefined;
@@ -269,7 +270,9 @@ export function compareStringArray(
     }
     for (let i = 0; i < x.length; ++i) {
         if (collections.stringCompare(x[i], y[i], false) !== 0) {
-            return `${label}: [${i}] ${x[i]} !== ${y[i]}`;
+            if (!cmpFuzzy || !cmpFuzzy(x[i], y[i])) {
+                return `${label}: [${i}] ${x[i]} !== ${y[i]}`;
+            }
         }
     }
     return undefined;
@@ -345,3 +348,7 @@ export function queryError(query: string, result: Error): Error {
 export function stringifyReadable(value: any): string {
     return JSON.stringify(value, undefined, 2);
 }
+
+export function isStem(x: string, y: string, stemLength = 2) {
+    return x.startsWith(y) && x.length - y.length <= stemLength;
+}
diff --git a/ts/packages/knowProTest/src/searchTest.ts b/ts/packages/knowProTest/src/searchTest.ts
@@ -11,11 +11,14 @@ import {
     searchRequestDef,
 } from "./types.js";
 import {
+    compareArray,
     compareNumberArray,
     compareObject,
     compareStringArray,
     dateRangeToTimeRange,
     getCommandArgs,
+    isStem,
+    isUndefinedOrEmpty,
     queryError,
     runTestBatch,
 } from "./common.js";
@@ -354,6 +357,7 @@ export function compareSearchExpr(
 function compareActionTerm(
     x?: kp.querySchema.ActionTerm,
     y?: kp.querySchema.ActionTerm,
+    strict: boolean = true,
 ): string | undefined {
     if (x === undefined && y === undefined) {
         return undefined;
@@ -362,26 +366,35 @@ function compareActionTerm(
         x?.actionVerbs?.words,
         y?.actionVerbs?.words,
         "verbs",
+        true,
+        strict ? undefined : (xv, yv) => isStem(xv, yv) || isStem(yv, xv),
     );
     if (error !== undefined) {
         return error;
     }
-    error = compareObject(x?.actorEntities, y?.actorEntities, "actorEntities");
+    error = compareEntityTerms(
+        x?.actorEntities,
+        y?.actorEntities,
+        "actorEntities",
+        strict,
+    );
     if (error !== undefined) {
         return error;
     }
-    error = compareObject(
+    error = compareEntityTerms(
         x?.additionalEntities,
         y?.additionalEntities,
         "additionalEntities",
+        strict,
     );
     if (error !== undefined) {
         return error;
     }
-    error = compareObject(
+    error = compareEntityTerms(
         x?.targetEntities,
         y?.targetEntities,
         "targetEntities",
+        strict,
     );
     if (error !== undefined) {
         return error;
@@ -392,6 +405,81 @@ function compareActionTerm(
     return undefined;
 }
 
+function compareEntityTerms(
+    x: kp.querySchema.EntityTerm[] | "*" | undefined,
+    y: kp.querySchema.EntityTerm[] | "*" | undefined,
+    label: string,
+    strict: boolean = true,
+): string | undefined {
+    if (isUndefinedOrEmpty(x) && isUndefinedOrEmpty(y)) {
+        return undefined;
+    }
+    if (!Array.isArray(x) || !Array.isArray(y)) {
+        return compareObject(x, y, label);
+    }
+    return compareArray(x, y, label, (xt, yt) =>
+        compareEntityTerm(xt, yt, label, strict),
+    );
+}
+
+function compareEntityTerm(
+    x: kp.querySchema.EntityTerm,
+    y: kp.querySchema.EntityTerm,
+    label: string,
+    strict: boolean,
+): string | undefined {
+    if (strict) {
+        return compareObject(x, y, label);
+    }
+
+    if (x.name !== y.name) {
+        return `${label}.name: ${x.name} !== ${y.name}`;
+    }
+
+    let error = compareTypes(x.type, y.type, label);
+    if (error !== undefined) {
+        return error;
+    }
+
+    if (x.isNamePronoun !== y.isNamePronoun) {
+        return `${label}.isNamePronoun: ${x.isNamePronoun} !== ${y.isNamePronoun}`;
+    }
+
+    return compareObject(x.facets, y.facets, label + ".facets");
+
+    function compareTypes(
+        xType: string[] | undefined,
+        yType: string[] | undefined,
+        label: string,
+    ): string | undefined {
+        let error = compareStringArray(xType, yType, label + ".type");
+        if (error === undefined) {
+            return undefined;
+        }
+        if (xType !== undefined && isTypeVariation(xType, yType)) {
+            return undefined;
+        }
+        if (yType !== undefined && isTypeVariation(yType, xType)) {
+            return undefined;
+        }
+        return error;
+    }
+}
+
+function isTypeVariation(xType: string[], yType?: string[]): boolean {
+    if (xType.length === 1 && isUndefinedOrEmpty(yType)) {
+        const xValue = xType[0];
+        switch (xValue.toLowerCase()) {
+            default:
+                break;
+
+            case "person":
+                return true;
+        }
+    }
+    return false;
+}
+
 export function compareSearchQueryScope(
     s1: kp.querySchema.SearchQuery,
     s2: kp.querySchema2.SearchQuery,
@@ -414,6 +502,7 @@ export function compareSearchQueryScope(
 export function compareSearchExprScope(
     s1: kp.querySchema.SearchExpr,
     s2: kp.querySchema2.SearchExpr,
+    strict: boolean = false,
 ): string | undefined {
     if (s1.filters.length !== s2.filters.length) {
         return `SearchExpr.filters.length: ${s1.filters.length} !== ${s2.filters.length}`;
@@ -423,15 +512,20 @@ export function compareSearchExprScope(
         const f1 = s1.filters[i];
         const f2 = s2.filters[i];
 
-        let error = compareObject(
+        let error = compareEntityTerms(
             f1.entitySearchTerms,
             f2.entitySearchTerms,
             "entitySearchTerms",
+            strict,
         );
         if (error !== undefined) {
             return error;
         }
-        error = compareActionTerm(f1.actionSearchTerm, f2.actionSearchTerm);
+        error = compareActionTerm(
+            f1.actionSearchTerm,
+            f2.actionSearchTerm,
+            strict,
+        );
         if (error !== undefined) {
             return error;
         }
diff --git a/ts/packages/memory/conversation/src/docSearchQuerySchema.ts b/ts/packages/memory/conversation/src/docSearchQuerySchema.ts
@@ -29,6 +29,7 @@ export type EntityTerm = {
     facets?: FacetTerm[];
 };
 
+// Use for action verbs only. Ensure nouns are not misinterpreted as verbs
 export type VerbsTerm = {
     words: string[]; // individual words in single or compound verb
     tense: "Past" | "Present" | "Future";
@@ -48,7 +49,7 @@ export type ActionTerm = {
     additionalEntities?: EntityTerm[];
     // Is the intent of the phrase translated to this ActionTerm to actually get information about a specific entities?
     // Examples:
-    // true: if asking for specific information about an entity, such as "What is Mia's phone number?" or "Where did Jane study?"
+    // true: if asking for specific information about an entity, such as "What did Mia say her phone number was?"
     // false if involves actions and interactions between entities, such as "What phone number did Mia mention in her note to Jane?"
     isInformational: boolean;
 };
@@ -65,10 +66,13 @@ export type ScopeFilter = {
 // Search a search engine using filters:
 // entitySearchTerms cannot contain entities already in actionSearchTerms
 export type SearchFilter = {
+    // Use actionSearchTerm for queries involving actions and interactions between entities.
     actionSearchTerm?: ActionTerm;
+    // Use entitySearchTerms for queries asking for specific information about entities and their attributes.
+    // E.g. "What is Mia's phone number?" or "Where did Jane study?"
     entitySearchTerms?: EntityTerm[];
     // searchTerms:
-    // Use for all concepts, topics, or other search terms that don't fit ActionTerms or EntityTerms
+    // Use for all concepts, topics, or other search terms that don't fit (or are not already handled by) ActionTerms or EntityTerms
     // - Do not use noisy searchTerms like "topic", "topics", "subject", "discussion" etc. even if they are mentioned in the user request
     // - Phrases like 'email address' or 'first name' are a single term
     // - use empty searchTerms array when user asks for summaries
diff --git a/ts/packages/memory/conversation/src/memory.ts b/ts/packages/memory/conversation/src/memory.ts
