clawmem 0.11.3 → 0.12.0

package/AGENTS.md

@@ -553,7 +553,7 @@ User Query + optional intent hint
   → Reciprocal Rank Fusion (k=60, top candidateLimit, up to 4-way parallel legs)
   → Intent-Aware Chunk Selection (intent terms at 0.5× weight alongside query terms at 1.0×)
   → Cross-Encoder Reranking (4000 char context; intent prepended to rerank query; chunk dedup; batch cap=4)
-  → Position-Aware Blending (α=0.75 top3, 0.60 mid, 0.40 tail)
+  → 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
   → MMR Diversity Filter (Jaccard bigram similarity > 0.6 → demoted, not removed)
 ```

package/CLAUDE.md

@@ -553,7 +553,7 @@ User Query + optional intent hint
   → Reciprocal Rank Fusion (k=60, top candidateLimit, up to 4-way parallel legs)
   → Intent-Aware Chunk Selection (intent terms at 0.5× weight alongside query terms at 1.0×)
   → Cross-Encoder Reranking (4000 char context; intent prepended to rerank query; chunk dedup; batch cap=4)
-  → Position-Aware Blending (α=0.75 top3, 0.60 mid, 0.40 tail)
+  → 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
   → MMR Diversity Filter (Jaccard bigram similarity > 0.6 → demoted, not removed)
 ```

package/README.md

@@ -813,7 +813,7 @@ User Query + optional intent hint
   → Reciprocal Rank Fusion → slice to candidateLimit (default 30)
   → 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)
-  → Position-Aware Blending (α=0.75 top3, 0.60 mid, 0.40 tail)
+  → 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)
   → MMR Diversity Filter (Jaccard bigram similarity > 0.6 → demoted)
   → Ranked Results

package/SKILL.md

@@ -389,7 +389,7 @@ User Query + optional intent hint
   -> Reciprocal Rank Fusion (k=60, top candidateLimit)
   -> Intent-Aware Chunk Selection (intent terms at 0.5x weight alongside query terms at 1.0x)
   -> Cross-Encoder Reranking (4000 char context; intent prepended to rerank query; chunk dedup; batch cap=4)
-  -> Position-Aware Blending (alpha=0.75 top3, 0.60 mid, 0.40 tail)
+  -> 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)
   -> Composite Scoring
   -> MMR Diversity Filter (Jaccard bigram similarity > 0.6 -> demoted, not removed)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.11.3",
+  "version": "0.12.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/mcp.ts

@@ -31,7 +31,7 @@ import {
   type EnrichedResult,
   type CoActivationFn,
 } from "./memory.ts";
-import { enrichResults, reciprocalRankFusion, toRanked, type RankedResult } from "./search-utils.ts";
+import { enrichResults, reciprocalRankFusion, toRanked, blendRerank, type RankedResult } from "./search-utils.ts";
 import { applyMMRDiversity } from "./mmr.ts";
 import { indexCollection, type IndexStats } from "./indexer.ts";
 import { listCollections } from "./collections.ts";
@@ -753,19 +753,21 @@ This is the recommended entry point for ALL memory queries.`,
         return { file: c.file, text };
       });
 
-      const reranked = await store.rerank(query, chunksToRerank, DEFAULT_RERANK_MODEL, intent);
+      let reranked: { file: string; score: number }[] = [];
+      try {
+        reranked = await store.rerank(query, chunksToRerank, DEFAULT_RERANK_MODEL, intent);
+      } catch {
+        reranked = []; // reranker unavailable → blendRerank falls back to pure RRF order
+      }
 
       const candidateMap = new Map(candidates.map(c => [c.file, c]));
-      const rrfRankMap = new Map(candidates.map((c, i) => [c.file, i + 1]));
-
-      // Blend RRF + reranker scores (position-aware)
-      const blended = reranked.map(r => {
-        const rrfRank = rrfRankMap.get(r.file) || candidates.length;
-        const rrfWeight = rrfRank <= 3 ? 0.75 : rrfRank <= 10 ? 0.60 : 0.40;
-        const blendedScore = rrfWeight * (1 / rrfRank) + (1 - rrfWeight) * r.score;
-        return { file: r.file, score: blendedScore };
-      });
-      blended.sort((a, b) => b.score - a.score);
+
+      // Blend the reranker (dominant signal) with a thin normalized-RRF tiebreaker; falls back
+      // to pure RRF order when the reranker is unavailable / all-zero. See blendRerank: the
+      // 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);
 
       // Map to SearchResults for composite scoring — hydrate from DB when needed
       const allSearchResults = [...store.searchFTS(query, 30)];

package/src/search-utils.ts

@@ -113,6 +113,51 @@ export function reciprocalRankFusion(
     .map(v => ({ ...v.result, score: v.score }));
 }
 
+// =============================================================================
+// Rerank / RRF Score Blend
+// =============================================================================
+
+/**
+ * Blend a cross-encoder reranker's scores with the upstream RRF ranking.
+ *
+ * The reranker is the dominant relevance signal; normalized RRF contributes a thin tiebreaker.
+ * An earlier blend used `w·(1/rrfRank)` with `w≥0.75` on the top tier, which made RRF rank-1
+ * mathematically immovable by the reranker (0.75·(1/1) exceeds any rank-2 ceiling) — the
+ * reranker could never promote the best document to the top. This blend normalizes the RRF
+ * score to [0,1] and gives the reranker the dominant weight, so a strong rerank score CAN
+ * promote a doc over RRF #1. Harness-validated 2026-06-25 against NL+KW known-item recall:
+ * lifts recall@1-5 and MRR@10 with no material pooled recall@10 regression.
+ *
+ * Falls back to pure RRF order when the reranker is unavailable or returned no usable signal
+ * (empty, or all-zero — e.g. a total remote+local failure). Maps over `candidates` (not the
+ * rerank output) so partial rerank coverage can never drop a candidate; an unscored doc takes
+ * rerank score 0 (so it sorts on its thin `(1-rerankWeight)·rrfNorm` term) and unscored docs
+ * 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).
+ * @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
+): { file: string; score: number }[] {
+  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);
+  const maxRrf = candidates.reduce((m, c) => Math.max(m, c.score), 0) || 1;
+  return candidates
+    .map(c => {
+      const rrfNorm = c.score / maxRrf; // [0,1]
+      if (!rerankUsable) return { file: c.file, score: rrfNorm };
+      const rr = rerankScoreMap.get(c.file);
+      const rerankScore = Number.isFinite(rr) ? (rr as number) : 0;
+      return { file: c.file, score: (1 - rerankWeight) * rrfNorm + rerankWeight * rerankScore };
+    })
+    .sort((a, b) => b.score - a.score);
+}
+
 /**
  * Convert a SearchResult to a RankedResult for use in RRF.
  */