clawmem 0.21.0 → 0.23.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` | +0.3 composite boost. 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 vector routes). 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 automatically to all search results.
+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. **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.
 
 ```
 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**.
-- **`query` tool (v0.13.0+):** non-recency queries use **0.70·search + 0.15·recency + 0.15·confidence**. `search`/`vsearch`/`memory_retrieve`/context-surfacing keep the 0.50/0.25/0.25 default.
+- `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.)
 - **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`** (+0.3 boost, persistent surfacing) — 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 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_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,8 +542,8 @@ 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. |
-| `vsearch` | Vector semantic search — for conceptual/fuzzy matching when exact keywords are unknown. 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. Composite scoring + co-activation boost + compact mode. **v0.23.0: the keyword relevance signal is real** — the exposed FTS score is a monotonic BM25 transform (a clamp bug flattened it to a constant 1.0 through v0.22.0, making ranking metadata-only). 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 |
 | `multi_get` | Retrieve multiple docs by glob or comma-separated list |
@@ -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 for +0.3 composite boost. 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`/`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_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:** Pinned documents get +0.3 additive boost (capped at 1.0). 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 vector routes (v0.22.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.
 
@@ -791,7 +791,7 @@ Notes referenced by the agent during a session get boosted (`access_count++`). U
 | `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server URL. Without it, falls to `node-llama-cpp` (if allowed). |
 | `CLAWMEM_RERANK_API_KEY` | (none) | Bearer token for an authenticated remote reranker endpoint. Independent of the embed and LLM keys. |
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Block `node-llama-cpp` from auto-downloading GGUF models. Set `true` for remote-only setups where you want fail-fast on unreachable endpoints. |
-| `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS` | `false` | **v0.21.0.** When `true`, the MCP direct tools (`search`, `vsearch`, `memory_retrieve`) score non-recency queries with the retrieval-tuned `query`-tool weights. Ships off — the eval evidence covered only the hybrid `query` pipeline. YAML equivalent: `retrieval.mcp_direct_tuned_weights` (env wins). |
+| `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS` | (superseded) | **No effect since v0.22.0** — the direct-pipeline eval this knob was gated on measured tuned weights at 1/19 hit@1; the direct vector routes rank by raw cosine instead. Still parsed for backward compatibility; setting it logs a once-per-process warning. |
 | `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | **v0.7.1.** Phase 2 consolidation merge-safety threshold when candidate and existing anchors align. Merges above this normalized 3-gram cosine score are allowed. |
 | `CLAWMEM_MERGE_SCORE_STRICT` | `0.98` | **v0.7.1.** Strictest merge-safety threshold — fallback when anchor sets are ambiguous. |
 | `CLAWMEM_MERGE_GUARD_DRY_RUN` | `false` | **v0.7.1.** When `true`, Phase 2 merge-safety rejections are logged but not enforced — use for calibration before enabling the gate. |

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` | +0.3 composite boost. 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 vector routes). 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 automatically to all search results.
+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. **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.
 
 ```
 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** (capped at 1.0).
-- **`query` tool (v0.13.0+):** non-recency queries use retrieval-tuned **0.70·search + 0.15·recency + 0.15·confidence**. `search`/`vsearch`/`memory_retrieve`/`context-surfacing` keep the 0.50/0.25/0.25 default.
+- **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.)
 - **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`** (+0.3 boost, persistent surfacing) — 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 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_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/architecture.md

@@ -56,7 +56,7 @@ Each indexed file becomes a document with:
 | `content_type` | Auto-detected: decision, deductive, preference, note, handoff, conversation, progress, research, hub, antipattern, project, milestone, problem |
 | `quality_score` | 0.0-1.0 based on length, structure, headings, lists, decision keywords, frontmatter |
 | `confidence` | Starts at 0.5, adjusted by contradiction detection and feedback |
-| `pinned` | Manual boost flag (+0.3 composite score) |
+| `pinned` | Lifecycle retention + priority among relevance-equivalent results (+0.3 on composite surfaces; exact-tie precedence on the raw vector routes) |
 | `snoozed_until` | Temporarily hidden from context surfacing |
 
 ## Fragments

package/docs/concepts/composite-scoring.md

@@ -1,6 +1,6 @@
 # Composite Scoring
 
-Every search result in ClawMem is scored using a composite formula that blends multiple signals beyond raw search relevance.
+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.
 
 ## 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`, `vsearch`, `memory_retrieve`, and the context-surfacing hook **keep the Normal column by default**. Since v0.21.0 a config knob — `retrieval.mcp_direct_tuned_weights: true` (or env `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS=true`) — switches the three MCP direct tools' non-recency scoring to the `query`-tool column; it ships **off** because the eval evidence covered only the hybrid `query` pipeline, and the flip is gated on a direct-pipeline eval (see [configuration](../reference/configuration.md)).
