clawmem 0.12.0 → 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 |

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 |

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.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,6 +28,7 @@ import {
 import {
   applyCompositeScoring,
   hasRecencyIntent,
+  QUERY_WEIGHTS,
   type EnrichedResult,
   type CoActivationFn,
 } from "./memory.ts";
@@ -807,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);