Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
search: saved facts keep the three-quarter threshold; corrections come in only under search.saved_facts_supersede, acknowledgements correct nothing
garrytan78d6ddce2c0d
diff --git a/docs/architecture/RETRIEVAL.md b/docs/architecture/RETRIEVAL.mdindex f321df2ab3..d0f2c11074 100644--- a/docs/architecture/RETRIEVAL.md+++ b/docs/architecture/RETRIEVAL.md@@ -344,15 +344,18 @@ Two cross-cutting seams sit around the pipeline rather than inside it:`src/core/search/saved-facts-match.ts`). Words match whole after stemming with the brain'sfull-text language, the facts keyword index's expression, so "renewal" finds"renews" and "count" does not match inside "countersigned"; words of a CJK- script match as substrings. A fact needs two words of a two- or three-word- query and three quarters of a longer one; the most matched words come first,- then the newest. This is the only place `search` returns saved facts: the+ script match as substrings. A fact needs three quarters of the query's words+ (both of a two-word query); the most matched words come first, then the+ newest. This is the only place `search` returns saved facts: thefacts arm, the facts block and the temporal reserve run in `query` alone.With `search.saved_facts_supersede=true` (default off), a newer fact with acorrection cue ("correction", "ignore the ...", "not what I posted") that- shares at least two matched words with a returned fact is returned too, every- fact it corrects moves below the facts nothing corrects, and those carry- `corrected_by` (the correcting fact's id). The cue is a fixed word list, so+ shares at least two matched words with a returned fact is returned too, even+ below the threshold, every fact it corrects moves below the facts nothing+ corrects, and those carry `corrected_by` (the correcting fact's id). An+ acknowledgement corrects nothing: a cue fact that adds no figure (a number+ other than a date or time) to the older fact, when it restates one of its+ figures or the older fact is itself a correction. The cue is a fixed word list, soan unmarked correction is not caught and a marked unrelated post can relabela fact; nothing stored changes.- **Temporal fact reserve (default off).** With `search.temporal_fact_reserve=true`,diff --git a/docs/architecture/key-files/entity-recall.md b/docs/architecture/key-files/entity-recall.mdindex c2f2be1a5d..67e91a3bf9 100644--- a/docs/architecture/key-files/entity-recall.md+++ b/docs/architecture/key-files/entity-recall.md@@ -24,7 +24,7 @@ card and `get_backlinks`. Guide: [entity recall](../../guides/entity-recall.md).- `src/core/verbs/entity-card-identity.ts` — the `entity` card's `aka_sources`, `identity_siblings`, `identity_excerpt` (verbatim lines of the page and its siblings from `sanitizeRemoteBody`, tiered: declarations, label lines with a name-like value, other label lines, lines with another capitalized run or code; 600 characters per page, 1,200 per card, `identity_excerpt_omitted`), `alias_guidance` (surface-aware) and the `identity_siblings_capped` notice. A segmented page is excerpted from its trusted, withdrawal-overlaid lead (`truthLead`, `EXCERPT_LEAD_BYTES` = 64 KiB, cut back to a whole line), never its body getters; the card equals the inline page's when the qualifying lines sit in that lead (`test/large-pages/segmented-read-refusals.test.ts`). `readSiblingIdentity` is its siblings-and-aliases half (one alias read for the page and its siblings; optional preloaded mention policy and pack), used alone by `entity names[]`. Tests: `test/mentions-identity-siblings.test.ts`.- `src/core/search/alias-fanout.ts` — search and query's alias fan-out: `resolveQueryEntity` (query n-grams up to 4 tokens through `resolveAliases` and linkable exact titles, longest first, capitalized or code-shaped unless a multi-word n-gram resolves to one page, case-sensitive aliases as written, a tie only when the pages are identity siblings), the names of the entity and its siblings by origin then length, at most `search.alias_fanout_max` (4) keyword queries of 5 rows (`searchAliasRequired`: the name as a required websearch phrase, ranked by the query's other terms through `SearchOpts.rankQuery` on both engines), at most 8 spliced rows with `matched_alias`, and the `fanout` meta (`alias_fanout` notice when capped). Offset 0 only. `resolving` takes the handler's `resolveQueryEntity` started before the search, so its reads overlap it. Tests: `test/search-alias-fanout.test.ts`, `test/search-other-names.test.ts`, `test/e2e/mentions-parity.test.ts`. `wholeQueryEntityNames`: when the whole query is one entity's name or alias, `match: "keyword"` lists pages matching any of its names (one websearch OR of phrases; `match_names` in the meta and the count line; rows found by another name carry `matched_alias`). `resolveQueryEntities` returns every entity a text names; its alias, linkable-title and case-sensitive alias reads run concurrently (`test/search-entity-resolve-concurrency.test.ts`).- `src/core/search/entity-facts.ts` — `entitySavedFacts`: when a search names an entity, its newest active saved facts (`factEntitySlugs`, 5) lead the model-visible saved-facts block, then up to 3 facts each of up to 2 entities those facts name (`linked_from`), before the word-overlap matches. Same active, audit-row and visibility rules as recall. Tests: `test/memory-sibling-facts.test.ts`.-- `src/core/search/saved-facts-match.ts` — `matchingSavedFacts`, the word-matched saved facts `search` and `query` report in `retrieval.saved_facts` after the named entity's facts (`ops/search.ts` `buildRetrievalResponseMeta`). Words match whole after stemming with the facts keyword index's expression (`factsFtsDocument`), CJK words as substrings; a fact needs two words of a two- or three-word query and three quarters of a longer one; most matched words first, then newest (time, then id), at most five after the #7043 collapse. One statement behind the facts-only EXISTS probe (`test/search/saved-facts-probe.test.ts`). `search.saved_facts_supersede` (default off): a newer fact with a correction cue that shares two matched words with a returned fact is returned too, and the facts it corrects move last with `corrected_by`. Also owns `FACT_MATCH_STOPWORDS`. Tests: `test/search-saved-facts-match.test.ts`, `test/search-saved-facts.test.ts`.+- `src/core/search/saved-facts-match.ts` — `matchingSavedFacts`, the word-matched saved facts `search` and `query` report in `retrieval.saved_facts` after the named entity's facts (`ops/search.ts` `buildRetrievalResponseMeta`). Words match whole after stemming with the facts keyword index's expression (`factsFtsDocument`), CJK words as substrings; a fact needs three quarters of the query's words; most matched words first, then newest (time, then id), at most five after the #7043 collapse. One statement behind the facts-only EXISTS probe (`test/search/saved-facts-probe.test.ts`). `search.saved_facts_supersede` (default off): a newer fact with a correction cue that shares two matched words with a returned fact is returned too, even below the threshold, and the facts it corrects move last with `corrected_by`; a cue fact that adds no figure to the older fact (`figures`: numbers, dates and times left out) corrects nothing when it restates one of its figures or the older fact is itself a correction. Also owns `FACT_MATCH_STOPWORDS`. Tests: `test/search-saved-facts-match.test.ts`, `test/search-saved-facts.test.ts`.- `src/core/schema-migrations/v206-entity-mention-index.ts` — additive: `page_aliases.origin` (`frontmatter` default, `declared`, `subject`), `case_sensitive`, `alias_text`, unique key `(source_id, alias_norm, slug, origin)`; tables `page_mention_state`, `mention_gazetteer_entries`, `mention_index_status` (RLS on when the role bypasses RLS). `GUARDED_TABLE_COLUMNS` lists the new `page_aliases` columns.Alias readers apply precedence frontmatter > declared > subject per source, and a derived alias never answers for another live page's exact title that the caller can read (the title competitor gets the caller's `pageReadFilter`, so a private title a private-excluding caller can't see never hides a readable alias) (`readAliases` in `src/core/search/read-enrichment.ts`, shared by both engines' `resolveAliases`), so `resolveEntitySlug`, the retrieval reflex, the alias hop, intent weights and `search-diagnose` rank an exact title first. `buildGazetteer` (`src/core/by-mention.ts`) applies the same precedence, drops an alias claimed by two pages at its best origin (unless the claimants are identity siblings, which all keep it), yields to a same-source title, drops a single-word alias equal to the first word of another multi-word entity name, applies the generic-word list to every single-word name, and carries `caseTokens` for case-sensitive entries; `opts.dropped` records every dropped name with its reason.diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 2eb414b316..40ab0782b2 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1321,7 +1321,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;// #7679 / #7685 orphaned worktree refresh. `since` is stamped at the merge slot.{ since: '0.60.472.0', id: 'refresh_orphan_7679', text: 'A managed `gbrain sources refresh` whose process died (for example a container replaced mid-refresh) no longer wedges the checkout: the next plain `gbrain sources refresh` on the owner host finishes the orphaned refresh through the `--resume` path before its own refresh and reports it as `recovered`, and the owner completes an orphaned `syncing` refresh once every member has synced to its target. A refresh whose holder is still running, or is recorded on another host, is never taken over. `gbrain sources writer status` and `gbrain sync status` now name the holder and its `liveness` (`live`, `orphaned`, `unknown`) with a fix naming `--resume`. With `--json`, a refusal that carries a structured fix (`refresh_in_progress`, `refresh_diverged`, a git read failure) now prints `fix` as an object (argv, actor, next) instead of a string; the prose stays in `suggestion`, so read that when a script needs text. A plain refresh of a checkout whose interrupted refresh needs a reset decision now refuses `refresh_recovery_required` (it refused `refresh_in_progress`).' },// GBRA-205 saved-facts wave (harness case cr-05). `since` is stamped at the merge slot.- { since: 'TBD', id: 'saved_facts_stems', text: 'Search `saved_facts` matches a saved fact\'s words the way the facts keyword index does: whole words after stemming with the brain\'s full-text language, so a query for "seats renewal" finds a fact that says "renews at 52 seats", and "count" no longer matches inside "countersigned". A three-word query now needs two of its words (it needed all three); other lengths keep their thresholds (two of two, three quarters of four or more), and words of a CJK script still match as substrings. Among facts matching as many words, the newest comes first, and at most five facts ride a reply. New and default off: `search.saved_facts_supersede` returns a newer fact with a correction cue ahead of the older fact it corrects and labels that one `corrected_by`.' },+ { since: 'TBD', id: 'saved_facts_stems', text: 'Search `saved_facts` matches a saved fact\'s words the way the facts keyword index does: whole words after stemming with the brain\'s full-text language, so a query for "seats renewal" finds a fact that says "renews at 52 seats", and "count" no longer matches inside "countersigned". A fact still needs three quarters of the query\'s words; words of a CJK script still match as substrings. Among facts matching as many words, the newest comes first, and at most five facts ride a reply. New and default off: `search.saved_facts_supersede` also returns a newer fact with a correction cue that shares two matched words with a returned fact, ahead of the fact it corrects, which is labelled `corrected_by`; an acknowledgement that adds no figure corrects nothing.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/search/saved-facts-match.ts b/src/core/search/saved-facts-match.tsindex 567bc8e10a..8c9a5da324 100644--- a/src/core/search/saved-facts-match.ts+++ b/src/core/search/saved-facts-match.ts@@ -30,6 +30,11 @@ export const SAVED_FACTS_SUPERSEDE_KEY = 'search.saved_facts_supersede';/** What marks a saved fact as a correction (Postgres ARE, matched case-insensitively). */const CORRECTION_CUE = String.raw`\m(correction|corrected|correcting|retract(s|ed|ing|ion)?|disregard|scratch that|i misspoke|i was wrong|not what (i|we) (posted|said|wrote)|ignore (the|my|that|what))\M`;+/** The figures a fact states: its numbers, with dates and clock times left out. */+function figures(text: string): Set<string> {+ return new Set(text.replace(/\b\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}(?::\d{2})?)?|\b\d{1,2}:\d{2}\b/g, ' ').match(/\d+(?:[.,]\d+)*/g) ?? []);+}+async function savedFactsSupersedeEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {try {const raw = (await engine.getConfig(SAVED_FACTS_SUPERSEDE_KEY))?.trim().toLowerCase();@@ -44,7 +49,7 @@ async function savedFactsSupersedeEnabled(engine: { getConfig(key: string): Prom* page search never returns them (gbrain-evals Cat 40: agents saved a* correction with remember and the next session's search missed it). This* finds active facts that contain at least three quarters of the query's words- * (two of a two- or three-word query), under the same source scope and+ * (both words of a two-word query), under the same source scope and* visibility rules recall applies, copies of one claim collapsed before the cap* (#7043).* Words match whole after stemming with the brain's full-text language, as the@@ -52,9 +57,12 @@ async function savedFactsSupersedeEnabled(engine: { getConfig(key: string): Prom* inside "countersigned". CJK words, which that parser does not split, match as* substrings. Most matched words first, then newest. With* `search.saved_facts_supersede` on, a newer fact with a correction cue that- * shares at least two matched words with a returned fact is returned too, and- * every fact it corrects moves below the facts nothing corrects, labelled- * `corrected_by`.+ * shares at least two matched words with a returned fact is returned too, even+ * below the threshold, and every fact it corrects moves below the facts nothing+ * corrects, labelled `corrected_by`. An acknowledgement corrects nothing: a cue+ * fact that adds no figure (a number other than a date or time) to the older+ * fact, when it restates one of its figures or the older fact is itself a+ * correction.*/export async function matchingSavedFacts(ctx: OperationContext, scope: { sourceId?: string; sourceIds?: string[]; minTrust?: TrustTier }, queryText: string, otherNames: string[] = []): Promise<Array<SavedFactMatch & CollapseColumns>> {// A query naming one of two declared names also matches facts saved under the other.@@ -97,7 +105,7 @@ export async function matchingSavedFacts(ctx: OperationContext, scope: { sourceISELECT f.id, f.fact, f.entity_slug, f.kind, f.valid_from::text AS valid_from, f.source, f.valid_from AS at, ${SAVED_FACT_COLLAPSE_COLUMNS},ARRAY(SELECT w.i FROM w WHERE CASE WHEN w.pat IS NOT NULL THEN lower(f.fact || ' ' || COALESCE(f.entity_slug, '')) LIKE w.patELSE ${doc} @@ w.tq END ORDER BY w.i) AS matched,- CASE WHEN k.n <= 3 THEN LEAST(2, k.n) ELSE ceil(k.n * 0.75)::int END AS need,+ GREATEST(LEAST(2, k.n), ceil(k.n * 0.75)::int) AS need,($6::boolean AND f.fact ~* $5) AS cueFROM facts f, kWHERE ${active}@@ -111,13 +119,17 @@ export async function matchingSavedFacts(ctx: OperationContext, scope: { sourceI[sources, [...AUDIT_ROW_SOURCES], terms, terms.map(t => hasCJK(t) ? `%${t.replace(/[\\%_]/g, m => `\\${m}`)}%` : null), CORRECTION_CUE, supersede],);const found = rows.map(({ at, matched, need, cue, ...fact }) => ({ fact: { ...fact, id: Number(fact.id) } as SavedFactMatch & CollapseColumns,- at: new Date(at as string).getTime(), words: new Set(matched.map(Number)), need: Number(need), cue }));+ at: new Date(at as string).getTime(), words: new Set(matched.map(Number)), need: Number(need), cue, figures: cue ? figures(fact.fact) : new Set<string>() }));const admitted = found.filter(r => r.words.size >= r.need);if (supersede) {for (const older of admitted) {// Posts saved in one flush share a time; the later id is the later post.+ // An acknowledgement is not a correction: a cue fact that adds no figure to the older fact+ // corrects it only when it restates no figure and the older fact is not a correction itself.+ const olderFigures = figures(older.fact.fact);const correction = found.filter(n => n.cue && (n.at > older.at || (n.at === older.at && n.fact.id > older.fact.id))- && [...n.words].filter(w => older.words.has(w)).length >= Math.min(2, n.need)).sort((a, b) => b.at - a.at || b.fact.id - a.fact.id)[0];+ && [...n.words].filter(w => older.words.has(w)).length >= Math.min(2, n.need)+ && !([...n.figures].every(x => olderFigures.has(x)) && (n.figures.size > 0 || older.cue))).sort((a, b) => b.at - a.at || b.fact.id - a.fact.id)[0];if (correction) older.fact.corrected_by = correction.fact.id;}const correcting = new Set(admitted.flatMap(r => r.fact.corrected_by ? [r.fact.corrected_by] : []));diff --git a/test/search-saved-facts-match.test.ts b/test/search-saved-facts-match.test.tsindex 8df463432f..88dad1f1d9 100644--- a/test/search-saved-facts-match.test.ts+++ b/test/search-saved-facts-match.test.ts@@ -3,9 +3,8 @@* `remember` is found by the next search for its words. Words match whole,* after stemming with the brain's full-text language ("renews" and "renewal"* share a stem; "count" no longer matches inside "countersigned"), and a fact- * needs two words of a two- or three-word query and three quarters of a longer- * one. Among equal matches the newest comes first; at most five facts ride a- * reply.+ * needs three quarters of the query's words, as before. Among equal matches+ * the newest comes first; at most five facts ride a reply.** `search.saved_facts_supersede` (default off): a newer fact carrying a* correction cue that shares the query's words with an older returned fact is@@ -66,6 +65,13 @@ beforeAll(async () => {ids.lease = await remember('Delta Example countersigned the warehouse lease.', '2026-09-01T09:00:00Z');ids.olderLease = await remember('The warehouse lease runs five years.', '2026-08-01T09:00:00Z');ids.newerLease = await remember('The warehouse lease renews in March.', '2026-08-15T09:00:00Z');+ ids.otherAccount = await remember('Kappa Example renews at 30 seats.', '2026-09-01T10:00:00Z');+ ids.delta = await remember('Delta Example has 50 seats, not 55.', '2026-08-01T09:00:00Z');+ ids.deltaAck = await remember('Correction noted: Delta Example has 50 seats, not 55.', '2026-08-01T09:05:00Z');+ ids.omega = await remember('Correction for the record: Omega Example stays with Carol Example.', '2026-07-01T09:00:00Z');+ ids.omegaAck = await remember('Correction noted: Omega Example stays with Carol Example.', '2026-07-01T09:05:00Z');+ ids.sigma = await remember('Correction: Sigma Example has 46 seats, not 52.', '2026-06-01T09:00:00Z');+ ids.sigmaAgain = await remember('Correction again: Sigma Example has 44 seats.', '2026-06-02T09:00:00Z');// A correction the remote caller may not read never comes back and never relabels a fact it can read.await engine.executeRaw(`INSERT INTO facts (source_id, fact, kind, visibility, source, valid_from)VALUES ('default', 'Correction: Orbix renewal seats are 40, ignore the earlier posts.', 'fact', 'private', 'fixture', '2026-09-03')`);@@ -73,22 +79,17 @@ beforeAll(async () => {afterAll(async () => { await engine.disconnect(); });describe('search saved facts: stem-aware whole-word matching', () => {- test('both posts come back for a three-word query that shares two words with each', async () => {+ test('the post comes back for every wording through its word forms; partial matches do not', async () => {await engine.setConfig(SAVED_FACTS_SUPERSEDE_KEY, 'false');- for (const q of WORDINGS.slice(0, 2)) {+ for (const q of WORDINGS) {const { facts } = await search(q);expect(facts.map(f => f.id), q).toContain(ids.first);- expect(facts.map(f => f.id), q).toContain(ids.correction);+ // The correction shares two words (the company and the seats): under three quarters.+ expect(facts.map(f => f.id), q).not.toContain(ids.correction);+ expect(facts.map(f => f.id), q).not.toContain(ids.otherAccount);expect(facts.some(f => f.corrected_by !== undefined), q).toBe(false);expect(facts.length, q).toBeLessThanOrEqual(5);}- // Four and five words: the first post shares three quarters, the correction only two- // (the company and the seats), so without the flag only the first post comes back.- for (const q of WORDINGS.slice(2)) {- const { facts } = await search(q);- expect(facts.map(f => f.id), q).toContain(ids.first);- expect(facts.map(f => f.id), q).not.toContain(ids.correction);- }});test('a query word matches whole words only', async () => {@@ -120,6 +121,8 @@ describe('search.saved_facts_supersede on', () => {expect(facts.find(f => f.id === ids.correction)?.corrected_by, q).toBeUndefined();expect(text, q).toContain('corrected by a newer saved fact');expect(text, q).not.toContain('are 40');+ // Only a correction comes in under three quarters, not any fact sharing two words.+ expect(facts.map(f => f.id), q).not.toContain(ids.otherAccount);expect(facts.length, q).toBeLessThanOrEqual(5);}} finally {@@ -127,6 +130,24 @@ describe('search.saved_facts_supersede on', () => {}});+ test('an acknowledgement that adds no figure relabels nothing', async () => {+ await engine.setConfig(SAVED_FACTS_SUPERSEDE_KEY, 'true');+ try {+ const { facts } = await search('Delta seats');+ expect(facts.map(f => f.id)).toEqual(expect.arrayContaining([ids.delta, ids.deltaAck]));+ expect(facts.some(f => f.corrected_by !== undefined)).toBe(false);+ // Acknowledging a correction does not correct it.+ const omega = await search('Omega Carol');+ expect(omega.facts.map(f => f.id)).toEqual(expect.arrayContaining([ids.omega, ids.omegaAck]));+ expect(omega.facts.some(f => f.corrected_by !== undefined)).toBe(false);+ // A correction of a correction that brings a new figure still corrects it.+ const sigma = await search('Sigma seats');+ expect(sigma.facts.find(f => f.id === ids.sigma)?.corrected_by).toBe(ids.sigmaAgain);+ } finally {+ await engine.setConfig(SAVED_FACTS_SUPERSEDE_KEY, 'false');+ }+ });+test('a newer fact with no correction cue relabels nothing', async () => {await engine.setConfig(SAVED_FACTS_SUPERSEDE_KEY, 'true');try {