+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.
 
 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.** MCP tools (`query`, `search`, `vsearch`) pass a co-activation function into `applyCompositeScoring()`, so the boost is part of the composite score used for ranking and `minScore` 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`, `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.
 
 ## Additional modifiers
 
 ### Pin boost
 
-Pinned documents receive +0.3 additive boost (capped at 1.0 total).
+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.
 
 ### Length normalization
 

package/docs/guides/upgrading.md

@@ -1,6 +1,6 @@
 # Upgrading ClawMem
 
-Guide for upgrading between released versions. Current: **v0.21.0**.
+Guide for upgrading between released versions. Current: **v0.23.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,31 @@ docker compose up -d reranker                      # /v1/rerank on :8090
 
 ---
 
+## 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.
+
+**Behavior change — MCP `vsearch` and `memory_retrieve` semantic/discovery rank non-recency queries by RAW cosine.** Reported scores on those routes are raw cosine (`scoreBasis: "vector-cosine"`), not composite values — expect a different numeric scale (unrelated results sit near ~0.4–0.55 on compressed-band embedding models, not near 0). `vsearch`'s `minScore` filters that raw scale and no longer defaults to 0.3 — omitted means no filter. If a workflow passed `minScore` tuned to composite values, re-tune it to your embedding model's band or omit it. Recency-phrased queries ("latest…", "recently…") behave exactly as before on every route.
+
+**Pinned documents** no longer float above more relevant results on those two routes — pin now means lifecycle retention plus winning exact-score ties. Hooks, `query`, and `search` keep the +0.3 composite pin boost.
+
+**`retrieval.mcp_direct_tuned_weights` / `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS` no longer has any effect** (superseded by its own gating eval). Configs that set it keep working; a once-per-process warning is logged — remove the key at your convenience.
+
+---
+
 ## v0.21.0: MCP internal-collection exclusion + embedding-geometry canary
 
 No migration command required. Two things to know:
@@ -71,7 +96,7 @@ No migration command required. Two things to know:
 
 **The canary baseline seeds itself.** The first `clawmem embed` run after upgrade (including a timer-fired one) probes the embedding server with a pair-separation battery and persists a first-healthy baseline; subsequent runs alert relative to it, and a broken-geometry server now aborts `embed --force` BEFORE anything is cleared. `--force-geometry` (proceed despite a failed probe; the vault is flagged tainted until a verified rebuild) and `--force --recalibrate-canary` (replace the baseline after a deliberate model/server change) are operator overrides, not upgrade steps.
 
