clawmem 0.12.0 → 0.14.0

package/AGENTS.md

@@ -200,6 +200,45 @@ systemctl --user status clawmem-watcher.service clawmem-embed.timer
 
 **Note:** The service files use `%h` (home directory specifier). If clawmem is installed elsewhere, update `ExecStart` paths. For remote GPU setups, add `Environment=CLAWMEM_EMBED_URL=http://host:8088` etc. to both service files (the `bin/clawmem` wrapper sets defaults).
 
+### Reranker health check (optional, recommended for remote-sidecar setups)
+
+`clawmem rerank-health` probes the reranker for **discrimination** (not just liveness) and exits non-zero when it is degenerate — catching the failure mode where a mis-converted reranker (e.g. the deprecated zerank-2 GGUF, whose llama.cpp conversion drops the score head) returns HTTP 200 + valid JSON but near-zero, non-discriminating scores, silently collapsing the final ranking to RRF. The same probe runs inside `clawmem doctor` (section 9); this scheduled unit alerts proactively without query traffic. Schedule it when the reranker is a remote sidecar that could be redeployed/reverted out from under you.
+
+```bash
+# clawmem-rerank-health.service — oneshot probe; exits 1 if the reranker is degenerate
+cat > ~/.config/systemd/user/clawmem-rerank-health.service << 'EOF'
+[Unit]
+Description=ClawMem reranker discrimination health check
+
+[Service]
+Type=oneshot
+# Hard outer bound — a hung reranker must not hang the check (the probe also times out per-request).
+TimeoutStartSec=120
+ExecStart=%h/clawmem/bin/clawmem rerank-health
+# Alert on failure: point this at your notifier unit (ntfy, mail, etc.).
+OnFailure=clawmem-rerank-health-alert@%n.service
+EOF
+
+# clawmem-rerank-health.timer — every 6h (the failure it guards is rare + infra-driven)
+cat > ~/.config/systemd/user/clawmem-rerank-health.timer << 'EOF'
+[Unit]
+Description=ClawMem reranker health check (every 6h)
+
+[Timer]
+OnCalendar=*-*-* 00/6:00:00
+Persistent=true
+RandomizedDelaySec=300
+
+[Install]
+WantedBy=timers.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now clawmem-rerank-health.timer
+```
+
+For remote GPU setups, add `Environment=CLAWMEM_RERANK_URL=http://host:8090` (+ embed/LLM) to the `.service`. `OnFailure=` is the primary alert path; the `curator-nudge` SessionStart hook is a secondary "you missed the page" surface. Run `clawmem rerank-health` (or `--json`) manually any time to check on demand.
+
 ---
 
 ## OpenClaw Integration: Memory System Configuration
@@ -461,6 +500,8 @@ Recency intent detected ("latest", "recent", "last session"):
 compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenceScore) × qualityMultiplier × coActivationBoost
 ```
 
+**`query` tool (v0.13.0+):** for non-recency queries the `query` tool uses retrieval-tuned weights `0.70 × searchScore + 0.15 × recencyScore + 0.15 × confidenceScore` (from a held-out judged eval). Recency intent still switches to the `0.10 / 0.70 / 0.20` weights above. `search`, `vsearch`, `memory_retrieve`, and the context-surfacing hook keep the `0.50 / 0.25 / 0.25` default.
+
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
 | decision, deductive, preference, hub | ∞ | Never decay |

package/CLAUDE.md

@@ -200,6 +200,45 @@ systemctl --user status clawmem-watcher.service clawmem-embed.timer
 
 **Note:** The service files use `%h` (home directory specifier). If clawmem is installed elsewhere, update `ExecStart` paths. For remote GPU setups, add `Environment=CLAWMEM_EMBED_URL=http://host:8088` etc. to both service files (the `bin/clawmem` wrapper sets defaults).
 
+### Reranker health check (optional, recommended for remote-sidecar setups)
+
+`clawmem rerank-health` probes the reranker for **discrimination** (not just liveness) and exits non-zero when it is degenerate — catching the failure mode where a mis-converted reranker (e.g. the deprecated zerank-2 GGUF, whose llama.cpp conversion drops the score head) returns HTTP 200 + valid JSON but near-zero, non-discriminating scores, silently collapsing the final ranking to RRF. The same probe runs inside `clawmem doctor` (section 9); this scheduled unit alerts proactively without query traffic. Schedule it when the reranker is a remote sidecar that could be redeployed/reverted out from under you.
+
+```bash
+# clawmem-rerank-health.service — oneshot probe; exits 1 if the reranker is degenerate
+cat > ~/.config/systemd/user/clawmem-rerank-health.service << 'EOF'
+[Unit]
+Description=ClawMem reranker discrimination health check
+
+[Service]
+Type=oneshot
+# Hard outer bound — a hung reranker must not hang the check (the probe also times out per-request).
+TimeoutStartSec=120
+ExecStart=%h/clawmem/bin/clawmem rerank-health
+# Alert on failure: point this at your notifier unit (ntfy, mail, etc.).
+OnFailure=clawmem-rerank-health-alert@%n.service
+EOF
+
+# clawmem-rerank-health.timer — every 6h (the failure it guards is rare + infra-driven)
+cat > ~/.config/systemd/user/clawmem-rerank-health.timer << 'EOF'
+[Unit]
+Description=ClawMem reranker health check (every 6h)
+
+[Timer]
+OnCalendar=*-*-* 00/6:00:00
+Persistent=true
+RandomizedDelaySec=300
+
+[Install]
+WantedBy=timers.target
+EOF
+
+systemctl --user daemon-reload
+systemctl --user enable --now clawmem-rerank-health.timer
+```
+
+For remote GPU setups, add `Environment=CLAWMEM_RERANK_URL=http://host:8090` (+ embed/LLM) to the `.service`. `OnFailure=` is the primary alert path; the `curator-nudge` SessionStart hook is a secondary "you missed the page" surface. Run `clawmem rerank-health` (or `--json`) manually any time to check on demand.
+
 ---
 
 ## OpenClaw Integration: Memory System Configuration
