Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Use-attributed feedback stage: multiply each result's ordering score by
* m = 1 + λ·2·(w − 0.5), with w the page's learned feedback weight (0.5 when
* never rated), so m stays within [1 − λ, 1 + λ] and a brain without ratings
* ranks exactly as before.
*
* It runs on the score that actually orders the list: the reranker's score on
* the reranked head when the reranker ran (a boost before the cross-encoder
* would be erased), the fused score otherwise. Raw `score` and `rerank_score`
* are never modified, so autocut and evidence grading read the same values as
* without feedback. The same read stamps each page's current content_hash for
* answer recording. Fail-open: any error leaves the list untouched.
*/
import type { BrainEngine } from '../engine.ts';
import type { SearchResult } from '../types.ts';
import { effectiveInfluence, loadFeedbackSettings } from '../feedback/settings.ts';
import { NEUTRAL_WEIGHT } from '../feedback/store.ts';
export interface FeedbackStageMeta {
applied: boolean;
boosted: number;
errored: boolean;
}
let stageErrors = 0;
/** Fail-open errors of the stage in this process (shown by `gbrain feedback status`). */
export function feedbackStageErrors(): number {
return stageErrors;
}
export function feedbackMultiplier(weight: number, influence: number): number {
return 1 + influence * 2 * (weight - NEUTRAL_WEIGHT);
}
async function readPageFeedback(
engine: BrainEngine,
pageIds: number[],
): Promise<Map<number, { content_hash: string | null; weight: number }>> {
const rows = await engine.executeRaw<{ id: number | string; content_hash: string | null; weight: number | string | null }>(
`SELECT p.id, p.content_hash,
CASE WHEN w.weight IS NULL THEN NULL
WHEN p.content_hash IS DISTINCT FROM w.content_hash
THEN ${NEUTRAL_WEIGHT} + (w.weight - ${NEUTRAL_WEIGHT}) / 2
ELSE w.weight END AS weight
FROM pages p
LEFT JOIN retrieval_weights w
ON w.source_id = p.source_id AND w.element_kind = 'page' AND w.element_key = p.slug
WHERE p.id = ANY($1::int[])`,
[pageIds],
);
const out = new Map<number, { content_hash: string | null; weight: number }>();
for (const r of rows) {
out.set(Number(r.id), { content_hash: r.content_hash, weight: r.weight == null ? NEUTRAL_WEIGHT : Number(r.weight) });
}
return out;
}
/**
* Apply the stage in place and return the (possibly re-sorted) list.
* `reranked` says whether the reranker reordered this list.
*/
export async function applyFeedbackStage(
engine: BrainEngine,
results: SearchResult[],
opts: { reranked: boolean; onMeta?: (m: FeedbackStageMeta) => void },
): Promise<SearchResult[]> {
if (results.length === 0) return results;
let meta: FeedbackStageMeta = { applied: false, boosted: 0, errored: false };
try {
const settings = await loadFeedbackSettings(engine);
if (!settings.enabled) return results;
const pageIds = [...new Set(results.map(r => r.page_id).filter(id => Number.isFinite(id)))];
const byPage = await readPageFeedback(engine, pageIds);
for (const r of results) {
const row = byPage.get(r.page_id);
if (row) r.content_hash = row.content_hash;
}
const influence = effectiveInfluence(settings);
if (influence <= 0) return results;
const scoreOf = (r: SearchResult): number | undefined =>
opts.reranked ? r.rerank_score : r.score;
let boosted = 0;
const keyed = results.map((r, index) => {
const base = scoreOf(r);
const weight = byPage.get(r.page_id)?.weight ?? NEUTRAL_WEIGHT;
if (base === undefined || !Number.isFinite(base) || weight === NEUTRAL_WEIGHT) {
return { r, index, key: base, scored: base !== undefined && Number.isFinite(base) };
}
const m = feedbackMultiplier(weight, influence);
r.feedback_boost = Math.round(m * 10_000) / 10_000;
boosted++;
return { r, index, key: base >= 0 ? base * m : base / m, scored: true };
});
meta = { applied: true, boosted, errored: false };
if (boosted === 0) return results;
const scored = keyed.filter(k => k.scored);
const unscored = keyed.filter(k => !k.scored);
scored.sort((a, b) => (b.key! - a.key!) || (a.index - b.index));
return [...scored, ...unscored].map(k => k.r);
} catch {
stageErrors++;
meta = { applied: false, boosted: 0, errored: true };
return results;
} finally {
opts.onMeta?.(meta);
}
}