claude-memory-layer 1.0.31 → 1.0.33

package/dist/server/index.js

@@ -8,11 +8,13 @@ const __dirname = dirname(__filename);
 // src/apps/server/index.ts
 import { Hono as Hono11 } from "hono";
 import { cors } from "hono/cors";
+import { getCookie, setCookie, deleteCookie } from "hono/cookie";
 import { logger } from "hono/logger";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import * as path13 from "path";
 import * as fs11 from "fs";
+import { createHmac, timingSafeEqual } from "crypto";
 import { fileURLToPath as fileUrlToPath } from "url";
 
 // src/apps/server/api/index.ts
@@ -2256,10 +2258,15 @@ function sqliteClose(db) {
 function toDateFromSQLite(value) {
   if (value instanceof Date)
     return value;
-  if (typeof value === "string")
-    return new Date(value);
   if (typeof value === "number")
     return new Date(value);
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:\.\d+)?$/.test(trimmed)) {
+      return /* @__PURE__ */ new Date(trimmed.replace(" ", "T") + "Z");
+    }
+    return new Date(trimmed);
+  }
   return new Date(String(value));
 }
 function toSQLiteTimestamp(date) {
@@ -2325,6 +2332,13 @@ var MarkdownMirror2 = class {
 };
 
 // src/core/sqlite-event-store.ts
+function normalizeQueryRewriteKind(value) {
+  const normalized = (value || "").trim().toLowerCase();
+  if (normalized === "follow-up-context" || normalized === "intent-rewrite")
+    return normalized;
+  return "none";
+}
+var REWRITTEN_QUERY_REWRITE_KIND_SQL = `LOWER(TRIM(COALESCE(query_rewrite_kind, 'none'))) IN ('follow-up-context', 'intent-rewrite')`;
 var SQLiteEventStore = class {
   db;
   initialized = false;
@@ -2585,6 +2599,8 @@ var SQLiteEventStore = class {
         session_id TEXT,
         project_hash TEXT,
         query_text TEXT NOT NULL,
+        raw_query_text TEXT,
+        query_rewrite_kind TEXT,
         strategy TEXT,
         candidate_event_ids TEXT,
         selected_event_ids TEXT,
@@ -2626,6 +2642,8 @@ var SQLiteEventStore = class {
       CREATE INDEX IF NOT EXISTS idx_helpfulness_event ON memory_helpfulness(event_id);
       CREATE INDEX IF NOT EXISTS idx_helpfulness_session ON memory_helpfulness(session_id);
       CREATE INDEX IF NOT EXISTS idx_helpfulness_score ON memory_helpfulness(helpfulness_score DESC);
+      CREATE INDEX IF NOT EXISTS idx_helpfulness_created_at ON memory_helpfulness(created_at);
+      CREATE INDEX IF NOT EXISTS idx_helpfulness_measured_at ON memory_helpfulness(measured_at);
       CREATE INDEX IF NOT EXISTS idx_retrieval_traces_created_at ON retrieval_traces(created_at DESC);
       CREATE INDEX IF NOT EXISTS idx_retrieval_traces_project_hash ON retrieval_traces(project_hash);
       CREATE INDEX IF NOT EXISTS idx_retrieval_traces_session_id ON retrieval_traces(session_id);
@@ -2659,6 +2677,18 @@ var SQLiteEventStore = class {
       sqliteExec(this.db, `ALTER TABLE retrieval_traces ADD COLUMN candidate_details_json TEXT;`);
     } catch {
     }
+    try {
+      sqliteExec(this.db, `ALTER TABLE retrieval_traces ADD COLUMN raw_query_text TEXT;`);
+    } catch {
+    }
+    try {
+      sqliteExec(this.db, `ALTER TABLE retrieval_traces ADD COLUMN query_rewrite_kind TEXT;`);
+    } catch {
+    }
+    try {
+      sqliteExec(this.db, `CREATE INDEX IF NOT EXISTS idx_retrieval_traces_query_rewrite_kind ON retrieval_traces(query_rewrite_kind);`);
+    } catch {
+    }
     const tableInfo = sqliteAll(this.db, "PRAGMA table_info(events)", []);
     const columnNames = tableInfo.map((col) => col.name);
     if (!columnNames.includes("access_count")) {
@@ -3444,8 +3474,11 @@ var SQLiteEventStore = class {
   /**
    * Get helpfulness statistics for dashboard
    */
-  async getHelpfulnessStats() {
+  async getHelpfulnessStats(since) {
     await this.initialize();
+    const sinceIso = since?.toISOString();
+    const evaluatedWhere = sinceIso ? `WHERE measured_at IS NOT NULL AND datetime(created_at) >= datetime(?)` : `WHERE measured_at IS NOT NULL`;
+    const totalWhere = sinceIso ? `WHERE datetime(created_at) >= datetime(?)` : ``;
     const stats = sqliteGet(
       this.db,
       `SELECT
@@ -3455,11 +3488,13 @@ var SQLiteEventStore = class {
          SUM(CASE WHEN helpfulness_score >= 0.4 AND helpfulness_score < 0.7 THEN 1 ELSE 0 END) as neutral,
          SUM(CASE WHEN helpfulness_score < 0.4 THEN 1 ELSE 0 END) as unhelpful
        FROM memory_helpfulness
-       WHERE measured_at IS NOT NULL`
+       ${evaluatedWhere}`,
+      sinceIso ? [sinceIso] : []
     );
     const totalRow = sqliteGet(
       this.db,
-      `SELECT COUNT(*) as total FROM memory_helpfulness`
+      `SELECT COUNT(*) as total FROM memory_helpfulness ${totalWhere}`,
+      sinceIso ? [sinceIso] : []
     );
     return {
       avgScore: Math.round((stats?.avg_score || 0) * 100) / 100,
@@ -3558,18 +3593,21 @@ var SQLiteEventStore = class {
   async recordRetrievalTrace(input) {
     await this.initialize();
     const traceId = randomUUID5();
+    const queryRewriteKind = normalizeQueryRewriteKind(input.queryRewriteKind);
     sqliteRun(
       this.db,
       `INSERT INTO retrieval_traces (
-        trace_id, session_id, project_hash, query_text, strategy,
+        trace_id, session_id, project_hash, query_text, raw_query_text, query_rewrite_kind, strategy,
         candidate_event_ids, selected_event_ids, candidate_details_json, selected_details_json,
         candidate_count, selected_count, confidence, fallback_trace
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         traceId,
         input.sessionId || null,
         input.projectHash || null,
         input.queryText,
+        input.rawQueryText || null,
+        queryRewriteKind,
         input.strategy || null,
         JSON.stringify(input.candidateEventIds || []),
         JSON.stringify(input.selectedEventIds || []),
@@ -3595,6 +3633,8 @@ var SQLiteEventStore = class {
         sessionId: row.session_id || void 0,
         projectHash: row.project_hash || void 0,
         queryText: row.query_text,
+        rawQueryText: row.raw_query_text || void 0,
+        queryRewriteKind: normalizeQueryRewriteKind(row.query_rewrite_kind),
         strategy: row.strategy || void 0,
         candidateEventIds: row.candidate_event_ids ? JSON.parse(row.candidate_event_ids) : [],
         selectedEventIds: row.selected_event_ids ? JSON.parse(row.selected_event_ids) : [],
@@ -3621,6 +3661,11 @@ var SQLiteEventStore = class {
           COUNT(*) as total_queries,
           AVG(candidate_count) as avg_candidate_count,
           AVG(selected_count) as avg_selected_count,
+          SUM(CASE WHEN ${REWRITTEN_QUERY_REWRITE_KIND_SQL} THEN 1 ELSE 0 END) as rewritten_queries,
+          SUM(CASE WHEN ${REWRITTEN_QUERY_REWRITE_KIND_SQL} AND selected_count > 0 THEN 1 ELSE 0 END) as rewritten_queries_with_selection,
+          SUM(CASE WHEN NOT (${REWRITTEN_QUERY_REWRITE_KIND_SQL}) AND selected_count > 0 THEN 1 ELSE 0 END) as raw_queries_with_selection,
+          AVG(CASE WHEN ${REWRITTEN_QUERY_REWRITE_KIND_SQL} THEN selected_count END) as avg_selected_count_for_rewritten_queries,
+          AVG(CASE WHEN NOT (${REWRITTEN_QUERY_REWRITE_KIND_SQL}) THEN selected_count END) as avg_selected_count_for_raw_queries,
           CASE
             WHEN SUM(candidate_count) > 0 THEN (SUM(selected_count) * 1.0 / SUM(candidate_count))
             ELSE 0
@@ -3628,15 +3673,41 @@ var SQLiteEventStore = class {
          FROM retrieval_traces`,
         []
       );
+      const totalQueries = Number(row?.total_queries || 0);
+      const rewrittenQueries = Number(row?.rewritten_queries || 0);
+      const rawQueries = Math.max(0, totalQueries - rewrittenQueries);
+      const rewrittenQueriesWithSelection = Number(row?.rewritten_queries_with_selection || 0);
+      const rawQueriesWithSelection = Number(row?.raw_queries_with_selection || 0);
       return {
-        totalQueries: Number(row?.total_queries || 0),
+        totalQueries,
         avgCandidateCount: Number(row?.avg_candidate_count || 0),
         avgSelectedCount: Number(row?.avg_selected_count || 0),
-        selectionRate: Number(row?.selection_rate || 0)
+        selectionRate: Number(row?.selection_rate || 0),
+        rewrittenQueries,
+        rewriteRate: totalQueries > 0 ? rewrittenQueries / totalQueries : 0,
+        rewrittenQueriesWithSelection,
+        rawQueriesWithSelection,
+        rewrittenSelectionRate: rewrittenQueries > 0 ? rewrittenQueriesWithSelection / rewrittenQueries : 0,
+        rawSelectionRate: rawQueries > 0 ? rawQueriesWithSelection / rawQueries : 0,
+        avgSelectedCountForRewrittenQueries: Number(row?.avg_selected_count_for_rewritten_queries || 0),
+        avgSelectedCountForRawQueries: Number(row?.avg_selected_count_for_raw_queries || 0)
       };
     } catch (err) {
       if (err?.message?.includes("no such table")) {
-        return { totalQueries: 0, avgCandidateCount: 0, avgSelectedCount: 0, selectionRate: 0 };
+        return {
+          totalQueries: 0,
+          avgCandidateCount: 0,
+          avgSelectedCount: 0,
+          selectionRate: 0,
+          rewrittenQueries: 0,
+          rewriteRate: 0,
+          rewrittenQueriesWithSelection: 0,
+          rawQueriesWithSelection: 0,
+          rewrittenSelectionRate: 0,
+          rawSelectionRate: 0,
+          avgSelectedCountForRewrittenQueries: 0,
+          avgSelectedCountForRawQueries: 0
+        };
       }
       throw err;
     }
@@ -4448,6 +4519,57 @@ var COMMAND_ARTIFACT_PATTERNS = [
   /<local-command-stdout>[\s\S]*?<\/local-command-stdout>/i,
   /<local-command-stderr>[\s\S]*?<\/local-command-stderr>/i
 ];
+var CONTINUATION_QUERY_PATTERNS = [
+  /^\s*(?:continue|resume|next|what(?:'s| is)? next|next\s+(?:step|task|action)|recommended\s+(?:next\s+)?(?:step|task|action)|what should (?:we|i) do next)\??\s*$/i,
+  /^\s*(?:응\s*)?(?:이어서(?:\s*진행(?:해줘)?)?|계속(?:\s*해줘)?|다음\s*(?:단계|작업|추천\s*작업|추천|할\s*일)?(?:은|는)?(?:\s*(?:뭐야|진행(?:해줘)?))?\??|남은\s*(?:추가(?:로)?\s*)?(?:(?:할\s*만한\s*)?(?:작업|일)|할\s*일)?(?:은|는)?\s*(?:있어|있나|있나요|뭐야)\??|추천\s*작업(?:은|는)?(?:\s*뭐야)?\??|진행해줘)\s*$/i
+];
+var SHORT_REPAIR_FOLLOW_UP_PATTERNS = [
+  /^\s*(?:fix\s+(?:it|that)|repair\s+(?:it|that)|resolve\s+(?:it|that)|that\s+bug|same\s+issue)\s*$/i,
+  /^\s*(?:그거|그것|이거|이것)?\s*(?:고쳐줘|수정해줘|해결해줘|처리해줘)\s*$/i
+];
+var CURRENT_STATE_QUERY_PATTERNS = [
+  /\bcurrent\b.*\b(?:state|status|deployment|blocker|pr|pull request)\b/i,
+  /\b(?:still|as current|current)\b.*\b(?:unresolved|open|pending|not completed)\b/i,
+  /\b(?:old|obsolete|stale|resolved|already resolved)\b.*\b(?:current|still|unresolved|open|state|status)\b/i,
+  /(?:현재|아직|이전|오래된|해결된).*(?:상태|미해결|열린|블로커|PR|풀리퀘스트)/i
+];
+var STALE_CONTENT_PATTERNS = [
+  /\b(?:obsolete|superseded|outdated)\b/i,
+  /\bstale\s+(?:operational\s+)?state\b/i,
+  /\bstale\s+after\b/i,
+  /\bno\s+longer\s+(?:valid|current|applies?)\b/i,
+  /\bearlier\s+(?:pull request|pr)\b[\s\S]{0,160}\b(?:open|not completed|had not completed)\b/i,
+  /\bshould\s+not\s+be\s+injected\s+as\s+current\s+context\b/i,
+  /(?:오래된|더 이상 유효하지|현재 상태가 아님)/i
+];
+var CONTINUATION_EXPANSION = "current next step plan roadmap status validation replay rerank memory usefulness continuation";
+var REPAIR_FOLLOW_UP_EXPANSION = "review blocker fix pattern dashboard error state metrics bucket validation sanitize rerun unresolved";
+var RETRIEVAL_PRIVACY_DECISION_EXPANSION = "retrieval telemetry privacy public api dashboard dashboards rawQueryText queryText raw query text expose safe trace metadata trace id reason strategy rewrite kind aggregate count counts candidate selected public panel";
+var DECISION_RECALL_TERMS = /* @__PURE__ */ new Set([
+  "decide",
+  "decided",
+  "decision",
+  "agreed",
+  "policy",
+  "constraint"
+]);
+var RETRIEVAL_PRIVACY_SURFACE_TERMS = /* @__PURE__ */ new Set([
+  "retrieval",
+  "dashboard",
+  "telemetry",
+  "trace"
+]);
+var DECISION_TOPIC_WEAK_TERMS = /* @__PURE__ */ new Set([
+  "api",
+  "dashboard",
+  "retrieval",
+  "trace",
+  "telemetry",
+  "query",
+  "raw",
+  "count",
+  "counts"
+]);
 var GENERIC_TECHNICAL_TERMS = /* @__PURE__ */ new Set([
   "api",
   "cli",
@@ -4465,6 +4587,87 @@ var GENERIC_TECHNICAL_TERMS = /* @__PURE__ */ new Set([
   "db",
   "sql"
 ]);
+var LOW_INFORMATION_QUERY_TERMS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "or",
+  "for",
+  "from",
+  "with",
+  "without",
+  "about",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why",
+  "how",
+  "did",
+  "does",
+  "do",
+  "we",
+  "i",
+  "in",
+  "to",
+  "of",
+  "on",
+  "as",
+  "be",
+  "was",
+  "were",
+  "decide",
+  "decided",
+  "decision",
+  "agreed",
+  "policy",
+  "constraint",
+  "showing",
+  "can",
+  "you",
+  "me",
+  "show",
+  "tell",
+  "please",
+  "should",
+  "would",
+  "could",
+  "this",
+  "that",
+  "these",
+  "those",
+  "use",
+  "using",
+  "treat",
+  "continue",
+  "resume",
+  "next",
+  "step",
+  "task",
+  "action",
+  "current",
+  "state",
+  "status",
+  "old",
+  "already",
+  "still",
+  "near",
+  "today",
+  "\uC751",
+  "\uADF8\uAC70",
+  "\uADF8\uAC83",
+  "\uC774\uAC70",
+  "\uC774\uAC83",
+  "\uB2E4\uC74C",
+  "\uB2E8\uACC4",
+  "\uC9C4\uD589",
+  "\uC9C4\uD589\uD574\uC918",
+  "\uACC4\uC18D",
+  "\uC774\uC5B4\uC11C",
+  "\uACE0\uCCD0\uC918",
+  "\uC218\uC815\uD574\uC918",
+  "\uD574\uACB0\uD574\uC918"
+]);
 function isCommandArtifactQuery(query) {
   const trimmed = query.trim();
   if (!trimmed)
@@ -4476,6 +4679,73 @@ function isCommandArtifactQuery(query) {
     return true;
   return COMMAND_ARTIFACT_PATTERNS.some((pattern) => pattern.test(trimmed));
 }
+function isGenericContinuationQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed)
+    return false;
+  if (!CONTINUATION_QUERY_PATTERNS.some((pattern) => pattern.test(trimmed)))
+    return false;
+  if (extractTechnicalQueryTerms(trimmed).length > 0)
+    return false;
+  const tokens = trimmed.match(/[A-Za-z0-9가-힣#._/-]+/g) ?? [];
+  if (tokens.length > 10)
+    return false;
+  return !/[A-Za-z0-9_-]+\.[A-Za-z0-9]+/.test(trimmed) && !/(?:^|\s)(?:feat|fix|chore|refactor|docs)\/[A-Za-z0-9._-]+/.test(trimmed) && !/[A-Za-z]:?[\\/]|\/Users\/|\.\/|\.\.\//.test(trimmed);
+}
+function isShortRepairFollowUpQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed)
+    return false;
+  if (extractTechnicalQueryTerms(trimmed).length > 0)
+    return false;
+  const tokens = trimmed.match(/[A-Za-z0-9가-힣#._/-]+/g) ?? [];
+  if (tokens.length > 8)
+    return false;
+  return SHORT_REPAIR_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+function isCurrentStateQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed)
+    return false;
+  return CURRENT_STATE_QUERY_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+function isStaleOrSupersededContent(content) {
+  const trimmed = content.trim();
+  if (!trimmed)
+    return false;
+  return STALE_CONTENT_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+function buildRetrievalQualityQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed)
+    return query;
+  if (isRetrievalPrivacyDecisionQuery(trimmed)) {
+    return `${trimmed} ${RETRIEVAL_PRIVACY_DECISION_EXPANSION}`;
+  }
+  if (isGenericContinuationQuery(trimmed)) {
+    return `${trimmed} ${CONTINUATION_EXPANSION}`;
+  }
+  if (isShortRepairFollowUpQuery(trimmed)) {
+    return `${trimmed} ${REPAIR_FOLLOW_UP_EXPANSION}`;
+  }
+  return query;
+}
+function isRetrievalPrivacyDecisionQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed)
+    return false;
+  const terms = new Set(tokenizeQualityText(trimmed));
+  const hasDecisionSignal = hasAnyTerm(terms, DECISION_RECALL_TERMS) || /(?:결정|정책|원칙)/i.test(trimmed);
+  if (!hasDecisionSignal)
+    return false;
+  const hasRawQuerySignal = terms.has("raw") && terms.has("query");
+  const hasPrivacySignal = terms.has("privacy") || terms.has("expose") || terms.has("redacted");
+  const hasRetrievalSurface = hasAnyTerm(terms, RETRIEVAL_PRIVACY_SURFACE_TERMS) || terms.has("api") && terms.has("query");
+  const hasQuerySurface = terms.has("query") && (terms.has("dashboard") || terms.has("trace") || terms.has("telemetry") || terms.has("api"));
+  const hasKoreanRetrievalSurface = /(?:검색|리트리벌|retrieval|대시보드|트레이스|텔레메트리|telemetry)/i.test(trimmed);
+  const hasKoreanPrivacySurface = /(?:원문|쿼리|프라이버시|개인정보|노출|트레이스|메타데이터)/i.test(trimmed);
+  return (hasRetrievalSurface || hasKoreanRetrievalSurface && hasKoreanPrivacySurface) && (hasRawQuerySignal || hasPrivacySignal || hasQuerySurface || hasKoreanPrivacySurface);
+}
 function extractTechnicalQueryTerms(query) {
   const matches = query.match(/[A-Za-z][A-Za-z0-9_.:-]{2,}/g) ?? [];
   const terms = matches.filter((term) => {
@@ -4493,9 +4763,87 @@ function hasTechnicalTermOverlap(query, content) {
   const normalizedContent = content.toLowerCase();
   return terms.some((term) => normalizedContent.includes(term));
 }
+function hasDiscriminativeTermOverlap(query, content) {
+  const queryTerms = extractDiscriminativeQueryTerms(query);
+  const contentTerms = new Set(tokenizeQualityText(content));
+  if (isRetrievalPrivacyDecisionQuery(query) && hasRetrievalPrivacyDecisionContent(contentTerms)) {
+    return true;
+  }
+  if (shouldRequireDecisionTopicOverlap(query)) {
+    const topicTerms = queryTerms.filter((term) => !DECISION_TOPIC_WEAK_TERMS.has(term));
+    if (topicTerms.length > 0) {
+      return topicTerms.some((term) => contentTerms.has(term));
+    }
+  }
+  if (queryTerms.length < 3)
+    return true;
+  const requiredHits = queryTerms.length >= 3 ? 2 : 1;
+  let hits = 0;
+  for (const term of queryTerms) {
+    if (contentTerms.has(term))
+      hits += 1;
+    if (hits >= requiredHits)
+      return true;
+  }
+  return false;
+}
 function shouldApplyTechnicalGuard(query) {
   return extractTechnicalQueryTerms(query).length > 0;
 }
+function hasAnyTerm(terms, expectedTerms) {
+  let found = false;
+  expectedTerms.forEach((term) => {
+    if (terms.has(term))
+      found = true;
+  });
+  return found;
+}
+function shouldRequireDecisionTopicOverlap(query) {
+  if (isRetrievalPrivacyDecisionQuery(query))
+    return false;
+  const trimmed = query.trim();
+  if (!trimmed)
+    return false;
+  const terms = new Set(tokenizeQualityText(trimmed));
+  return hasAnyTerm(terms, DECISION_RECALL_TERMS) || /(?:결정|정책|원칙)/i.test(trimmed);
+}
+function extractDiscriminativeQueryTerms(query) {
+  const seen = /* @__PURE__ */ new Set();
+  const terms = [];
+  for (const token of tokenizeQualityText(query)) {
+    if (LOW_INFORMATION_QUERY_TERMS.has(token))
+      continue;
+    if (GENERIC_TECHNICAL_TERMS.has(token))
+      continue;
+    if (seen.has(token))
+      continue;
+    seen.add(token);
+    terms.push(token);
+  }
+  return terms;
+}
+function hasRetrievalPrivacyDecisionContent(contentTerms) {
+  const hasDashboardTraceMetadata = contentTerms.has("dashboard") && (contentTerms.has("trace") || contentTerms.has("metadata")) && (contentTerms.has("safe") || contentTerms.has("strategy") || contentTerms.has("rewrite") || contentTerms.has("candidate") || contentTerms.has("selected") || contentTerms.has("count") || contentTerms.has("reason"));
+  const hasRawQueryPrivacyPolicy = contentTerms.has("retrieval") && (contentTerms.has("privacy") || contentTerms.has("expose") || contentTerms.has("raw") && contentTerms.has("query") && (contentTerms.has("dashboard") || contentTerms.has("telemetry") || contentTerms.has("api") || contentTerms.has("public")));
+  return hasDashboardTraceMetadata || hasRawQueryPrivacyPolicy;
+}
+function tokenizeQualityText(text) {
+  return text.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().replace(/[^A-Za-z0-9가-힣\s_.:-]/g, " ").split(/\s+/).flatMap((token) => token.split(/(?=[._:-])|(?<=[._:-])/g)).map((token) => normalizeQualityToken(token.replace(/^[._:-]+|[._:-]+$/g, ""))).filter((token) => token.length >= 2);
+}
+function normalizeQualityToken(token) {
+  if (token === "apis")
+    return "api";
+  if (token === "ids")
+    return "id";
+  if (LOW_INFORMATION_QUERY_TERMS.has(token) || GENERIC_TECHNICAL_TERMS.has(token))
+    return token;
+  if (token.length > 4 && token.endsWith("ies"))
+    return `${token.slice(0, -3)}y`;
+  if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss") && !token.endsWith("us") && !token.endsWith("is")) {
+    return token.slice(0, -1);
+  }
+  return token;
+}
 
 // src/core/retriever.ts
 var DEFAULT_OPTIONS = {
@@ -4548,6 +4896,7 @@ var Retriever = class {
     const opts = { ...DEFAULT_OPTIONS, ...options };
     const sessionFilter = opts.scope?.sessionId ?? opts.sessionId;
     const fallbackTrace = [];
+    const qualityQuery = buildRetrievalQualityQuery(query);
     if (isCommandArtifactQuery(query)) {
       fallbackTrace.push("guard:command-artifact-query");
       const emptyMatch = this.matcher.matchSearchResults([], () => 0);
@@ -4564,6 +4913,7 @@ var Retriever = class {
     const fallbackEnabled = (opts.strategy ?? "auto") === "auto";
     const primaryStrategy = opts.strategy === "auto" ? "fast" : opts.strategy || "fast";
     let current = await this.runStage(query, {
+      qualityQuery,
       strategy: primaryStrategy,
       topK: opts.topK,
       minScore: opts.minScore,
@@ -4581,6 +4931,7 @@ var Retriever = class {
     fallbackTrace.push(`stage:primary:${primaryStrategy}`);
     if (fallbackEnabled && this.shouldFallback(current.matchResult, current.results) && primaryStrategy !== "deep") {
       current = await this.runStage(query, {
+        qualityQuery,
         strategy: "deep",
         topK: opts.topK,
         minScore: opts.minScore,
@@ -4598,6 +4949,7 @@ var Retriever = class {
     }
     if (fallbackEnabled && this.shouldFallback(current.matchResult, current.results)) {
       current = await this.runStage(query, {
+        qualityQuery,
         strategy: "deep",
         topK: opts.topK,
         minScore: Math.max(0.5, opts.minScore - 0.15),
@@ -4614,11 +4966,21 @@ var Retriever = class {
       fallbackTrace.push("fallback:scope-expanded");
     }
     if (fallbackEnabled && this.shouldFallback(current.matchResult, current.results)) {
-      const summary = await this.buildSummaryFallback(query, opts.topK);
+      const summary = await this.buildSummaryFallback(qualityQuery, opts.topK);
+      const scopedSummary = await this.applyScopeFilters(summary, {
+        scope: opts.scope,
+        projectScopeMode: opts.projectScopeMode,
+        projectHash: opts.projectHash,
+        allowedProjectHashes: opts.allowedProjectHashes
+      });
+      const filteredSummary = this.applyQualityFilters(scopedSummary, {
+        query,
+        minScore: opts.minScore
+      });
       current = {
-        results: summary,
-        candidateResults: summary,
-        matchResult: this.matcher.matchSearchResults(summary, () => 0)
+        results: filteredSummary,
+        candidateResults: filteredSummary,
+        matchResult: this.matcher.matchSearchResults(filteredSummary, () => 0)
       };
       fallbackTrace.push("fallback:summary");
     }
@@ -4643,7 +5005,10 @@ var Retriever = class {
         semanticScore: r.semanticScore,
         lexicalScore: r.lexicalScore,
         recencyScore: r.recencyScore
-      }))
+      })),
+      rawQueryText: current.queryRewriteKind ? query : void 0,
+      effectiveQueryText: current.effectiveQueryText,
+      queryRewriteKind: current.queryRewriteKind
     };
   }
   async retrieveUnified(query, options = {}) {
@@ -4681,8 +5046,11 @@ var Retriever = class {
     }
   }
   async runStage(query, input) {
-    let rerankQuery = query;
-    let initialResults = await this.searchByStrategy(query, {
+    const searchQuery = input.qualityQuery ?? query;
+    let rerankQuery = searchQuery;
+    let effectiveQueryText;
+    let queryRewriteKind;
+    let initialResults = await this.searchByStrategy(searchQuery, {
       strategy: input.strategy,
       topK: input.topK,
       minScore: input.minScore,
@@ -4690,9 +5058,12 @@ var Retriever = class {
     });
     if (input.intentRewrite && input.strategy === "deep" && this.queryRewriter) {
       const rewritten = (await this.queryRewriter(query))?.trim();
-      if (rewritten && rewritten !== query) {
-        rerankQuery = `${query} ${rewritten}`;
-        const rewrittenResults = await this.searchByStrategy(rewritten, {
+      const normalizedQuery = query.trim();
+      if (rewritten && rewritten !== normalizedQuery) {
+        effectiveQueryText = `${normalizedQuery} ${rewritten}`.trim();
+        queryRewriteKind = "intent-rewrite";
+        rerankQuery = buildRetrievalQualityQuery(effectiveQueryText);
+        const rewrittenResults = await this.searchByStrategy(buildRetrievalQualityQuery(rewritten), {
           strategy: "deep",
           topK: input.topK,
           minScore: Math.max(0.5, input.minScore - 0.1),
@@ -4719,10 +5090,14 @@ var Retriever = class {
     });
     const top = qualityFiltered.slice(0, input.topK);
     const matchResult = this.matcher.matchSearchResults(top, () => 0);
-    return { results: top, candidateResults: qualityFiltered, matchResult };
+    return { results: top, candidateResults: qualityFiltered, matchResult, effectiveQueryText, queryRewriteKind };
   }
   applyQualityFilters(results, options) {
     let filtered = [...results];
+    if (isCurrentStateQuery(options.query)) {
+      filtered = filtered.filter((result) => !isStaleOrSupersededContent(result.content));
+    }
+    filtered = filtered.filter((result) => hasDiscriminativeTermOverlap(options.query, result.content));
     if (shouldApplyTechnicalGuard(options.query)) {
       filtered = filtered.filter((result) => hasTechnicalTermOverlap(options.query, result.content));
     }
@@ -5030,7 +5405,21 @@ _Context:_ ${sessionContext}`;
     });
   }
   tokenize(text) {
-    return text.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).filter((t) => t.length >= 2).slice(0, 64);
+    return text.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).map((token) => this.normalizeToken(token)).filter((t) => t.length >= 2).slice(0, 64);
+  }
+  normalizeToken(token) {
+    if (token === "apis")
+      return "api";
+    if (token === "ids")
+      return "id";
+    if (token === "does")
+      return token;
+    if (token.length > 4 && token.endsWith("ies"))
+      return `${token.slice(0, -3)}y`;
+    if (token.length > 3 && token.endsWith("s") && !token.endsWith("ss") && !token.endsWith("us") && !token.endsWith("is") && !token.endsWith("ps")) {
+      return token.slice(0, -1);
+    }
+    return token;
   }
   keywordOverlap(a, b) {
     if (a.length === 0 || b.length === 0)
@@ -5093,9 +5482,9 @@ var RetrievalAnalyticsService = class {
     await this.deps.initialize();
     return this.deps.retrievalStore.getHelpfulMemories(limit);
   }
-  async getHelpfulnessStats() {
+  async getHelpfulnessStats(since) {
     await this.deps.initialize();
-    return this.deps.retrievalStore.getHelpfulnessStats();
+    return this.deps.retrievalStore.getHelpfulnessStats(since);
   }
   /**
    * Extract topic keywords from event content (markdown headings and key terms).
@@ -5520,7 +5909,9 @@ var RetrievalOrchestrator = class {
     await this.deps.traceStore.recordRetrievalTrace({
       sessionId: options?.sessionId,
       projectHash: projectHash || void 0,
-      queryText: query,
+      queryText: result.effectiveQueryText || query,
+      rawQueryText: result.rawQueryText || (result.queryRewriteKind ? query : void 0),
+      queryRewriteKind: result.queryRewriteKind || "none",
       strategy: options?.strategy || "auto",
       candidateEventIds,
       selectedEventIds,
@@ -7514,8 +7905,8 @@ var MemoryService = class {
   /**
    * Get helpfulness statistics for dashboard
    */
-  async getHelpfulnessStats() {
-    return this.retrievalAnalyticsService.getHelpfulnessStats();
+  async getHelpfulnessStats(since) {
+    return this.retrievalAnalyticsService.getHelpfulnessStats(since);
   }
   /**
    * Mark a consolidated memory as accessed
@@ -8070,6 +8461,346 @@ function computeSessionTurnCount(sessionEvents) {
     return turnIds.size;
   return sessionEvents.filter((e) => e.eventType === "user_prompt").length;
 }
+function normalizeQueryRewriteKind2(value) {
+  const normalized = (value || "").trim().toLowerCase();
+  if (normalized === "follow-up-context" || normalized === "intent-rewrite")
+    return normalized;
+  return "none";
+}
+function normalizeMetric(value) {
+  const numberValue = Number(value || 0);
+  if (!Number.isFinite(numberValue))
+    return 0;
+  return Math.max(0, Math.min(1, numberValue));
+}
+function getTimestampMs(value) {
+  if (value instanceof Date)
+    return value.getTime();
+  if (typeof value === "string") {
+    const parsed = new Date(value).getTime();
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+}
+function isRewrittenRetrievalTrace(trace) {
+  return normalizeQueryRewriteKind2(trace.queryRewriteKind) !== "none";
+}
+function getTraceSelectedCount(trace) {
+  return Number(trace.selectedCount ?? trace.selectedEventIds?.length ?? 0);
+}
+function getTraceCandidateCount(trace) {
+  return Number(trace.candidateCount ?? trace.candidateEventIds?.length ?? trace.candidateDetails?.length ?? 0);
+}
+function makeRetrievalReviewItem(trace) {
+  const candidateCount = getTraceCandidateCount(trace);
+  const selectedCount = getTraceSelectedCount(trace);
+  const queryRewriteKind = normalizeQueryRewriteKind2(trace.queryRewriteKind);
+  const rewritten = queryRewriteKind !== "none";
+  const createdAtMs = getTimestampMs(trace.createdAt);
+  const createdAt = createdAtMs > 0 ? new Date(createdAtMs).toISOString() : (/* @__PURE__ */ new Date(0)).toISOString();
+  let reason = null;
+  let severity = "info";
+  let priority = 0;
+  let title = "";
+  let detail = "";
+  let action = "";
+  if (candidateCount > 0 && selectedCount === 0 && rewritten) {
+    reason = "rewritten-query-no-selection";
+    severity = "warn";
+    priority = 100;
+    title = "Rewritten query selected no memories";
+    detail = `${candidateCount} candidates were found after query rewrite, but no memory was selected.`;
+    action = "Review rewrite wording, rerank scores, and final selection thresholds for this trace.";
+  } else if (candidateCount > 0 && selectedCount === 0) {
+    reason = "candidate-no-selection";
+    severity = "warn";
+    priority = 90;
+    title = "Candidates found but nothing selected";
+    detail = `${candidateCount} candidates were available, but the final selection injected no memory.`;
+    action = "Review rerank thresholds and candidate filtering; consider overfetching before final selection.";
+  } else if (candidateCount === 0) {
+    reason = "empty-candidate-set";
+    severity = "info";
+    priority = 70;
+    title = "Retrieval found no candidates";
+    detail = "The retrieval pipeline returned no candidate memories for this trace.";
+    action = "Check trigger/query rewrite coverage and whether the project has indexed memories for this topic.";
+  } else if (candidateCount >= 10 && safeRatio(selectedCount, candidateCount) < 0.15) {
+    reason = "low-selection-rate";
+    severity = "info";
+    priority = 60;
+    title = "Low selection ratio from many candidates";
+    detail = `${selectedCount} of ${candidateCount} candidates were selected.`;
+    action = "Inspect score distribution and MMR/diversity settings before lowering thresholds.";
+  }
+  if (!reason)
+    return null;
+  return {
+    traceId: trace.traceId || "unknown-trace",
+    reason,
+    severity,
+    priority,
+    title,
+    detail,
+    action,
+    queryRewriteKind,
+    rewritten,
+    strategy: trace.strategy || null,
+    candidateCount,
+    selectedCount,
+    candidateEventIds: (trace.candidateEventIds || []).slice(0, 5),
+    selectedEventIds: (trace.selectedEventIds || []).slice(0, 5),
+    candidateDetails: (trace.candidateDetails || []).slice(0, 3).map((detail2) => ({
+      eventId: detail2.eventId,
+      score: detail2.score,
+      semanticScore: detail2.semanticScore,
+      lexicalScore: detail2.lexicalScore,
+      recencyScore: detail2.recencyScore
+    })),
+    selectedDetails: (trace.selectedDetails || []).slice(0, 3).map((detail2) => ({
+      eventId: detail2.eventId,
+      score: detail2.score,
+      semanticScore: detail2.semanticScore,
+      lexicalScore: detail2.lexicalScore,
+      recencyScore: detail2.recencyScore
+    })),
+    createdAt
+  };
+}
+function buildRetrievalReviewQueue(traces, limit) {
+  const reviewItems = traces.map(makeRetrievalReviewItem).filter((item) => item !== null).sort((a, b) => b.priority - a.priority || new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+  return {
+    summary: {
+      totalTraces: traces.length,
+      reviewItems: reviewItems.length,
+      returnedItems: Math.min(reviewItems.length, limit),
+      candidateNoSelection: reviewItems.filter((item) => item.reason === "candidate-no-selection").length,
+      emptyCandidateSet: reviewItems.filter((item) => item.reason === "empty-candidate-set").length,
+      rewrittenNoSelection: reviewItems.filter((item) => item.reason === "rewritten-query-no-selection").length,
+      lowSelectionRate: reviewItems.filter((item) => item.reason === "low-selection-rate").length
+    },
+    items: reviewItems.slice(0, limit)
+  };
+}
+function parseStatsLimit(value, fallback, max) {
+  if (!value)
+    return fallback;
+  if (!/^\d+$/.test(value))
+    return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return fallback;
+  return Math.min(parsed, max);
+}
+function usefulnessScoreLabel(score, confidence) {
+  if (confidence <= 0)
+    return "unknown";
+  if (score >= 80)
+    return "excellent";
+  if (score >= 60)
+    return "good";
+  if (score >= 40)
+    return "watch";
+  return "low";
+}
+function buildMemoryUsefulnessDiagnostics(input) {
+  const { metrics, counts } = input;
+  const diagnostics = [];
+  if (counts.promptCount > 0 && counts.retrievalQueries === 0) {
+    diagnostics.push({
+      key: "no-retrieval-traces",
+      severity: "warn",
+      metric: "retrievalUsageRate",
+      value: 0,
+      target: 0.5,
+      title: "No retrieval traces were recorded",
+      detail: `${counts.promptCount} prompts were seen, but none produced a retrieval trace in this window.`,
+      action: "Confirm the prompt hook is enabled and broaden adherence triggers for continuation, write-intent, and project-specific prompts."
+    });
+  }
+  if (counts.promptCount > 0 && metrics.memoryHitRate < 0.5) {
+    diagnostics.push({
+      key: "low-memory-hit-rate",
+      severity: "warn",
+      metric: "memoryHitRate",
+      value: metrics.memoryHitRate,
+      target: 0.5,
+      title: "Memory checks are missing many prompts",
+      detail: `Only ${counts.memoryCheckedPrompts} of ${counts.promptCount} prompts had an adherence check in this window.`,
+      action: "Broaden adherence triggers for continuation, write-intent, topic-shift, and project-specific prompts."
+    });
+  }
+  if (counts.retrievalQueries > 0 && metrics.queryYieldRate < 0.6) {
+    diagnostics.push({
+      key: "low-query-yield-rate",
+      severity: "warn",
+      metric: "queryYieldRate",
+      value: metrics.queryYieldRate,
+      target: 0.6,
+      title: "Searches often select no memory",
+      detail: `${counts.queriesWithSelected} of ${counts.retrievalQueries} retrieval queries injected at least one memory.`,
+      action: "Overfetch candidates, then filter/rerank before applying the final injection threshold."
+    });
+  }
+  if (counts.totalEvaluated > 0 && metrics.avgHelpfulnessScore < 0.7) {
+    diagnostics.push({
+      key: "low-helpfulness-score",
+      severity: "warn",
+      metric: "avgHelpfulnessScore",
+      value: metrics.avgHelpfulnessScore,
+      target: 0.7,
+      title: "Injected memories are not translating into outcomes",
+      detail: `${counts.totalEvaluated} evaluated retrievals averaged ${(metrics.avgHelpfulnessScore * 100).toFixed(1)}% helpfulness.`,
+      action: "Review low-scoring retrieval samples for stale decisions, cross-project noise, or raw transcript snippets."
+    });
+  }
+  if (counts.totalRetrievals > 0 && metrics.evaluationCoverage < 0.8) {
+    diagnostics.push({
+      key: "low-evaluation-coverage",
+      severity: "info",
+      metric: "evaluationCoverage",
+      value: metrics.evaluationCoverage,
+      target: 0.8,
+      title: "Many retrievals are still unevaluated",
+      detail: `${counts.totalEvaluated} of ${counts.totalRetrievals} retrievals have measured helpfulness.`,
+      action: "Ensure Stop/session-end hooks or pending-session backfill are running so usefulness reflects real outcomes."
+    });
+  }
+  if (counts.candidateMemories > 0 && counts.selectedMemories === 0) {
+    diagnostics.push({
+      key: "candidates-without-selection",
+      severity: "warn",
+      metric: "selectionRate",
+      value: metrics.selectionRate,
+      target: 0.2,
+      title: "Candidates are found but none are injected",
+      detail: `${counts.candidateMemories} candidates were retrieved, but no memories passed the injection policy.`,
+      action: "Inspect threshold settings and prompt-injection policy before lowering filters globally."
+    });
+  }
+  return diagnostics.slice(0, 3);
+}
+function computeMemoryUsefulnessSummary(events, helpfulness, traces, now, window, limits = {}) {
+  const windowEvents = events.filter((event) => inWindow(event, now, window));
+  const prompts = windowEvents.filter((event) => event.eventType === "user_prompt");
+  const promptCount = prompts.length;
+  const memoryCheckedPrompts = prompts.filter((prompt) => prompt.metadata?.adherence?.checked).length;
+  const windowMs = windowToMs(window);
+  const windowStart = now - windowMs;
+  const windowTraces = traces.filter((trace) => {
+    const ts = getTimestampMs(trace.createdAt);
+    return ts > 0 && ts >= windowStart;
+  });
+  const oldestEventTimestamp = events.reduce((oldest, event) => {
+    const timestamp = event.timestamp?.getTime?.() || 0;
+    return timestamp > 0 ? Math.min(oldest, timestamp) : oldest;
+  }, Number.POSITIVE_INFINITY);
+  const oldestTraceTimestamp = traces.reduce((oldest, trace) => {
+    const timestamp = getTimestampMs(trace.createdAt);
+    return timestamp > 0 ? Math.min(oldest, timestamp) : oldest;
+  }, Number.POSITIVE_INFINITY);
+  const eventWindowTruncated = Boolean(
+    limits.eventsLimit && events.length >= limits.eventsLimit && Number.isFinite(oldestEventTimestamp) && oldestEventTimestamp >= windowStart
+  );
+  const traceWindowTruncated = Boolean(
+    limits.tracesLimit && traces.length >= limits.tracesLimit && Number.isFinite(oldestTraceTimestamp) && oldestTraceTimestamp >= windowStart
+  );
+  const retrievalQueries = windowTraces.length;
+  const candidateCounts = windowTraces.map((trace) => Number(trace.candidateCount ?? trace.candidateEventIds?.length ?? 0));
+  const selectedCounts = windowTraces.map((trace) => getTraceSelectedCount(trace));
+  const totalCandidateCount = candidateCounts.reduce((sum, count) => sum + (Number.isFinite(count) ? count : 0), 0);
+  const totalSelectedCount = selectedCounts.reduce((sum, count) => sum + (Number.isFinite(count) ? count : 0), 0);
+  const queriesWithSelected = selectedCounts.filter((count) => Number.isFinite(count) && count > 0).length;
+  const rewrittenTraces = windowTraces.filter(isRewrittenRetrievalTrace);
+  const rawTraces = windowTraces.filter((trace) => !isRewrittenRetrievalTrace(trace));
+  const rewrittenQueries = rewrittenTraces.length;
+  const rawQueries = rawTraces.length;
+  const rewrittenSelectedCount = rewrittenTraces.reduce((sum, trace) => {
+    const selectedCount = getTraceSelectedCount(trace);
+    return sum + (Number.isFinite(selectedCount) ? selectedCount : 0);
+  }, 0);
+  const rawSelectedCount = rawTraces.reduce((sum, trace) => {
+    const selectedCount = getTraceSelectedCount(trace);
+    return sum + (Number.isFinite(selectedCount) ? selectedCount : 0);
+  }, 0);
+  const rewrittenQueriesWithSelected = rewrittenTraces.filter((trace) => getTraceSelectedCount(trace) > 0).length;
+  const rawQueriesWithSelected = rawTraces.filter((trace) => getTraceSelectedCount(trace) > 0).length;
+  const totalEvaluated = Number(helpfulness.totalEvaluated || 0);
+  const totalRetrievals = Number(helpfulness.totalRetrievals || 0);
+  const helpful = Number(helpfulness.helpful || 0);
+  const neutral = Number(helpfulness.neutral || 0);
+  const unhelpful = Number(helpfulness.unhelpful || 0);
+  const retrievalsPerPrompt = safeRatio(retrievalQueries, promptCount);
+  const metrics = {
+    avgHelpfulnessScore: round(normalizeMetric(helpfulness.avgScore)),
+    usefulRecallRate: round(safeRatio(helpful, totalEvaluated)),
+    memoryHitRate: round(safeRatio(memoryCheckedPrompts, promptCount)),
+    retrievalUsageRate: round(Math.min(1, retrievalsPerPrompt)),
+    queryYieldRate: round(safeRatio(queriesWithSelected, retrievalQueries)),
+    evaluationCoverage: round(safeRatio(totalEvaluated, totalRetrievals)),
+    retrievalsPerPrompt: round(retrievalsPerPrompt),
+    avgCandidatesPerQuery: round(safeRatio(totalCandidateCount, retrievalQueries), 2),
+    avgSelectedPerQuery: round(safeRatio(totalSelectedCount, retrievalQueries), 2),
+    selectionRate: round(safeRatio(totalSelectedCount, totalCandidateCount)),
+    queryRewriteRate: round(safeRatio(rewrittenQueries, retrievalQueries)),
+    rewrittenQueryYieldRate: round(safeRatio(rewrittenQueriesWithSelected, rewrittenQueries)),
+    rawQueryYieldRate: round(safeRatio(rawQueriesWithSelected, rawQueries)),
+    avgSelectedPerRewrittenQuery: round(safeRatio(rewrittenSelectedCount, rewrittenQueries), 2),
+    avgSelectedPerRawQuery: round(safeRatio(rawSelectedCount, rawQueries), 2)
+  };
+  const counts = {
+    promptCount,
+    memoryCheckedPrompts,
+    retrievalQueries,
+    queriesWithSelected,
+    rewrittenQueries,
+    rawQueries,
+    rewrittenQueriesWithSelected,
+    rawQueriesWithSelected,
+    selectedMemories: totalSelectedCount,
+    candidateMemories: totalCandidateCount,
+    totalEvaluated,
+    totalRetrievals,
+    helpful,
+    neutral,
+    unhelpful
+  };
+  const componentSpecs = [
+    { key: "avgHelpfulnessScore", label: "Average helpfulness score", value: metrics.avgHelpfulnessScore, weight: 0.3, available: totalEvaluated > 0 },
+    { key: "usefulRecallRate", label: "Useful recall rate", value: metrics.usefulRecallRate, weight: 0.25, available: totalEvaluated > 0 },
+    { key: "memoryHitRate", label: "Memory hit rate", value: metrics.memoryHitRate, weight: 0.2, available: promptCount > 0 },
+    { key: "retrievalUsageRate", label: "Retrieval usage rate", value: metrics.retrievalUsageRate, weight: 0.15, available: promptCount > 0 },
+    { key: "queryYieldRate", label: "Query yield rate", value: metrics.queryYieldRate, weight: 0.1, available: retrievalQueries > 0 }
+  ];
+  const totalWeight = componentSpecs.reduce((sum, component) => sum + component.weight, 0);
+  const availableWeight = componentSpecs.filter((component) => component.available).reduce((sum, component) => sum + component.weight, 0);
+  const weightedScore = availableWeight > 0 ? componentSpecs.reduce((sum, component) => sum + (component.available ? component.value * component.weight : 0), 0) / availableWeight : 0;
+  const scoreValue = round(weightedScore * 100, 1);
+  const confidence = round(safeRatio(availableWeight, totalWeight), 2);
+  const components = componentSpecs.map((component) => ({
+    ...component,
+    contribution: component.available ? round(component.value * component.weight * 100, 2) : 0
+  }));
+  return {
+    window,
+    score: {
+      value: scoreValue,
+      label: usefulnessScoreLabel(scoreValue, confidence),
+      confidence
+    },
+    metrics,
+    counts,
+    components,
+    diagnostics: buildMemoryUsefulnessDiagnostics({ metrics, counts }),
+    limits: {
+      eventsLimit: limits.eventsLimit || events.length,
+      tracesLimit: limits.tracesLimit || traces.length,
+      eventWindowTruncated,
+      traceWindowTruncated
+    },
+    generatedAt: new Date(now).toISOString()
+  };
+}
 function computeKpiMetrics(events, usefulRecallRate) {
   const prompts = events.filter((e) => e.eventType === "user_prompt");
   const promptCount = prompts.length;
@@ -8396,6 +9127,32 @@ statsRouter.get("/helpfulness", async (c) => {
     await memoryService.shutdown();
   }
 });
+statsRouter.get("/usefulness", async (c) => {
+  const rawWindow = c.req.query("window") || "7d";
+  const window = rawWindow === "24h" || rawWindow === "30d" ? rawWindow : "7d";
+  const memoryService = getLightweightServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const now = Date.now();
+    const eventLimit = 2e4;
+    const traceLimit = 5e3;
+    const windowStart = new Date(now - windowToMs(window));
+    const [events, helpfulness, traces] = await Promise.all([
+      memoryService.getRecentEvents(eventLimit),
+      memoryService.getHelpfulnessStats(windowStart),
+      memoryService.getRecentRetrievalTraces(traceLimit)
+    ]);
+    return c.json(computeMemoryUsefulnessSummary(events, helpfulness, traces, now, window, {
+      eventsLimit: eventLimit,
+      tracesLimit: traceLimit
+    }));
+  } catch (error) {
+    console.error("[stats/usefulness] failed to calculate dashboard metrics", error);
+    return c.json({ error: "Unable to calculate memory usefulness statistics" }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
 statsRouter.get("/retrieval-traces", async (c) => {
   const limit = parseInt(c.req.query("limit") || "50", 10);
   const memoryService = getServiceFromQuery(c);
@@ -8405,26 +9162,43 @@ statsRouter.get("/retrieval-traces", async (c) => {
     const traceStats = await memoryService.getRetrievalTraceStats();
     return c.json({
       stats: traceStats,
-      traces: traces.map((t) => ({
-        traceId: t.traceId,
-        sessionId: t.sessionId || null,
-        projectHash: t.projectHash || null,
-        queryText: t.queryText,
-        strategy: t.strategy || null,
-        candidateEventIds: t.candidateEventIds,
-        selectedEventIds: t.selectedEventIds,
-        candidateDetails: t.candidateDetails || [],
-        selectedDetails: t.selectedDetails || [],
-        candidateCount: t.candidateCount,
-        selectedCount: t.selectedCount,
-        confidence: t.confidence || null,
-        fallbackTrace: t.fallbackTrace,
-        createdAt: t.createdAt.toISOString()
-      }))
+      traces: traces.map((t) => {
+        const queryRewriteKind = normalizeQueryRewriteKind2(t.queryRewriteKind);
+        return {
+          traceId: t.traceId,
+          sessionId: t.sessionId || null,
+          projectHash: t.projectHash || null,
+          queryRewriteKind,
+          rewritten: queryRewriteKind !== "none",
+          strategy: t.strategy || null,
+          candidateEventIds: t.candidateEventIds,
+          selectedEventIds: t.selectedEventIds,
+          candidateDetails: t.candidateDetails || [],
+          selectedDetails: t.selectedDetails || [],
+          candidateCount: t.candidateCount,
+          selectedCount: t.selectedCount,
+          confidence: t.confidence || null,
+          fallbackTrace: t.fallbackTrace,
+          createdAt: t.createdAt.toISOString()
+        };
+      })
     });
   } catch (error) {
     return c.json({
-      stats: { totalQueries: 0, avgCandidateCount: 0, avgSelectedCount: 0, selectionRate: 0 },
+      stats: {
+        totalQueries: 0,
+        avgCandidateCount: 0,
+        avgSelectedCount: 0,
+        selectionRate: 0,
+        rewrittenQueries: 0,
+        rewriteRate: 0,
+        rewrittenQueriesWithSelection: 0,
+        rawQueriesWithSelection: 0,
+        rewrittenSelectionRate: 0,
+        rawSelectionRate: 0,
+        avgSelectedCountForRewrittenQueries: 0,
+        avgSelectedCountForRawQueries: 0
+      },
       traces: [],
       error: error.message
     }, 500);
@@ -8432,6 +9206,40 @@ statsRouter.get("/retrieval-traces", async (c) => {
     await memoryService.shutdown();
   }
 });
+statsRouter.get("/retrieval-review-queue", async (c) => {
+  const limit = parseStatsLimit(c.req.query("limit"), 10, 50);
+  const scanLimit = parseStatsLimit(c.req.query("scanLimit"), 500, 5e3);
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const traces = await memoryService.getRecentRetrievalTraces(scanLimit);
+    return c.json({
+      ...buildRetrievalReviewQueue(traces, limit),
+      limits: {
+        requestedLimit: limit,
+        scanLimit,
+        scannedTraces: traces.length
+      }
+    });
+  } catch (error) {
+    console.error("Failed to build retrieval review queue");
+    return c.json({
+      summary: {
+        totalTraces: 0,
+        reviewItems: 0,
+        returnedItems: 0,
+        candidateNoSelection: 0,
+        emptyCandidateSet: 0,
+        rewrittenNoSelection: 0,
+        lowSelectionRate: 0
+      },
+      items: [],
+      error: "Unable to build retrieval review queue"
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
 statsRouter.get("/kpi", async (c) => {
   const rawWindow = c.req.query("window") || "7d";
   const window = rawWindow === "24h" || rawWindow === "30d" ? rawWindow : "7d";
@@ -9083,12 +9891,9 @@ healthRouter.get("/", async (c) => {
 var apiRouter = new Hono10().route("/sessions", sessionsRouter).route("/events", eventsRouter).route("/search", searchRouter).route("/stats", statsRouter).route("/citations", citationsRouter).route("/turns", turnsRouter).route("/projects", projectsRouter).route("/chat", chatRouter).route("/health", healthRouter);
 
 // src/apps/server/index.ts
-var app = new Hono11();
 var moduleDir = path13.dirname(fileUrlToPath(import.meta.url));
-app.use("/*", cors());
-app.use("/*", logger());
-app.route("/api", apiRouter);
-app.get("/health", (c) => c.json({ status: "ok", timestamp: (/* @__PURE__ */ new Date()).toISOString() }));
+var DASHBOARD_SESSION_COOKIE = "cml_dashboard_session";
+var DEFAULT_SESSION_MAX_AGE_SECONDS = 60 * 60 * 24 * 30;
 function resolveUiPath() {
   const candidates = [
     // Built server: dist/server/index.js -> dist/ui
@@ -9101,28 +9906,230 @@ function resolveUiPath() {
   ];
   return candidates.find((candidate) => fs11.existsSync(path13.join(candidate, "index.html"))) ?? candidates[0];
 }
-var uiPath = resolveUiPath();
-if (fs11.existsSync(uiPath)) {
-  app.use("/*", serveStatic({ root: uiPath }));
+function normalizeDashboardHost(host = "localhost") {
+  const normalized = host.trim().toLowerCase();
+  if (normalized === "" || normalized === "localhost" || normalized === "127.0.0.1") {
+    return "127.0.0.1";
+  }
+  if (normalized === "0.0.0.0") {
+    return "0.0.0.0";
+  }
+  throw new Error("Invalid dashboard host: expected localhost, 127.0.0.1, or 0.0.0.0");
+}
+function displayHost(hostname) {
+  return hostname === "0.0.0.0" ? "0.0.0.0" : "localhost";
 }
-app.get("*", (c) => {
-  const indexPath = path13.join(uiPath, "index.html");
-  if (fs11.existsSync(indexPath)) {
-    return c.html(fs11.readFileSync(indexPath, "utf-8"));
+function normalizeServerOptions(portOrOptions) {
+  if (typeof portOrOptions === "number") {
+    return { port: portOrOptions, host: "localhost" };
   }
-  return c.text('UI not built. Run "npm run build:ui" first.', 404);
-});
+  return {
+    port: portOrOptions?.port ?? 37777,
+    host: portOrOptions?.host ?? "localhost",
+    password: portOrOptions?.password,
+    cookieMaxAgeSeconds: portOrOptions?.cookieMaxAgeSeconds,
+    now: portOrOptions?.now
+  };
+}
+function parseDashboardServerPort(portOption) {
+  const normalized = (portOption ?? "37777").trim();
+  if (!/^\d+$/.test(normalized)) {
+    throw new Error("Invalid PORT: expected a positive integer");
+  }
+  const port = Number.parseInt(normalized, 10);
+  if (!Number.isSafeInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("Invalid PORT: expected a TCP port between 1 and 65535");
+  }
+  return port;
+}
+function resolveDashboardServerEnv(env) {
+  const hostname = normalizeDashboardHost(env.DASHBOARD_HOST ?? "localhost");
+  const password = env.DASHBOARD_PASSWORD || env.CLAUDE_MEMORY_LAYER_DASHBOARD_PASSWORD;
+  return {
+    port: parseDashboardServerPort(env.PORT),
+    host: displayHost(hostname),
+    password: password || void 0
+  };
+}
+function nowSeconds(now) {
+  return Math.floor(now() / 1e3);
+}
+function signSessionPayload(payload, password) {
+  return createHmac("sha256", password).update(`claude-memory-layer-dashboard:${payload}`).digest("base64url");
+}
+function createDashboardSessionToken(password, now) {
+  const payload = String(nowSeconds(now));
+  return `${payload}.${signSessionPayload(payload, password)}`;
+}
+function timingSafeStringEqual(a, b) {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+function verifyDashboardSessionToken(token, password, maxAgeSeconds, now) {
+  if (!token)
+    return false;
+  const [payload, signature, extra] = token.split(".");
+  if (!payload || !signature || extra !== void 0 || !/^\d+$/.test(payload))
+    return false;
+  const expectedSignature = signSessionPayload(payload, password);
+  if (!timingSafeStringEqual(signature, expectedSignature))
+    return false;
+  const issuedAt = Number.parseInt(payload, 10);
+  const age = nowSeconds(now) - issuedAt;
+  return Number.isSafeInteger(issuedAt) && age >= 0 && age <= maxAgeSeconds;
+}
+function isDashboardAuthenticated(c, options) {
+  if (!options.password)
+    return true;
+  return verifyDashboardSessionToken(
+    getCookie(c, DASHBOARD_SESSION_COOKIE),
+    options.password,
+    options.cookieMaxAgeSeconds,
+    options.now
+  );
+}
+function isApiRequest(c) {
+  return c.req.path.startsWith("/api/");
+}
+function wantsAuthJson(c) {
+  const accept = c.req.header("accept") ?? "";
+  const contentType = c.req.header("content-type") ?? "";
+  return accept.includes("application/json") || contentType.includes("application/json");
+}
+function isSecureRequest(c) {
+  const forwardedProto = c.req.header("x-forwarded-proto");
+  return forwardedProto === "https" || c.req.url.startsWith("https://");
+}
+function renderLoginPage(message) {
+  const errorBlock = message ? `<div class="error">${message}</div>` : "";
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dashboard Login</title>
+  <style>
+    :root { color-scheme: dark; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { min-height: 100vh; margin: 0; display: grid; place-items: center; background: radial-gradient(circle at top, #243b55 0%, #141e30 42%, #070b12 100%); color: #f8fafc; }
+    .card { width: min(420px, calc(100vw - 40px)); padding: 32px; border: 1px solid rgba(148,163,184,.25); border-radius: 20px; background: rgba(15,23,42,.78); box-shadow: 0 24px 80px rgba(0,0,0,.35); }
+    h1 { margin: 0 0 8px; font-size: 28px; }
+    p { margin: 0 0 24px; color: #cbd5e1; }
+    label { display: block; margin-bottom: 8px; color: #e2e8f0; font-size: 14px; }
+    input { width: 100%; box-sizing: border-box; padding: 12px 14px; border-radius: 12px; border: 1px solid rgba(148,163,184,.35); background: rgba(2,6,23,.72); color: #f8fafc; font-size: 16px; }
+    button { width: 100%; margin-top: 16px; padding: 12px 14px; border: 0; border-radius: 12px; background: linear-gradient(135deg, #38bdf8, #818cf8); color: #020617; font-weight: 700; cursor: pointer; }
+    .error { margin-bottom: 16px; padding: 10px 12px; border-radius: 10px; background: rgba(248,113,113,.14); color: #fecaca; border: 1px solid rgba(248,113,113,.35); }
+  </style>
+</head>
+<body>
+  <main class="card">
+    <h1>Dashboard Login</h1>
+    <p>Enter the dashboard password to continue.</p>
+    ${errorBlock}
+    <form method="post" action="/api/auth/login">
+      <label for="password">Password</label>
+      <input id="password" name="password" type="password" autocomplete="current-password" autofocus required>
+      <button type="submit">Unlock dashboard</button>
+    </form>
+  </main>
+</body>
+</html>`;
+}
+async function readSubmittedPassword(c) {
+  const contentType = c.req.header("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const body2 = await c.req.json().catch(() => ({}));
+    return typeof body2.password === "string" ? body2.password : "";
+  }
+  const body = await c.req.parseBody().catch(() => ({}));
+  const password = body.password;
+  return typeof password === "string" ? password : "";
+}
+function createAuthOptions(options) {
+  return {
+    password: options.password ?? "",
+    cookieMaxAgeSeconds: options.cookieMaxAgeSeconds ?? DEFAULT_SESSION_MAX_AGE_SECONDS,
+    now: options.now ?? Date.now
+  };
+}
+function createDashboardApp(options = {}) {
+  const app2 = new Hono11();
+  const authOptions = createAuthOptions(options);
+  app2.use("*", cors());
+  app2.use("*", logger());
+  app2.get("/health", (c) => c.json({ status: "ok", timestamp: (/* @__PURE__ */ new Date()).toISOString() }));
+  app2.get("/api/auth/status", (c) => c.json({
+    enabled: Boolean(authOptions.password),
+    authenticated: isDashboardAuthenticated(c, authOptions)
+  }));
+  app2.post("/api/auth/login", async (c) => {
+    if (!authOptions.password) {
+      return c.json({ enabled: false, authenticated: true });
+    }
+    const submittedPassword = await readSubmittedPassword(c);
+    if (!timingSafeStringEqual(submittedPassword, authOptions.password)) {
+      if (wantsAuthJson(c))
+        return c.json({ error: "Invalid password" }, 401);
+      return c.html(renderLoginPage("Invalid password"), 401);
+    }
+    const token = createDashboardSessionToken(authOptions.password, authOptions.now);
+    setCookie(c, DASHBOARD_SESSION_COOKIE, token, {
+      httpOnly: true,
+      sameSite: "Lax",
+      secure: isSecureRequest(c),
+      path: "/",
+      maxAge: authOptions.cookieMaxAgeSeconds
+    });
+    if (wantsAuthJson(c))
+      return c.json({ authenticated: true });
+    return c.redirect("/", 303);
+  });
+  app2.post("/api/auth/logout", (c) => {
+    deleteCookie(c, DASHBOARD_SESSION_COOKIE, { path: "/" });
+    if (wantsAuthJson(c))
+      return c.json({ authenticated: false });
+    return c.redirect("/", 303);
+  });
+  if (authOptions.password) {
+    app2.use("*", async (c, next) => {
+      if (isDashboardAuthenticated(c, authOptions)) {
+        await next();
+        return;
+      }
+      if (isApiRequest(c))
+        return c.json({ error: "Authentication required" }, 401);
+      return c.html(renderLoginPage(), 401);
+    });
+  }
+  app2.route("/api", apiRouter);
+  const uiPath = resolveUiPath();
+  if (fs11.existsSync(uiPath)) {
+    app2.use("/*", serveStatic({ root: uiPath }));
+  }
+  app2.get("*", (c) => {
+    const indexPath = path13.join(uiPath, "index.html");
+    if (fs11.existsSync(indexPath)) {
+      return c.html(fs11.readFileSync(indexPath, "utf-8"));
+    }
+    return c.text('UI not built. Run "npm run build:ui" first.', 404);
+  });
+  return app2;
+}
+var app = createDashboardApp();
 var serverInstance = null;
-function startServer(port = 37777) {
+function startServer(portOrOptions = 37777) {
   if (serverInstance) {
     return serverInstance;
   }
+  const options = normalizeServerOptions(portOrOptions);
+  const hostname = normalizeDashboardHost(options.host);
+  const port = options.port;
   serverInstance = serve({
-    fetch: app.fetch,
+    fetch: createDashboardApp(options).fetch,
     port,
-    hostname: "127.0.0.1"
+    hostname
   });
-  console.log(`\u{1F9E0} Code Memory viewer started at http://localhost:${port}`);
+  console.log(`\u{1F9E0} Code Memory viewer started at http://${displayHost(hostname)}:${port}`);
   return serverInstance;
 }
 function stopServer() {
@@ -9141,12 +10148,14 @@ async function isServerRunning(port = 37777) {
 }
 var isMainModule = process.argv[1]?.includes("server/index") || process.argv[1]?.endsWith("server.js");
 if (isMainModule) {
-  const port = parseInt(process.env.PORT || "37777", 10);
-  startServer(port);
+  startServer(resolveDashboardServerEnv(process.env));
 }
 export {
   app,
+  createDashboardApp,
   isServerRunning,
+  normalizeDashboardHost,
+  resolveDashboardServerEnv,
   startServer,
   stopServer
 };