clawmem 0.22.0 → 0.24.0

package/AGENTS.md

@@ -105,9 +105,9 @@ All other retrieval is handled by Tier 2 hooks. **Do NOT call MCP tools speculat
 | `kg_query` | Entity SPO triples with temporal validity. Entity facts, NOT causal "why". |
 | `session_log` | "last time" / "yesterday" / "what did we do". Do NOT use `query` for cross-session. |
 | `profile` | User profile (static facts + dynamic context). |
-| `memory_pin` | Lifecycle retention + priority among relevance-equivalent results (+0.3 composite boost on composite surfaces; exact-tie precedence on raw vector routes). PROACTIVELY for constraints, architecture decisions, corrections. |
+| `memory_pin` | Lifecycle retention + priority among relevance-equivalent results (+0.3 composite boost on composite surfaces; exact-tie precedence on raw routes — vector + `search` non-recency). PROACTIVELY for constraints, architecture decisions, corrections. |
 | `memory_snooze` | PROACTIVELY when `<vault-context>` surfaces noise — snooze 30 days. |
-| `memory_forget` | Deactivate a memory by closest match. Sparingly — prefer snooze. |
+| `memory_forget` | Deactivate a memory by closest match. Sparingly — prefer snooze. Weak matches return a disambiguation list instead of acting (v0.23.0). |
 | `build_graphs` | Temporal backbone + semantic graph after bulk ingestion. NOT after every reindex. |
 | `timeline` | Temporal neighborhood around a doc. Progressive disclosure: search → timeline → get. |
 | `memory_evolution_status` | How a doc's A-MEM metadata evolved over time. |
@@ -135,14 +135,14 @@ The pipeline autonomously generates lex/vec/hyde variants, fuses BM25 + vector v
 
 ## Composite scoring
 
-Applied on the composite surfaces: hooks, `query`, `search`, and `memory_retrieve`'s keyword/hybrid/causal/complex modes. **v0.22.0: MCP `vsearch` and `memory_retrieve` semantic/discovery rank non-recency queries by RAW cosine instead** (`scoreBasis: "vector-cosine"`; metadata breaks exact ties only; `minScore` filters raw with no default); recency-intent queries keep composite everywhere.
+Applied on the composite surfaces: hooks, `query`, and `memory_retrieve`'s keyword/hybrid/causal/complex modes. **v0.22.0: MCP `vsearch` and `memory_retrieve` semantic/discovery rank non-recency queries by RAW cosine instead** (`scoreBasis: "vector-cosine"`; metadata breaks exact ties only; `minScore` filters raw with no default); recency-intent queries keep composite everywhere. **v0.23.0:** `searchScore` on FTS surfaces is the monotonic `|bm25|/(1+|bm25|)` transform (it was a constant 1.0 through v0.22.0 due to a clamp bug — keyword relevance contributed zero ordering); FTS-transform scores and cosines are independent monotonic signals, not one calibrated scale. **v0.24.0: MCP `search` ranks non-recency queries by the RAW BM25 transform** (`scoreBasis: "fts-bm25"`; metadata breaks exact ties only; `minScore` filters raw with no default) — judged keyword eval: raw MRR 0.848 vs composite 0.415 over 43 targets, composite losing even on the fresh-doc-favorable slice; recency-intent queries keep composite.
 
 ```
 compositeScore = (0.50·searchScore + 0.25·recencyScore + 0.25·confidenceScore) × qualityMultiplier × coActivationBoost
 ```
 
-- `qualityMultiplier = 0.7 + 0.6·qualityScore` (0.7× … 1.3×); `coActivationBoost` up to +15%; length-normalized (floor 30%); frequency boost capped +10%; **pinned docs +0.3 additive on composite surfaces** (raw vector routes: pin = exact-tie precedence only).
-- **`query` tool (v0.13.0+):** non-recency queries use **0.70·search + 0.15·recency + 0.15·confidence**. `search`, `memory_retrieve`'s composite modes, and context-surfacing keep the 0.50/0.25/0.25 default. (`vsearch` + `memory_retrieve` semantic/discovery use RAW cosine for non-recency queries as of v0.22.0 — no composite weights at all.)
+- `qualityMultiplier = 0.7 + 0.6·qualityScore` (0.7× … 1.3×); `coActivationBoost` up to +15%; length-normalized (floor 30%); frequency boost capped +10%; **pinned docs +0.3 additive on composite surfaces** (raw routes — vector + `search` non-recency: pin = exact-tie precedence only).
+- **`query` tool (v0.13.0+):** non-recency queries use **0.70·search + 0.15·recency + 0.15·confidence**. `memory_retrieve`'s composite modes, context-surfacing, and `search`'s recency branch keep the 0.50/0.25/0.25 default. (`vsearch` + `memory_retrieve` semantic/discovery use RAW cosine, and `search` uses the RAW BM25 transform, for non-recency queries — v0.22.0/v0.24.0: no composite weights at all.)
 - **Recency intent** ("latest"/"recent"/"last session") switches all to **0.10·search + 0.70·recency + 0.20·confidence**.
 - **Half-lives:** decision/deductive/preference/hub/antipattern = ∞ · project 120d · research 90d · problem/milestone/note 60d · conversation/progress 45d · handoff 30d (extend up to 3× for frequently-accessed).
 
