Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Cosine re-score after fusion: blend each row's normalized RRF score with
* the raw cosine between the query and its chunk embedding.
*
* Text-space cosines are computed in SQL (LHF wave 2 item 3,
* `cosineByChunkIdsStatement` in engine-sql/chunks.ts): shipping about a
* hundred full embeddings to JavaScript was nearly all of the `fuse` stage.
* The statement keeps the JavaScript rules: a row is hydrated when its chunk
* is visible and has an embedding in the column; a hydrated vector with other
* dimensions or zero norm scores 0; an unhydrated row blends with cosine 0;
* and when nothing hydrates the rows come back untouched. If the statement
* fails, this search falls back to hydrating the vectors and computing in
* JavaScript (logged once per process with the SQLSTATE, and reported to the
* caller through `onFallback`). The image space ('both' mode) stays in
* JavaScript.
*/
import type { BrainEngine } from '../engine.ts';
import type { SearchResult } from '../types.ts';
import { cosineByChunkIdsStatement } from '../engine-sql/chunks.ts';
import { warnOncePerProcess } from '../utils.ts';
const DEBUG = process.env.GBRAIN_SEARCH_DEBUG === '1';
/** Text-space cosines by chunk id, computed by the database; absent ids did not hydrate. */
async function sqlCosines(engine: BrainEngine, ids: number[], column: string, query: Float32Array): Promise<Map<number, number>> {
const { text, params } = cosineByChunkIdsStatement(ids, column, query);
const rows = await engine.executeRaw<{ id: number; cosine: number }>(text, params);
return new Map(rows.map(row => [Number(row.id), Number(row.cosine)]));
}
/** Text-space cosines by chunk id through the JavaScript path (hydrate, then `cosineSimilarity`). */
async function jsCosines(engine: BrainEngine, ids: number[], column: string, query: Float32Array): Promise<Map<number, number>> {
const embeddings = await engine.getEmbeddingsByChunkIds(ids, column);
return new Map([...embeddings].map(([id, embedding]) => [id, cosineSimilarity(query, embedding)]));
}
export async function cosineReScore(
engine: BrainEngine,
results: SearchResult[],
queryEmbedding: Float32Array,
column: string = 'embedding',
imageSpace?: { queryEmbedding: Float32Array; column: string },
attribute = false,
onFallback?: () => void,
): Promise<SearchResult[]> {
return startCosineReScore(engine, results, queryEmbedding, column, imageSpace, onFallback)(results, attribute);
}
/**
* GBRA-156: start the cosine reads for `candidates` now and re-score later. Fusion only merges its input lists, so
* the fused rows' chunks are among the candidates' and hybrid search starts these reads beside the reads that run
* before fusion instead of a round trip after them. Only the re-scored rows' own cosines count, so the result is the
* one `cosineReScore` returns for those rows.
*/
export function startCosineReScore(
engine: BrainEngine,
candidates: SearchResult[],
queryEmbedding: Float32Array,
column: string = 'embedding',
imageSpace?: { queryEmbedding: Float32Array; column: string },
onFallback?: () => void,
): (results: SearchResult[], attribute?: boolean) => Promise<SearchResult[]> {
// 'both' mode: image-arm rows live in the image space (image column,
// multimodal query vector); everything else in the text space.
const inImageSpace = (r: SearchResult): boolean => imageSpace !== undefined && r.modality === 'image';
const idsFor = (rows: SearchResult[], image: boolean) => rows
.filter(r => inImageSpace(r) === image)
.map(r => r.chunk_id)
.filter((id): id is number => id != null);
const reads = (async (): Promise<{ cosines: Map<number, number>; imageCosines: Map<number, number> } | null> => {
const chunkIds = idsFor(candidates, false);
const imageChunkIds = idsFor(candidates, true);
let cosines = new Map<number, number>();
let imageCosines = new Map<number, number>();
try {
// v0.36 (D9): score in the active column so rescore happens in the
// same embedding space the HNSW just ranked in.
if (chunkIds.length > 0) {
try {
cosines = await sqlCosines(engine, chunkIds, column, queryEmbedding);
} catch (err) {
const sqlstate = (err as { code?: unknown } | null)?.code;
warnOncePerProcess('cosine-rescore-sql-fallback',
`[gbrain] cosine re-score in SQL failed (SQLSTATE ${typeof sqlstate === 'string' ? sqlstate : 'unknown'}); computing it in JavaScript for this process's failing searches.`);
onFallback?.();
cosines = await jsCosines(engine, chunkIds, column, queryEmbedding);
}
}
if (imageSpace && imageChunkIds.length > 0) {
imageCosines = await jsCosines(engine, imageChunkIds, imageSpace.column, imageSpace.queryEmbedding);
}
} catch {
// DB error is non-fatal: the rows come back without re-scoring
return null;
}
return { cosines, imageCosines };
})();
return async (results, attribute = false) => {
const chunkIds = idsFor(results, false);
const imageChunkIds = idsFor(results, true);
if (chunkIds.length === 0 && imageChunkIds.length === 0) return results;
const read = await reads;
if (!read) return results;
const own = (all: Map<number, number>, ids: number[]) => new Map(ids.filter(id => all.has(id)).map(id => [id, all.get(id)!]));
const cosines = own(read.cosines, chunkIds);
const imageCosines = own(read.imageCosines, imageChunkIds);
if (cosines.size === 0 && imageCosines.size === 0) return results;
// Normalize RRF scores to 0-1 for blending
const maxRrf = Math.max(...results.map(r => r.score));
return results.map(r => {
// #3695: a row with no hydrated chunk embedding (the synthetic chunkless
// row for an embed_skip'd oversized page, or a chunk whose embedding did
// not hydrate) goes through the same blend with cosine 0, so it never
// keeps its raw post-RRF score next to rows on the blended [0, 1] scale.
const cosine = r.chunk_id != null ? ((inImageSpace(r) ? imageCosines : cosines).get(r.chunk_id) ?? 0) : 0;
const normRrf = maxRrf > 0 ? r.score / maxRrf : 0;
const blended = 0.7 * normRrf + 0.3 * cosine;
if (DEBUG) {
console.error(`[search-debug] ${r.slug}:${r.chunk_id} cosine=${cosine.toFixed(4)} norm_rrf=${normRrf.toFixed(4)} blended=${blended.toFixed(4)}`);
}
// v0.46.15: stamp the raw cosine — evidence + --explain read it.
return { ...r, score: blended, cosine, ...(attribute ? { blend_norm_rrf: normRrf } : {}) };
}).sort((a, b) => b.score - a.score);
};
}
export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
// Vectors from different embedding spaces are incomparable: a length
// mismatch used to yield a truncated dot product or NaN.
if (a.length !== b.length) return 0;
let dot = 0, magA = 0, magB = 0;
for (let i = 0; i < a.length; i++) {
dot += a[i] * b[i];
magA += a[i] * a[i];
magB += b[i] * b[i];
}
const denom = Math.sqrt(magA) * Math.sqrt(magB);
return denom === 0 ? 0 : dot / denom;
}