Share Recall

Issue #1047/#1052: a signal distinguishing "relevant results found" from "likely nothing relevant" (so an agent can stop probing / go external instead of trusting a weak hit), WITHOUT changing ranking.

level is driven by absolute semantic match strength, made robust to embedding-model scale via prominence (#1052):

• top_score — the RAW semantic cosine of the best hit (absolute match strength in [0, 1]). High ⇒ something closely matches the query.
• prominence — (top_score - mean_background_cosine) / mean_background_cosine over the candidate pool. A ratio, so it is invariant to the overall cosine scale a given embedding model produces (text-embedding-3-small and qwen3-embedding sit at different absolute cosines, but a real match is proportionally far above its background in both). level thresholds on this; a near-duplicate top_score floors level to at least moderate.

How an agent should use it (it is a TRIAGE hint, not a correctness verdict):

• none / low → likely nothing relevant; prefer an external source over forcing an answer out of these results. This is the high-value signal and is reliable without a reranker.
• high / moderate → relevant memory is likely present; READ the returned summaries and judge from their content. level measures topical match strength, so a closely-related "near-miss" (an adjacent topic) can also read high — it does NOT guarantee the exact fact you asked for is stored. The returned content is the source of truth; level only says whether it is worth reading. Distinguishing near-miss from an exact match needs a cross-encoder (pass use_rerank=true); plain bi-encoder cosine cannot.

Why this supersedes the original #1047 z-score approach: that bucketed on relative_margin (background std-devs), but max-normalization in the hybrid merge erases absolute strength, and dividing by a flat off-topic tail's tiny std inflated the margin — so irrelevant queries scored high (benchmarked). relative_margin is retained for transparency but is NO LONGER the basis for level; note it reads high even for off-topic queries.

prominence / relative_margin are None for keyword-only searches (no semantic cosines) and single-candidate pools; there level falls back to the original z-score separation heuristic.

#2144: what the recall LLM selector did to this page.

applied: true carries model, kept / dropped (results left and removed) and dropped_memory_ids (at most 20, page order); applied: false carries only reason and the page is the unselected one. Serialized without the unset keys.