Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

search: search.saved_facts_supersede on by default (Garry, 2026-10-27)

garrytan0c568a6109ce
diff --git a/docs/architecture/RETRIEVAL.md b/docs/architecture/RETRIEVAL.md
index d0f2c11074..8c96dd7942 100644
--- a/docs/architecture/RETRIEVAL.md
+++ b/docs/architecture/RETRIEVAL.md
@@ -348,7 +348,7 @@ Two cross-cutting seams sit around the pipeline rather than inside it:
(both of a two-word query); the most matched words come first, then the
newest. This is the only place `search` returns saved facts: the
facts arm, the facts block and the temporal reserve run in `query` alone.
- With `search.saved_facts_supersede=true` (default off), a newer fact with a
+ With `search.saved_facts_supersede` (default on; `false` turns it off), a newer fact with a
correction cue ("correction", "ignore the ...", "not what I posted") that
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
diff --git a/docs/architecture/key-files/entity-recall.md b/docs/architecture/key-files/entity-recall.md
index 67e91a3bf9..b8e42bec4e 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 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/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 on; `false` turns it 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.ts
index 40ab0782b2..616db2ae81 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 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.' },
+ { 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. On by default (`gbrain config set search.saved_facts_supersede false` turns it off): search 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/config.ts b/src/core/config.ts
index e15605bfb3..09618aaf8c 100644
--- a/src/core/config.ts
+++ b/src/core/config.ts
@@ -1437,7 +1437,7 @@ export const KNOWN_CONFIG_KEYS: readonly string[] = [
'search.evidence_tail_trim', // GBRA-156: protected top-3 tail trim of auto conversation blocks (default off; search/evidence-tail-trim.ts)
'search.entity_anchoring', // entity-anchored retrieval for entity-scoped current-state query/search (default off; search/entity-anchor.ts)
'search.query_facts_arm', // query adds matching active facts as rows in spare capacity (default on; search/facts-arm.ts)
- 'search.saved_facts_supersede', // search saved_facts: a newer fact with a correction cue goes ahead of the fact it corrects, labelled corrected_by (default off; search/saved-facts-match.ts)
+ 'search.saved_facts_supersede', // search saved_facts: a newer fact with a correction cue goes ahead of the fact it corrects, labelled corrected_by (default on; search/saved-facts-match.ts)
'search.temporal_fact_reserve', // temporal-cue queries reserve up to 15% of the token budget for question-ranked dated facts (default off; search/facts-arm.ts)
'search.page_rank_cut', // W5: whole_pages (default) | off — page unit + caller token_budget stops adding pages once their whole pages fill factor x the budget (search/page-rank-cut.ts)
'search.page_rank_cut_factor', // W5: whole_pages target = factor x the budget (default 1.5)
diff --git a/src/core/search/saved-facts-match.ts b/src/core/search/saved-facts-match.ts
index 8c9a5da324..62c27aa39e 100644
--- a/src/core/search/saved-facts-match.ts
+++ b/src/core/search/saved-facts-match.ts
@@ -2,7 +2,7 @@
* The saved facts `search` and `query` report beside their rows
* (`retrieval.saved_facts`, after the facts of the entity the query names):
* active facts that share the query's words, matched as stemmed whole words.
- * `search.saved_facts_supersede` (default off) adds correction-cue ordering.
+ * `search.saved_facts_supersede` (default on) adds correction-cue ordering.
* Tests: test/search-saved-facts-match.test.ts, test/search-saved-facts.test.ts,
* test/search/saved-facts-probe.test.ts.
*/
@@ -25,7 +25,7 @@ export interface SavedFactMatch { id: number; fact: string; entity_slug: string
/** With `search.saved_facts_supersede` on: the newer returned fact that corrects this one. */
corrected_by?: number }
-/** Default off: a newer saved fact carrying a correction cue is returned ahead of the older fact it corrects, which is labelled `corrected_by`. */
+/** Default on (set false to turn off): a newer saved fact carrying a correction cue is returned ahead of the older fact it corrects, which is labelled `corrected_by`. */
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`;
@@ -38,9 +38,9 @@ function figures(text: string): Set<string> {
async function savedFactsSupersedeEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
try {
const raw = (await engine.getConfig(SAVED_FACTS_SUPERSEDE_KEY))?.trim().toLowerCase();
- return raw === 'true' || raw === 'on' || raw === '1' || raw === 'yes';
+ return !(raw === 'false' || raw === 'off' || raw === '0' || raw === 'no');
} catch {
- return false;
+ return true;
}
}
diff --git a/test/search-saved-facts-match.test.ts b/test/search-saved-facts-match.test.ts
index 88dad1f1d9..0b91117cf8 100644
--- a/test/search-saved-facts-match.test.ts
+++ b/test/search-saved-facts-match.test.ts
@@ -6,7 +6,7 @@
* 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
+ * `search.saved_facts_supersede` (default on): a newer fact carrying a
* correction cue that shares the query's words with an older returned fact is
* returned ahead of it, and the older one is labelled `corrected_by`. The
* fixture is the shape of a harness case where a channel post was corrected
@@ -109,6 +109,20 @@ describe('search saved facts: stem-aware whole-word matching', () => {
});
describe('search.saved_facts_supersede on', () => {
+ test('on by default: with the key unset the correction comes back ahead of the fact it corrects', async () => {
+ await engine.unsetConfig(SAVED_FACTS_SUPERSEDE_KEY);
+ try {
+ for (const q of WORDINGS) {
+ const { facts } = await search(q);
+ expect(order(facts, ids.correction), q).toBeGreaterThanOrEqual(0);
+ expect(order(facts, ids.correction), q).toBeLessThan(order(facts, ids.first));
+ expect(facts.find(f => f.id === ids.first)?.corrected_by, q).toBe(ids.correction);
+ }
+ } finally {
+ await engine.setConfig(SAVED_FACTS_SUPERSEDE_KEY, 'false');
+ }
+ });
+
test('the correction comes back ahead of the fact it corrects, which is labelled, for every wording', async () => {
await engine.setConfig(SAVED_FACTS_SUPERSEDE_KEY, 'true');
try {