-**Opt-in knob:** `retrieval.mcp_direct_tuned_weights` (config) / `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS` (env), default `false` — scores the MCP direct tools' non-recency queries with the retrieval-tuned `query`-tool weights. Leave it off unless you have direct-pipeline eval evidence for your vault.
+**Opt-in knob:** `retrieval.mcp_direct_tuned_weights` (config) / `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS` (env), default `false` — scored the MCP direct tools' non-recency queries with the retrieval-tuned `query`-tool weights. *(Superseded in v0.22.0 — the knob no longer has any effect; see the v0.22.0 section above.)*
 
 Upgrades from v0.13 → v0.20 shipped no steps beyond the [quick path](#quick-path) — schema changes auto-apply; see [RELEASE_NOTES.md](../../RELEASE_NOTES.md) for what each version changed.
 

package/docs/internals/query-pipeline.md

@@ -79,6 +79,8 @@ 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).
+
 ## 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 using composite scoring (relevance, recency, confidence, quality, co-activation)
+- **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
 - **Tracks** decisions, handoffs, and session history across conversations
 - **Traverses** causal and semantic graphs to answer "why" and "what led to" questions
 

package/docs/reference/configuration.md

@@ -38,7 +38,7 @@ Full provider matrix and behavior: [../guides/cloud-embedding.md](../guides/clou
 |---|---|---|
 | `CLAWMEM_PROFILE` | `balanced` | `speed` / `balanced` / `deep`. Sets the kept-score ratio (65% / 55% / 45%), vector timeout, max results, and the `factsTokens` sub-budget. Only `deep` adds query expansion + reranking to the hook path. `speed` makes hooks BM25-only (sub-500ms). |
 | `CLAWMEM_NUDGE_INTERVAL` | `15` | Prompts between lifecycle tool use before a `<vault-nudge>` is injected. `0` to disable. |
-| `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS` | `false` | When `true`, the MCP direct tools (`search`, `vsearch`, `memory_retrieve`) score non-recency queries with the retrieval-tuned `query`-tool weights (search 0.70) instead of the Normal weights. Ships **off**: the eval evidence covered only the hybrid `query` pipeline; flipping the default is gated on a direct-pipeline eval. YAML equivalent in `config.yaml`: `retrieval.mcp_direct_tuned_weights: true` (env wins). |
+| `CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS` | (superseded) | **No effect since v0.22.0.** The direct-pipeline eval this knob was gated on measured tuned weights at 1/19 hit@1; the direct vector routes now rank by raw cosine instead (see [mcp-tools](mcp-tools.md) → Scoring regimes). Still parsed for backward compatibility — setting it (env or `retrieval.mcp_direct_tuned_weights` in `config.yaml`) logs a once-per-process warning. |
 
 The context-surfacing hook `timeout` is **not** an env var — it lives in `~/.claude/settings.json` (8s default). See [../troubleshooting.md](../troubleshooting.md) → *Tuning the context-surfacing hook timeout*.
 

package/docs/reference/mcp-tools.md

@@ -6,6 +6,10 @@ 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.
+
+**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.
 
 ### memory_retrieve
@@ -47,25 +51,29 @@ 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. Ranking is composite (see the score-provenance note above); the underlying keyword relevance signal is the monotonic BM25 transform introduced in v0.23.0.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
 | `query` | string | required | Search query |
 | `limit` | number | 10 | Max results |
+| `minScore` | number | 0 | Composite-score floor (values shifted in v0.23.0 — the searchScore input is now a real relevance signal, not a constant) |
 | `compact` | boolean | true | Compact output |
 | `collection` | string | — | Filter by collection |
 | `includeInternal` | boolean | false | Include system-internal `_clawmem` docs |
 | `vault` | string | — | Named vault |
 
+Score fields: compact results report the rounded **composite** score; non-compact results carry both `score` (raw BM25 transform) and `compositeScore`.
+
 ### vsearch
 
-Vector only. Semantic similarity.
+Vector only. Semantic similarity. Non-recency queries rank by RAW cosine (`scoreBasis: "vector-cosine"`, v0.22.0); recency-intent queries use the composite regime.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
 | `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 |
 | `collection` | string | — | Filter by collection |
 | `includeInternal` | boolean | false | Include system-internal `_clawmem` docs |
@@ -178,7 +186,7 @@ Recent session history with handoffs and file changes.
 
 ### memory_pin
 
-Pin a memory for permanent prioritization (+0.3 composite boost).
+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.
 
 | Param | Type | Default | Description |
 |-------|------|---------|-------------|
@@ -208,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.21.0",
+  "version": "0.23.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, 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 = 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/config.ts

@@ -54,11 +54,11 @@ export interface LifecyclePolicy {
 
 export interface RetrievalConfig {
   /**
-   * Option-B knob (VSEARCH-TRUST-HARDENING (a)): when true, the MCP direct tools
-   * (search / vsearch / memory_retrieve) score non-recency queries with the
-   * retrieval-tuned QUERY_WEIGHTS instead of DEFAULT_WEIGHTS. Default FALSE —
-   * the flip is gated on a direct-pipeline eval (the n=199 evidence covered only
-   * the hybrid `query` pipeline).
+   * SUPERSEDED as of v0.22.0 and no longer consumed anywhere: the direct-pipeline
+   * eval this knob was gated on measured tuned weights at 1/19 hit@1 (BACKLOG
+   * Source 48), and the direct vector routes now rank by raw similarity instead
+   * (VSEARCH-RAW-PRIMARY-DESIGN.md). Still parsed so existing configs don't break;
+   * setting it warns once per process.
    */
   mcp_direct_tuned_weights: boolean;
 }
@@ -126,6 +126,8 @@ export function getActiveProfile(): ProfileConfig {
 // ---------------------------------------------------------------------------
 
 let _cachedConfig: ClawMemConfig | null = null;
+// Once-per-process compatibility warning for the superseded tuned-weights knob (v0.22.0).
+let _warnedTunedWeightsKnob = false;
 
 /**
  * Load vault configuration from env vars and config file.
@@ -186,13 +188,18 @@ export function loadVaultConfig(): ClawMemConfig {
     };
   }
 
-  // 4. Retrieval knobs (optional). Env override for tests / staged rollout.
+  // 4. Retrieval knobs (optional). Parsed for backward compatibility only —
+  // mcp_direct_tuned_weights is superseded as of v0.22.0 and has no effect.
   let retrieval: RetrievalConfig | undefined;
   const envTuned = process.env.CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS;
-  const yamlTuned = parsedYaml?.retrieval && typeof parsedYaml.retrieval === "object"
-    ? parsedYaml.retrieval.mcp_direct_tuned_weights === true
-    : false;
+  const yamlHasTuned = !!(parsedYaml?.retrieval && typeof parsedYaml.retrieval === "object"
+    && parsedYaml.retrieval.mcp_direct_tuned_weights !== undefined);
+  const yamlTuned = yamlHasTuned ? parsedYaml.retrieval.mcp_direct_tuned_weights === true : false;
   retrieval = { mcp_direct_tuned_weights: envTuned !== undefined ? envTuned === "true" : yamlTuned };
+  if ((envTuned !== undefined || yamlHasTuned) && !_warnedTunedWeightsKnob) {
+    _warnedTunedWeightsKnob = true;
+    console.warn("[clawmem] retrieval.mcp_direct_tuned_weights / CLAWMEM_MCP_DIRECT_TUNED_WEIGHTS is superseded as of v0.22.0 and has no effect — the direct vector routes rank by raw similarity.");
+  }
 
   _cachedConfig = { vaults, lifecycle, retrieval };
   return _cachedConfig;

package/src/mcp.ts

@@ -33,7 +33,8 @@ import {
   type EnrichedResult,
   type CoActivationFn,
 } from "./memory.ts";
-import { enrichResults, reciprocalRankFusion, toRanked, blendRerank, type RankedResult } from "./search-utils.ts";
+import { enrichResults, reciprocalRankFusion, toRanked, blendRerank, hasStrongFtsSignal, attachRrfScores, type RankedResult } from "./search-utils.ts";
+import { selectScoringRegime, rankRawPrimary, VECTOR_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";
@@ -140,12 +141,6 @@ function degradedGuidanceText(legs: DegradedLeg[]): string {
     : "Note: vector results truncated at the scan cap.";
 }
 
-// Option-B weights knob (design (a)): default-off; flips search/vsearch/memory_retrieve
-// non-recency scoring to the retrieval-tuned weights only when explicitly enabled.
-function mcpDirectWeightsOption(): { weights: typeof QUERY_WEIGHTS } | undefined {
-  return loadVaultConfig().retrieval?.mcp_direct_tuned_weights ? { weights: QUERY_WEIGHTS } : undefined;
-}
-
 function classifyRetrievalMode(query: string): "keyword" | "semantic" | "causal" | "timeline" | "discovery" | "complex" | "hybrid" {
   const q = query.toLowerCase();
 
@@ -335,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 {
@@ -388,7 +379,7 @@ This is the recommended entry point for ALL memory queries.`,
         }
 
         const enriched = enrichResults(store, fused, query);