@@ -162,7 +162,7 @@ compositeScore = (0.50·searchScore + 0.25·recencyScore + 0.25·confidenceScore
 
 ## Memory lifecycle (pin / snooze / forget — manual tools)
 
-- **`memory_pin`** (lifecycle retention + priority among relevance-equivalent results; +0.3 boost on composite surfaces, exact-tie precedence on raw vector routes) — PROACTIVELY when: user says "remember this"/"important"; an architecture/critical decision was just made; a user preference/constraint should persist. Do NOT pin routine/session-specific items.
+- **`memory_pin`** (lifecycle retention + priority among relevance-equivalent results; +0.3 boost on composite surfaces, exact-tie precedence on raw routes) — PROACTIVELY when: user says "remember this"/"important"; an architecture/critical decision was just made; a user preference/constraint should persist. Do NOT pin routine/session-specific items.
 - **`memory_snooze`** — PROACTIVELY when a memory keeps surfacing but isn't relevant now, user says "not now"/"later", or content is time-boxed.
 - **`memory_forget`** — only when genuinely wrong or permanently obsolete. Prefer snooze for temporary suppression.
 - **Contradiction auto-resolution:** when `decision-extractor` detects a new decision contradicting an old one, the old one's confidence is lowered automatically — no manual action needed.

package/README.md

@@ -542,7 +542,7 @@ Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 | Tool | Description |
 |---|---|
 | `memory_retrieve` | **Preferred entry point.** Auto-classifies query and routes to optimal backend (query, intent_search, session_log, find_similar, or query_plan). Use instead of manually choosing a search tool. |
-| `search` | BM25 keyword search — for exact terms, config names, error codes, filenames. Composite scoring + co-activation boost + compact mode. Collection filter supports comma-separated values. Prefer `memory_retrieve` for auto-routing. |
+| `search` | BM25 keyword search — for exact terms, config names, error codes, filenames. **v0.24.0: non-recency queries rank by the RAW BM25 transform** (`scoreBasis: "fts-bm25"`; judged keyword eval MRR 0.848 vs composite 0.415; metadata breaks exact ties only; `minScore` filters raw, no default); recency-intent queries keep composite. Collection filter supports comma-separated values. Prefer `memory_retrieve` for auto-routing. |
 | `vsearch` | Vector semantic search — for conceptual/fuzzy matching when exact keywords are unknown. **v0.22.0: non-recency queries rank by RAW cosine (`scoreBasis: "vector-cosine"`; metadata breaks exact ties only; `minScore` filters raw with no default)**; recency-intent queries keep composite. Collection filter supports comma-separated values. Prefer `memory_retrieve` for auto-routing. |
 | `query` | Full hybrid pipeline (BM25 + vector + rerank) — general-purpose when query type is unclear. WRONG for "why" questions (use `intent_search`) or cross-session queries (use `session_log`). Prefer `memory_retrieve` for auto-routing. Intent hint, strong-signal bypass, chunk dedup, candidateLimit, MMR diversity, compact mode. |
 | `get` | Retrieve single document by path or docid |
@@ -594,8 +594,8 @@ Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 
 | Tool | Description |
 |---|---|
-| `memory_forget` | Search → deactivate closest match (with audit trail) |
-| `memory_pin` | Pin a memory: lifecycle retention + priority among relevance-equivalent results (+0.3 composite boost on hook/`query`/`search` surfaces; exact-tie precedence on the raw vector routes). USE PROACTIVELY when: user states a persistent constraint, makes an architecture decision, or corrects a misconception. Don't wait for curator — pin critical decisions immediately. |
+| `memory_forget` | Search → deactivate closest match (with audit trail). Weak matches return a disambiguation list instead of acting (v0.23.0) |
+| `memory_pin` | Pin a memory: lifecycle retention + priority among relevance-equivalent results (+0.3 composite boost on hook/`query` surfaces; exact-tie precedence on the raw routes — vector + `search` non-recency). USE PROACTIVELY when: user states a persistent constraint, makes an architecture decision, or corrects a misconception. Don't wait for curator — pin critical decisions immediately. |
 | `memory_snooze` | Temporarily hide a memory from context surfacing until a date. USE PROACTIVELY when `<vault-context>` repeatedly surfaces irrelevant content — snooze for 30 days instead of ignoring it. |
 | `status` | Index health with content type distribution |
 | `reindex` | Trigger vault re-scan |
@@ -695,7 +695,7 @@ Content types are inferred from frontmatter or file path patterns. Half-lives ex
 
 **Frequency boost:** Documents with higher revision counts or duplicate counts get a durability signal: `freqSignal = (revisions - 1) × 2 + (duplicates - 1)`, `freqBoost = min(0.10, log1p(freqSignal) × 0.03)`. Revision count (content evolution) is weighted 2× vs duplicate count (ingest repetition). Capped at 10%.
 
-**Pin boost:** Pin = lifecycle retention + priority among relevance-equivalent results. On composite surfaces pinned documents get a +0.3 additive boost (capped at 1.0); on the raw vector routes (v0.22.0) pin breaks exact raw-score ties only. Use `memory_pin` to pin critical memories.
+**Pin boost:** Pin = lifecycle retention + priority among relevance-equivalent results. On composite surfaces pinned documents get a +0.3 additive boost (capped at 1.0); on the raw routes — the vector tools (v0.22.0) and non-recency `search` (v0.24.0) — pin breaks exact raw-score ties only. Use `memory_pin` to pin critical memories.
 
 **Snooze:** Snoozed documents are filtered out of context surfacing until their snooze date. Use `memory_snooze` for temporary suppression.
 

package/SKILL.md

@@ -92,9 +92,9 @@ All other retrieval is handled by Tier 2 hooks. **Do NOT call MCP tools speculat
 | `kg_query` | Entity SPO triples with temporal validity. Entity facts, NOT causal "why" (use `intent_search`). |
 | `session_log` | "last time" / "yesterday" / "what did we do". Do NOT use `query` for cross-session. |
 | `profile` | User profile (static facts + dynamic context). |
-| `memory_pin` | Lifecycle retention + priority among relevance-equivalent results (+0.3 composite boost on composite surfaces; exact-tie precedence on raw vector routes). Use PROACTIVELY for constraints, architecture decisions, corrections. |
+| `memory_pin` | Lifecycle retention + priority among relevance-equivalent results (+0.3 composite boost on composite surfaces; exact-tie precedence on raw routes — vector + `search` non-recency). Use PROACTIVELY for constraints, architecture decisions, corrections. |
 | `memory_snooze` | Use PROACTIVELY when `<vault-context>` surfaces noise — snooze 30 days. |
-| `memory_forget` | Deactivate a memory by closest match. Sparingly — prefer snooze. |
+| `memory_forget` | Deactivate a memory by closest match. Sparingly — prefer snooze. Weak matches return a disambiguation list instead of acting (v0.23.0). |
 | `build_graphs` | Temporal backbone + semantic graph after bulk ingestion. NOT after every reindex. |
 | `timeline` | Temporal neighborhood around a doc. Progressive disclosure: search → timeline → get. |
 | `memory_evolution_status` | How a doc's A-MEM metadata evolved over time. |
@@ -189,7 +189,7 @@ Query -> intent classification (WHY/WHEN/ENTITY/WHAT)
 
 ## Composite scoring (how ranking works)
 
-Applied on the composite surfaces: hooks, `query`, `search`, and `memory_retrieve`'s keyword/hybrid/causal/complex modes. **v0.22.0: MCP `vsearch` and `memory_retrieve` semantic/discovery rank non-recency queries by RAW cosine instead** (`scoreBasis: "vector-cosine"`; metadata breaks exact ties only; `minScore` filters raw with no default); recency-intent queries keep composite everywhere.
+Applied on the composite surfaces: hooks, `query`, and `memory_retrieve`'s keyword/hybrid/causal/complex modes. **v0.22.0: MCP `vsearch` and `memory_retrieve` semantic/discovery rank non-recency queries by RAW cosine instead** (`scoreBasis: "vector-cosine"`; metadata breaks exact ties only; `minScore` filters raw with no default); recency-intent queries keep composite everywhere. **v0.23.0:** `searchScore` on FTS surfaces is the monotonic `|bm25|/(1+|bm25|)` transform (it was a constant 1.0 through v0.22.0 due to a clamp bug — keyword relevance contributed zero ordering); FTS-transform scores and cosines are independent monotonic signals, not one calibrated scale. **v0.24.0: MCP `search` ranks non-recency queries by the RAW BM25 transform** (`scoreBasis: "fts-bm25"`; metadata breaks exact ties only; `minScore` filters raw with no default) — judged keyword eval: raw MRR 0.848 vs composite 0.415 over 43 targets, composite losing even on the fresh-doc-favorable slice; recency-intent queries keep composite.
 
 ```
 compositeScore = (0.50·searchScore + 0.25·recencyScore + 0.25·confidenceScore) × qualityMultiplier × coActivationBoost
@@ -198,8 +198,8 @@ compositeScore = (0.50·searchScore + 0.25·recencyScore + 0.25·confidenceScore
 - `qualityMultiplier = 0.7 + 0.6·qualityScore` (0.7× penalty … 1.3× boost).
 - `coActivationBoost = 1 + min(coCount/10, 0.15)` (docs surfaced together get up to +15%).
 - Length normalization penalizes verbose entries (floor 30%); frequency boost capped at +10%.
-- **Pinned docs: +0.3 additive on composite surfaces** (capped at 1.0); on the raw vector routes pin = exact-tie precedence only.
-- **`query` tool (v0.13.0+):** non-recency queries use retrieval-tuned **0.70·search + 0.15·recency + 0.15·confidence**. `search`, `memory_retrieve`'s composite modes, and `context-surfacing` keep the 0.50/0.25/0.25 default. (`vsearch` + `memory_retrieve` semantic/discovery use RAW cosine for non-recency queries as of v0.22.0 — no composite weights at all.)
+- **Pinned docs: +0.3 additive on composite surfaces** (capped at 1.0); on the raw routes (vector + `search` non-recency) pin = exact-tie precedence only.
+- **`query` tool (v0.13.0+):** non-recency queries use retrieval-tuned **0.70·search + 0.15·recency + 0.15·confidence**. `memory_retrieve`'s composite modes, `context-surfacing`, and `search`'s recency branch keep the 0.50/0.25/0.25 default. (`vsearch` + `memory_retrieve` semantic/discovery use RAW cosine, and `search` uses the RAW BM25 transform, for non-recency queries — v0.22.0/v0.24.0: no composite weights at all.)
 - **Recency intent** ("latest"/"recent"/"last session") switches all to **0.10·search + 0.70·recency + 0.20·confidence**.
 
 **Content-type half-lives:** decision / deductive / preference / hub / antipattern = ∞ (never decay) · project 120d · research 90d · problem / milestone / note 60d · conversation / progress 45d · handoff 30d. Half-lives extend up to 3× for frequently-accessed memories. Attention decay: non-durable types (handoff, progress, conversation, note, project) lose 5% confidence/week without access; decision / deductive / preference / hub / research / antipattern are exempt.
@@ -210,7 +210,7 @@ compositeScore = (0.50·searchScore + 0.25·recencyScore + 0.25·confidenceScore
 
 ## Memory lifecycle (pin / snooze / forget — manual tools)
 
-- **`memory_pin`** (lifecycle retention + priority among relevance-equivalent results; +0.3 boost on composite surfaces, exact-tie precedence on raw vector routes) — PROACTIVELY when: user says "remember this"/"important"; an architecture/critical decision was just made; a user preference/constraint should persist across sessions. Do NOT pin routine/session-specific items.
+- **`memory_pin`** (lifecycle retention + priority among relevance-equivalent results; +0.3 boost on composite surfaces, exact-tie precedence on raw routes) — PROACTIVELY when: user says "remember this"/"important"; an architecture/critical decision was just made; a user preference/constraint should persist across sessions. Do NOT pin routine/session-specific items.
 - **`memory_snooze`** — PROACTIVELY when a memory keeps surfacing but isn't relevant now, user says "not now"/"later", or content is time-boxed.
 - **`memory_forget`** — only when genuinely wrong or permanently obsolete. Prefer snooze for temporary suppression.
 - **Contradiction auto-resolution:** when `decision-extractor` detects a new decision contradicting an old one, the old one's confidence is lowered automatically — no manual action needed.

package/docs/concepts/composite-scoring.md

@@ -1,6 +1,6 @@
 # Composite Scoring
 
-Composite scoring blends multiple signals beyond raw search relevance. **It applies to the hook pipeline (context surfacing), the `query` hybrid pipeline, `search`, and `memory_retrieve`'s keyword/hybrid/causal/complex modes.** Since v0.22.0 the direct vector routes — MCP `vsearch` and `memory_retrieve` semantic/discovery — do NOT use it for non-recency queries: they rank by raw vector cosine, with metadata (including pin) breaking exact score ties only, and report `scoreBasis: "vector-cosine"`. That split is measured, not aesthetic: on a judged set against the live vault, raw cosine ranked 16/19 targets #1 (MRR 0.912) while this composite ranked 1/19 (MRR 0.307) and pushed 14/19 correct answers below the old minScore floor — in the compressed-high similarity band of modern embedding models, every multiplier below is larger than the raw margins separating right answers from wrong ones. Recency-intent queries keep composite (the Recency column) on every route that had it.
+Composite scoring blends multiple signals beyond raw search relevance. **It applies to the hook pipeline (context surfacing), the `query` hybrid pipeline, and `memory_retrieve`'s keyword/hybrid/causal/complex modes.** The direct retrieval routes do NOT use it for non-recency queries: since v0.22.0 MCP `vsearch` and `memory_retrieve` semantic/discovery rank by raw vector cosine (`scoreBasis: "vector-cosine"`), and since v0.24.0 MCP `search` ranks by the raw BM25 transform (`scoreBasis: "fts-bm25"`) — metadata (including pin) breaks exact score ties only on all of them. Both splits are measured, not aesthetic: on judged sets against the live vault, raw cosine ranked 16/19 targets #1 (MRR 0.912) vs composite 1/19 (MRR 0.307, 14/19 pushed below the old minScore floor), and raw-FTS ranked 33/43 keyword targets #1 (MRR 0.848) vs composite 6/43 (MRR 0.415) — composite lost even on the fresh-doc-favorable slice (0.348 vs 0.801), so the multipliers below bury keyword relevance rather than refine it. Recency-intent queries keep composite (the Recency column) on every route that had it.
 
 ## Formula
 
@@ -19,10 +19,12 @@ compositeScore = (w_search * searchScore + w_recency * recencyScore + w_confiden
 
 Recency intent is detected automatically when queries contain "latest", "recent", "last session", etc. — and **takes precedence over the `query`-tool weights**: a recency-phrased `query` call still uses the Recency-intent column.
 
-The **`query` tool** uses retrieval-tuned weights (search 0.70) derived from a held-out judged-relevance eval (v0.13.0) — more weight on topical relevance measurably improves graded NDCG@10 without demoting the newest-correct version of evolving docs. `search`, the composite `memory_retrieve` modes, and the context-surfacing hook **keep the Normal column**. The v0.21.0 `retrieval.mcp_direct_tuned_weights` knob is **superseded as of v0.22.0 and has no effect** — the direct-pipeline eval it was gated on measured tuned weights at 1/19 hit@1, and the direct vector routes moved to raw ordering instead. The key is still parsed (a once-per-process warning is logged if set) so existing configs don't break.
+The **`query` tool** uses retrieval-tuned weights (search 0.70) derived from a held-out judged-relevance eval (v0.13.0) — more weight on topical relevance measurably improves graded NDCG@10 without demoting the newest-correct version of evolving docs. The composite `memory_retrieve` modes, the context-surfacing hook, and `search`'s recency branch **keep the Normal column**. The v0.21.0 `retrieval.mcp_direct_tuned_weights` knob is **superseded as of v0.22.0 and has no effect** — the direct-pipeline eval it was gated on measured tuned weights at 1/19 hit@1, and the direct routes moved to raw ordering instead. The key is still parsed (a once-per-process warning is logged if set) so existing configs don't break.
 
 Threshold note: EOS-anchored last-token embedding models (e.g. zembed-1 served correctly) produce a **compressed-high similarity band** — unrelated pairs sit near ~0.4 rather than ~0.2. Relative ordering is what matters; treat absolute `minScore` cutoffs as model-dependent rather than universal.
 
+`searchScore` provenance (v0.23.0): on FTS/BM25 surfaces the input is the monotonic transform `|bm25|/(1+|bm25|)` of FTS5's negative-is-better `bm25()` (through v0.22.0 a clamp bug flattened it to a constant 1.0, which made composite ranking on those surfaces metadata-only); on vector surfaces it is the raw cosine. The two are independent monotonic signals on an uncalibrated common range — composite blends them where pools mix (hooks, REST hybrid), which removes the old unconditional FTS-over-vector dominance but does not make the channels numerically comparable.
+
 ## Signal breakdown
 
 ### Search score (0.0 - 1.0)
@@ -92,13 +94,13 @@ coActivationBoost = 1 + min(coCount / 10, 0.15)
 
 Documents frequently surfaced together in the same session get up to 15% boost.
 
-**Where co-activation is applied depends on the caller.** The composite MCP surfaces (`query`, `search`, and `vsearch` on recency-intent queries only) pass a co-activation function into `applyCompositeScoring()`, so the boost is part of the composite score used for ranking and — on `vsearch` and `search`, the tools that expose `minScore` — for `minScore` filtering. On `vsearch`'s non-recency (raw) regime, co-activation contributes only to the exact-tie key, never to ranking or filtering. The context-surfacing hook does NOT pass co-activation into composite scoring — instead it applies a separate spreading-activation step *after* adaptive threshold filtering. This means the hook's threshold decisions are based on scores without co-activation, and co-activation only boosts results that already passed the threshold. This is intentional: it prevents relationship boosts from rescuing otherwise-weak results into the surfaced set.
+**Where co-activation is applied depends on the caller.** The composite MCP surfaces (`query`, plus `search` and `vsearch` on recency-intent queries only) pass a co-activation function into `applyCompositeScoring()`, so the boost is part of the composite score used for ranking and — on `vsearch` and `search`, the tools that expose `minScore` — for `minScore` filtering. On the non-recency (raw) regimes of `vsearch` (v0.22.0) and `search` (v0.24.0), co-activation contributes only to the exact-tie key, never to ranking or filtering. The context-surfacing hook does NOT pass co-activation into composite scoring — instead it applies a separate spreading-activation step *after* adaptive threshold filtering. This means the hook's threshold decisions are based on scores without co-activation, and co-activation only boosts results that already passed the threshold. This is intentional: it prevents relationship boosts from rescuing otherwise-weak results into the surfaced set.
 
 ## Additional modifiers
 
 ### Pin boost
 
-On composite surfaces, pinned documents receive a +0.3 additive boost (capped at 1.0 total). Pin's contract is **lifecycle retention + prioritization among relevance-equivalent results** — on the raw vector routes (v0.22.0) it therefore breaks exact raw-score ties only and never lifts a document over a more relevant one.
+On composite surfaces, pinned documents receive a +0.3 additive boost (capped at 1.0 total). Pin's contract is **lifecycle retention + prioritization among relevance-equivalent results** — on the raw routes (the vector tools since v0.22.0, and non-recency `search` since v0.24.0) it therefore breaks exact raw-score ties only and never lifts a document over a more relevant one.
 
 ### Length normalization
 

package/docs/guides/upgrading.md

@@ -1,6 +1,6 @@
 # Upgrading ClawMem
 
-Guide for upgrading between released versions. Current: **v0.22.0**.
+Guide for upgrading between released versions. Current: **v0.24.0**.
 
 ClawMem upgrades are designed to be drop-in: pull the new version, restart any long-lived processes, and the SQLite schema auto-migrates on first open. This guide documents per-version specifics for upgrades that have additional considerations beyond the quick path below.
 
@@ -59,6 +59,29 @@ docker compose up -d reranker                      # /v1/rerank on :8090
 
 ---
 
+## v0.24.0: raw-BM25-primary ranking on `search`
+
+No migration steps — drop-in. Behavior notes:
+
+- **MCP `search` ordering changes for non-recency queries**: results now rank by the raw BM25 transform instead of the composite blend (judged keyword eval: raw MRR 0.848 vs composite 0.415 over 43 targets; the composite lost even the fresh-doc-favorable slice). If you depended on recency/quality multipliers reordering keyword results, phrase the query with recency intent ("recent …", "latest …") — that branch keeps composite — or use `query`.
+- **`minScore` on `search` is now raw-basis with NO default** for non-recency queries: omitted = no filter, explicit `0` honored. Previous composite-scale floors (e.g. `0.3`) do not translate — the raw transform maps `0.70 ⇔ |bm25| ≈ 2.3` and `0.85 ⇔ |bm25| ≈ 5.7`.
+- **`structuredContent.scoreBasis`** on `search` reports `"fts-bm25"` (non-recency) or `"composite"` (recency-intent). Consumers that parsed the compact `score` as a composite value should read the basis field.
+- **CLI `search`, REST, hooks, `query`, and `memory_retrieve` are unchanged** — the ranking-contract change is scoped to the MCP `search` tool, exactly as evaluated.
+- New ops knob: `CLAWMEM_DISABLE_FTS_BYPASS=true` disables the query-pipeline strong-signal bypass at both consumers (MCP + CLI) — harness/incident use.
+
+## v0.23.0: monotonic BM25 exposed score
+
+No migration command, no schema change, no re-embed. Restart long-lived processes per the quick path.
+
+**Behavior change — the exposed FTS score is a real relevance signal.** Through v0.22.0 a clamp bug flattened every FTS result's `score` to the constant 1.0, so ranking on the BM25 surfaces (`search`, REST keyword mode, CLI search, `memory_retrieve` keyword and its semantic-mode FTS fallback, hook FTS lanes) was effectively metadata-only. The score is now `|bm25|/(1+|bm25|)` — bounded [0,1), higher is better. What to expect after upgrading:
+
+- `search` results reorder toward keyword relevance; reported scores drop from the old flat values and vary per hit. If a workflow compared `search` scores against a hardcoded cutoff tuned to the constant-1.0 era, re-tune it (the composite floor semantics of `minScore` are unchanged; the observed values shifted).
+- The `query` pipeline's strong-signal bypass actually fires now on unambiguous keyword queries (skipping LLM expansion, which makes those calls faster) — and no longer fires on a lone weak match.
+- `memory_forget` targeting is stricter: weak keyword matches return a disambiguation list instead of auto-selecting. If a script relied on forget acting on any single match, it must now pass a more specific query or a path.
+- `clawmem doctor`/curator's BM25 probe reports honestly — a near-empty vault may now show a degraded BM25 probe where it previously passed vacuously.
+
+---
+
 ## v0.22.0: raw-cosine ranking on the direct vector routes
 
 No migration command, no schema change, no re-embed. Restart long-lived processes per the quick path.

package/docs/internals/query-pipeline.md

@@ -79,6 +79,10 @@ When the top BM25 hit scores >= 0.85 and the gap to the second hit is >= 0.15, t
 
 The bypass is disabled when `intent` is provided — intent implies the query is ambiguous, so keyword confidence alone is insufficient.
 
+Functional as of v0.23.0: through v0.22.0 a clamp bug flattened every FTS score to a constant 1.0, so with two or more hits the gap was always 0 (the bypass never fired) and with exactly one hit the gap was always 1.0 (it fired even on a garbage match). The scores are now the monotonic `|bm25|/(1+|bm25|)` transform — 0.85 corresponds to |bm25| ≥ 5.67 — and the check itself lives in one shared helper (`hasStrongFtsSignal`) used by both this pipeline and the CLI `query` command. Threshold tuning is deliberately deferred to a judged query-pipeline A/B (BACKLOG 49.3).
+
+Ops escape hatch (v0.24.0): `CLAWMEM_DISABLE_FTS_BYPASS=true` forces the full expansion path on every query at BOTH consumers (the MCP pipeline and the CLI `query`), via the shared `ftsBypassEnabled()` read in `search-utils.ts`. Intended for A/B harnesses and incident triage; `hasStrongFtsSignal` itself stays pure.
+
 ## Query expansion
 
 The LLM generates lex (keyword), vec (semantic), and hyde (hypothetical answer) variants of the query, each carried as a typed `ExpandedQuery`. Variants are **routed by type**: `lex` expansions are searched on BM25 only, `vec` and `hyde` on vector only. The original query is the only leg that fans out to *both* backends. All legs are searched in parallel and fused; the original query's two lists receive 2x weight in RRF, ensuring it anchors the ranking.

package/docs/introduction.md

@@ -6,7 +6,7 @@ ClawMem is an open-source memory engine for Claude Code and AI agents. It runs o
 
 - **Indexes** markdown documents into a local SQLite vault with full-text search (BM25) and vector embeddings
 - **Retrieves** relevant context automatically via hooks or on-demand via MCP tools / REST API
-- **Scores** results per route: raw vector cosine on the direct vector tools (v0.22.0), composite scoring (relevance, recency, confidence, quality, co-activation) on the hook and hybrid pipelines
+- **Scores** results per route: raw vector cosine on the direct vector tools (v0.22.0), the raw BM25 transform on non-recency `search` (v0.24.0), composite scoring (relevance, recency, confidence, quality, co-activation) on the hook and hybrid pipelines
 - **Tracks** decisions, handoffs, and session history across conversations
 - **Traverses** causal and semantic graphs to answer "why" and "what led to" questions
 

package/docs/reference/mcp-tools.md

@@ -6,7 +6,9 @@ Complete reference for ClawMem's MCP server tools. These let AI agents search, r
 
 **Internal-collection visibility (v0.21.0):** the retrieval tools `search`, `vsearch`, `query`, `query_plan`, `memory_retrieve`, and `find_similar` exclude the system-internal `_clawmem` collection (observations/deductions/handoffs) by default. Opt-ins: pass `includeInternal: true` (all six tools), or — on the tools that expose a `collection` parameter (`search`, `vsearch`, `query`) — name `_clawmem` explicitly in the filter. `find_similar` auto-includes internal results when the REFERENCE document is itself internal. `intent_search`, `find_causal_links`, `kg_query`, `session_log`, and `timeline` are NOT filtered — system memory is their substrate by design.
 
-**Scoring regimes (v0.22.0):** the direct vector routes — `vsearch` and `memory_retrieve`'s semantic/discovery modes — rank non-recency queries by RAW vector cosine. Their `structuredContent` carries `scoreBasis: "vector-cosine"`; raw cosine values are specific to the embedding model that produced them and are NOT comparable across models or to composite scores. Document metadata — including pin — participates only inside groups of exactly-equal raw scores. On these routes `minScore` filters the raw score and has NO default (omitted = no filter; an explicit `0` is honored). Recency-intent queries ("latest…", "recently…", "yesterday…") keep the composite regime with its 0.3 default floor and report `scoreBasis: "composite"`, as do `search`, `query`, `query_plan`, and `memory_retrieve`'s keyword/hybrid/causal/complex modes. `find_similar` has always ranked by raw cosine. Rationale: on the measured vault, raw cosine ranked 16/19 judged targets #1 (MRR 0.912) while the composite stack ranked 1/19 and filtered 14/19 out entirely.
+**Scoring regimes (v0.22.0 vector · v0.24.0 FTS):** the direct retrieval routes — `vsearch` and `memory_retrieve`'s semantic/discovery modes (v0.22.0), and `search` (v0.24.0) — rank non-recency queries by their RAW channel score: vector cosine (`scoreBasis: "vector-cosine"`) on the vector routes, the monotonic BM25 transform (`scoreBasis: "fts-bm25"`) on `search`. Raw values are channel-specific and NOT comparable across channels, across embedding models, or to composite scores. Document metadata — including pin — participates only inside groups of exactly-equal raw scores. On these routes `minScore` filters the raw score and has NO default (omitted = no filter; an explicit `0` is honored). Recency-intent queries ("latest…", "recently…", "yesterday…") keep the composite regime and report `scoreBasis: "composite"` — `vsearch`'s recency branch keeps its 0.3 composite default floor, `search`'s keeps 0 — as do `query`, `query_plan`, and `memory_retrieve`'s keyword/hybrid/causal/complex modes. `find_similar` has always ranked by raw cosine. Rationale — both splits are measured, not aesthetic: on judged sets against the live vault, raw cosine ranked 16/19 targets #1 (MRR 0.912) vs composite 1/19 (0.307); raw-FTS ranked 33/43 keyword targets #1 (MRR 0.848) vs composite 6/43 (0.415), with composite losing even on the fresh-doc-favorable slice (0.348 vs 0.801).
+
+**FTS score provenance (v0.23.0):** the raw `score` on BM25/FTS results is the monotonic transform `|bm25|/(1+|bm25|)` of FTS5's negative-is-better `bm25()` value — bounded [0,1), higher is better, stable across queries. (Through v0.22.0 a clamp bug flattened it to a constant 1.0, so composite ranking on FTS surfaces was effectively metadata-only and score-threshold gates never filtered.) FTS-transform scores and vector cosines are **independent monotonic signals, not a calibrated common scale** — compare within a channel, not across channels.
 
 **Degraded vector results (v0.21.0):** under default exclusion the vector scan escalates its depth to fill `limit` with allowed documents, up to a hard cap. When the cap prevents an exhaustive scan and the result is under-filled, `structuredContent` carries `degraded: true` with `degradedReason`: `"excluded-dominant"` (distinct excluded docs account for the shortfall — the guidance line suggests `includeInternal: true` or a refined query) or `"cap-truncation"` (shortfall driven by fragment dedup, neutral guidance). Multi-leg routes (`query`, `query_plan`, `memory_retrieve` complex mode) aggregate `degraded = any(leg)` and list per-leg reasons in `structuredContent.degradedLegs`; single-vector routes (`vsearch`, `find_similar`, `memory_retrieve`'s other modes) report the flat `degraded` + `degradedReason` pair. A small vault whose whole index is scanned without hitting the cap returns a plain short list with NO marker.
 
@@ -38,7 +40,7 @@ Full hybrid pipeline: BM25 + vector + query expansion + cross-encoder reranking.
 |-------|------|---------|-------------|
 | `query` | string | required | Search query |
 | `limit` | number | 10 | Max results |
-| `compact` | boolean | true | Compact output |
+| `compact` | boolean | false | Compact output |
 | `collection` | string | — | Filter by collection (comma-separated for multi) |
 | `intent` | string | — | Domain hint for ambiguous queries (steers expansion, reranking, chunk selection) |
 | `candidateLimit` | number | 30 | Candidates for reranking (tune precision vs speed) |
@@ -49,17 +51,20 @@ BM25 strong-signal bypass: skips expansion when top BM25 hit >= 0.85 with gap >=
 
 ### search
 
-BM25 only. Zero GPU cost.
+BM25 only. Zero GPU cost. Non-recency queries rank by the RAW BM25 transform (`scoreBasis: "fts-bm25"`, v0.24.0 — see the regimes note above); recency-intent queries use the composite regime.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
 | `query` | string | required | Search query |
 | `limit` | number | 10 | Max results |
-| `compact` | boolean | true | Compact output |
+| `minScore` | number | — | Score floor. Non-recency: filters the RAW BM25 transform, NO default (omitted = no filter; explicit `0` honored). Recency-intent: composite floor, default 0 |
+| `compact` | boolean | false | Compact output |
 | `collection` | string | — | Filter by collection |
 | `includeInternal` | boolean | false | Include system-internal `_clawmem` docs |
 | `vault` | string | — | Named vault |
 
+Score fields: on non-recency queries the reported ranking score IS the raw BM25 transform (compact `score` and non-compact `compositeScore` both carry it; non-compact `score` is the same raw value). On recency-intent queries compact `score` / non-compact `compositeScore` are composite while non-compact `score` stays the raw transform.
+
 ### vsearch
 
 Vector only. Semantic similarity. Non-recency queries rank by RAW cosine (`scoreBasis: "vector-cosine"`, v0.22.0); recency-intent queries use the composite regime.
@@ -69,7 +74,7 @@ Vector only. Semantic similarity. Non-recency queries rank by RAW cosine (`score
 | `query` | string | required | Search query |
 | `limit` | number | 10 | Max results |
 | `minScore` | number | — | Raw-cosine floor on non-recency queries (no default — omitted means no filter; explicit `0` honored). Recency-intent queries keep the composite-scale 0.3 default. |
-| `compact` | boolean | true | Compact output |
+| `compact` | boolean | false | Compact output |
 | `collection` | string | — | Filter by collection |
 | `includeInternal` | boolean | false | Include system-internal `_clawmem` docs |
 | `vault` | string | — | Named vault |
@@ -181,7 +186,7 @@ Recent session history with handoffs and file changes.
 
 ### memory_pin
 
-Pin a memory: lifecycle retention plus prioritization among relevance-equivalent results. On composite surfaces (hooks, `query`, `search`) pinned docs get the +0.3 composite boost; on the raw vector routes (v0.22.0) pin wins exact raw-score ties but never overrides a relevance difference.
+Pin a memory: lifecycle retention plus prioritization among relevance-equivalent results. On composite surfaces (hooks, `query`) pinned docs get the +0.3 composite boost; on the raw routes (`vsearch`/`memory_retrieve` semantic-discovery v0.22.0, `search` non-recency v0.24.0) pin wins exact raw-score ties but never overrides a relevance difference.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -211,6 +216,8 @@ Permanently deactivate a memory.
 
 **Search behavior (v0.2.6+, all three tools):** Query matching cascades through four strategies: exact path match → BM25 full-text → title-token overlap → vector similarity. This prevents "No matching memory found" errors when the document exists but BM25 fails to match (e.g., too many AND'd terms). Path-like queries (containing `/` or ending in `.md`) try direct path matching first. `memory_forget` requires higher confidence to act — ambiguous matches return candidates instead of mutating.
 
+**Targeting confidence (v0.23.0):** the confidence gate (`score ≥ 0.7`, or a ≥ 0.2 gap to the runner-up when more than one candidate exists) is now live for BM25 candidates — through v0.22.0 every FTS candidate carried a constant score of 1.0, so `memory_forget` treated ANY keyword match as high-confidence and auto-selected it. Weak matches — including a lone weak match — now return the candidate list for disambiguation instead of acting. Stricter, safer targeting for a destructive operation.
+
 ## Lifecycle
 
 ### lifecycle_status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "On-device memory layer for AI agents. Claude Code, OpenClaw, and Hermes. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/clawmem.ts

@@ -58,7 +58,7 @@ import { formatSearchResults, type OutputFormat } from "./formatter.ts";
 import { indexCollection, parseDocument } from "./indexer.ts";
 import { detectBeadsProject } from "./beads.ts";
 import { applyCompositeScoring, hasRecencyIntent, type EnrichedResult } from "./memory.ts";
-import { enrichResults, reciprocalRankFusion, toRanked, type RankedResult } from "./search-utils.ts";
+import { enrichResults, reciprocalRankFusion, toRanked, hasStrongFtsSignal, ftsBypassEnabled, type RankedResult } from "./search-utils.ts";
 import { splitDocument } from "./splitter.ts";
 import { getProfile, updateProfile, isProfileStale } from "./profile.ts";
 import { regenerateAllDirectoryContexts } from "./directory-context.ts";
@@ -1095,9 +1095,7 @@ async function cmdQuery(args: string[]) {
 
   // Step 1: BM25 for strong signal check
   const ftsResults = s.searchFTS(query, 20);
-  const topScore = ftsResults[0]?.score ?? 0;
-  const secondScore = ftsResults[1]?.score ?? 0;
-  const strongSignal = topScore >= 0.85 && (topScore - secondScore) >= 0.15;
+  const strongSignal = ftsBypassEnabled() && hasStrongFtsSignal(ftsResults);
 
   // Step 2: Query expansion (skip if strong BM25 signal). expandQuery now returns
   // typed ExpandedQuery[] (lex/vec/hyde) — no more brittle string re-parsing, and

package/src/mcp.ts

@@ -33,8 +33,8 @@ import {
   type EnrichedResult,
   type CoActivationFn,
 } from "./memory.ts";
-import { enrichResults, reciprocalRankFusion, toRanked, blendRerank, type RankedResult } from "./search-utils.ts";
-import { selectScoringRegime, rankRawPrimary, VECTOR_SCORE_BASIS, COMPOSITE_SCORE_BASIS } from "./scoring-regime.ts";
+import { enrichResults, reciprocalRankFusion, toRanked, blendRerank, hasStrongFtsSignal, ftsBypassEnabled, attachRrfScores, type RankedResult } from "./search-utils.ts";
+import { selectScoringRegime, rankRawPrimary, VECTOR_SCORE_BASIS, FTS_SCORE_BASIS, COMPOSITE_SCORE_BASIS } from "./scoring-regime.ts";
 import { applyMMRDiversity } from "./mmr.ts";
 import { indexCollection, type IndexStats } from "./indexer.ts";
 import { listCollections } from "./collections.ts";
@@ -330,11 +330,7 @@ This is the recommended entry point for ALL memory queries.`,
         } catch (e) { rethrowIfFatalVectorError(e); /* else: no vectors */ }
         const rrfWeights = intent.intent === 'WHY' ? [1.0, 1.5] : intent.intent === 'WHEN' ? [1.5, 1.0] : [1.0, 1.0];
         const fusedRanked = reciprocalRankFusion([bm25Results.map(toRanked), vecResults.map(toRanked)], rrfWeights);
-        const allSearch = [...bm25Results, ...vecResults];
-        let fused: SearchResult[] = fusedRanked.map(fr => {
-          const orig = allSearch.find(r => r.filepath === fr.file);
-          return orig ? { ...orig, score: fr.score } : null;
-        }).filter((r): r is SearchResult => r !== null);
+        let fused: SearchResult[] = attachRrfScores(fusedRanked, [...bm25Results, ...vecResults]);
 
         if (intent.intent === 'WHY' || intent.intent === 'ENTITY') {
           try {
@@ -460,11 +456,7 @@ This is the recommended entry point for ALL memory queries.`,
         } catch (e) { rethrowIfFatalVectorError(e); /* */ }
         if (vec.length > 0) {
           const fusedRanked = reciprocalRankFusion([bm25.map(toRanked), vec.map(toRanked)], [1.0, 1.0]);
-          const allSearch = [...bm25, ...vec];
-          results = fusedRanked.map(fr => {
-            const orig = allSearch.find(r => r.filepath === fr.file);
-            return orig ? { ...orig, score: fr.score } : null;
-          }).filter((r): r is SearchResult => r !== null);
+          results = attachRrfScores(fusedRanked, [...bm25, ...vec]);
         } else {
           results = bm25;
         }
@@ -566,7 +558,7 @@ This is the recommended entry point for ALL memory queries.`,
   );
 
   // ---------------------------------------------------------------------------
-  // Tool: search (BM25 + composite)
+  // Tool: search (BM25 — raw-transform ranking; composite on recency intent)
   // ---------------------------------------------------------------------------
 
   server.registerTool(
@@ -577,7 +569,7 @@ This is the recommended entry point for ALL memory queries.`,
       inputSchema: {
         query: z.string().describe("Search query"),
         limit: z.number().optional().default(10),
-        minScore: z.number().optional().default(0),
+        minScore: z.number().optional().describe("Score floor. Non-recency queries filter the RAW FTS score, the monotonic |bm25|/(1+|bm25|) transform (default: no filter; explicit 0 honored). Recency-intent queries keep the composite-scale default 0."),
         collection: z.string().optional().describe("Filter to collection (single name or comma-separated)"),
         compact: z.boolean().optional().default(false).describe("Return compact results (id, path, title, score, snippet) instead of full content"),
         includeInternal: z.boolean().optional().default(false).describe("Include system-internal _clawmem docs (observations/deductions) — excluded by default"),
@@ -594,8 +586,16 @@ This is the recommended entry point for ALL memory queries.`,
 
       const coFn = (path: string) => store.getCoActivated(path);
       const enriched = enrichResults(store, results, query);
-      const scored = applyCompositeScoring(enriched, query, coFn)
-        .filter(r => r.compositeScore >= (minScore || 0));
+      // v0.24.0 two-regime scoring (S49-JUDGED-EVAL-DESIGN.md, SWITCH verdict): non-recency
+      // queries rank by the raw FTS transform — metadata (incl. pin) breaks exact score
+      // ties only, and minScore (if given) filters the raw score with NO default floor.
+      // Recency-intent queries keep the pre-v0.24.0 composite behavior including its
+      // default-0 floor.
+      const regime = selectScoringRegime(query);
+      const sScoreBasis = regime === "raw" ? FTS_SCORE_BASIS : COMPOSITE_SCORE_BASIS;
+      const scored = regime === "raw"
+        ? rankRawPrimary(enriched, query, coFn).filter(r => minScore === undefined || r.compositeScore >= minScore)
+        : applyCompositeScoring(enriched, query, coFn).filter(r => r.compositeScore >= (minScore || 0));
 
       if (compact) {
         const items = scored.map(r => ({
@@ -604,7 +604,7 @@ This is the recommended entry point for ALL memory queries.`,
           snippet: (r.body || "").substring(0, 150), content_type: r.contentType, modified_at: r.modifiedAt,
           fragment: r.fragmentType ? { type: r.fragmentType, label: r.fragmentLabel } : undefined,
         }));
