feat: fixed-alpha weighted-RRF on the warm search path

[EtanHey]

Summary

• add deterministic two-leg weighted RRF for warm brain_search traffic only
• keep the fixed default vector alpha at 0.25 and add call-time BRAINLAYER_RRF_ALPHA override with finite validation/clamping
• remove trigram retrieval, candidate union, fusion score, and agent-profile trigram weighting from the warm path while preserving legacy trigram behavior for other consumers
• thread warm fusion through regular and entity/KG MCP search paths
• mark FTS fallback payloads with degraded: true while preserving search_mode and fallback_reason
• include fusion mode and effective alpha in the hybrid cache key

Stack

This PR is stacked on #584 (feat/boost-confound-optin). Merge #584 first, then retarget/rebase this PR to main before deleting the base branch.

Test plan

• TDD red: 10 targeted tests failed before implementation
• targeted warm RRF/fallback tests: 10 passed
• hybrid/KG/trigram/consumer regression set: 140 passed
• Ruff check + format: clean
• full permitted local suite: 3492 passed, 9 skipped, 61 deselected, 1 xfailed
• local CodeRabbit review: 0 findings across 5 relevant files
• pre-push Python 3.12 unit gate: 3454 passed, 9 skipped, 61 deselected, 1 xfailed
• MCP registration: 3 passed
• isolated eval/hook routing: 40 passed
• Bun regression: 1 passed
• FTS5 determinism shell regression: passed

---

Note

Medium Risk
Changes ranking for all warm MCP search traffic and removes trigram recall on that path; mis-tuned BRAINLAYER_RRF_ALPHA could skew vector vs lexical balance, though legacy paths are unchanged.

Overview
Introduces a warm interactive search path for MCP brain_search (standard hybrid and entity KG hybrid) by passing warm_rrf=True into hybrid_search.

When warm_rrf is on, fusion is vector + FTS only: trigram FTS retrieval, candidate union, and trigram scoring are skipped; RRF uses a shared _weighted_rrf_score helper with default vector weight 0.25, overridable via BRAINLAYER_RRF_ALPHA (validated and clamped to [0, 1]). Non-warm callers keep the legacy trigram leg and prior fusion behavior.

Hybrid cache keys now include warm_rrf and the effective alpha so warm vs legacy results do not collide.

When embedding fails or times out and search runs as FTS fallback, structured responses add degraded: true alongside existing search_mode and fallback_reason (empty, compact, and full result shapes).

^{Reviewed by Cursor Bugbot for commit d11c9f2. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add fixed-alpha weighted RRF fusion to hybrid_search warm search path

• Adds a warm_rrf flag to SearchMixin.hybrid_search in search_repo.py that switches scoring to a two-leg (semantic + FTS) weighted RRF, dropping the trigram leg entirely.
• The vector leg weight (alpha) is read from the BRAINLAYER_RRF_ALPHA environment variable at runtime, clamped to [0.0, 1.0], with a fallback to the existing RRF_VECTOR_ALPHA constant.
• The search handler in search_handler.py now passes warm_rrf=True into all hybrid_search calls and into the KG hybrid search dispatcher.
• When FTS fallback occurs (vector timeout or error), the structured response now includes degraded: True alongside fallback_reason.
• Behavioral Change: cache keys for hybrid search now include warm_rrf and the effective alpha value, so existing warm-path cache entries will miss after this change.

^{Macroscope summarized d11c9f2.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 561ecdc7-8582-43b1-abca-f3210da27c79

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/weighted-rrf-warm

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_902cc7f1-2f04-4ae0-9875-86ac38db6998)

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[EtanHey]

@cursor @BugBot review

[EtanHey]

@codex review

[cursor]

You need to increase your spend limit or enable usage-based billing to run background agents. Go to Cursor

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d11c9f2575

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Route smart brain_search calls through warm RRF

Adding warm_rrf=True here only covers the generic _search path. For brain_search queries that match the smart-route signals, such as “previously …” or “history of …”, _brain_search_dispatch returns _think/_recall before reaching this call, and those engine paths still call store.hybrid_search without warm_rrf, so a subset of warm MCP brain_search traffic keeps the legacy trigram/three-leg fusion instead of the new fixed-alpha two-leg behavior.

Useful? React with 👍 / 👎.

[EtanHey]

Fixed in recovery PR #588. Engine think/recall now accept and forward warm_rrf, and the smart MCP dispatch enables it for both routes; route-level tests assert the flag.