claude-memory-layer 1.0.32 → 1.0.33

package/dist/ui/assets/js/bootstrap.js

@@ -76,7 +76,9 @@ function setupEventListeners() {
         b.classList.toggle('active', b.dataset.kpiWindow === window);
       });
       await loadKpiData();
+      await loadMemoryUsefulnessData();
       updateKpiCardsUI();
+      updateMemoryUsefulnessUI();
       renderKpiTrendChart();
     });
   });

package/dist/ui/assets/js/overview.js

@@ -4,28 +4,51 @@ async function loadKpiData() {
     .catch(() => null);
 }
 
+async function loadMemoryUsefulnessData() {
+  state.memoryUsefulness = await fetch(apiUrl(`${API_BASE}/stats/usefulness`, { window: state.kpiWindow }))
+    .then(r => r.json())
+    .catch(() => null);
+}
+
 async function refreshData() {
   const btn = document.getElementById('refresh-btn');
   if(btn) btn.classList.add('loading');
+  const refreshRequestId = (state.refreshRequestId || 0) + 1;
+  state.refreshRequestId = refreshRequestId;
+  const projectAtStart = state.currentProject;
+  const kpiWindowAtStart = state.kpiWindow;
 
   try {
-    const [stats, shared, mostAccessed, helpfulness, retrievalTraces, adherenceSummary] = await Promise.all([
+    const [stats, shared, mostAccessed, helpfulness, memoryUsefulness, retrievalTraces, retrievalReviewQueue, adherenceSummary] = await Promise.all([
       fetch(apiUrl(`${API_BASE}/stats`)).then(r => r.json()).catch(() => null),
       fetch(apiUrl(`${API_BASE}/stats/shared`)).then(r => r.json()).catch(() => null),
       fetch(apiUrl(`${API_BASE}/stats/most-accessed`, { limit: 10 })).then(r => r.json()).catch(() => null),
       fetch(apiUrl(`${API_BASE}/stats/helpfulness`, { limit: 5 })).then(r => r.json()).catch(() => null),
+      fetch(apiUrl(`${API_BASE}/stats/usefulness`, { window: state.kpiWindow })).then(r => r.json()).catch(() => null),
       fetch(apiUrl(`${API_BASE}/stats/retrieval-traces`, { limit: 20 })).then(r => r.json()).catch(() => null),
+      fetch(apiUrl(`${API_BASE}/stats/retrieval-review-queue`, { limit: 10 })).then(r => r.json()).catch(() => null),
       fetchAdherenceSummary().catch(() => null)
     ]);
 
+    if (
+      refreshRequestId !== state.refreshRequestId ||
+      projectAtStart !== state.currentProject ||
+      kpiWindowAtStart !== state.kpiWindow
+    ) {
+      return;
+    }
+
     state.stats = stats;
     state.sharedStats = shared;
     state.mostAccessed = mostAccessed;
     state.helpfulness = helpfulness;
+    state.memoryUsefulness = memoryUsefulness;
     state.retrievalTraces = retrievalTraces;
+    state.retrievalReviewQueue = retrievalReviewQueue;
     state.adherenceSummary = adherenceSummary;
 
     await loadKpiData();
+    if (refreshRequestId !== state.refreshRequestId) return;
 
     updateStatsUI();
     updateSharedUI();
@@ -336,6 +359,7 @@ function updateTopAccessedEventsUI() {
 
 function updateMemoryUsageUI() {
   updateGraduationBars();
+  updateMemoryUsefulnessUI();
   updateHelpfulnessUI();
   updateMostHelpfulList();
   updateTopAccessedEventsUI();
@@ -431,6 +455,78 @@ function updateGraduationBars() {
   }).join('');
 }
 
+function updateMemoryUsefulnessUI() {
+  const scoreEl = document.getElementById('memory-usefulness-score');
+  const summaryEl = document.getElementById('memory-usefulness-summary');
+  const breakdownEl = document.getElementById('memory-usefulness-breakdown');
+  const diagnosticsEl = document.getElementById('memory-usefulness-diagnostics');
+  if (!scoreEl || !summaryEl || !breakdownEl) return;
+
+  const payload = state.memoryUsefulness;
+  if (!payload || payload.error || !payload.score) {
+    scoreEl.textContent = '-';
+    scoreEl.className = 'memory-usefulness-score score-unknown';
+    summaryEl.innerHTML = '<span style="color:var(--text-muted);">No usefulness telemetry yet.</span>';
+    breakdownEl.innerHTML = '';
+    if (diagnosticsEl) diagnosticsEl.innerHTML = '';
+    return;
+  }
+
+  const score = payload.score || {};
+  const counts = payload.counts || {};
+  const label = score.label || 'unknown';
+  const confidencePct = ((score.confidence || 0) * 100).toFixed(0);
+  scoreEl.textContent = Number(score.value || 0).toFixed(1).replace(/\.0$/, '');
+  scoreEl.className = `memory-usefulness-score score-${label}`;
+
+  summaryEl.innerHTML = `
+    <span class="usefulness-pill usefulness-${escapeHtml(label)}">${escapeHtml(label)}</span>
+    <span><strong>${formatNumber(counts.retrievalQueries || 0)}</strong> queries</span>
+    <span><strong>${formatNumber(counts.rewrittenQueries || 0)}</strong> rewritten</span>
+    <span><strong>${formatNumber(counts.promptCount || 0)}</strong> prompts</span>
+    <span><strong>${formatNumber(counts.totalEvaluated || 0)}</strong> evaluated</span>
+    <span title="How many input signals were available for the composite score"><strong>${confidencePct}%</strong> confidence</span>
+  `;
+
+  const components = payload.components || [];
+  breakdownEl.innerHTML = components.map((component) => {
+    const valuePct = `${((component.value || 0) * 100).toFixed(1)}%`;
+    const availableClass = component.available ? '' : ' unavailable';
+    const availableText = component.available ? valuePct : 'n/a';
+    const width = Math.max(0, Math.min(100, (component.value || 0) * 100));
+    return `
+      <div class="usefulness-component${availableClass}">
+        <div class="usefulness-component-row">
+          <span>${escapeHtml(component.label || component.key)}</span>
+          <strong>${availableText}</strong>
+        </div>
+        <div class="usefulness-bar-track"><div class="usefulness-bar-fill" style="width:${width}%;"></div></div>
+      </div>
+    `;
+  }).join('');
+
+  const diagnostics = (payload.diagnostics || []).slice(0, 3);
+  if (!diagnosticsEl) return;
+  if (diagnostics.length === 0) {
+    diagnosticsEl.innerHTML = '<div class="usefulness-diagnostics-empty">No immediate improvement actions.</div>';
+    return;
+  }
+
+  diagnosticsEl.innerHTML = `
+    <div class="usefulness-diagnostics-title">Top improvement actions</div>
+    ${diagnostics.map((diagnostic) => `
+      <div class="usefulness-diagnostic usefulness-diagnostic-${escapeHtml(diagnostic.severity || 'info')}">
+        <div class="usefulness-diagnostic-header">
+          <span class="usefulness-diagnostic-severity">${escapeHtml(diagnostic.severity || 'info')}</span>
+          <strong>${escapeHtml(diagnostic.title || diagnostic.key || 'Improve memory usefulness')}</strong>
+        </div>
+        <div class="usefulness-diagnostic-detail">${escapeHtml(diagnostic.detail || '')}</div>
+        <div class="usefulness-diagnostic-action">${escapeHtml(diagnostic.action || '')}</div>
+      </div>
+    `).join('')}
+  `;
+}
+
 function updateHelpfulnessUI() {
   const container = document.getElementById('helpfulness-summary');
   if (!container) return;
@@ -490,7 +586,68 @@ function updateMostHelpfulList() {
 }
 
 
+function updateRetrievalReviewQueueUI() {
+  const summaryEl = document.getElementById('retrieval-review-summary');
+  const listEl = document.getElementById('retrieval-review-list');
+  if (!summaryEl || !listEl) return;
+
+  const payload = state.retrievalReviewQueue;
+  if (payload?.error) {
+    summaryEl.innerHTML = '<span style="color:var(--warning, #FEB019);">Retrieval review queue is temporarily unavailable.</span>';
+    listEl.innerHTML = '<div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">Unable to load bad retrieval cases right now.</div>';
+    return;
+  }
+  const summary = payload?.summary;
+  const items = payload?.items || [];
+
+  if (!summary || !Number.isFinite(summary.reviewItems) || summary.reviewItems === 0) {
+    summaryEl.innerHTML = '<span style="color:var(--text-muted);">No retrieval traces need review.</span>';
+    listEl.innerHTML = '<div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">No bad retrieval cases in the current scan</div>';
+    return;
+  }
+
+  summaryEl.innerHTML = `
+    <div style="display:flex; gap:14px; flex-wrap:wrap; font-size:12px;">
+      <span><strong>${formatNumber(summary.reviewItems)}</strong> review items</span>
+      <span><strong>${formatNumber(summary.rewrittenNoSelection || 0)}</strong> rewritten no-selection</span>
+      <span><strong>${formatNumber(summary.candidateNoSelection || 0)}</strong> candidate no-selection</span>
+      <span><strong>${formatNumber(summary.emptyCandidateSet || 0)}</strong> empty candidates</span>
+    </div>
+  `;
+
+  listEl.innerHTML = items.slice(0, 10).map((item) => {
+    const ts = item.createdAt ? new Date(item.createdAt).toLocaleString() : '-';
+    const severityColor = item.severity === 'warn' ? 'var(--warning, #FEB019)' : 'var(--accent-primary)';
+    const rewriteKind = item.queryRewriteKind || (item.rewritten ? 'rewritten' : 'none');
+    const rewriteBadge = rewriteKind && rewriteKind !== 'none'
+      ? `<span class="event-type-badge" title="Safe rewrite classification">${escapeHtml(rewriteKind)}</span>`
+      : '';
+    const candidateIds = (item.candidateEventIds || []).slice(0, 3)
+      .map((id) => `<span class="event-type-badge">${escapeHtml((id || '').slice(0, 8))}...</span>`)
+      .join(' ');
+    const selectedIds = (item.selectedEventIds || []).slice(0, 3)
+      .map((id) => `<span class="event-type-badge">${escapeHtml((id || '').slice(0, 8))}...</span>`)
+      .join(' ');
+    return `
+      <div class="shared-item" style="align-items:flex-start; border-left:2px solid ${severityColor};">
+        <div class="shared-info" style="align-items:flex-start; flex-direction:column; gap:4px;">
+          <span style="font-size:12px; color:var(--text-secondary);"><strong>${escapeHtml(item.title || 'Retrieval trace needs review')}</strong></span>
+          <span style="font-size:11px; color:var(--text-muted);">Trace ${escapeHtml((item.traceId || '').slice(0, 18))} · ${ts} · reason=${escapeHtml(item.reason || 'unknown')} · strategy=${escapeHtml(item.strategy || 'auto')} ${rewriteBadge}</span>
+          <span style="font-size:11px; color:var(--text-muted);">${escapeHtml(item.detail || '')}</span>
+          <span style="font-size:11px; color:var(--text-secondary);"><strong>Action:</strong> ${escapeHtml(item.action || '')}</span>
+          <span style="font-size:11px; color:var(--text-muted);">candidates: ${candidateIds || '-'} · selected: ${selectedIds || '-'}</span>
+        </div>
+        <div style="display:flex; flex-direction:column; align-items:flex-end; gap:2px; min-width:68px;">
+          <span style="font-size:13px; font-weight:600; color:${severityColor};">${Number(item.selectedCount || 0)}/${Number(item.candidateCount || 0)}</span>
+          <span style="font-size:10px; color:var(--text-muted);">sel/cand</span>
+        </div>
+      </div>
+    `;
+  }).join('');
+}
+
 function updateRetrievalTraceUI() {
+  updateRetrievalReviewQueueUI();
   const summaryEl = document.getElementById('retrieval-trace-summary');
   const listEl = document.getElementById('retrieval-trace-list');
   if (!summaryEl || !listEl) return;
@@ -506,12 +663,14 @@ function updateRetrievalTraceUI() {
   }
 
   const selectionRate = ((stats.selectionRate || 0) * 100).toFixed(1);
+  const rewriteRate = ((stats.rewriteRate || 0) * 100).toFixed(1);
   summaryEl.innerHTML = `
     <div style="display:flex; gap:14px; flex-wrap:wrap; font-size:12px;">
       <span><strong>${formatNumber(stats.totalQueries)}</strong> queries</span>
       <span><strong>${Number(stats.avgCandidateCount || 0).toFixed(1)}</strong> avg candidates</span>
       <span><strong>${Number(stats.avgSelectedCount || 0).toFixed(1)}</strong> avg selected</span>
       <span><strong>${selectionRate}%</strong> selection rate</span>
+      <span title="Share of retrieval queries enriched with previous prompt/assistant context"><strong>${rewriteRate}%</strong> rewrite rate</span>
     </div>
   `;
 
@@ -520,6 +679,10 @@ function updateRetrievalTraceUI() {
     const confidence = t.confidence || 'n/a';
     const selected = Number(t.selectedCount || 0);
     const candidates = Number(t.candidateCount || 0);
+    const rewriteKind = t.queryRewriteKind || (t.rewritten ? 'rewritten' : 'none');
+    const rewriteBadge = rewriteKind && rewriteKind !== 'none'
+      ? `<span class="event-type-badge" title="Query was enriched before retrieval">${escapeHtml(rewriteKind)}</span>`
+      : '';
     const selectedDetails = (t.selectedDetails || []).slice(0, 2);
     const candidateDetails = (t.candidateDetails || []).slice(0, 3);
     const selectedIdsHtml = selectedDetails.length > 0
@@ -536,8 +699,8 @@ function updateRetrievalTraceUI() {
     return `
       <div class="shared-item" style="align-items:flex-start;">
         <div class="shared-info" style="align-items:flex-start; flex-direction:column; gap:4px;">
-          <span style="font-size:12px; color:var(--text-secondary);"><strong>Q:</strong> ${escapeHtml((t.queryText || '').slice(0, 120))}</span>
-          <span style="font-size:11px; color:var(--text-muted);">${ts} · strategy=${escapeHtml(t.strategy || 'auto')} · conf=${escapeHtml(confidence)}</span>
+          <span style="font-size:12px; color:var(--text-secondary);"><strong>Trace:</strong> ${escapeHtml((t.traceId || '').slice(0, 12)) || '-'}</span>
+          <span style="font-size:11px; color:var(--text-muted);">${ts} · strategy=${escapeHtml(t.strategy || 'auto')} · conf=${escapeHtml(confidence)} ${rewriteBadge}</span>
           <span style="font-size:11px; color:var(--text-muted);">selected IDs: ${selectedIdsHtml}</span>
           <span style="font-size:11px; color:var(--text-muted);">candidates: ${candidateDetails.map((d) => `<span class=\"event-type-badge\" style=\"cursor:pointer;\" onclick=\"openDetailModal('${d.eventId}')\">${escapeHtml((d.eventId || '').slice(0, 8))}...</span>`).join(' ') || '-'}</span>
           ${scoreBreakdownHtml}

package/dist/ui/assets/js/state.js

@@ -11,7 +11,9 @@ const state = {
   sharedStats: null,
   mostAccessed: null,
   helpfulness: null,
+  memoryUsefulness: null,
   retrievalTraces: null,
+  retrievalReviewQueue: null,
   adherenceSummary: null,
   adherenceWindow: '24h',
   userPromptSearchQuery: '',
@@ -22,6 +24,7 @@ const state = {
   currentSort: 'recent',
   currentView: 'overview',
   currentProject: '', // empty = global
+  refreshRequestId: 0,
   projects: [],
   events: [],
   isLoading: false,

package/dist/ui/index.html

@@ -340,6 +340,18 @@
                 <div id="graduation-bars"></div>
               </div>
 
+              <div style="margin-top:20px;">
+                <div class="section-label">Memory Usefulness Score</div>
+                <div class="memory-usefulness-panel">
+                  <div class="memory-usefulness-header">
+                    <div class="memory-usefulness-score score-unknown" id="memory-usefulness-score">-</div>
+                    <div id="memory-usefulness-summary" class="memory-usefulness-summary">Loading...</div>
+                  </div>
+                  <div id="memory-usefulness-breakdown" class="memory-usefulness-breakdown"></div>
+                  <div id="memory-usefulness-diagnostics" class="memory-usefulness-diagnostics"></div>
+                </div>
+              </div>
+
               <div style="margin-top:20px;">
                 <div class="section-label">Helpfulness</div>
                 <div id="helpfulness-summary" style="padding:8px 0; font-size:13px; color:var(--text-muted);">Loading...</div>
@@ -378,6 +390,14 @@
                   <div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">Loading...</div>
                 </div>
               </div>
+
+              <div style="margin-top:20px;">
+                <div class="section-label">Bad Retrieval Review Queue</div>
+                <div id="retrieval-review-summary" style="padding:8px 0; font-size:13px; color:var(--text-muted);">Loading...</div>
+                <div id="retrieval-review-list" class="shared-list">
+                  <div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">Loading...</div>
+                </div>
+              </div>
             </div>
 
           </div>

package/dist/ui/style.css

@@ -676,6 +676,199 @@ body {
   text-align: right;
 }
 
+/* Memory Usefulness */
+.memory-usefulness-panel {
+  padding: 12px;
+  border: 1px solid var(--border-subtle);
+  border-radius: 12px;
+  background: rgba(255,255,255,0.03);
+}
+
+.memory-usefulness-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+
+.memory-usefulness-score {
+  min-width: 62px;
+  font-size: 30px;
+  font-weight: 800;
+  line-height: 1;
+  letter-spacing: -1px;
+}
+
+.memory-usefulness-score.score-excellent,
+.memory-usefulness-score.score-good {
+  color: var(--success);
+}
+
+.memory-usefulness-score.score-watch {
+  color: var(--warning);
+}
+
+.memory-usefulness-score.score-low {
+  color: var(--error);
+}
+
+.memory-usefulness-score.score-unknown {
+  color: var(--text-muted);
+}
+
+.memory-usefulness-summary {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px 10px;
+  font-size: 12px;
+  color: var(--text-secondary);
+}
+
+.usefulness-pill {
+  padding: 2px 7px;
+  border-radius: 999px;
+  font-size: 10px;
+  font-weight: 800;
+  text-transform: uppercase;
+  letter-spacing: 0.4px;
+}
+
+.usefulness-excellent,
+.usefulness-good {
+  background: rgba(52, 211, 153, 0.14);
+  color: #34D399;
+}
+
+.usefulness-watch {
+  background: rgba(254, 176, 25, 0.14);
+  color: #FEB019;
+}
+
+.usefulness-low {
+  background: rgba(255, 69, 96, 0.14);
+  color: #FF4560;
+}
+
+.usefulness-unknown {
+  background: rgba(148, 163, 184, 0.14);
+  color: #94A3B8;
+}
+
+.memory-usefulness-breakdown {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.memory-usefulness-diagnostics {
+  margin-top: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.usefulness-diagnostics-title {
+  font-size: 11px;
+  font-weight: 800;
+  color: var(--text-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.4px;
+}
+
+.usefulness-diagnostic {
+  padding: 10px;
+  border: 1px solid var(--border-subtle);
+  border-radius: 10px;
+  background: rgba(255,255,255,0.025);
+}
+
+.usefulness-diagnostic-warn {
+  border-color: rgba(254, 176, 25, 0.32);
+  background: rgba(254, 176, 25, 0.06);
+}
+
+.usefulness-diagnostic-info {
+  border-color: rgba(0, 240, 255, 0.24);
+  background: rgba(0, 240, 255, 0.04);
+}
+
+.usefulness-diagnostic-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  color: var(--text-primary);
+  margin-bottom: 5px;
+}
+
+.usefulness-diagnostic-severity {
+  padding: 1px 6px;
+  border-radius: 999px;
+  font-size: 9px;
+  font-weight: 800;
+  text-transform: uppercase;
+  color: var(--bg-primary);
+  background: var(--warning);
+}
+
+.usefulness-diagnostic-info .usefulness-diagnostic-severity {
+  background: var(--accent-secondary);
+}
+
+.usefulness-diagnostic-detail,
+.usefulness-diagnostic-action,
+.usefulness-diagnostics-empty {
+  font-size: 11px;
+  line-height: 1.45;
+  color: var(--text-muted);
+}
+
+.usefulness-diagnostic-action {
+  margin-top: 5px;
+  color: var(--text-secondary);
+}
+
+.usefulness-diagnostic-action::before {
+  content: 'Action: ';
+  color: var(--accent-secondary);
+  font-weight: 700;
+}
+
+.usefulness-component {
+  opacity: 1;
+}
+
+.usefulness-component.unavailable {
+  opacity: 0.45;
+}
+
+.usefulness-component-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 10px;
+  font-size: 11px;
+  color: var(--text-secondary);
+  margin-bottom: 4px;
+}
+
+.usefulness-component-row strong {
+  color: var(--text-primary);
+}
+
+.usefulness-bar-track {
+  height: 5px;
+  background: rgba(255,255,255,0.05);
+  border-radius: 999px;
+  overflow: hidden;
+}
+
+.usefulness-bar-fill {
+  height: 100%;
+  background: linear-gradient(90deg, var(--accent-primary), var(--accent-secondary));
+  border-radius: 999px;
+  transition: width 0.5s;
+}
+
 /* Endless Mode */
 .endless-card {
   background: linear-gradient(135deg, rgba(16, 16, 24, 0.6) 0%, rgba(20, 20, 30, 0.6) 100%);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-layer",
-  "version": "1.0.32",
+  "version": "1.0.33",
   "description": "Claude Code plugin that learns from conversations to provide personalized assistance",
   "main": "dist/index.js",
   "bin": {
@@ -30,6 +30,10 @@
     "ops:health": "npm run ops:sync-gap:report && npm run ops:sync-gap:heal && npm run ops:review:resolve",
     "ops:projects:clean-unknown": "node scripts/delete-unknown-projects.js",
     "benchmark:replay": "tsx scripts/replay-retrieval-benchmark.ts",
+    "eval:retrieval-replay": "tsx scripts/replay-retrieval-benchmark.ts --fixture benchmarks/replay/golden-memory-usefulness-v1.json --format markdown --no-per-query --min-query-yield 1 --min-no-match-accuracy 1 --max-forbidden-hits 0 --max-failed-queries 0",
+    "eval:retrieval-replay:report": "tsx scripts/replay-retrieval-benchmark.ts --fixture benchmarks/replay/golden-memory-usefulness-v1.json --format markdown --no-per-query",
+    "benchmark:replay:promote-review": "tsx scripts/promote-retrieval-review-queue.ts",
+    "benchmark:replay:validate-promotion": "tsx scripts/validate-replay-promotion-candidates.ts",
     "benchmark:qrels": "tsx scripts/generate-session-qrels.ts",
     "postinstall": "node scripts/postinstall-embedding-backend.cjs"
   },