-        return { content: [{ type: "text", text: formatSearchSummary(items.map(i => ({ ...i, file: i.path, compositeScore: i.score, context: null })), query) }], structuredContent: { results: items } };
+        return { content: [{ type: "text", text: formatSearchSummary(items.map(i => ({ ...i, file: i.path, compositeScore: i.score, context: null })), query) }], structuredContent: { results: items, scoreBasis: sScoreBasis } };
       }
 
       const filtered: SearchResultItem[] = scored.map(r => {
@@ -623,7 +623,7 @@ This is the recommended entry point for ALL memory queries.`,
 
       return {
         content: [{ type: "text", text: formatSearchSummary(filtered, query) }],
-        structuredContent: { results: filtered },
+        structuredContent: { results: filtered, scoreBasis: sScoreBasis },
       };
     }
   );
@@ -747,12 +747,9 @@ This is the recommended entry point for ALL memory queries.`,
         : undefined;
       const excl = resolveExcludedCollections(includeInternal, collections);
       const initialFts = store.searchFTS(query, 20, undefined, collections, dateRange, excl);
-      const topScore = initialFts.length > 0 ? Math.abs(initialFts[0]!.score) : 0;
-      const secondScore = initialFts.length > 1 ? Math.abs(initialFts[1]!.score) : 0;
       // When intent is provided, disable strong-signal bypass — the obvious BM25
       // match may not be what the caller wants (e.g. "performance" with intent "web page load times")
-      const hasStrongSignal = !intent && initialFts.length > 0
-        && topScore >= 0.85 && (topScore - secondScore) >= 0.15;
+      const hasStrongSignal = !intent && ftsBypassEnabled() && hasStrongFtsSignal(initialFts);
 
       // Step 2: Query expansion (skipped if strong signal). Typed routing —
       // original → BOTH FTS + vector (2× RRF anchor), lex → FTS only, vec/hyde → vector only.
@@ -1101,9 +1098,11 @@ This is the recommended entry point for ALL memory queries.`,
 
     const top = candidates[0]!;
 
-    // Clear winner: high score OR significant gap to #2
+    // Clear winner: high score OR significant gap to #2. The gap clause requires an
+    // actual #2 to gap against — a lone weak candidate must not qualify (destructive
+    // ops would otherwise auto-select a garbage single match).
     const gap = candidates.length > 1 ? top.score - candidates[1]!.score : 1.0;
-    const confident = top.score >= 0.7 || gap >= 0.2;
+    const confident = top.score >= 0.7 || (candidates.length > 1 && gap >= 0.2);
 
     // For destructive ops (forget), require higher confidence
     if (destructive && !confident) {
@@ -1724,11 +1723,7 @@ This is the recommended entry point for ALL memory queries.`,
       const fusedRanked = reciprocalRankFusion([bm25Results.map(toRanked), vecResults.map(toRanked)], rrfWeights);
 
       // Map RRF results back to SearchResult with updated scores
-      const allSearchResults = [...bm25Results, ...vecResults];
-      const fused: SearchResult[] = fusedRanked.map(fr => {
-        const original = allSearchResults.find(r => r.filepath === fr.file);
-        return original ? { ...original, score: fr.score } : null;
-      }).filter((r): r is SearchResult => r !== null);
+      const fused: SearchResult[] = attachRrfScores(fusedRanked, [...bm25Results, ...vecResults]);
 
       // Step 4: Graph expansion (if enabled and intent allows)
       let expanded = fused;
@@ -1922,10 +1917,11 @@ This is the recommended entry point for ALL memory queries.`,
           const vec = detGraph.results;
           if (detGraph.degraded && detGraph.degradedReason) degradedLegs.push({ leg: `clause${clauseIdx}:graph:vector`, reason: detGraph.degradedReason });
           const fused = reciprocalRankFusion([bm25.map(toRanked), vec.map(toRanked)], [1.0, 1.0]);
-          const searchMap = new Map([...bm25, ...vec].map(r => [r.filepath, r]));
-          results = fused
-            .map(fr => searchMap.get(fr.file))
-            .filter((r): r is SearchResult => r !== null);
+          // Carry the RRF-fused score (parity with causal + intent_search): the graph
+          // traversal below anchors on `score`, which must be RRF-scale, not raw single-channel.
+          // vec-first: this site historically preferred the vector variant on duplicate
+          // paths (its pre-helper Map construction let later entries overwrite) — preserved.
+          results = attachRrfScores(fused, [...vec, ...bm25]);
 
           // Graph expansion for WHY/ENTITY
           if (intent.intent === 'WHY' || intent.intent === 'ENTITY') {

package/src/scoring-regime.ts

@@ -1,15 +1,17 @@
 /**
- * Centralized scoring-regime selection for the MCP direct vector routes (v0.22.0).
+ * Centralized scoring-regime selection for the MCP direct retrieval routes
+ * (vector routes v0.22.0; FTS `search` route v0.24.0).
  *
  * Two regimes:
  *
  *   "raw"               — non-recency queries on the evidenced raw routes (`vsearch`,
- *                         `memory_retrieve` semantic/discovery): results rank by RAW
- *                         vector cosine DESC. Document metadata — including pin —
- *                         participates ONLY inside groups of exactly-equal raw scores.
- *                         The reported score IS the raw cosine (scoreBasis
- *                         "vector-cosine"): specific to the embedding model that
- *                         produced it, and not comparable to composite scores.
+ *                         `memory_retrieve` semantic/discovery, `search`): results rank
+ *                         by the RAW channel score DESC — vector cosine on the vector
+ *                         routes (scoreBasis "vector-cosine"), the monotonic BM25
+ *                         transform on the FTS route (scoreBasis "fts-bm25"). Document
+ *                         metadata — including pin — participates ONLY inside groups of
+ *                         exactly-equal raw scores. Raw scores are channel-specific and
+ *                         not comparable to composite scores or across channels.
  *
  *   "recency-composite" — hasRecencyIntent(query): the pre-v0.22.0 composite behavior,
  *                         unchanged (RECENCY_WEIGHTS blend, multipliers, pin boost,
@@ -20,6 +22,10 @@
  * below the old composite minScore — every metadata signal large enough to matter is
  * larger than the 0.03–0.10 raw margins that separate right answers from wrong ones,
  * so metadata may only ever break exact raw-score ties on these routes.
+ * FTS basis (BACKLOG Source 49.2, judged keyword eval 2026-07-11): raw-FTS-primary
+ * MRR 0.848 vs shipped composite 0.415 over 43 judged targets (held-out 0.875 vs
+ * 0.335, composite hit@1 0/20) — composite lost even on the composite-favorable
+ * fresh-among-many shape (0.348 vs 0.801).
  */
 import {
   applyCompositeScoring,
@@ -30,8 +36,11 @@ import {
   type CompositeScoringOptions,
 } from "./memory.ts";
 
-/** Reported score basis for raw-regime results: raw vector cosine. */
+/** Reported score basis for raw-regime results on the vector routes: raw cosine. */
 export const VECTOR_SCORE_BASIS = "vector-cosine" as const;
+/** Reported score basis for raw-regime results on the FTS route (v0.24.0): the
+ *  monotonic |bm25|/(1+|bm25|) transform. */
+export const FTS_SCORE_BASIS = "fts-bm25" as const;
 /** Reported score basis for composite-scored results. */
 export const COMPOSITE_SCORE_BASIS = "composite" as const;
 
@@ -43,15 +52,17 @@ export function selectScoringRegime(query: string): ScoringRegime {
 }
 
 /**
- * Raw-primary ranking (design R1/R2): raw score DESC; within a group of exactly-equal
- * raw scores the deterministic tie order is pinned DESC, then legacy composite DESC,
- * then displayPath ASC. `compositeScore` on the returned rows carries the RAW score —
- * the reported score is the raw cosine.
+ * Raw-primary ranking (design R1/R2): raw channel score DESC; within a group of
+ * exactly-equal raw scores the deterministic tie order is pinned DESC, then legacy
+ * composite DESC, then displayPath ASC. `compositeScore` on the returned rows carries
+ * the RAW score — vector cosine on the vector routes, the monotonic BM25 transform on
+ * the FTS route. Exact transformed-score ties are legitimate relevance-equivalent
+ * groups on both channels.
  *
  * Callers gate on selectScoringRegime() first — this ranker is only meaningful for
  * non-recency queries (the legacy composite computed here for tie keys therefore never
  * takes the RECENCY_WEIGHTS branch). Inputs are document-unique on these routes
- * (searchVecDetailed hydrates one row per document).
+ * (searchVecDetailed and searchFTS both hydrate one row per document).
  *
  * `options.now` flows to the tie-key composite so frozen-clock evaluation (the v0.22.0
  * acceptance bundle) is bit-reproducible.

package/src/search-utils.ts

@@ -201,3 +201,45 @@ export function toRanked(r: SearchResult): RankedResult {
     score: r.score,
   };
 }
+
+/**
+ * Map RRF-fused results back to their originating SearchResults, carrying the FUSED
+ * score. Downstream consumers — graph-traversal anchors, composite enrichment — must
+ * see the fusion's relevance scale, not a raw single-channel score (S49.1 U2: the
+ * query_plan graph clause used to drop the fused score, anchoring traversal on raw
+ * FTS values). First occurrence wins when a doc appears in multiple channels
+ * (matching the previous `find`-based lookups); fused entries with no originating
+ * SearchResult are dropped.
+ */
+export function attachRrfScores(fused: RankedResult[], originals: SearchResult[]): SearchResult[] {
+  const byPath = new Map<string, SearchResult>();
+  for (const r of originals) {
+    if (!byPath.has(r.filepath)) byPath.set(r.filepath, r);
+  }
+  return fused
+    .map(fr => { const orig = byPath.get(fr.file); return orig ? { ...orig, score: fr.score } : null; })
+    .filter((r): r is SearchResult => r !== null);
+}
+
+/**
+ * BM25 strong-signal check on ftsScoreFromBm25-scale results: the top hit is strong
+ * (≥ 0.85 ⇔ |bm25| ≥ 5.67) AND clearly separated from #2 (gap ≥ 0.15; a missing #2
+ * counts as 0, so a lone WEAK hit does not qualify). Callers use this to skip LLM
+ * query expansion when the keyword answer is unambiguous.
+ */
+export function hasStrongFtsSignal(results: SearchResult[]): boolean {
+  if (results.length === 0) return false;
+  const top = results[0]!.score;
+  const second = results.length > 1 ? results[1]!.score : 0;
+  return top >= 0.85 && (top - second) >= 0.15;
+}
+
+/**
+ * Ops escape hatch for the BM25 strong-signal bypass: CLAWMEM_DISABLE_FTS_BYPASS=true
+ * forces the full expansion path on every query (both the MCP `query` pipeline and the
+ * CLI `query` consume this). Read at call time so A/B harnesses and tests can toggle
+ * per invocation; `hasStrongFtsSignal` itself stays pure.
+ */
+export function ftsBypassEnabled(): boolean {
+  return process.env.CLAWMEM_DISABLE_FTS_BYPASS !== "true";
+}

package/src/server.ts

@@ -12,7 +12,7 @@
 
 import type { Server } from "bun";
 import type { Store, SearchResult, TimelineResult } from "./store.ts";
-import { enrichResults, reciprocalRankFusion, toRanked } from "./search-utils.ts";
+import { enrichResults, reciprocalRankFusion, toRanked, attachRrfScores } from "./search-utils.ts";
 import { applyCompositeScoring, hasRecencyIntent, type EnrichedResult } from "./memory.ts";
 import { applyMMRDiversity } from "./mmr.ts";
 import { listCollections } from "./collections.ts";
@@ -617,11 +617,7 @@ async function handleRetrieve(req: Request, _url: URL, store: Store): Promise<Re
     } catch (e) { rethrowIfFatalVectorError(e); /* vector unavailable */ }
     const weights = intent.intent === "WHEN" ? [1.5, 1.0] : [1.0, 1.5];
     const fused = reciprocalRankFusion([bm25.map(toRanked), vec.map(toRanked)], weights);
-    const allResults = [...bm25, ...vec];
-    results = fused.map(fr => {
-      const orig = allResults.find(r => r.filepath === fr.file);
-      return orig ? { ...orig, score: fr.score } : null;
-    }).filter((r): r is SearchResult => r !== null);
+    results = attachRrfScores(fused, [...bm25, ...vec]);
   } else if (mode === "keyword") {
     results = store.searchFTS(query, limit * 2, undefined, collections);
   } else if (mode === "semantic") {

package/src/store.ts

@@ -3506,6 +3506,20 @@ function buildFTS5Query(query: string): string | null {
   return terms.map(t => `"${t}"*`).join(' AND ');
 }
 
+/**
+ * Convert an FTS5 bm25() value into a stable [0,1) relevance score where higher is better.
+ *
+ * FTS5's bm25() is negative-is-better: it returns -1 × the BM25 score, so it is ≤ 0 for
+ * every match. The transform is per-row and monotonic in match strength (|bm25|/(1+|bm25|))
+ * with no per-query normalization, so cross-query comparisons, minScore filters, and the
+ * strong-signal bypass all stay meaningful. A hypothetical positive input clamps to 0
+ * rather than inverting the ordering.
+ */
+export function ftsScoreFromBm25(bm25Score: number): number {
+  const m = Math.max(0, -bm25Score);
+  return m / (1 + m);
+}
+
 export function searchFTS(db: Database, query: string, limit: number = 20, collectionId?: number, collections?: string[], dateRange?: { start: string; end: string }, excludeCollections?: string[]): SearchResult[] {
   const ftsQuery = buildFTS5Query(query);
   if (!ftsQuery) return [];
@@ -3558,9 +3572,7 @@ export function searchFTS(db: Database, query: string, limit: number = 20, colle
   const rows = db.prepare(sql).all(...params) as { filepath: string; display_path: string; title: string; body: string; hash: string; modified_at: string; bm25_score: number }[];
   return rows.map(row => {
     const collectionName = row.filepath.split('//')[1]?.split('/')[0] || "";
-    // Convert bm25 (lower is better) into a stable (0..1] score where higher is better.
-    // Avoid per-query normalization so "strong signal" heuristics can work.
-    const score = 1 / (1 + Math.max(0, row.bm25_score));
+    const score = ftsScoreFromBm25(row.bm25_score);
     return {
       filepath: row.filepath,
       displayPath: row.display_path,
@@ -4172,14 +4184,24 @@ export type ExpandedQuery = {
 const EXPAND_CACHE_VERSION = "v3-qmd-terse-typed";
 const EXPAND_PROVIDER_FINGERPRINT = "qmd-terse";
 
-export async function expandQuery(query: string, model: string = DEFAULT_QUERY_MODEL, db: Database, intent?: string): Promise<ExpandedQuery[]> {
-  // Typed-JSON cache. Versioned key (include intent + provider fingerprint).
-  const cacheKey = getCacheKey(`expandQuery:${EXPAND_CACHE_VERSION}`, {
+/**
+ * The EXACT llm_cache key expandQuery(query, model, intent) reads and writes.
+ * Exported for eval harnesses (S49.3 freeze protocol): delete/verify expansion
+ * cache rows without replicating the private key construction — the version and
+ * provider fingerprint stay in one place.
+ */
+export function expandQueryCacheKey(query: string, model: string = DEFAULT_QUERY_MODEL, intent?: string): string {
+  return getCacheKey(`expandQuery:${EXPAND_CACHE_VERSION}`, {
     query,
     model,
     provider: EXPAND_PROVIDER_FINGERPRINT,
     ...(intent && { intent }),
   });
+}
+
+export async function expandQuery(query: string, model: string = DEFAULT_QUERY_MODEL, db: Database, intent?: string): Promise<ExpandedQuery[]> {
+  // Typed-JSON cache. Versioned key (include intent + provider fingerprint).
+  const cacheKey = expandQueryCacheKey(query, model, intent);
   const cached = getCachedResult(db, cacheKey);
   if (cached) {
     try {