Garry's Opinionated OpenClaw/Hermes Agent Brain
Key files: Recall ranking
Subsystem index. Read only the entries relevant to your change. Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
recall's question ranking itself (pool, score, admission) is the
src/core/facts/question-recall.ts entry in Graph And Facts.
This page covers the two switches layered on it (#2941, #2953) and the
typed-claim conflict lane whose proposals recall labels contested.
Confidence weighting and entity grouping
With recall.confidence_weighting on, rankFactsByQuestion multiplies each
admitted fact's relevance by confidenceFactor(recallConfidence(...)) after
admission (admission still reads raw relevance, so the admitted set never
changes), orders by that rank score, newest valid_from, id, and only then
collapses copies (#7043) and cuts to limit; weightedRepresentative
delivers a collapsed group's best-ranked copy, not its newest. The response
keeps relevance raw and adds rank_score and confidence_factor per fact
(src/core/ops/facts.ts).
With recall.group_by_entity on and no entity, groupFactsByEntity runs
in the recall op after the limit and budget cuts, so it only reorders the
delivered facts: groups keyed by (source_id, entity_slug), ordered by their
best fact, a null-entity group for unscoped facts, facts_groups
[{source_id, entity_slug, fact_ids, top_relevance}], and, when two or more
entities answer, entity_unspecified {candidates, suggestion} plus the
entity_unspecified info notice whose decision offers one recall per entity
(at most 5). Grouping reads delivered rows only, so a remote caller never
learns of a hidden entity. Both switches work the same on repo-less brains:
they read database rows only.
Tests: test/recall-confidence-grouping.test.ts (both engines; Postgres
through test/e2e/recall-confidence-grouping-postgres.test.ts).
Typed claims and the claim-conflict lane
remember takes claim_metric, claim_value, claim_unit and
claim_period (a single call and each batch item, never shared across items;
src/core/verbs.ts, src/core/remember-batch.ts). parseClaimParams
validates them with the facts-fence codec as the oracle and refuses
invalid_params with the corrected call as fix.mcp. The claim rides the
write request into src/core/persistence/memory-prepare.ts: the new row, the
fence row fenceRowOf renders, the hold payload and its release
(src/core/trust/owner-actions.ts, src/core/trust/release-publish.ts), and
the receipt. A typed write never supersedes a typed fact in another claim slot
(sameClaimSlot in src/core/facts/single-prepare.ts); the same text with a
claim supersedes an untyped copy and never rewrites a typed one
(claim_ignored: existing_claim). A remote recall fences a quoted fact's
claim strings like its text (recallClaimColumns in src/core/ops/facts.ts),
and a remote remember strips that fence from copied claim fields.
The detector proposes one decide_proposals row per conflicting pair: same
source, entity, metric, unit and period (null-safe), same as-of bucket, both
facts active, non-audit and the same visibility. A fact on a member page pairs
only with another fact on that page (onMemberPageSql,
src/core/access/member-facts.ts). The unique expression index
decide_proposals_claim_pair_uidx (migration v288) over the unordered pair for
claim_conflicts: sweeps and insertProposal's ON CONFLICT DO NOTHING keep
concurrent runs to one row; the anti-joins skip pairs any sweep already
proposed and pairs with a pending trust supersede_fact proposal. It runs as
the global dream phase claim_conflicts (after edge_contradictions, sources
with no local path included, no_coordinated_write) and as
gbrain decide sweep --claims. src/core/trust/review.ts lists pending
proposals with both facts active as kind contradiction (dp<id>) with
supersede, forget, confirm and drop argv plus command_meta; the
--accept-all path in src/commands/trust.ts skips them.
Tests: test/claim-conflicts.test.ts and test/remember-typed-claims.test.ts
(both engines; Postgres through their test/e2e/*-postgres.test.ts twins).
Files
src/core/facts/recall-config.ts— recall's config keys:recall.confidence_weightingandrecall.group_by_entity(on|off, default off; unset, unreadable or unknown stored values read as off) andrecall.question_admission(reserve|facts_arm).recallConfigValueRefusalis whatgbrain config set(commands/config.ts) calls for everyrecall.*key, so a typo is refused instead of stored.src/core/facts/decay.ts—effectiveConfidence(confidence × exp(-age/half-life) fromvalid_from; the hot-memory injector and recall's CLI JSONeffective_confidence) andrecallConfidence(fact, dated, now), the weighting's belief weight: trust is a floor (TRUST_RECALL_FLOOR:user_confirmedandoperator_curatedweigh 1 at any age), every other tier decays byeffectiveConfidencetimesTRUST_RECALL_WEIGHT(tool 0.9, agent and unknown 0.8, external 0.6). A writer-datedfactrow does not decay; expired or lapsed rows weigh 0.confidenceFactor(w) = 0.5 + 0.5w, so weighting at most halves a score.src/core/facts/typed-claim.ts— the typed-claim columns:parseClaimParams(fence round-trip validation,claim_metricrequired with any other key),claimColumns/storedClaim(set columns only),claimBucketand its SQL twinclaimBucketSql(UTC day; ISO week, month, quarter or year forweekly/monthly/quarterly/annual/annually/yearly; any other period is a day bucket),sameClaimSlot.src/core/facts/claim-conflicts.ts— the keyless detector:dream.claim_conflicts.mode(propose|off, default off; anything else reads off andgbrain config setrefuses it),dream.claim_conflicts.max_pairs(default 500; the rest isdeferredand the run ispartial),runClaimConflicts(engine, {sourceIds, dryRun})andclaimConflictsCyclePhase(skippedwithmode_offwhen off). Proposals carryp_supersede1,model_resolvednull and aclaim_conflicts:<uuid>sweep id.src/core/facts/contested-claims.ts—withDecideContested: recall'scontested{proposal_refdp<id>, role, fact_id} for a delivered fact in a pending decide proposal whose other fact the caller can read (world-only when remote, private provenance, the trust floor, active); one batched read, and a failed read setsfacts_degraded: {reason: 'contested_unavailable'}instead of failing the recall. The CLI prints(contested by #<id>).src/commands/decide/claims-sweep.ts—gbrain decide sweep --claims [--source <id>] [--dry-run] [--json]: no slot,--sinceor key; an unknown or archived source refusesunknown_sourcewith nothing written; exits 1 only on afailedrun.