fix(recall): normalize graph keyword scores into the 0-1 component range

[jack-arturo]

Fixes #190.

Problem

_graph_keyword_search returned the raw Cypher additive score — +2 per keyword contained in content, +1 per keyword in any tag, summed over all extracted keywords, plus a +2/+1 whole-phrase bonus — so a K-keyword query can score up to 3K+3 while every other channel (vector cosine, metadata, trending importance) lives in 0–1.

Observed during the 2026-06-11 production forensics: a tag-scoped exact-content match returned keyword=11.0, final_score=4.03. Consequences:

• SEARCH_WEIGHT_KEYWORD (0.35) × 11 = 3.85 — a keyword hit trumps any vector/metadata/importance combination, scaling with query length rather than match quality.
• Defeats RECALL_RELEVANCE_GATE semantics (PR fix(recall): gate query-independent scoring on topical evidence within tag scope (#130) #186): evidence = max(vector, keyword, metadata, exact) assumes 0–1 components; evidence = 11 sails past any gate.

Fix

1. Producer: normalize the raw score by its per-query maximum (3·len(keywords) + 3 when a phrase is present; 3 in the phrase-only branch) before it leaves _graph_keyword_search. This is a monotone per-query transform — within-channel ordering (and the Cypher ORDER BY) is unchanged; only cross-channel blending changes, which is the point.
2. Consumer: defensively clamp the keyword component to min(1.0, …) in _compute_metadata_score, so no future producer can break the 0–1 contract or the gate again.

Verification

• 4 new tests in tests/test_keyword_score_normalization.py (TDD'd against the bug, including the literal keyword=11.0 repro). Full suite: 503 passed.
• Production-corpus lab A/B (10,142-memory snapshot, 200 queries, vs the pooled 3-run parity baseline from the 2026-06-11 release sweep):
  • Recall@5 −0.2pp, Recall@10 −0.7pp, MRR −0.008, NDCG@10 −0.007 (all within baseline run-to-run variance; paired t-test p=0.32)
  • Per-query: 196/197 unchanged, 0 improved, 1 regressed
  • The single flip is the intended behavior change made visible: the expected memory held rank 1 only via the inflated keyword score (ranks 2–5 identical before/after). It's in the fallback-typed Memory cohort (MRR 0.15 baseline — the known data-quality cohort from feat(enrichment): expose classification fallback-rate metrics in /enrichment/status #188's classification incident).

Notes

• This lands on main independently of the feat(recall): make recency decay window and curve configurable #182–feat(recall): date-aware ranking + latest-fact selection (#158, #159) #187 chain; fix(recall): gate query-independent scoring on topical evidence within tag scope (#130) #186's gate evidence check is the main beneficiary once the chain rebases over it.
• Trending (importance), metadata (capped), and vector (cosine) channels were verified already bounded; the graph keyword channel was the only unbounded producer.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes an imbalance in the recall score blending by normalizing the graph keyword-search score component into the same 0–1 range used by other scoring channels, and adds a defensive clamp to prevent future producers from violating that contract. This directly addresses #190 and restores the intended semantics of blended scoring (and downstream gating that assumes bounded components).

Changes:

• Normalize _graph_keyword_search raw Cypher additive scores by a per-query maximum so emitted match_score stays in [0, 1].
• Clamp the keyword component in _compute_metadata_score to at most 1.0 for match_type in {"keyword", "trending"}.
• Add regression tests covering max-score normalization, the production repro (raw=11), the phrase-only path, and consumer-side clamping.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
automem/search/runtime_recall_helpers.py	Normalizes graph keyword raw scores to [0,1] before formatting results.
automem/utils/scoring.py	Clamps keyword component to <= 1.0 to preserve the 0–1 component contract defensively.
tests/test_keyword_score_normalization.py	Adds regression tests for normalization and the consumer clamp, including the keyword=11.0 repro.