@@ -461,6 +500,8 @@ Recency intent detected ("latest", "recent", "last session"):
 compositeScore = (0.10 × searchScore + 0.70 × recencyScore + 0.20 × confidenceScore) × qualityMultiplier × coActivationBoost
 ```
 
+**`query` tool (v0.13.0+):** for non-recency queries the `query` tool uses retrieval-tuned weights `0.70 × searchScore + 0.15 × recencyScore + 0.15 × confidenceScore` (from a held-out judged eval). Recency intent still switches to the `0.10 / 0.70 / 0.20` weights above. `search`, `vsearch`, `memory_retrieve`, and the context-surfacing hook keep the `0.50 / 0.25 / 0.25` default.
+
 | Content Type | Half-Life | Effect |
 |--------------|-----------|--------|
 | decision, deductive, preference, hub | ∞ | Never decay |

package/README.md

@@ -814,7 +814,7 @@ User Query + optional intent hint
   → Intent-Aware Chunk Selection (intent terms at 0.5× weight alongside query terms at 1.0×)
   → Cross-Encoder Reranking (4000 char context; intent prepended; chunk dedup; batch cap=4)
   → Rerank/RRF Blend (blendRerank: 0.9·reranker + 0.1·normalized-RRF tiebreaker; reranker can promote over RRF #1; falls back to RRF order if reranker unavailable)
-  → SAME Composite Scoring ((search × 0.5 + recency × 0.25 + confidence × 0.25) × qualityMultiplier × lengthNorm × coActivationBoost + pinBoost)
+  → Composite Scoring (query-tuned: (search × 0.70 + recency × 0.15 + confidence × 0.15) × qualityMultiplier × lengthNorm × coActivationBoost + pinBoost; recency-intent queries → 0.10/0.70/0.20; other tools keep the 0.50/0.25/0.25 default)
   → MMR Diversity Filter (Jaccard bigram similarity > 0.6 → demoted)
   → Ranked Results
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.12.0",
+  "version": "0.14.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

@@ -2157,6 +2157,27 @@ async function cmdDoctor() {
     // openclaw CLI unavailable — skip silently
   }
 
+  // 9. Reranker discrimination (active probe — asserts the reranker DISCRIMINATES, not just
+  //    responds). Liveness is worthless here: the broken zerank-2 GGUF returned HTTP 200 + valid
+  //    JSON + finite positive ~1e-11 scores and passed every other check while silently collapsing
+  //    the final ranking to RRF. This routes a golden hard-pair set through the live reranker
+  //    (cache-bypassed, coverage-enforced) and checks calibration + per-pair discrimination.
+  try {
+    const s = getStore();
+    const { probeRerankHealth } = await import("./health/rerank-health.ts");
+    const health = await probeRerankHealth(s, { timeoutMs: 8000 });
+    if (health.ok) {
+      console.log(`${c.green}✓${c.reset} Reranker: discriminates (coverage ${health.pairsScored}/${health.pairsTotal}, max score ${health.maxScore.toFixed(2)} ≥ ${health.thresholds.calibFloor}, min margin ${health.minMargin.toFixed(2)} ≥ ${health.thresholds.discrimMargin})`);
+    } else {
+      console.log(`${c.red}✗${c.reset} Reranker: degenerate / not discriminating (coverage ${health.pairsScored}/${health.pairsTotal}, max score ${health.maxScore.toExponential(1)}, min margin ${health.minMargin.toFixed(2)})`);
+      for (const f of health.failures.slice(0, 4)) console.log(`   ${c.dim}${f}${c.reset}`);
+      console.log(`   ${c.dim}Likely the deprecated zerank-2 GGUF (no score head) — re-deploy the seq-cls sidecar. See CLAUDE.md "SOTA upgrade".${c.reset}`);
+      issues++;
+    }
+  } catch (err) {
+    console.log(`${c.yellow}!${c.reset} Reranker: could not probe (${(err as Error).message})`);
+  }
+
   console.log();
   if (issues > 0) {
     console.log(`${c.yellow}${issues} issue(s) found.${c.reset}`);
@@ -2165,6 +2186,41 @@ async function cmdDoctor() {
   }
 }
 
+// =============================================================================
+// Reranker health (scheduled-check CLI)
+// =============================================================================
+
+// Oneshot reranker discrimination probe. Exits non-zero on degeneracy so a systemd OnFailure= (or
+// any scheduled check) can alert — the standalone counterpart to doctor section 9. Routes through
+// the live, cache-bypassed, coverage-enforced probe (src/health/rerank-health.ts).
+async function cmdRerankHealth(args: string[]) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      json: { type: "boolean", default: false },
+      "timeout-ms": { type: "string" },
+    },
+    allowPositionals: false,
+  });
+  const timeoutMs = values["timeout-ms"] ? parseInt(values["timeout-ms"] as string, 10) : undefined;
+  const store = getStore();
+  const { probeRerankHealth } = await import("./health/rerank-health.ts");
+  const health = await probeRerankHealth(store, timeoutMs ? { timeoutMs } : {});
+
+  if (values.json) {
+    console.log(JSON.stringify(health));
+  } else if (health.ok) {
+    console.log(`${c.green}✓ Reranker healthy${c.reset} — coverage ${health.pairsScored}/${health.pairsTotal}, max score ${health.maxScore.toFixed(2)} ≥ ${health.thresholds.calibFloor}, min margin ${health.minMargin.toFixed(2)} ≥ ${health.thresholds.discrimMargin}`);
+  } else {
+    console.log(`${c.red}✗ Reranker degenerate / not discriminating${c.reset} — coverage ${health.pairsScored}/${health.pairsTotal}, max score ${health.maxScore.toExponential(1)}, min margin ${health.minMargin.toFixed(2)}`);
+    for (const f of health.failures) console.log(`  - ${f}`);
+    console.log(`Likely the deprecated zerank-2 GGUF (no score head) — re-deploy the seq-cls sidecar. See CLAUDE.md "SOTA upgrade".`);
+  }
+  // Non-zero exit on degeneracy so systemd OnFailure= / a scheduled check can alert. Use exitCode
+  // (not process.exit) so main()'s finally { closeStore() } still runs.
+  process.exitCode = health.ok ? 0 : 1;
+}
+
 // =============================================================================
 // Bootstrap
 // =============================================================================
@@ -2495,6 +2551,9 @@ async function main() {
       case "doctor":
         await cmdDoctor();
         break;
+      case "rerank-health":
+        await cmdRerankHealth(subArgs);
+        break;
       case "path":
         cmdPath();
         break;
@@ -3189,6 +3248,7 @@ ${c.bold}Integration:${c.reset}
   clawmem serve [--port 7438] [--host 127.0.0.1]  Start HTTP REST API server
   clawmem update-context               Regenerate all directory CLAUDE.md files
   clawmem doctor                       Full health check
+  clawmem rerank-health [--json]       Probe reranker discrimination (exit 1 if degenerate)
 
 ${c.bold}Options:${c.reset}
   -n, --num <N>        Number of results

package/src/health/rerank-golden.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "_comment": "Reranker-health golden set. Each triple is (query, relevant, hardNegative) where the hard-negative is the SAME topic as the relevant doc but answers a different sub-question — a near-random reranker (e.g. the deprecated zerank-2 GGUF that scored ~1e-11) cannot consistently rank relevant>hardNegative on these, while a working cross-encoder does. Constraints: same-topic fine-grained negatives (off-topic negatives would pass even on a broken reranker); discriminating signal in the first ~400 chars (store.rerank truncates docs to 400); vault-independent + deterministic. See RERANKER-HEALTH-GUARD-DESIGN.md §4.",
+  "triples": [
+    {
+      "query": "how to fix a memory leak from an unclosed file handle in python",
+      "relevant": "Unclosed file handles leak file descriptors and their buffers. Always open files with a `with open(path) as f:` context manager so the file is closed automatically when the block exits, even on an exception. Forgetting to close files inside a long-running loop is a classic descriptor leak.",
+      "hardNegative": "A common Python memory leak comes from circular references that keep objects alive past their scope. The cyclic garbage collector usually reclaims them, but objects defining `__del__` inside a reference cycle can be left uncollected. Use weakref to break the cycle.",
+      "note": "same topic = python memory leaks; query targets the file-handle cause, negative is the circular-reference cause"
+    },
+    {
+      "query": "what is the difference between git rebase and git merge",
+      "relevant": "git rebase rewrites history by replaying your commits onto a new base, producing a linear history with no merge commit, whereas git merge creates a merge commit that ties two histories together and preserves both. Rebase changes commit hashes, so never rebase shared branches; merge keeps hashes intact.",
+      "hardNegative": "git cherry-pick copies a single commit from one branch and re-applies it onto your current branch as a new commit. It is the tool for porting one specific fix without merging or rebasing the entire source branch.",
+      "note": "same topic = git history operations; query is rebase-vs-merge, negative is cherry-pick"
+    },
+    {
+      "query": "what does the http 429 status code mean",
+      "relevant": "HTTP 429 Too Many Requests means the client has sent too many requests in a given window and is being rate limited. The response commonly carries a Retry-After header telling the client how long to wait before retrying.",
+      "hardNegative": "HTTP 503 Service Unavailable means the server is temporarily unable to handle the request, usually due to overload or maintenance. It is a server-side 5xx error and may also include a Retry-After header.",
+      "note": "same topic = HTTP status codes that carry Retry-After; query is 429 (client rate limit), negative is 503 (server unavailable)"
+    },
+    {
+      "query": "what are the steps of the tcp three-way handshake",
+      "relevant": "The TCP three-way handshake establishes a connection in three steps: the client sends SYN, the server replies SYN-ACK, and the client sends ACK. After that final ACK the connection is established and data can flow.",
+      "hardNegative": "TCP connection teardown uses a four-way exchange: one side sends FIN, the peer ACKs it, then the peer sends its own FIN which is ACKed in return. This closes each direction of the connection independently.",
+      "note": "same topic = TCP connection lifecycle; query is the handshake (setup), negative is teardown"
+    },
+    {
+      "query": "difference between inner join and left join in sql",
+      "relevant": "An INNER JOIN returns only rows that have a match in both tables. A LEFT JOIN returns every row from the left table plus matched rows from the right, filling NULLs where there is no match — so a LEFT JOIN keeps the unmatched left rows that an INNER JOIN drops.",
+      "hardNegative": "A SQL CROSS JOIN returns the Cartesian product of two tables — every row of the first paired with every row of the second — with no join condition. It is rarely intended unless you genuinely want all combinations.",
+      "note": "same topic = SQL join types; query is inner-vs-left, negative is cross join"
+    },
+    {
+      "query": "why would you use a tuple instead of a list in python",
+      "relevant": "Tuples are immutable, so they can be used as dictionary keys or set members and are safe to share without defensive copying. Their immutability also signals that the collection is not meant to change, and they are slightly more memory-efficient than lists.",
+      "hardNegative": "A list comprehension builds a new list from an iterable in a single expression, like [x*x for x in range(10)]. It is usually more readable and faster than an equivalent for-loop that repeatedly appends to a list.",
+      "note": "same topic = python sequences; query is tuple-vs-list (immutability), negative is list comprehension"
+    },
+    {
+      "query": "is the http put method idempotent",
+      "relevant": "Yes, HTTP PUT is idempotent: sending the same PUT request multiple times has the same effect as sending it once, because it replaces the target resource with the supplied representation. A client can safely retry a PUT after a network failure.",
+      "hardNegative": "HTTP POST is not idempotent: each POST typically creates a new resource or triggers a new action, so retrying a POST after a timeout can create duplicates. Use an idempotency key when you need safe retries.",
+      "note": "same topic = HTTP method idempotency; query is PUT (idempotent), negative is POST (not idempotent)"
+    },
+    {
+      "query": "what is the difference between a docker image and a docker container",
+      "relevant": "A Docker image is an immutable, layered template built from a Dockerfile. A container is a running (or stopped) instance of that image with a thin writable layer on top. Many containers can be started from a single image.",
+      "hardNegative": "A Docker volume is a persistent storage mechanism managed by Docker and mounted into a container so data survives container restarts and removals. Volumes are the preferred way to persist database files.",
+      "note": "same topic = docker concepts; query is image-vs-container, negative is volume"
+    }
+  ]
+}

package/src/health/rerank-health.ts

@@ -0,0 +1,150 @@
+/**
+ * Reranker health probe — asserts the reranker DISCRIMINATES, not just that it responds.
+ *
+ * Background: the deployed zerank-2 GGUF was mis-converted (no score head), so it returned
+ * HTTP 200 + valid JSON + finite positive scores (~1e-11) yet ranked near-randomly and silently
+ * collapsed the final ranking to RRF. Liveness checks all passed. This probe instead runs a small
+ * golden set of same-topic (query, relevant, hard-negative) triples through the LIVE reranker
+ * (cache-bypassed) and asserts three things:
+ *
+ *   1. coverage     — the reranker scored every probe doc (store.rerank throws RerankCoverageError
+ *                     otherwise, before its zero-fill would hide an omitted score);
+ *   2. calibration  — the best relevant-doc score lands in a sane band (>= CALIB_FLOOR);
+ *   3. discrimination — EVERY pair clears score(relevant) - score(hardNegative) >= DISCRIM_MARGIN.
+ *
+ * See RERANKER-HEALTH-GUARD-DESIGN.md.
+ */
+import { readFileSync } from "fs";
+import { join } from "path";
+import { DEFAULT_RERANK_MODEL, RerankCoverageError, RerankMalformedResponseError, type Store } from "../store.ts";
+
+// Thresholds — LOCKED from a live zerank-2-seq baseline (2026-06-26, 8-pair golden set):
+//   relevant scores 0.9233-0.9700, hard-neg max 0.3120, min margin 0.6417, 0/8 inverted.
+//   broken zerank-2 GGUF regime: every score <= 8.03e-7 (32-query probe). 5-6 OOM of separation.
+// CALIB_FLOOR is the band that catches the ~0 collapse (kept conservative — the margin does the
+// discrimination, so the band must not false-fail a working-but-lower reranker). DISCRIM_MARGIN is
+// 2.5x below the live min margin (0.64) so healthy never trips, far above the degenerate ~0.
+export const RERANK_CALIB_FLOOR = 0.05; // band: best relevant-doc score across pairs must clear this
+export const RERANK_DISCRIM_MARGIN = 0.25; // per-pair: score(relevant) - score(hardNegative) >= this
+// Default per-probe-request timeout (the production remote fetch is otherwise untimed; a hung
+// reranker must not hang the healthcheck).
+export const RERANK_PROBE_TIMEOUT_MS = 10_000;
+
+export interface GoldenTriple {
+  query: string;
+  relevant: string;
+  hardNegative: string;
+  note?: string;
+}
+
+export interface RerankHealthResult {
+  ok: boolean;
+  coverageOk: boolean;
+  maxScore: number; // best relevant-doc score across pairs (calibration-band input)
+  minMargin: number; // smallest (relevant - hardNegative) margin across pairs
+  pairsTotal: number;
+  pairsScored: number; // pairs where both docs were scored (full coverage)
+  failures: string[]; // human-readable failure reasons (empty iff ok)
+  thresholds: { calibFloor: number; discrimMargin: number };
+}
+
+/** Load the shipped golden set (or an explicit path, for tests). */
+export function loadGoldenSet(path?: string): GoldenTriple[] {
+  const p = path ?? join(import.meta.dir, "rerank-golden.json");
+  const parsed = JSON.parse(readFileSync(p, "utf-8")) as { triples: GoldenTriple[] };
+  return parsed.triples;
+}
+
+/**
+ * Probe the reranker behind `store` for discrimination + calibration. Routes through store.rerank
+ * with { noCache, requireLiveCoverage, timeoutMs } so it exercises the FULL production path
+ * (remote → local fallback, dedup, intent, 400-char truncation) while bypassing the cache and
+ * enforcing live coverage. `store` is structurally typed so tests can pass a fake reranker.
+ */
+export async function probeRerankHealth(
+  store: Pick<Store, "rerank">,
+  opts: {
+    thresholds?: { calibFloor?: number; discrimMargin?: number };
+    timeoutMs?: number;
+    model?: string;
+    triples?: GoldenTriple[];
+  } = {},
+): Promise<RerankHealthResult> {
+  const calibFloor = opts.thresholds?.calibFloor ?? RERANK_CALIB_FLOOR;
+  const discrimMargin = opts.thresholds?.discrimMargin ?? RERANK_DISCRIM_MARGIN;
+  const timeoutMs = opts.timeoutMs ?? RERANK_PROBE_TIMEOUT_MS;
+  const model = opts.model ?? DEFAULT_RERANK_MODEL;
+  const triples = opts.triples ?? loadGoldenSet();
+
+  const failures: string[] = [];
+  let maxScore = 0;
+  let minMargin = Infinity;
+  let pairsScored = 0;
+
+  for (let i = 0; i < triples.length; i++) {
+    const t = triples[i]!;
+    const relFile = `golden-${i}-rel`;
+    const negFile = `golden-${i}-neg`;
+    const docs = [
+      { file: relFile, text: t.relevant },
+      { file: negFile, text: t.hardNegative },
+    ];
+    const label = `pair ${i} ("${t.query.slice(0, 40)}")`;
+
+    let scored: { file: string; score: number }[];
+    try {
+      // intent omitted (4th arg undefined); options force a live, coverage-checked call.
+      scored = await store.rerank(t.query, docs, model, undefined, {
+        noCache: true,
+        requireLiveCoverage: true,
+        timeoutMs,
+      });
+    } catch (err) {
+      if (err instanceof RerankCoverageError) {
+        failures.push(`${label}: coverage — reranker did not score ${err.missing.length} doc(s)`);
+      } else if (err instanceof RerankMalformedResponseError) {
+        failures.push(`${label}: malformed response — ${err.problems.join("; ")}`);
+      } else {
+        failures.push(`${label}: probe error — ${(err as Error).message}`);
+      }
+      continue;
+    }
+
+    const scoreMap = new Map(scored.map((s) => [s.file, s.score]));
+    const relScore = scoreMap.get(relFile);
+    const negScore = scoreMap.get(negFile);
+    if (relScore === undefined || negScore === undefined || !Number.isFinite(relScore) || !Number.isFinite(negScore)) {
+      // requireLiveCoverage should have thrown already; defensive.
+      failures.push(`${label}: missing or non-finite score after rerank`);
+      continue;
+    }
+
+    pairsScored++;
+    maxScore = Math.max(maxScore, relScore);
+    const margin = relScore - negScore;
+    minMargin = Math.min(minMargin, margin);
+    if (margin < discrimMargin) {
+      failures.push(
+        `${label}: margin ${margin.toFixed(3)} < ${discrimMargin} (rel ${relScore.toFixed(3)} vs neg ${negScore.toFixed(3)})`,
+      );
+    }
+  }
+
+  if (maxScore < calibFloor) {
+    failures.push(
+      `calibration: max relevant-doc score ${maxScore.toExponential(2)} < floor ${calibFloor} — reranker is inert/degenerate (likely the deprecated zerank-2 GGUF; re-deploy the seq-cls sidecar)`,
+    );
+  }
+  if (minMargin === Infinity) minMargin = 0; // no pair scored
+
+  return {
+    ok: failures.length === 0,
+    coverageOk: pairsScored === triples.length,
+    maxScore,
+    minMargin,
+    pairsTotal: triples.length,
+    pairsScored,
+    failures,
+    thresholds: { calibFloor, discrimMargin },
+  };
+}

package/src/mcp.ts

@@ -28,6 +28,7 @@ import {
 import {
   applyCompositeScoring,
   hasRecencyIntent,
+  QUERY_WEIGHTS,
   type EnrichedResult,
   type CoActivationFn,
 } from "./memory.ts";
@@ -46,6 +47,25 @@ import {
 import { listVaults, loadVaultConfig } from "./config.ts";
 import { getEntityGraphNeighbors, searchEntities } from "./entity.ts";
 
+// =============================================================================
+// Reranker fallback telemetry
+// =============================================================================
+
+// blendRerank silently degrades to RRF order when the reranker is degenerate (the deprecated
+// zerank-2 GGUF emitted ~1e-11 scores that contributed nothing at weight 0.9). This surfaces that
+// otherwise-invisible regression. Rate-limited to at most one stderr line per minute; the running
+// count is included so a persistent failure is obvious. Run `clawmem doctor` for the full probe.
+let rerankFallbackCount = 0;
+let lastRerankFallbackWarnAt = 0;
+function onRerankFallback(reason: string): void {
+  rerankFallbackCount++;
+  const now = Date.now();
+  if (now - lastRerankFallbackWarnAt > 60_000) {
+    lastRerankFallbackWarnAt = now;
+    console.error(`[clawmem] reranker degraded → RRF fallback (${reason}); ${rerankFallbackCount} occurrence(s) this process. Run 'clawmem doctor' to check the reranker.`);
+  }
+}
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -767,7 +787,7 @@ This is the recommended entry point for ALL memory queries.`,
       // prior w·(1/rrfRank) blend made RRF rank-1 immovable by the reranker. Harness-validated
       // 2026-06-25 (NL+KW known-item recall): lifts recall@1-5 + MRR@10 with no material pooled
       // recall@10 regression.
