claude-memory-layer 1.0.17 → 1.0.19

package/dist/server/index.js

@@ -18,8 +18,8 @@ import { cors } from "hono/cors";
 import { logger } from "hono/logger";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
-import * as path6 from "path";
-import * as fs6 from "fs";
+import * as path7 from "path";
+import * as fs7 from "fs";
 
 // src/server/api/index.ts
 import { Hono as Hono10 } from "hono";
@@ -92,57 +92,57 @@ function toDate(value) {
     return new Date(value);
   return new Date(String(value));
 }
-function createDatabase(path7, options) {
+function createDatabase(path8, options) {
   if (options?.readOnly) {
-    return new duckdb.Database(path7, { access_mode: "READ_ONLY" });
+    return new duckdb.Database(path8, { access_mode: "READ_ONLY" });
   }
-  return new duckdb.Database(path7);
+  return new duckdb.Database(path8);
 }
 function dbRun(db, sql, params = []) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     if (params.length === 0) {
       db.run(sql, (err) => {
         if (err)
           reject(err);
         else
-          resolve2();
+          resolve3();
       });
     } else {
       db.run(sql, ...params, (err) => {
         if (err)
           reject(err);
         else
-          resolve2();
+          resolve3();
       });
     }
   });
 }
 function dbAll(db, sql, params = []) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     if (params.length === 0) {
       db.all(sql, (err, rows) => {
         if (err)
           reject(err);
         else
-          resolve2(convertBigInts(rows || []));
+          resolve3(convertBigInts(rows || []));
       });
     } else {
       db.all(sql, ...params, (err, rows) => {
         if (err)
           reject(err);
         else
-          resolve2(convertBigInts(rows || []));
+          resolve3(convertBigInts(rows || []));
       });
     }
   });
 }
 function dbClose(db) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     db.close((err) => {
       if (err)
         reject(err);
       else
-        resolve2();
+        resolve3();
     });
   });
 }
@@ -780,12 +780,12 @@ import { randomUUID as randomUUID2 } from "crypto";
 import Database from "better-sqlite3";
 import * as fs from "fs";
 import * as nodePath from "path";
