clawmem 0.11.3 → 0.13.0

package/AGENTS.md

@@ -461,6 +461,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 |
@@ -553,7 +555,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

@@ -461,6 +461,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 |
@@ -553,7 +555,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,8 +813,8 @@ 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)
-  → SAME Composite Scoring ((search × 0.5 + recency × 0.25 + confidence × 0.25) × qualityMultiplier × lengthNorm × coActivationBoost + pinBoost)
+  → 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 (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/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.13.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

@@ -28,10 +28,11 @@ import {
 import {
   applyCompositeScoring,
   hasRecencyIntent,
+  QUERY_WEIGHTS,
   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 +754,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)];
@@ -805,7 +808,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

@@ -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.
  */