ai-lens 0.8.117 → 0.8.119

package/.commithash

@@ -1 +1 @@
-28976f3
+8674f71

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 History of changes to the `ai-lens` CLI package on npm. New entries go on top. Format: `## X.Y.Z — YYYY-MM-DD`, followed by user-facing bullets.
 
+## 0.8.119 — 2026-07-02
+- feat: team-memory injection now fires only on genuinely relevant prompts — the trigger matches distinctive terms of the memory title instead of an absolute score, cutting noise ~20x while keeping real matches
+- feat: the full team memory pool is delivered to the session cache (previously most team-tier memories could never surface), server-gated to clients on this version and newer
+
+## 0.8.118 — 2026-07-01
+- fix(team-memory): injected memory now actually reaches the model on Claude Code (via `additionalContext`, not a user-only `systemMessage` banner) — before, relevant memory showed on screen but the model never received it. Silent by design; no screen clutter
+
 ## 0.8.117 — 2026-07-01
 - fix(team-memory): never inject team memory in projects outside your `projects` filter — an unrelated repo now gets nothing, even if it's on your machine
 

package/client/capture.js

@@ -1735,21 +1735,23 @@ export function maybeEmitSessionStartMemoryIndex(primary, { now = Date.now() } =
 // empty cache ⇒ this is a no-op) and relevance (local BM25 threshold).
 // =============================================================================
 
-// Relevance floor for the local BM25 scorer. Below this a candidate never surfaces.
-// PROVISIONAL, UNCALIBRATED — a starting guess to be tuned live on analytics ([0118]).
-// Measured band on realistic pairs (see test/client/memory-match.test.js): a single
-// on-topic term ("iceberg") ~2.2; a 2-word on-topic prompt 3–4; a generic dev prompt
-// sharing ONE weak word with a memory preview lands ~1.2–1.4 (just under) — so 1.5
-// currently suppresses single-generic-word overlaps while passing 2+ on-topic-word
-// matches. That margin is THIN (a 0.1–0.2 shift flips borderline prompts), which is
-// exactly why the number is deferred to live tuning, not treated as final. Bounded
-// blast radius (budget below + phase-N unshown-gate) keeps a mis-tuned floor from
-// flooding — worst case is 1–2 extra short memories, never a dump.
-// Calibrated on live prod pairs (analytics pilot, 2026-07): genuine matches score
-// ≫3 (specific-term prompts hit 3–13), noise clusters at 1.5–2.0. 3.0 cleanly
-// separates them — precision over recall BY DESIGN: silence beats a context-rotting
-// near-miss. Tunable down with PostHog match data if it proves too quiet.
-const MEMORY_MATCH_MIN_SCORE = 3.0;
+// Inject decision rule — REPLACED the absolute raw-BM25 floor (was 1.5, then 3.0).
+// A 20k-prompt historical replay (analytics, 90d, board [0102]) showed the raw sum
+// cannot be thresholded: it grows with prompt length, so long unrelated prompts
+// (pasted logs, slash-command expansions) hit 4–23 while true matches are defined
+// by WHICH terms hit. The shipped rule uses the two per-candidate signals from
+// scoreCandidates (client/memory-match.js):
+//   dth      — distinctive title hits (unique query terms landing in the TITLE
+//              that are rare in the pool, df ≤ max(1, ⌊0.3·N⌋));
+//   coverage — raw score / the query's saturation ceiling (length-normalized).
+// `dth >= 2 && coverage >= 0.12` measured on the replay golden set
+// (test/client/memory-match-golden.test.js): recall 65% on verified positive
+// pairs, 4.5% fire-rate on the 20k noise set (~7 injects/day team-wide) — vs 100%
+// noise fire-rate for the old raw>=3 on a full pool. Precision over recall BY
+// DESIGN: silence beats a context-rotting near-miss. Tune ONLY against the golden
+// harness + PostHog memory_matched (top_dth/top_coverage) data.
+const MEMORY_MATCH_MIN_DTH = 2;
+const MEMORY_MATCH_MIN_COVERAGE = 0.12;
 // Budget: never inject more than this many memories per prompt (repo OR team-general
 // alike) — keeps a prompt light even on a broad match.
 const MEMORY_INJECT_BUDGET = 2;
@@ -1888,16 +1890,17 @@ export function maybeEmitUserPromptMemoryInject(primary, { now = Date.now() } =
     // Score with the local BM25-lite scorer over the whole pool.
     const scored = scoreCandidates(promptText, entries);
     const byId = new Map(entries.map(e => [e.id, e]));
-    const scoreOf = new Map(scored.map(s => [s.id, s.score]));
+    const signalOf = new Map(scored.map(s => [s.id, s]));
 
     // Relevance-gated selection (UNIFORM across phases): inject ONLY candidates —
-    // repo OR team-general — that clear MEMORY_MATCH_MIN_SCORE for THIS prompt and
-    // were not already shown this session. NO unconditional team-general dump: a
-    // low-signal prompt ("давай делай", "continue") scores ~0 → injects NOTHING.
-    // Precision over recall BY DESIGN — silence beats context-rot. `promptIndex`
+    // repo OR team-general — that clear the dth+coverage decision rule (see the
+    // constants block) for THIS prompt and were not already shown this session.
+    // NO unconditional team-general dump: a low-signal prompt ("давай делай",
+    // "continue") has no distinctive title hits → injects NOTHING. Ranking among
+    // qualifiers stays by raw score (scoreCandidates sort order). `promptIndex`
     // still advances via commitCount() for telemetry, but no longer gates selection.
     const picked = scored
-      .filter(s => s.score >= MEMORY_MATCH_MIN_SCORE && !shown[s.id])
+      .filter(s => s.dth >= MEMORY_MATCH_MIN_DTH && s.coverage >= MEMORY_MATCH_MIN_COVERAGE && !shown[s.id])
       .map(s => byId.get(s.id))
       .filter(Boolean)
       .slice(0, MEMORY_INJECT_BUDGET);
@@ -1908,8 +1911,15 @@ export function maybeEmitUserPromptMemoryInject(primary, { now = Date.now() } =
     const text = renderPromptInject(picked);
     if (!text) { commitCount(); return NONE; }
 
+    // Claude → hookSpecificOutput.additionalContext: this is the field the MODEL
+    // actually receives (injected into the context window + persisted to the
+    // transcript, survives --resume). `systemMessage` is a USER-only banner the
+    // model NEVER sees — using it meant the memory showed on screen but the model
+    // couldn't use it. Silent by design (no banner): the model gets it, the user's
+    // screen stays clean. Cursor's `additional_context` is already the model-context
+    // field. (See Claude Code hooks: UserPromptSubmit additionalContext vs systemMessage.)
     const out = source === 'claude_code'
-      ? { systemMessage: text }
+      ? { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } }
       : { additional_context: text + CURSOR_RELAY_SUFFIX };
     process.stdout.write(JSON.stringify(out));
 
@@ -1918,12 +1928,17 @@ export function maybeEmitUserPromptMemoryInject(primary, { now = Date.now() } =
     commitCount();
 
     const matchedIds = picked.map(e => e.id);
-    const topScore = matchedIds.reduce((m, id) => Math.max(m, scoreOf.get(id) || 0), 0);
+    // top_* = max over the picked set. top_score keeps its raw-BM25 semantics
+    // (telemetry continuity); top_dth/top_coverage carry the decision signals so
+    // the live PostHog stream can validate/re-tune the rule against real traffic.
+    const agg = (key) => matchedIds.reduce((m, id) => Math.max(m, signalOf.get(id)?.[key] || 0), 0);
     return {
       wrote: true,
       match: {
         matched_ids: matchedIds,
-        top_score: topScore,
+        top_score: agg('score'),
+        top_dth: agg('dth'),
+        top_coverage: agg('coverage'),
         prompt_index: promptIndex,
         n_matched: matchedIds.length,
         had_team_general: hadTeamGeneral,

package/client/memory-match.js

@@ -11,10 +11,26 @@
  * this must have ZERO runtime deps (no `natural`, no tokenizer package). ~1 file,
  * pure functions, deterministic — fully unit-testable without I/O.
  *
- * The corpus is the SMALL primed pool (cap ~30 candidates), so this is BM25 with a
- * tiny-corpus caveat baked in: idf is FLOORED (a term present in every candidate
- * would otherwise get idf ≤ 0 and vanish, even when it's the whole point of the
- * prompt). See IDF_FLOOR.
+ * The corpus is the SMALL primed pool (up to ~100 candidates for 0.8.119+ clients,
+ * legacy cap ~30), so this is BM25 with a tiny-corpus caveat baked in: idf is
+ * FLOORED (a term present in every candidate would otherwise get idf ≤ 0 and
+ * vanish, even when it's the whole point of the prompt). See IDF_FLOOR.
+ *
+ * DECISION SIGNALS (post-replay redesign, board [0102]): a 20k-prompt historical
+ * replay showed the RAW BM25 sum cannot be thresholded — it grows with prompt
+ * length (long pasted logs hit 4–23 on unrelated memories), while true matches
+ * are distinguished by WHICH terms hit, not how many points accumulate. So each
+ * scored candidate also carries:
+ *   - `dth` (distinctive title hits) — how many unique query terms land in the
+ *     candidate's TITLE while being RARE in the pool (df ≤ max(1, ⌊0.3·N⌋)).
+ *     df-based on purpose: an absolute idf cutoff is unreachable for pools of
+ *     N ≤ 3 (a title term always has df ≥ 1 → idf ≤ 1.204), silently disabling
+ *     injection for small teams.
+ *   - `coverage` — rawScore / the query's saturation ceiling (every unique term
+ *     matched at tf→∞ on an average-length doc). Normalizes away prompt length.
+ * The inject decision in capture.js is `dth >= 2 && coverage >= 0.12`, measured
+ * on the replay golden set (test/client/memory-match-golden.test.js): recall 65%
+ * on verified positives, 4.5% fire-rate on the noise set (vs 100% for raw>=3).
  *
  * Bilingual by design: memory titles + our MEMORY.md entries are Russian; prompts
  * are mixed RU/EN. Tokenization is Unicode-letter/number aware so Cyrillic and
@@ -36,6 +52,12 @@ const WEIGHT_TAGS = 2;
 const WEIGHT_PATHS = 2;
 const WEIGHT_PREVIEW = 1;
 
+// A query term is "distinctive" for dth-counting when its pool document frequency
+// is at most this fraction of the pool (floored at 1 so N=3 pools still work).
+// 0.3 reproduces the replay-measured cutoff (df ≤ 20 at N = 67) and stays
+// reachable at any pool size — see the header note on why NOT an idf cutoff.
+const DISTINCTIVE_DF_RATIO = 0.3;
+
 // Bilingual stopwords (EN + RU) — high-frequency function words that carry no
 // topic signal. Kept deliberately small; over-stopping hurts recall more than a
 // few function words hurt precision on this tiny corpus.
@@ -104,8 +126,11 @@ export function candidateBag(cand) {
  *
  * @param {string} promptText  the user's current prompt (already truncated upstream)
  * @param {Array<object>} candidates  primed light-index entries ({id,title,tags,repo_rel_paths,preview,…})
- * @returns {Array<{id:string,score:number}>} candidates with score > 0, sorted desc by score.
- *          Stable tie-break by id so ordering is deterministic across engines.
+ * @returns {Array<{id:string,score:number,dth:number,coverage:number}>} candidates
+ *          with score > 0, sorted desc by score. Stable tie-break by id so ordering
+ *          is deterministic across engines. `dth`/`coverage` are the inject-decision
+ *          signals (see header); `score` stays the raw BM25 sum used for RANKING
+ *          and telemetry (`top_score` semantics unchanged).
  */
 export function scoreCandidates(promptText, candidates) {
   const queryTerms = tokenize(promptText);
@@ -114,18 +139,21 @@ export function scoreCandidates(promptText, candidates) {
   }
 
   // Build per-candidate term-frequency maps + doc lengths from the weighted bags.
+  // titleTerms is kept separately for dth: a hit only counts as "title" when the
+  // term appears in the title field itself, not merely anywhere in the bag.
   const docs = [];
   for (const cand of candidates) {
     if (!cand || cand.id == null) continue;
     const bag = candidateBag(cand);
     const tf = new Map();
     for (const t of bag) tf.set(t, (tf.get(t) || 0) + 1);
-    docs.push({ id: cand.id, tf, length: bag.length });
+    docs.push({ id: cand.id, tf, length: bag.length, titleTerms: new Set(tokenize(cand.title)) });
   }
   if (docs.length === 0) return [];
 
   const N = docs.length;
   const avgdl = docs.reduce((s, d) => s + d.length, 0) / N || 1;
+  const distinctiveDfCap = Math.max(1, Math.floor(DISTINCTIVE_DF_RATIO * N));
 
   // Document frequency per UNIQUE query term (over the pool = the corpus).
   const uniqueQueryTerms = [...new Set(queryTerms)];
@@ -144,17 +172,28 @@ export function scoreCandidates(promptText, candidates) {
     idf.set(term, Math.max(raw, IDF_FLOOR));
   }
 
+  // Query saturation ceiling for coverage: what the score would be if EVERY unique
+  // query term matched at tf→∞ on an average-length doc (den → f + K1 ⇒ factor
+  // (K1+1)/(1+K1)·f/(f+…) → (K1+1)/(1+K1) at f=1 normalization). Constant per
+  // query, so coverage is comparable across prompts of any length.
+  let sumIdfSat = 0;
+  for (const term of uniqueQueryTerms) sumIdfSat += idf.get(term) * (K1 + 1) / (1 + K1);
+
   const results = [];
   for (const d of docs) {
     let score = 0;
+    let dth = 0;
     for (const term of uniqueQueryTerms) {
       const f = d.tf.get(term);
       if (!f) continue;
+      if (d.titleTerms.has(term) && df.get(term) <= distinctiveDfCap) dth++;
       const num = f * (K1 + 1);
       const den = f + K1 * (1 - B + B * (d.length / avgdl));
       score += idf.get(term) * (num / den);
     }
-    if (score > 0) results.push({ id: d.id, score });
+    if (score > 0) {
+      results.push({ id: d.id, score, dth, coverage: sumIdfSat > 0 ? score / sumIdfSat : 0 });
+    }
   }
 
   results.sort((a, b) => (b.score - a.score) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lens",
-  "version": "0.8.117",
+  "version": "0.8.119",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {