🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(memory): TieredMemoryStore recalls multi-word and natural-language queries (#4152)
r85537ab4d809
diff --git a/v3/@claude-flow/memory/src/tiered-memory.test.ts b/v3/@claude-flow/memory/src/tiered-memory.test.tsindex e4f1b59a5c..5d04464831 100644--- a/v3/@claude-flow/memory/src/tiered-memory.test.ts+++ b/v3/@claude-flow/memory/src/tiered-memory.test.ts@@ -266,3 +266,50 @@ describe('TieredMemoryStore — durability (#2887)', () => {).toEqual({ n: 0 });});});++describe('TieredMemoryStore — multi-word recall (#4152)', () => {+ const LESSON = "#1851: parseInt(pair, 16) tolerates trailing garbage ('1z' -> 1); validate the whole hex body before decoding";+ let store: TieredMemoryStore;+ beforeEach(() => {+ store = new TieredMemoryStore();+ store.store('lesson-1851', LESSON, 'semantic');+ store.store('unrelated', 'Concrete slabs must cure for 7 days before heavy loads', 'semantic');+ });++ it('three words taken from the stored value find it (they used to return [])', () => {+ expect(store.recall('parseInt trailing garbage').map(e => e.key)).toEqual(['lesson-1851']);+ });++ it('a natural-language question about the lesson finds it', () => {+ const hit = store.recall('why did malformed hex like 1z decode instead of failing');+ expect(hit.map(e => e.key)).toContain('lesson-1851');+ expect(hit.map(e => e.key)).not.toContain('unrelated');+ });++ it('single words and exact phrases still work and rank first', () => {+ expect(store.recall('hex').map(e => e.key)).toEqual(['lesson-1851']);+ expect(store.recall('validate the whole hex body').map(e => e.key)[0]).toBe('lesson-1851');+ });++ it('a query that shares only one incidental word with an entry does not match', () => {+ expect(store.recall('how long before heavy rain arrives tomorrow').map(e => e.key)).toEqual([]);+ });++ it('ranks the better term coverage first, then the newest', () => {+ const s = new TieredMemoryStore();+ s.store('a', 'trailing garbage in hex input', 'working');+ s.store('b', 'trailing garbage', 'working');+ s.store('c', 'garbage only here', 'working');+ expect(s.recall('hex trailing garbage').map(e => e.key)[0]).toBe('a');+ });++ it('stop words alone match nothing', () => {+ expect(store.recall('what is the').map(e => e.key)).toEqual([]);+ });++ it('respects topK and validity windows as before', () => {+ const s = new TieredMemoryStore();+ for (let i = 0; i < 8; i++) s.store(`k${i}`, `parse trailing garbage ${i}`, 'working');+ expect(s.recall('parse trailing garbage', 3)).toHaveLength(3);+ });+});diff --git a/v3/@claude-flow/memory/src/tiered-memory.ts b/v3/@claude-flow/memory/src/tiered-memory.tsindex 500fdda31a..9385dc96f5 100644--- a/v3/@claude-flow/memory/src/tiered-memory.ts+++ b/v3/@claude-flow/memory/src/tiered-memory.ts@@ -145,6 +145,46 @@ const MAX_PER_TIER = 5000;const MAX_ARCHIVED = 5000;const MAX_VALUE_LENGTH = 100_000;const MAX_QUERY_LENGTH = 10_000;+/** Upper bound on entries scanned by one recall (the store itself is bounded far below this). */+const MAX_RECALL_SCAN = 50_000;++/** Words that carry no retrieval signal in a natural-language question (#4152). */+const RECALL_STOP_WORDS = new Set([+ 'the', 'and', 'for', 'are', 'was', 'were', 'what', 'why', 'how', 'did', 'does', 'from', 'with', 'that', 'this',+ 'have', 'has', 'about', 'know', 'into', 'your', 'when', 'where', 'which', 'will', 'can', 'you', 'our', 'not', 'but',+ 'than', 'then', 'there', 'their', 'them', 'who', 'whom', 'would', 'should', 'could', 'any', 'all', 'its', 'also',+ 'of', 'is', 'in', 'to', 'it', 'on', 'at', 'as', 'be', 'by', 'or', 'an', 'if', 'so', 'do', 'we', 'us', 'my', 'me', 'am',+]);++/** Distinct lowercase query terms of length >= 2 with stop words removed. */+export function recallTerms(query: string): string[] {+ const terms = query.toLowerCase().split(/[^a-z0-9_]+/).filter(t => t.length >= 2 && !RECALL_STOP_WORDS.has(t));+ return [...new Set(terms)];+}++/** Light stem so "decode" finds "decoding" and "failing" finds "failed" (kept at >= 4 characters). */+function recallStem(term: string): string {+ for (const suffix of ['ing', 'ed', 'es', 'e', 's']) {+ if (term.length - suffix.length >= 4 && term.endsWith(suffix)) return term.slice(0, -suffix.length);+ }+ return term;+}++/**+ * Relevance of `text` (already lowercased) for a query: 1 when the whole query+ * is a contiguous substring (the old behaviour, so existing exact recalls rank+ * first), otherwise the fraction of query terms present, provided at least two+ * terms (or the only term) match and the fraction is >= 0.4. Zero means no match.+ */+export function recallScore(text: string, q: string, terms: string[]): number {+ if (q.length > 0 && text.includes(q)) return 1;+ if (terms.length === 0) return 0;+ let matched = 0;+ for (const t of terms) if (text.includes(t) || text.includes(recallStem(t))) matched++;+ const needed = Math.min(2, terms.length);+ const coverage = matched / terms.length;+ return matched >= needed && coverage >= 0.4 ? coverage * 0.95 : 0;+}let idCounter = 0;function nextId(): string {@@ -369,7 +409,10 @@ export class TieredMemoryStore {}/**- * Substring recall across tiers, newest first. By default only+ * Recall across tiers, best match first then newest. A query matches an entry+ * when the whole query is a substring of its key or value (as before) OR when+ * enough of its terms are present (#4152: a multi-word question used to return+ * [] because only the entire string was tested). By default only* temporally-valid entries are returned; pass `{ includeExpired: true }`* to audit superseded / expired / future-dated facts too.*/@@ -378,32 +421,38 @@ export class TieredMemoryStore {const q = query.toLowerCase().substring(0, MAX_QUERY_LENGTH);const includeExpired = options?.includeExpired === true;const now = Date.now();- const results: TieredMemoryEntry[] = [];-- const consider = (entry: TieredMemoryEntry): boolean => {- if (!entry.key.toLowerCase().includes(q) && !entry.value.toLowerCase().includes(q)) {- return false;- }- if (!includeExpired && !isTemporallyValid(entry, now)) return false;- results.push(entry);- return true;+ const terms = recallTerms(q);+ const scored: Array<{ entry: TieredMemoryEntry; score: number }> = [];+ let scanned = 0;++ const consider = (entry: TieredMemoryEntry): void => {+ const score = Math.max(+ recallScore(entry.key.toLowerCase(), q, terms),+ recallScore(`${entry.key} ${entry.value}`.toLowerCase(), q, terms),+ );+ if (score <= 0) return;+ if (!includeExpired && !isTemporallyValid(entry, now)) return;+ scored.push({ entry, score });};outer: for (const map of Object.values(this.tiers)) {for (const entry of map.values()) {consider(entry);- if (results.length >= safeTopK * 3) break outer; // early exit for large stores+ if (++scanned >= MAX_RECALL_SCAN) break outer; // bound the work on very large stores}}- if (includeExpired && results.length < safeTopK * 3) {+ if (includeExpired && scanned < MAX_RECALL_SCAN) {for (const entry of this.archived) {consider(entry);- if (results.length >= safeTopK * 3) break;+ if (++scanned >= MAX_RECALL_SCAN) break;}}- return results.sort((a, b) => b.ts - a.ts).slice(0, safeTopK);+ return scored+ .sort((a, b) => b.score - a.score || b.entry.ts - a.entry.ts)+ .slice(0, safeTopK)+ .map(r => r.entry);}/** Hard-delete an active entry by key (used by hierarchical-delete). */