-      const blended = blendRerank(candidates, reranked);
+      const blended = blendRerank(candidates, reranked, { onFallback: onRerankFallback });
 
       // Map to SearchResults for composite scoring — hydrate from DB when needed
       const allSearchResults = [...store.searchFTS(query, 30)];
@@ -807,7 +827,10 @@ This is the recommended entry point for ALL memory queries.`,
 
       const coFn = (path: string) => store.getCoActivated(path);
       const enriched = enrichResults(store, searchResults, query);
-      let scored = applyCompositeScoring(enriched, query, coFn)
+      // Phase B (§11.12): the `query` tool's hybrid+rerank pipeline uses QUERY_WEIGHTS (search 0.70) —
+      // the eval-validated re-weight. Recency intent still wins RECENCY_WEIGHTS by construction
+      // (applyCompositeScoring ignores options.weights when hasRecencyIntent(query) and !forceWeights).
+      let scored = applyCompositeScoring(enriched, query, coFn, { weights: QUERY_WEIGHTS })
         .filter(r => r.compositeScore >= (minScore || 0));
       if (diverse !== false) scored = applyMMRDiversity(scored);
       scored = scored.slice(0, limit || 10);

package/src/memory.ts

@@ -185,6 +185,15 @@ export type CompositeWeights = {
 
 export const DEFAULT_WEIGHTS: CompositeWeights = { search: 0.5, recency: 0.25, confidence: 0.25 };
 export const RECENCY_WEIGHTS: CompositeWeights = { search: 0.1, recency: 0.7, confidence: 0.2 };
+// Query-tool retrieval weights (Phase B, 2026-06-25). A held-out judged eval (n=199, GLM-5.2 judge,
+// quadratic-weighted κ=0.681 vs an independent annotator) showed the default 0.50 search weight
+// under-weights topical relevance for a work-memory vault: w_search 0.70 lifts graded NDCG@10 by +0.064
+// (paired permutation p<1e-4, robust across precision/exploratory/temporal families) with ZERO freshness regression —
+// the newest-correct doc is never demoted in the supersession guard (demotionRate 0), whereas 0.80
+// demotes it out of the top-10 in 2/19 cases. Applied ONLY by the `query` tool's full hybrid+rerank
+// pipeline (the path the eval mirrored). NOT applied under recency intent — RECENCY_WEIGHTS wins by
+// construction in applyCompositeScoring. See BLEND-COMPOSITE-REBALANCE-DESIGN.md §11.12.
+export const QUERY_WEIGHTS: CompositeWeights = { search: 0.7, recency: 0.15, confidence: 0.15 };
 
 const RECENCY_PATTERNS = [
   /\brecent(ly)?\b/i,
@@ -274,13 +283,28 @@ function canonicalMemoryMultiplier(path: string, contentType: string, query: str
   return 1.0;
 }
 
+export type CompositeScoringOptions = {
+  /** Query-scoped weights override. Replaces DEFAULT_WEIGHTS; NOT applied under recency intent unless forceWeights. */
+  weights?: CompositeWeights;
+  /** Injected clock for deterministic scoring (tests/eval). Defaults to new Date(). */
+  now?: Date;
+  /** Test/experiment only: apply `weights` even under recency intent (bypass the RECENCY_WEIGHTS switch). */
+  forceWeights?: boolean;
+};
+
 export function applyCompositeScoring(
   results: EnrichedResult[],
   query: string,
-  coActivationFn?: CoActivationFn
+  coActivationFn?: CoActivationFn,
+  options?: CompositeScoringOptions
 ): ScoredResult[] {
-  const weights = hasRecencyIntent(query) ? RECENCY_WEIGHTS : DEFAULT_WEIGHTS;
-  const now = new Date();
+  const recencyIntent = hasRecencyIntent(query);
+  // Recency intent keeps RECENCY_WEIGHTS (production contract) unless forceWeights overrides (experiments).
+  // A query-scoped `weights` override otherwise replaces DEFAULT_WEIGHTS; absent options => exact prior behavior.
+  const weights = (recencyIntent && !options?.forceWeights)
+    ? RECENCY_WEIGHTS
+    : (options?.weights ?? (recencyIntent ? RECENCY_WEIGHTS : DEFAULT_WEIGHTS));
+  const now = options?.now ?? new Date();
 
   const scored = results.map(r => {
     const recency = recencyScore(r.modifiedAt, r.contentType, now, r.accessCount, r.lastAccessedAt);

package/src/search-utils.ts

@@ -7,6 +7,23 @@
 import type { Store, SearchResult } from "./store.ts";
 import type { EnrichedResult } from "./memory.ts";
 
+/**
+ * Runtime floor below which the whole reranker output is treated as degenerate (→ RRF fallback).
+ * Permissive by design: its only job is to catch the near-zero collapse (the deprecated zerank-2
+ * GGUF maxed at 8.03e-7), NOT to grade quality. A working zerank-2-seq scores >= ~0.1, so it never
+ * false-trips a healthy reranker. Distinct from the stricter doctor CALIB_FLOOR (rerank-health.ts).
+ */
+export const RERANK_DEGENERATE_FLOOR = 1e-4;
+
+export interface BlendRerankOptions {
+  /** Reranker dominance in the blend (default 0.9). */
+  rerankWeight?: number;
+  /** Reranker is treated as unusable (→ RRF fallback) unless some score exceeds this floor. */
+  degenerateFloor?: number;
+  /** Invoked when the reranker is unusable and the blend silently falls back to pure RRF order. */
+  onFallback?: (reason: string) => void;
+}
+
 // =============================================================================
 // Result Enrichment
 // =============================================================================
@@ -135,17 +152,31 @@ export function reciprocalRankFusion(
  * preserve their relative RRF order among themselves.
  *
  * @param candidates - RRF-ordered candidates; `score` is the RRF fusion score (positive).
- * @param reranked - reranker output `{file, score in [0,1]}`; may be empty/partial/all-zero.
- * @param rerankWeight - weight on the reranker term (default 0.9; `1-rerankWeight` on RRF).
+ * @param reranked - reranker output `{file, score in [0,1]}`; may be empty/partial/all-zero/degenerate.
+ * @param options - bare number (rerankWeight, back-compat) OR { rerankWeight, degenerateFloor, onFallback }.
  * @returns candidates re-scored and sorted by blended score descending.
  */
 export function blendRerank(
   candidates: { file: string; score: number }[],
   reranked: { file: string; score: number }[],
-  rerankWeight: number = 0.9
+  options: number | BlendRerankOptions = {}
 ): { file: string; score: number }[] {
+  const opts: BlendRerankOptions = typeof options === "number" ? { rerankWeight: options } : options;
+  const rerankWeight = opts.rerankWeight ?? 0.9;
+  const degenerateFloor = opts.degenerateFloor ?? RERANK_DEGENERATE_FLOOR;
+
   const rerankScoreMap = new Map(reranked.map(r => [r.file, r.score]));
-  const rerankUsable = reranked.length > 0 && reranked.some(r => Number.isFinite(r.score) && r.score > 0);
+  // Usable iff at least one score clears the degenerate floor. The old check (`> 0`) let the broken
+  // reranker's ~1e-11 scores through as "usable", contributing ~nothing at weight 0.9 — a silent
+  // collapse to RRF order. The floor closes that hole; onFallback makes the degrade visible.
+  const rerankUsable = reranked.length > 0 && reranked.some(r => Number.isFinite(r.score) && r.score > degenerateFloor);
+  if (!rerankUsable && opts.onFallback) {
+    opts.onFallback(
+      reranked.length === 0
+        ? "reranker returned no scores"
+        : `all ${reranked.length} rerank scores <= degenerate floor ${degenerateFloor}`
+    );
+  }
   const maxRrf = candidates.reduce((m, c) => Math.max(m, c.score), 0) || 1;
   return candidates
     .map(c => {

package/src/store.ts

@@ -1143,7 +1143,7 @@ export type Store = {
 
   // Query expansion & reranking
   expandQuery: (query: string, model?: string, intent?: string) => Promise<ExpandedQuery[]>;
-  rerank: (query: string, documents: { file: string; text: string }[], model?: string, intent?: string) => Promise<{ file: string; score: number }[]>;
+  rerank: (query: string, documents: { file: string; text: string }[], model?: string, intent?: string, options?: RerankProbeOptions) => Promise<{ file: string; score: number }[]>;
 
   // Document retrieval
   findDocument: (filename: string, options?: { includeBody?: boolean }) => DocumentResult | DocumentNotFound;
@@ -1337,7 +1337,7 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
 
     // Query expansion & reranking
     expandQuery: (query: string, model?: string, intent?: string) => expandQuery(query, model, db, intent),
-    rerank: (query: string, documents: { file: string; text: string }[], model?: string, intent?: string) => rerank(query, documents, model, db, intent),
+    rerank: (query: string, documents: { file: string; text: string }[], model?: string, intent?: string, options?: RerankProbeOptions) => rerank(query, documents, model, db, intent, options),
 
     // Document retrieval
     findDocument: (filename: string, options?: { includeBody?: boolean }) => findDocument(db, filename, options),
@@ -3630,9 +3630,46 @@ export async function expandQuery(query: string, model: string = DEFAULT_QUERY_M
 // Reranking
 // =============================================================================
 
-export async function rerank(query: string, documents: { file: string; text: string }[], model: string = DEFAULT_RERANK_MODEL, db: Database, intent?: string): Promise<{ file: string; score: number }[]> {
+/** Options for the reranker health probe. Production query/hook callers omit all of these. */
+export type RerankProbeOptions = {
+  /** Skip the rerank cache entirely — forces a live endpoint call (health probes). */
+  noCache?: boolean;
+  /** Throw RerankCoverageError if any input doc was not scored by the reranker (checked before zero-fill). */
+  requireLiveCoverage?: boolean;
+  /** Abort signal for the remote fetch. */
+  signal?: AbortSignal;
+  /** Convenience: derive AbortSignal.timeout(timeoutMs) for the remote fetch when no signal is given. */
+  timeoutMs?: number;
+};
+
+/** Thrown by rerank() when requireLiveCoverage is set and the reranker did not score every input doc. */
+export class RerankCoverageError extends Error {
+  constructor(public readonly missing: string[]) {
+    super(`rerank coverage incomplete: ${missing.length} document(s) not scored by the reranker`);
+    this.name = "RerankCoverageError";
+  }
+}
+
+/**
+ * Thrown by rerank() when requireLiveCoverage is set and the reranker's raw response violates the
+ * coverage contract: wrong result count, duplicate/out-of-range index, or a non-finite score. A
+ * malformed-but-responding reranker is exactly the failure a health probe must catch — it must not
+ * be silently accepted (and a duplicate index can otherwise leave a doc unscored, or an out-of-range
+ * index can crash the score apply).
+ */
+export class RerankMalformedResponseError extends Error {
+  constructor(public readonly problems: string[]) {
+    super(`rerank response malformed: ${problems.join("; ")}`);
+    this.name = "RerankMalformedResponseError";
+  }
+}
+
+export async function rerank(query: string, documents: { file: string; text: string }[], model: string = DEFAULT_RERANK_MODEL, db: Database, intent?: string, options?: RerankProbeOptions): Promise<{ file: string; score: number }[]> {
   // Prepend intent to rerank query so the reranker scores with domain context
   const rerankQuery = intent ? `${intent}\n\n${query}` : query;
+  const noCache = options?.noCache === true;
+  // Health probes thread a timeout to the remote fetch (the production path is otherwise untimed).
+  const fetchSignal = options?.signal ?? (options?.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined);
 
   // Deduplicate identical chunk texts — same content from different files shares a single score
   const textToFiles = new Map<string, string[]>();
@@ -3650,16 +3687,22 @@ export async function rerank(query: string, documents: { file: string; text: str
   const cachedResults: Map<string, number> = new Map();
   const uncachedDocs: RerankDocument[] = [];
 
-  // Check cache for each unique document
-  for (const doc of uniqueDocs) {
-    const cacheKey = getCacheKey("rerank", { query: rerankQuery, file: doc.file, model });
-    const cached = getCachedResult(db, cacheKey);
-    if (cached !== null) {
-      const score = parseFloat(cached);
-      // Apply score to all files sharing this text
-      for (const file of textToFiles.get(doc.text)!) cachedResults.set(file, score);
-    } else {
-      uncachedDocs.push({ file: doc.file, text: doc.text });
+  // Check cache for each unique document. noCache (health probes) skips the cache entirely so the
+  // call always exercises the live endpoint — a cached probe would mask an endpoint silently
+  // reverted to a broken reranker.
+  if (noCache) {
+    for (const doc of uniqueDocs) uncachedDocs.push({ file: doc.file, text: doc.text });
+  } else {
+    for (const doc of uniqueDocs) {
+      const cacheKey = getCacheKey("rerank", { query: rerankQuery, file: doc.file, model });
+      const cached = getCachedResult(db, cacheKey);
+      if (cached !== null) {
+        const score = parseFloat(cached);
+        // Apply score to all files sharing this text
+        for (const file of textToFiles.get(doc.text)!) cachedResults.set(file, score);
+      } else {
+        uncachedDocs.push({ file: doc.file, text: doc.text });
+      }
     }
   }
 
@@ -3684,13 +3727,50 @@ export async function rerank(query: string, documents: { file: string; text: str
               query: rerankQuery,
               documents: batch.map(d => d.text.slice(0, 400)),
             }),
+            signal: fetchSignal,
           });
           if (resp.ok) {
-            const data = await resp.json() as { results: { index: number; relevance_score: number }[] };
-            for (const r of data.results) {
-              const doc = batch[r.index]!;
-              const cacheKey = getCacheKey("rerank", { query: rerankQuery, file: doc.file, model });
-              setCachedResult(db, cacheKey, r.relevance_score.toString());
+            let data: { results: { index: number; relevance_score: number }[] };
+            try {
+              data = await resp.json() as { results: { index: number; relevance_score: number }[] };
+            } catch {
+              // Invalid JSON from a 200 response. For a probe this is a malformed remote → surface it;
+              // for production treat it like a transport failure and fall through to local.
+              if (options?.requireLiveCoverage) throw new RerankMalformedResponseError(["response body is not valid JSON"]);
+              break;
+            }
+            // Strict contract for health probes: a results array of exactly batch.length, each with a
+            // unique in-range integer index and a finite numeric score. A malformed-but-responding
+            // reranker (including a null/primitive body) must surface, not be silently accepted.
+            if (options?.requireLiveCoverage) {
+              const problems: string[] = [];
+              if (data === null || typeof data !== "object" || !Array.isArray(data.results)) {
+                problems.push("response is not an object with a results array");
+              } else {
+                if (data.results.length !== batch.length) {
+                  problems.push(`batch expected ${batch.length} results, got ${data.results.length}`);
+                }
+                const seen = new Set<number>();
+                for (const r of data.results) {
+                  if (!Number.isInteger(r?.index) || r.index < 0 || r.index >= batch.length) problems.push(`index ${r?.index} out of range`);
+                  else if (seen.has(r.index)) problems.push(`duplicate index ${r.index}`);
+                  else seen.add(r.index);
+                  if (typeof r?.relevance_score !== "number" || !Number.isFinite(r.relevance_score)) problems.push(`non-finite score at index ${r?.index}`);
+                }
+              }
+              if (problems.length > 0) throw new RerankMalformedResponseError(problems);
+            }
+            // Defensive (all callers): guard a non-array body, and skip out-of-range/non-finite entries
+            // so a malformed response can never crash the score apply or store garbage. Under
+            // requireLiveCoverage the strict check above has already thrown; here a skipped entry just
+            // leaves the doc unscored (→ coverage error for probes, → zero-fill for production).
+            for (const r of (Array.isArray(data?.results) ? data.results : [])) {
+              const doc = batch[r.index];
+              if (!doc || typeof r.relevance_score !== "number" || !Number.isFinite(r.relevance_score)) continue;
+              if (!noCache) {
+                const cacheKey = getCacheKey("rerank", { query: rerankQuery, file: doc.file, model });
+                setCachedResult(db, cacheKey, r.relevance_score.toString());
+              }
               // Apply score to all files sharing this text
               for (const file of textToFiles.get(doc.text)!) cachedResults.set(file, r.relevance_score);
             }
@@ -3699,8 +3779,11 @@ export async function rerank(query: string, documents: { file: string; text: str
           }
         }
         scored = cachedResults.size > 0;
-      } catch {
-        // Remote failed, fall through to local
+      } catch (e) {
+        // Network/transport failure → fall through to local. But a malformed-response error (only
+        // raised under requireLiveCoverage) is a probe FINDING about the remote endpoint — propagate
+        // it instead of masking it with the local fallback.
+        if (e instanceof RerankMalformedResponseError) throw e;
       }
     }
 
@@ -3712,8 +3795,10 @@ export async function rerank(query: string, documents: { file: string; text: str
         const rerankResult = await llm.rerank(rerankQuery, remaining, { model });
         for (const result of rerankResult.results) {
           const doc = remaining.find(d => d.file === result.file);
-          const cacheKey = getCacheKey("rerank", { query: rerankQuery, file: result.file, model });
-          setCachedResult(db, cacheKey, result.score.toString());
+          if (!noCache) {
+            const cacheKey = getCacheKey("rerank", { query: rerankQuery, file: result.file, model });
+            setCachedResult(db, cacheKey, result.score.toString());
+          }
           // Apply score to all files sharing this text
           if (doc) {
             for (const file of textToFiles.get(doc.text)!) cachedResults.set(file, result.score);
@@ -3725,6 +3810,14 @@ export async function rerank(query: string, documents: { file: string; text: str
     }
   }
 
+  // Coverage check BEFORE the zero-fill below (health probes only, via requireLiveCoverage).
+  // After the map, an omitted score and a true 0 are indistinguishable, so a partial endpoint
+  // would otherwise look fully covered. See RERANKER-HEALTH-GUARD-DESIGN.md §5 (H1/M4).
+  if (options?.requireLiveCoverage) {
+    const missing = documents.filter(doc => !cachedResults.has(doc.file)).map(doc => doc.file);
+    if (missing.length > 0) throw new RerankCoverageError(missing);
+  }
+
   // Return all results sorted by score
   return documents
     .map(doc => ({ file: doc.file, score: cachedResults.get(doc.file) || 0 }))