-        const scored = applyCompositeScoring(enriched, query, undefined, mcpDirectWeightsOption()).slice(0, lim);
+        const scored = applyCompositeScoring(enriched, query).slice(0, lim);
         const items = scored.map(r => ({
           docid: `#${r.docid}`, path: r.displayPath, title: r.title,
           score: Math.round(r.compositeScore * 100) / 100,
@@ -426,7 +417,7 @@ This is the recommended entry point for ALL memory queries.`,
         const seen = new Set<string>();
         const deduped = allResults.filter(r => { if (seen.has(r.filepath)) return false; seen.add(r.filepath); return true; });
         const enriched = enrichResults(store, deduped, query);
-        const scored = applyCompositeScoring(enriched, query, undefined, mcpDirectWeightsOption()).slice(0, lim);
+        const scored = applyCompositeScoring(enriched, query).slice(0, lim);
         const items = scored.map(r => ({
           docid: `#${r.docid}`, path: r.displayPath, title: r.title,
           score: Math.round(r.compositeScore * 100) / 100,
@@ -442,12 +433,16 @@ This is the recommended entry point for ALL memory queries.`,
       // --- Keyword / Semantic / Discovery / Hybrid modes ---
       let results: SearchResult[] = [];
       let singleLegDegraded: DegradedLeg | undefined;
+      // semantic/discovery: the raw regime applies ONLY to results the vector leg actually
+      // served — the FTS fallback's scores are not cosine, so it keeps composite scoring.
+      let vectorLegServed = false;
       if (effectiveMode === "keyword") {
         results = store.searchFTS(query, lim, undefined, undefined, undefined, excl);
       } else if (effectiveMode === "semantic" || effectiveMode === "discovery") {
         try {
           const det = await store.searchVecDetailed(query, DEFAULT_EMBED_MODEL, lim, { excludeCollections: excl });
           results = det.results;
+          vectorLegServed = true;
           if (det.degraded && det.degradedReason) singleLegDegraded = { leg: `${effectiveMode}:vector`, reason: det.degradedReason };
         } catch (e) { rethrowIfFatalVectorError(e); results = store.searchFTS(query, lim, undefined, undefined, undefined, excl); }
       } else {
@@ -461,18 +456,24 @@ 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;
         }
       }
 
       const enriched = enrichResults(store, results, query);
-      const scored = applyCompositeScoring(enriched, query, undefined, mcpDirectWeightsOption()).slice(0, lim);
+      // v0.22.0 two-regime scoring (VSEARCH-RAW-PRIMARY-DESIGN.md R1/R4): vector-served
+      // semantic/discovery results on non-recency queries rank by raw cosine (metadata
+      // breaks exact ties only). Keyword/hybrid modes and the FTS fallback keep composite —
+      // their scores are not cosine, so the raw contract cannot hold there.
+      const rawRegime = vectorLegServed
+        && (effectiveMode === "semantic" || effectiveMode === "discovery")
+        && selectScoringRegime(query) === "raw";
+      const retrieveScoreBasis = rawRegime ? VECTOR_SCORE_BASIS : COMPOSITE_SCORE_BASIS;
+      const scored = rawRegime
+        ? rankRawPrimary(enriched, query).slice(0, lim)
+        : applyCompositeScoring(enriched, query).slice(0, lim);
       const modeDegraded = singleLegDegraded ? { degraded: true as const, degradedReason: singleLegDegraded.reason } : {};
       const modeDegradedNote = singleLegDegraded ? `\n${degradedGuidanceText([singleLegDegraded])}` : "";
       if (compact) {
@@ -483,7 +484,7 @@ This is the recommended entry point for ALL memory queries.`,
         }));
         return {
           content: [{ type: "text", text: `[routed: ${effectiveMode}] ${formatSearchSummary(items.map(i => ({ ...i, file: i.path, compositeScore: i.score, context: null })), query)}${modeDegradedNote}` }],
-          structuredContent: { mode: effectiveMode, results: items, ...modeDegraded },
+          structuredContent: { mode: effectiveMode, results: items, scoreBasis: retrieveScoreBasis, ...modeDegraded },
         };
       }
       const items: SearchResultItem[] = scored.map(r => {
@@ -497,7 +498,7 @@ This is the recommended entry point for ALL memory queries.`,
       });
       return {
         content: [{ type: "text", text: `[routed: ${effectiveMode}] ${formatSearchSummary(items, query)}${modeDegradedNote}` }],
-        structuredContent: { mode: effectiveMode, results: items, ...modeDegraded },
+        structuredContent: { mode: effectiveMode, results: items, scoreBasis: retrieveScoreBasis, ...modeDegraded },
       };
     }
   );
@@ -585,7 +586,7 @@ 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, mcpDirectWeightsOption())
+      const scored = applyCompositeScoring(enriched, query, coFn)
         .filter(r => r.compositeScore >= (minScore || 0));
 
       if (compact) {
@@ -631,7 +632,7 @@ This is the recommended entry point for ALL memory queries.`,
       inputSchema: {
         query: z.string().describe("Natural language query"),
         limit: z.number().optional().default(10),
-        minScore: z.number().optional().default(0.3),
+        minScore: z.number().optional().describe("Score floor. Non-recency queries filter the RAW cosine score (default: no filter; explicit 0 honored; cosine values are embedding-model-specific). Recency-intent queries keep the composite-scale default 0.3."),
         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"),
@@ -656,8 +657,17 @@ 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, mcpDirectWeightsOption())
-        .filter(r => r.compositeScore >= (minScore || 0.3));
+      // v0.22.0 two-regime scoring (VSEARCH-RAW-PRIMARY-DESIGN.md R1–R4): non-recency
+      // queries rank by raw cosine — 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.22.0 composite behavior including its 0.3 default.
+      const regime = selectScoringRegime(query);
+      const vsScoreBasis = regime === "raw" ? VECTOR_SCORE_BASIS : COMPOSITE_SCORE_BASIS;
+      const scored = regime === "raw"
+        ? rankRawPrimary(enriched, query, coFn).filter(r => minScore === undefined || r.compositeScore >= minScore)
+        // Recency branch preserves v0.21 semantics EXACTLY, including `||`: an explicit
+        // minScore of 0 still applies the 0.3 composite floor (R4 unchanged-recency contract).
+        : applyCompositeScoring(enriched, query, coFn).filter(r => r.compositeScore >= (minScore || 0.3));
 
       if (compact) {
         const items = scored.map(r => ({
@@ -666,7 +676,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)}${vsDegradedNote}` }], structuredContent: { results: items, ...vsDegraded } };
+        return { content: [{ type: "text", text: `${formatSearchSummary(items.map(i => ({ ...i, file: i.path, compositeScore: i.score, context: null })), query)}${vsDegradedNote}` }], structuredContent: { results: items, scoreBasis: vsScoreBasis, ...vsDegraded } };
       }
 
       const items: SearchResultItem[] = scored.map(r => {
@@ -685,7 +695,7 @@ This is the recommended entry point for ALL memory queries.`,
 
       return {
         content: [{ type: "text", text: `${formatSearchSummary(items, query)}${vsDegradedNote}` }],
-        structuredContent: { results: items, ...vsDegraded },
+        structuredContent: { results: items, scoreBasis: vsScoreBasis, ...vsDegraded },
       };
     }
   );
@@ -729,12 +739,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 && 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.
@@ -1083,9 +1090,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) {
@@ -1706,11 +1715,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;
@@ -1904,10 +1909,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

@@ -0,0 +1,79 @@
+/**
+ * Centralized scoring-regime selection for the MCP direct vector routes (v0.22.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.
+ *
+ *   "recency-composite" — hasRecencyIntent(query): the pre-v0.22.0 composite behavior,
+ *                         unchanged (RECENCY_WEIGHTS blend, multipliers, pin boost,
+ *                         contentType priority sort, composite-scale minScore default).
+ *
+ * Measured basis (BACKLOG Source 48): raw cosine ranked 16/19 judged targets #1
+ * (MRR 0.912) where the composite stack ranked 1/19 (MRR 0.307) and filtered 14/19
+ * 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.
+ */
+import {
+  applyCompositeScoring,
+  hasRecencyIntent,
+  type EnrichedResult,
+  type ScoredResult,
+  type CoActivationFn,
+  type CompositeScoringOptions,
+} from "./memory.ts";
+
+/** Reported score basis for raw-regime results: raw vector cosine. */
+export const VECTOR_SCORE_BASIS = "vector-cosine" as const;
+/** Reported score basis for composite-scored results. */
+export const COMPOSITE_SCORE_BASIS = "composite" as const;
+
+export type ScoringRegime = "raw" | "recency-composite";
+
+/** One switch point for the raw-route regime decision (design R4). */
+export function selectScoringRegime(query: string): ScoringRegime {
+  return hasRecencyIntent(query) ? "recency-composite" : "raw";
+}
+
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * `options.now` flows to the tie-key composite so frozen-clock evaluation (the v0.22.0
+ * acceptance bundle) is bit-reproducible.
+ */
+export function rankRawPrimary(
+  results: EnrichedResult[],
+  query: string,
+  coActivationFn?: CoActivationFn,
+  options?: CompositeScoringOptions
+): ScoredResult[] {
+  const legacy = applyCompositeScoring(results, query, coActivationFn, options);
+  const legacyByPath = new Map(legacy.map(s => [s.filepath, s]));
+  const ranked = results.map(r => {
+    const l = legacyByPath.get(r.filepath) ?? ({ ...r, compositeScore: r.score, recencyScore: 0 } as ScoredResult);
+    return { row: { ...l, compositeScore: r.score } as ScoredResult, legacyComposite: l.compositeScore };
+  });
+  ranked.sort((a, b) => {
+    if (b.row.compositeScore !== a.row.compositeScore) return b.row.compositeScore - a.row.compositeScore;
+    const pinDelta = (b.row.pinned ? 1 : 0) - (a.row.pinned ? 1 : 0);
+    if (pinDelta !== 0) return pinDelta;
+    if (b.legacyComposite !== a.legacyComposite) return b.legacyComposite - a.legacyComposite;
+    return a.row.displayPath < b.row.displayPath ? -1 : a.row.displayPath > b.row.displayPath ? 1 : 0;
+  });
+  return ranked.map(r => r.row);
+}

package/src/search-utils.ts

@@ -201,3 +201,35 @@ 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;
+}

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,