-function createSQLiteDatabase(path7, options) {
-  const dir = nodePath.dirname(path7);
+function createSQLiteDatabase(path8, options) {
+  const dir = nodePath.dirname(path8);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
-  const db = new Database(path7, {
+  const db = new Database(path8, {
     readonly: options?.readonly ?? false
   });
   if (!options?.readonly && (options?.walMode ?? true)) {
@@ -2431,7 +2431,7 @@ var SyncWorker = class {
    * Sleep utility
    */
   sleep(ms) {
-    return new Promise((resolve2) => setTimeout(resolve2, ms));
+    return new Promise((resolve3) => setTimeout(resolve3, ms));
   }
   /**
    * Get sync statistics
@@ -3461,8 +3461,8 @@ _Context:_ ${sessionContext}`;
   matchesMetadataScope(metadata, expected) {
     if (!metadata)
       return false;
-    return Object.entries(expected).every(([path7, value]) => {
-      const actual = path7.split(".").reduce((acc, key) => {
+    return Object.entries(expected).every(([path8, value]) => {
+      const actual = path8.split(".").reduce((acc, key) => {
         if (typeof acc !== "object" || acc === null)
           return void 0;
         return acc[key];
@@ -6899,6 +6899,12 @@ var MemoryService = class {
   recordMemoryAccess(eventId, sessionId, confidence = 1) {
     this.graduation.recordAccess(eventId, sessionId, confidence);
   }
+  /**
+   * Backward-compatible alias used by some hooks
+   */
+  async close() {
+    await this.shutdown();
+  }
   /**
    * Shutdown service
    */
@@ -7115,6 +7121,7 @@ eventsRouter.get("/", async (c) => {
         sessionId: e.sessionId,
         preview: e.content.slice(0, 200) + (e.content.length > 200 ? "..." : ""),
         contentLength: e.content.length,
+        metadata: e.metadata,
         accessCount: e.access_count || 0,
         lastAccessedAt: e.last_accessed_at || null
       })),
@@ -7241,7 +7248,175 @@ searchRouter.get("/", async (c) => {
 
 // src/server/api/stats.ts
 import { Hono as Hono4 } from "hono";
+import * as fs5 from "fs";
+import * as path5 from "path";
 var statsRouter = new Hono4();
+var DEFAULT_KPI_THRESHOLDS = {
+  usefulRecallRateMin: 0.45,
+  reworkRateMax: 0.25,
+  postChangeFailureRateMax: 0.2,
+  avgCompletionTurnsMax: 12,
+  memoryHitRateMin: 0.35
+};
+function loadKpiThresholds() {
+  try {
+    const filePath = path5.resolve(process.cwd(), "config", "kpi-thresholds.json");
+    if (!fs5.existsSync(filePath))
+      return DEFAULT_KPI_THRESHOLDS;
+    const parsed = JSON.parse(fs5.readFileSync(filePath, "utf-8"));
+    return {
+      usefulRecallRateMin: Number(parsed.usefulRecallRateMin ?? DEFAULT_KPI_THRESHOLDS.usefulRecallRateMin),
+      reworkRateMax: Number(parsed.reworkRateMax ?? DEFAULT_KPI_THRESHOLDS.reworkRateMax),
+      postChangeFailureRateMax: Number(parsed.postChangeFailureRateMax ?? DEFAULT_KPI_THRESHOLDS.postChangeFailureRateMax),
+      avgCompletionTurnsMax: Number(parsed.avgCompletionTurnsMax ?? DEFAULT_KPI_THRESHOLDS.avgCompletionTurnsMax),
+      memoryHitRateMin: Number(parsed.memoryHitRateMin ?? DEFAULT_KPI_THRESHOLDS.memoryHitRateMin)
+    };
+  } catch {
+    return DEFAULT_KPI_THRESHOLDS;
+  }
+}
+function windowToMs(window) {
+  if (window === "24h")
+    return 24 * 60 * 60 * 1e3;
+  if (window === "7d")
+    return 7 * 24 * 60 * 60 * 1e3;
+  return 30 * 24 * 60 * 60 * 1e3;
+}
+function inWindow(e, now, window) {
+  return now - e.timestamp.getTime() <= windowToMs(window);
+}
+function isEditToolName(name) {
+  return ["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(name);
+}
+function parseToolPayload(e) {
+  if (e.eventType !== "tool_observation")
+    return null;
+  try {
+    const payload = JSON.parse(e.content);
+    return {
+      toolName: payload?.toolName,
+      success: payload?.success,
+      filePath: payload?.metadata?.filePath,
+      command: payload?.metadata?.command
+    };
+  } catch {
+    return {
+      toolName: e.metadata?.toolName,
+      success: e.metadata?.success,
+      filePath: e.metadata?.filePath,
+      command: e.metadata?.command
+    };
+  }
+}
+function isTestLikeCommand(command) {
+  if (!command)
+    return false;
+  return /(test|jest|vitest|pytest|go test|cargo test|lint|eslint|build|tsc)/i.test(command);
+}
+function safeRatio(num, den) {
+  if (!Number.isFinite(num) || !Number.isFinite(den) || den <= 0)
+    return 0;
+  return num / den;
+}
+function round(value, digits = 4) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+function computeSessionTurnCount(sessionEvents) {
+  const turnIds = /* @__PURE__ */ new Set();
+  for (const e of sessionEvents) {
+    const turnId = e.metadata?.turnId;
+    if (typeof turnId === "string" && turnId.length > 0)
+      turnIds.add(turnId);
+  }
+  if (turnIds.size > 0)
+    return turnIds.size;
+  return sessionEvents.filter((e) => e.eventType === "user_prompt").length;
+}
+function computeKpiMetrics(events, usefulRecallRate) {
+  const prompts = events.filter((e) => e.eventType === "user_prompt");
+  const promptCount = prompts.length;
+  const memoryHitPrompts = prompts.filter((p) => p.metadata?.adherence?.checked).length;
+  const memoryHitRate = round(safeRatio(memoryHitPrompts, promptCount));
+  const sessions = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    const arr = sessions.get(e.sessionId) || [];
+    arr.push(e);
+    sessions.set(e.sessionId, arr);
+  }
+  let sessionTurnTotal = 0;
+  let sessionTurnSamples = 0;
+  let firstValidEditMinutesTotal = 0;
+  let firstValidEditSamples = 0;
+  for (const sessionEvents of sessions.values()) {
+    sessionEvents.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    const turns = computeSessionTurnCount(sessionEvents);
+    if (turns > 0) {
+      sessionTurnTotal += turns;
+      sessionTurnSamples++;
+    }
+    const firstPrompt = sessionEvents.find((e) => e.eventType === "user_prompt");
+    const firstEdit = sessionEvents.find((e) => {
+      const payload = parseToolPayload(e);
+      return payload?.toolName && isEditToolName(payload.toolName) && payload.success === true;
+    });
+    if (firstPrompt && firstEdit) {
+      const minutes = (firstEdit.timestamp.getTime() - firstPrompt.timestamp.getTime()) / 6e4;
+      if (minutes >= 0) {
+        firstValidEditMinutesTotal += minutes;
+        firstValidEditSamples++;
+      }
+    }
+  }
+  const avgCompletionTurns = round(safeRatio(sessionTurnTotal, sessionTurnSamples), 2);
+  const timeToFirstValidEditMinutes = round(safeRatio(firstValidEditMinutesTotal, firstValidEditSamples), 2);
+  const editActions = [];
+  let testRunsAfterEdit = 0;
+  let failedTestRunsAfterEdit = 0;
+  for (const [sessionId, sessionEvents] of sessions.entries()) {
+    const sorted = [...sessionEvents].sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    let seenEdit = false;
+    for (const e of sorted) {
+      const payload = parseToolPayload(e);
+      if (!payload?.toolName)
+        continue;
+      if (isEditToolName(payload.toolName) && payload.success === true) {
+        editActions.push({ sessionId, timestamp: e.timestamp.getTime(), filePath: payload.filePath });
+        seenEdit = true;
+        continue;
+      }
+      if (seenEdit && isTestLikeCommand(payload.command)) {
+        testRunsAfterEdit++;
+        if (payload.success === false)
+          failedTestRunsAfterEdit++;
+      }
+    }
+  }
+  const THIRTY_MIN_MS = 30 * 60 * 1e3;
+  let reworkCount = 0;
+  const bySessionFile = /* @__PURE__ */ new Map();
+  const sortedEdits = [...editActions].sort((a, b) => a.timestamp - b.timestamp);
+  for (const edit of sortedEdits) {
+    if (!edit.filePath)
+      continue;
+    const key = `${edit.sessionId}::${edit.filePath}`;
+    const prev = bySessionFile.get(key);
+    if (typeof prev === "number" && edit.timestamp - prev <= THIRTY_MIN_MS) {
+      reworkCount++;
+    }
+    bySessionFile.set(key, edit.timestamp);
+  }
+  const reworkRate = round(safeRatio(reworkCount, editActions.length));
+  const postChangeFailureRate = round(safeRatio(failedTestRunsAfterEdit, testRunsAfterEdit));
+  return {
+    memoryHitRate,
+    usefulRecallRate,
+    avgCompletionTurns,
+    timeToFirstValidEditMinutes,
+    reworkRate,
+    postChangeFailureRate
+  };
+}
 statsRouter.get("/shared", async (c) => {
   const memoryService = getServiceFromQuery(c);
   try {
@@ -7521,6 +7696,129 @@ statsRouter.get("/retrieval-traces", async (c) => {
     await memoryService.shutdown();
   }
 });
+statsRouter.get("/kpi", async (c) => {
+  const rawWindow = c.req.query("window") || "7d";
+  const window = rawWindow === "24h" || rawWindow === "30d" ? rawWindow : "7d";
+  const memoryService = getServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const now = Date.now();
+    const thresholds = loadKpiThresholds();
+    const allEvents = await memoryService.getRecentEvents(2e4);
+    const events = allEvents.filter((e) => inWindow(e, now, window));
+    const helpfulness = await memoryService.getHelpfulnessStats();
+    const usefulRecallRate = helpfulness.totalEvaluated > 0 ? round(safeRatio(helpfulness.helpful, helpfulness.totalEvaluated)) : 0;
+    const metrics = computeKpiMetrics(events, usefulRecallRate);
+    const windowMs = windowToMs(window);
+    const prevEvents = allEvents.filter((e) => {
+      const age = now - e.timestamp.getTime();
+      return age > windowMs && age <= windowMs * 2;
+    });
+    const previousMetrics = computeKpiMetrics(prevEvents, usefulRecallRate);
+    const deltas = {
+      memoryHitRate: round(metrics.memoryHitRate - previousMetrics.memoryHitRate),
+      usefulRecallRate: round(metrics.usefulRecallRate - previousMetrics.usefulRecallRate),
+      avgCompletionTurns: round(metrics.avgCompletionTurns - previousMetrics.avgCompletionTurns, 2),
+      timeToFirstValidEditMinutes: round(metrics.timeToFirstValidEditMinutes - previousMetrics.timeToFirstValidEditMinutes, 2),
+      reworkRate: round(metrics.reworkRate - previousMetrics.reworkRate),
+      postChangeFailureRate: round(metrics.postChangeFailureRate - previousMetrics.postChangeFailureRate)
+    };
+    const THIRTY_MIN_MS = 30 * 60 * 1e3;
+    const trendWindowMs = 30 * 24 * 60 * 60 * 1e3;
+    const trendEvents = allEvents.filter((e) => now - e.timestamp.getTime() <= trendWindowMs);
+    const buckets = /* @__PURE__ */ new Map();
+    for (const e of trendEvents) {
+      const day = e.timestamp.toISOString().split("T")[0];
+      const arr = buckets.get(day) || [];
+      arr.push(e);
+      buckets.set(day, arr);
+    }
+    const trendDaily = Array.from(buckets.entries()).sort((a, b) => a[0].localeCompare(b[0])).map(([date, dayEvents]) => {
+      const dayPrompts = dayEvents.filter((e) => e.eventType === "user_prompt");
+      const dayPromptCount = dayPrompts.length;
+      const dayMemoryHit = dayPrompts.filter((p) => p.metadata?.adherence?.checked).length;
+      const dayEdits = dayEvents.filter((e) => {
+        const p = parseToolPayload(e);
+        return Boolean(p?.toolName && isEditToolName(p.toolName) && p.success === true);
+      });
+      const dayEditActions = dayEdits.map((e) => {
+        const p = parseToolPayload(e);
+        return { sessionId: e.sessionId, timestamp: e.timestamp.getTime(), filePath: p?.filePath };
+      }).filter((x) => Boolean(x.filePath));
+      let dayReworkCount = 0;
+      const dayBySessionFile = /* @__PURE__ */ new Map();
+      for (const edit of dayEditActions) {
+        const key = `${edit.sessionId}::${edit.filePath}`;
+        const prev = dayBySessionFile.get(key);
+        if (typeof prev === "number" && edit.timestamp - prev <= THIRTY_MIN_MS)
+          dayReworkCount++;
+        dayBySessionFile.set(key, edit.timestamp);
+      }
+      const dayTests = dayEvents.filter((e) => {
+        const p = parseToolPayload(e);
+        return Boolean(p?.toolName && isTestLikeCommand(p.command));
+      });
+      const dayFailedTests = dayEvents.filter((e) => {
+        const p = parseToolPayload(e);
+        return Boolean(p?.toolName && isTestLikeCommand(p.command) && p.success === false);
+      });
+      const turnsBySession = /* @__PURE__ */ new Map();
+      for (const e of dayEvents) {
+        const arr = turnsBySession.get(e.sessionId) || [];
+        arr.push(e);
+        turnsBySession.set(e.sessionId, arr);
+      }
+      let dayTurnsTotal = 0;
+      let dayTurnsSamples = 0;
+      for (const sessionEvents of turnsBySession.values()) {
+        const turns = computeSessionTurnCount(sessionEvents);
+        if (turns > 0) {
+          dayTurnsTotal += turns;
+          dayTurnsSamples++;
+        }
+      }
+      return {
+        date,
+        memoryHitRate: round(safeRatio(dayMemoryHit, dayPromptCount)),
+        usefulRecallRate,
+        reworkRate: round(safeRatio(dayReworkCount, dayEditActions.length)),
+        postChangeFailureRate: round(safeRatio(dayFailedTests.length, dayTests.length)),
+        avgCompletionTurns: round(safeRatio(dayTurnsTotal, dayTurnsSamples), 2)
+      };
+    });
+    const alerts = [];
+    if (metrics.usefulRecallRate < thresholds.usefulRecallRateMin) {
+      alerts.push({ metric: "usefulRecallRate", level: "warn", message: "Useful recall rate is below threshold", value: metrics.usefulRecallRate, threshold: thresholds.usefulRecallRateMin });
+    }
+    if (metrics.reworkRate > thresholds.reworkRateMax) {
+      alerts.push({ metric: "reworkRate", level: "warn", message: "Rework rate is above threshold", value: metrics.reworkRate, threshold: thresholds.reworkRateMax });
+    }
+    if (metrics.postChangeFailureRate > thresholds.postChangeFailureRateMax) {
+      alerts.push({ metric: "postChangeFailureRate", level: "warn", message: "Post-change failure rate is above threshold", value: metrics.postChangeFailureRate, threshold: thresholds.postChangeFailureRateMax });
+    }
+    if (metrics.avgCompletionTurns > thresholds.avgCompletionTurnsMax) {
+      alerts.push({ metric: "avgCompletionTurns", level: "warn", message: "Average completion turns is above threshold", value: metrics.avgCompletionTurns, threshold: thresholds.avgCompletionTurnsMax });
+    }
+    if (metrics.memoryHitRate < thresholds.memoryHitRateMin) {
+      alerts.push({ metric: "memoryHitRate", level: "warn", message: "Memory hit rate is below threshold", value: metrics.memoryHitRate, threshold: thresholds.memoryHitRateMin });
+    }
+    return c.json({
+      window,
+      metrics,
+      previousMetrics,
+      deltas,
+      trend: {
+        daily: trendDaily
+      },
+      thresholds,
+      alerts
+    });
+  } catch (error) {
+    return c.json({ error: error.message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
 statsRouter.post("/graduation/run", async (c) => {
   const memoryService = getServiceFromQuery(c);
   try {
@@ -7768,19 +8066,19 @@ turnsRouter.post("/backfill", async (c) => {
 
 // src/server/api/projects.ts
 import { Hono as Hono7 } from "hono";
-import * as fs5 from "fs";
-import * as path5 from "path";
+import * as fs6 from "fs";
+import * as path6 from "path";
 import * as os3 from "os";
 var projectsRouter = new Hono7();
 projectsRouter.get("/", async (c) => {
   try {
-    const projectsDir = path5.join(os3.homedir(), ".claude-code", "memory", "projects");
-    if (!fs5.existsSync(projectsDir)) {
+    const projectsDir = path6.join(os3.homedir(), ".claude-code", "memory", "projects");
+    if (!fs6.existsSync(projectsDir)) {
       return c.json({ projects: [] });
     }
-    const projectHashes = fs5.readdirSync(projectsDir).filter((name) => {
-      const fullPath = path5.join(projectsDir, name);
-      return fs5.statSync(fullPath).isDirectory();
+    const projectHashes = fs6.readdirSync(projectsDir).filter((name) => {
+      const fullPath = path6.join(projectsDir, name);
+      return fs6.statSync(fullPath).isDirectory();
     });
     const registry = loadSessionRegistry();
     const hashToPath = /* @__PURE__ */ new Map();
@@ -7790,17 +8088,17 @@ projectsRouter.get("/", async (c) => {
       }
     }
     const projects = projectHashes.map((hash) => {
-      const dirPath = path5.join(projectsDir, hash);
-      const dbPath = path5.join(dirPath, "events.sqlite");
+      const dirPath = path6.join(projectsDir, hash);
+      const dbPath = path6.join(dirPath, "events.sqlite");
       let dbSize = 0;
-      if (fs5.existsSync(dbPath)) {
-        dbSize = fs5.statSync(dbPath).size;
+      if (fs6.existsSync(dbPath)) {
+        dbSize = fs6.statSync(dbPath).size;
       }
       const projectPath = hashToPath.get(hash) || `unknown (${hash})`;
       return {
         hash,
         projectPath,
-        projectName: path5.basename(projectPath),
+        projectName: path6.basename(projectPath),
         dbSize,
         dbSizeHuman: formatBytes(dbSize)
       };
@@ -7925,7 +8223,7 @@ function buildPrompt(statsContext, memoryContext, history, currentMessage) {
   return parts.join("\n");
 }
 function streamClaudeResponse(prompt, stream) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const proc = spawn("claude", [
       "-p",
       "--output-format",
@@ -7997,7 +8295,7 @@ function streamClaudeResponse(prompt, stream) {
       if (code !== 0 && code !== null) {
         reject(new Error(`Claude CLI exited with code ${code}`));
       } else {
-        resolve2();
+        resolve3();
       }
     });
   });
@@ -8054,14 +8352,14 @@ app.use("/*", cors());
 app.use("/*", logger());
 app.route("/api", apiRouter);
 app.get("/health", (c) => c.json({ status: "ok", timestamp: (/* @__PURE__ */ new Date()).toISOString() }));
-var uiPath = path6.join(__dirname, "../../dist/ui");
-if (fs6.existsSync(uiPath)) {
+var uiPath = path7.join(__dirname, "../../dist/ui");
+if (fs7.existsSync(uiPath)) {
   app.use("/*", serveStatic({ root: uiPath }));
 }
 app.get("*", (c) => {
-  const indexPath = path6.join(uiPath, "index.html");
-  if (fs6.existsSync(indexPath)) {
-    return c.html(fs6.readFileSync(indexPath, "utf-8"));
+  const indexPath = path7.join(uiPath, "index.html");
+  if (fs7.existsSync(indexPath)) {
+    return c.html(fs7.readFileSync(indexPath, "utf-8"));
   }
   return c.text('UI not built. Run "npm run build:ui" first.', 404);
 });