claude-memory-layer 1.0.49 → 1.0.51

package/dist/server/api/index.js

@@ -6,7 +6,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 // src/apps/server/api/index.ts
-import { Hono as Hono10 } from "hono";
+import { Hono as Hono11 } from "hono";
 
 // src/apps/server/api/sessions.ts
 import { Hono } from "hono";
@@ -12570,10 +12570,25 @@ sessionsRouter.get("/", async (c) => {
           id: event.sessionId,
           startedAt: event.timestamp,
           eventCount: 1,
-          lastEventAt: event.timestamp
+          lastEventAt: event.timestamp,
+          promptPreview: event.eventType === "user_prompt" ? event.content.slice(0, 160) : "",
+          firstUserPromptAt: event.eventType === "user_prompt" ? event.timestamp : null,
+          toolCount: event.eventType === "tool_observation" ? 1 : 0,
+          responseCount: event.eventType === "agent_response" ? 1 : 0,
+          eventTypeCounts: { [event.eventType || "unknown"]: 1 },
+          source: typeof event.metadata?.source === "string" ? event.metadata.source : null
         });
       } else {
         existing.eventCount++;
+        const eventType = event.eventType || "unknown";
+        existing.eventTypeCounts[eventType] = (existing.eventTypeCounts[eventType] || 0) + 1;
+        if (event.eventType === "tool_observation") existing.toolCount++;
+        if (event.eventType === "agent_response") existing.responseCount++;
+        if (event.eventType === "user_prompt" && (!existing.firstUserPromptAt || event.timestamp < existing.firstUserPromptAt)) {
+          existing.firstUserPromptAt = event.timestamp;
+          existing.promptPreview = event.content.slice(0, 160);
+        }
+        if (!existing.source && typeof event.metadata?.source === "string") existing.source = event.metadata.source;
         if (event.timestamp < existing.startedAt) {
           existing.startedAt = event.timestamp;
         }
@@ -14616,7 +14631,7 @@ turnsRouter.get("/", async (c) => {
   if (!sessionId) {
     return c.json({ error: "sessionId is required" }, 400);
   }
-  const memoryService = getServiceFromQuery(c);
+  const memoryService = getLightweightServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const turns = await memoryService.getSessionTurns(sessionId, { limit, offset });
@@ -14650,7 +14665,7 @@ turnsRouter.get("/", async (c) => {
 });
 turnsRouter.get("/:turnId", async (c) => {
   const { turnId } = c.req.param();
-  const memoryService = getServiceFromQuery(c);
+  const memoryService = getLightweightServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const events = await memoryService.getEventsByTurn(turnId);
@@ -14725,6 +14740,58 @@ import * as fs10 from "fs";
 import * as path12 from "path";
 import * as os7 from "os";
 var projectsRouter = new Hono7();
+projectsRouter.get("/:hash/detail", async (c) => {
+  const { hash } = c.req.param();
+  const registry = loadSessionRegistry();
+  const projectPath = getRegisteredProjectPath(registry, hash);
+  const storagePath = resolveProjectStoragePath(hash);
+  const memoryService = new MemoryService({
+    storagePath,
+    projectHash: hash,
+    ...projectPath ? { projectPath } : {},
+    readOnly: true,
+    lightweightMode: true,
+    analyticsEnabled: false,
+    sharedStoreConfig: DISABLED_SHARED_STORE_CONFIG
+  });
+  try {
+    await memoryService.initialize();
+    const [stats, recentEvents, retrieval, outbox] = await Promise.all([
+      memoryService.getStats(),
+      memoryService.getRecentEvents(1e3),
+      memoryService.getRetrievalTraceStats(),
+      memoryService.getOutboxStats()
+    ]);
+    const eventSummary = summarizeProjectEvents(recentEvents);
+    return c.json({
+      project: {
+        hash,
+        projectName: projectPath ? path12.basename(projectPath) : `unknown (${hash})`,
+        registered: Boolean(projectPath)
+      },
+      storage: {
+        eventCount: stats.totalEvents,
+        vectorCount: stats.vectorCount,
+        levels: stats.levelStats || []
+      },
+      sessions: eventSummary.sessions,
+      eventTypes: eventSummary.eventTypes,
+      sources: eventSummary.sources,
+      activity: eventSummary.activity,
+      retrieval: {
+        totalQueries: retrieval.totalQueries,
+        avgCandidateCount: retrieval.avgCandidateCount,
+        avgSelectedCount: retrieval.avgSelectedCount,
+        selectionRate: retrieval.selectionRate
+      },
+      outbox: summarizeProjectOutbox(outbox)
+    });
+  } catch {
+    return c.json({ error: "Project detail unavailable" }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
 projectsRouter.get("/", async (c) => {
   try {
     const projectsDir = path12.join(os7.homedir(), ".claude-code", "memory", "projects");
@@ -14764,6 +14831,57 @@ projectsRouter.get("/", async (c) => {
     return c.json({ projects: [], error: error.message }, 500);
   }
 });
+function getRegisteredProjectPath(registry, hash) {
+  for (const entry of Object.values(registry.sessions)) {
+    if (entry.projectHash === hash) {
+      return entry.projectPath;
+    }
+  }
+  return void 0;
+}
+function summarizeProjectEvents(events) {
+  const sessions = /* @__PURE__ */ new Set();
+  const eventTypes = {};
+  const sources = {};
+  let firstEventAt = null;
+  let lastEventAt = null;
+  for (const event of events) {
+    if (event.sessionId) sessions.add(event.sessionId);
+    incrementBucket(eventTypes, event.eventType || "unknown");
+    const source = typeof event.metadata?.source === "string" ? event.metadata.source : "unknown";
+    incrementBucket(sources, source || "unknown");
+    const timestamp = normalizeIsoTimestamp(event.timestamp);
+    if (!timestamp) continue;
+    if (!firstEventAt || timestamp < firstEventAt) firstEventAt = timestamp;
+    if (!lastEventAt || timestamp > lastEventAt) lastEventAt = timestamp;
+  }
+  return {
+    sessions: { total: sessions.size },
+    eventTypes,
+    sources,
+    activity: { firstEventAt, lastEventAt }
+  };
+}
+function summarizeProjectOutbox(outbox) {
+  const embedding = outbox.embedding || {};
+  const vector = outbox.vector || {};
+  return {
+    pending: (embedding.pending || 0) + (vector.pending || 0),
+    processing: (embedding.processing || 0) + (vector.processing || 0),
+    failed: (embedding.failed || 0) + (vector.failed || 0),
+    stuckProcessing: (embedding.stuckProcessing || 0) + (vector.stuckProcessing || 0)
+  };
+}
+function incrementBucket(bucket, rawLabel) {
+  const label = rawLabel.replace(/[^a-zA-Z0-9_.:-]/g, "_").slice(0, 80) || "unknown";
+  bucket[label] = (bucket[label] || 0) + 1;
+}
+function normalizeIsoTimestamp(value) {
+  if (!value) return null;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toISOString();
+}
 function formatBytes(bytes) {
   if (bytes === 0) return "0 B";
   const k = 1024;
@@ -15052,7 +15170,101 @@ function streamClaudeResponse(prompt, stream) {
 
 // src/apps/server/api/health.ts
 import { Hono as Hono9 } from "hono";
+import { spawnSync } from "child_process";
 var healthRouter = new Hono9();
+function hasEnvSignal(name) {
+  const value = process.env[name];
+  return typeof value === "string" && value.trim().length > 0;
+}
+function claudeAuthSignal() {
+  return hasEnvSignal("ANTHROPIC_API_KEY") || hasEnvSignal("CLAUDE_API_KEY") || hasEnvSignal("CLAUDE_CODE_OAUTH_TOKEN") ? "env-present" : "not-detected";
+}
+function detectClaudeCli() {
+  const result = spawnSync("claude", ["--version"], {
+    encoding: "utf-8",
+    timeout: 3e3
+  });
+  const authSignal = claudeAuthSignal();
+  const errorCode = result.error?.code;
+  if (errorCode === "ENOENT") {
+    return { status: "missing", command: "claude", authSignal };
+  }
+  if (result.status === 0) {
+    const version = String(result.stdout || "").split("\n")[0]?.trim().slice(0, 80) || void 0;
+    return { status: "available", command: "claude", authSignal, ...version ? { version } : {} };
+  }
+  return { status: "error", command: "claude", authSignal };
+}
+function detectEmbeddingBackend() {
+  const disabled = ["1", "true", "yes"].includes(String(process.env.CLAUDE_MEMORY_DISABLE_VECTOR || "").toLowerCase());
+  return {
+    status: disabled ? "disabled" : "enabled",
+    backend: "@huggingface/transformers"
+  };
+}
+function aggregateOutbox(outbox) {
+  const pending = (outbox.embedding?.pending || 0) + (outbox.vector?.pending || 0);
+  const processing = (outbox.embedding?.processing || 0) + (outbox.vector?.processing || 0);
+  const failed = (outbox.embedding?.failed || 0) + (outbox.vector?.failed || 0);
+  const stuckProcessing = (outbox.embedding?.stuckProcessing || 0) + (outbox.vector?.stuckProcessing || 0);
+  return { pending, processing, failed, stuckProcessing };
+}
+healthRouter.get("/setup", async (c) => {
+  const memoryService = getLightweightServiceFromQuery(c);
+  try {
+    await memoryService.initialize();
+    const [stats, outbox] = await Promise.all([
+      memoryService.getStats(),
+      memoryService.getOutboxStats()
+    ]);
+    const outboxTotals = aggregateOutbox(outbox);
+    const claudeCli = detectClaudeCli();
+    const embeddings = detectEmbeddingBackend();
+    const recommendations = [];
+    if (claudeCli.status !== "available") {
+      recommendations.push("Install or authenticate Claude CLI to enable Ask Memory assistant responses.");
+    }
+    if (embeddings.status === "disabled") {
+      recommendations.push("Enable vector embeddings to improve semantic retrieval and memory usefulness.");
+    }
+    if (outboxTotals.failed > 0 || outboxTotals.stuckProcessing > 0) {
+      recommendations.push("Run vector health recovery before trusting retrieval freshness.");
+    }
+    let status = "ok";
+    if (claudeCli.status !== "available" || embeddings.status === "disabled") {
+      status = "needs-setup";
+    } else if (outboxTotals.failed > 0 || outboxTotals.stuckProcessing > 0) {
+      status = "needs-attention";
+    }
+    const scoped = Boolean(c.req.query("project") || c.req.query("projectId"));
+    return c.json({
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      setup: {
+        scope: scoped ? "project" : "global",
+        storage: {
+          status: "ok",
+          totalEvents: stats.totalEvents,
+          vectorCount: stats.vectorCount
+        },
+        outbox: outboxTotals
+      },
+      providers: {
+        claudeCli,
+        embeddings
+      },
+      recommendations
+    });
+  } catch {
+    return c.json({
+      status: "error",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      error: "Setup health check failed"
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
 healthRouter.get("/", async (c) => {
   const memoryService = getLightweightServiceFromQuery(c);
   try {
@@ -15144,8 +15356,230 @@ healthRouter.post("/recover", async (c) => {
   }
 });
 
+// src/apps/server/api/playground.ts
+import { Hono as Hono10 } from "hono";
+var playgroundRouter = new Hono10();
+function normalizeWindowSize(value) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed)) return 3;
+  return Math.max(1, Math.min(10, Math.trunc(parsed)));
+}
+function disclosureOptions(options = {}) {
+  const {
+    windowSize: _windowSize,
+    selectedResultId: _selectedResultId,
+    ...rest
+  } = options;
+  return rest;
+}
+var SOURCE_EVENT_PREVIEW_CHARS = 500;
+var SOURCE_EVENT_LIMIT = 3;
+function asRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function safeSourcePreview(value) {
+  const raw = typeof value === "string" ? value : String(value ?? "");
+  const sanitized = String(sanitizeGovernanceAuditValue(raw));
+  return sanitized.length > SOURCE_EVENT_PREVIEW_CHARS ? `${sanitized.slice(0, SOURCE_EVENT_PREVIEW_CHARS)}...` : sanitized;
+}
+function sanitizeSourceEvent(event) {
+  const record = asRecord(event);
+  if (!record) {
+    return { preview: safeSourcePreview(event) };
+  }
+  const safe = {};
+  if (record.id !== void 0) safe.id = sanitizeGovernanceAuditValue(record.id, "id");
+  if (record.eventId !== void 0) safe.eventId = sanitizeGovernanceAuditValue(record.eventId, "eventId");
+  if (record.sessionId !== void 0) safe.sessionId = sanitizeGovernanceAuditValue(record.sessionId, "sessionId");
+  if (record.eventType !== void 0) safe.eventType = sanitizeGovernanceAuditValue(record.eventType, "eventType");
+  if (record.timestamp !== void 0) safe.timestamp = sanitizeGovernanceAuditValue(record.timestamp, "timestamp");
+  const previewSource = record.content ?? record.preview ?? "";
+  safe.preview = safeSourcePreview(previewSource);
+  if (typeof record.content === "string") {
+    safe.contentLength = record.content.length;
+  }
+  return safe;
+}
+function sanitizeStringArray(value) {
+  if (!Array.isArray(value)) return void 0;
+  return value.map((item) => safeSourcePreview(item).slice(0, 160)).filter((item) => item.length > 0);
+}
+function sanitizePlaygroundSource(source) {
+  const record = asRecord(source);
+  if (!record) return source;
+  const safe = {};
+  if (record.sourceRef !== void 0) safe.sourceRef = sanitizeGovernanceAuditValue(record.sourceRef, "sourceRef");
+  if (record.sourceType !== void 0) safe.sourceType = sanitizeGovernanceAuditValue(record.sourceType, "sourceType");
+  if (record.retrievalLayer !== void 0) safe.retrievalLayer = sanitizeGovernanceAuditValue(record.retrievalLayer, "retrievalLayer");
+  if (record.summary !== void 0) safe.summary = sanitizeGovernanceAuditValue(record.summary, "summary");
+  const eventIds = sanitizeStringArray(record.eventIds);
+  if (eventIds) safe.eventIds = eventIds;
+  const rawEvents = Array.isArray(record.rawEvents) ? record.rawEvents : [];
+  safe.rawEvents = rawEvents.slice(0, SOURCE_EVENT_LIMIT).map(sanitizeSourceEvent);
+  if (rawEvents.length > SOURCE_EVENT_LIMIT) {
+    safe.omittedRawEventCount = rawEvents.length - SOURCE_EVENT_LIMIT;
+  }
+  if (record.primaryEvent !== void 0) safe.primaryEvent = sanitizeSourceEvent(record.primaryEvent);
+  if (record.rawEvent !== void 0) safe.rawEvent = sanitizeSourceEvent(record.rawEvent);
+  if (record.event !== void 0) safe.event = sanitizeSourceEvent(record.event);
+  return safe;
+}
+function sanitizeScore(value) {
+  const score = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(score) ? score : void 0;
+}
+function sanitizeReasons(value) {
+  return sanitizeStringArray(value)?.slice(0, 8) ?? [];
+}
+function sanitizeSearchResult(result) {
+  const record = asRecord(result);
+  if (!record) return { snippet: safeSourcePreview(result) };
+  const safe = {};
+  if (record.id !== void 0) safe.id = sanitizeGovernanceAuditValue(record.id, "id");
+  if (record.sourceRef !== void 0) safe.sourceRef = sanitizeGovernanceAuditValue(record.sourceRef, "sourceRef");
+  if (record.resultType !== void 0) safe.resultType = sanitizeGovernanceAuditValue(record.resultType, "resultType");
+  const score = sanitizeScore(record.score);
+  if (score !== void 0) safe.score = score;
+  safe.snippet = safeSourcePreview(record.snippet ?? record.preview ?? record.summary ?? "");
+  if (record.preview !== void 0) safe.preview = safeSourcePreview(record.preview);
+  safe.reasons = sanitizeReasons(record.reasons);
+  return safe;
+}
+var PLAYGROUND_META_FIELDS = [
+  "total",
+  "totalMatches",
+  "usedVector",
+  "usedKeyword",
+  "usedRerank",
+  "queryTimeMs",
+  "strategy"
+];
+function copySafeMetaValue(target, source, field) {
+  const value = source[field];
+  if (typeof value === "number" || typeof value === "boolean") {
+    target[field] = value;
+  } else if (typeof value === "string") {
+    target[field] = safeSourcePreview(value).slice(0, 160);
+  }
+}
+function sanitizeMeta(meta) {
+  const record = asRecord(meta);
+  if (!record) return void 0;
+  const safe = {};
+  for (const field of PLAYGROUND_META_FIELDS) {
+    copySafeMetaValue(safe, record, field);
+  }
+  return safe;
+}
+function sanitizePlaygroundSearch(search) {
+  const record = asRecord(search);
+  if (!record) return search;
+  const safe = {
+    results: Array.isArray(record.results) ? record.results.map(sanitizeSearchResult) : []
+  };
+  const meta = sanitizeMeta(record.meta);
+  if (meta) safe.meta = meta;
+  return safe;
+}
+function sanitizeExpansionFact(fact) {
+  const record = asRecord(fact);
+  if (!record) return { snippet: safeSourcePreview(fact) };
+  const safe = {};
+  if (record.id !== void 0) safe.id = sanitizeGovernanceAuditValue(record.id, "id");
+  if (record.eventId !== void 0) safe.eventId = sanitizeGovernanceAuditValue(record.eventId, "eventId");
+  if (record.sourceRef !== void 0) safe.sourceRef = sanitizeGovernanceAuditValue(record.sourceRef, "sourceRef");
+  if (record.eventType !== void 0) safe.eventType = sanitizeGovernanceAuditValue(record.eventType, "eventType");
+  if (record.sessionId !== void 0) safe.sessionId = sanitizeGovernanceAuditValue(record.sessionId, "sessionId");
+  if (record.timestamp !== void 0) safe.timestamp = sanitizeGovernanceAuditValue(record.timestamp, "timestamp");
+  const preview = safeSourcePreview(record.snippet ?? record.summary ?? record.preview ?? record.content ?? "");
+  safe.snippet = preview;
+  safe.preview = preview;
+  return safe;
+}
+function sanitizeRelatedSource(source) {
+  const record = asRecord(source);
+  if (!record) return { preview: safeSourcePreview(source) };
+  const safe = {};
+  if (record.sourceRef !== void 0) safe.sourceRef = sanitizeGovernanceAuditValue(record.sourceRef, "sourceRef");
+  const eventIds = sanitizeStringArray(record.eventIds);
+  if (eventIds) safe.eventIds = eventIds;
+  const previewSource = record.snippet ?? record.summary ?? record.preview;
+  if (previewSource !== void 0) safe.preview = safeSourcePreview(previewSource);
+  return safe;
+}
+function sanitizePlaygroundExpansion(expansion) {
+  const record = asRecord(expansion);
+  if (!record) return expansion;
+  const safe = {};
+  if (record.target !== void 0) safe.target = sanitizeSearchResult(record.target);
+  safe.surroundingFacts = Array.isArray(record.surroundingFacts) ? record.surroundingFacts.slice(0, 12).map(sanitizeExpansionFact) : [];
+  safe.relatedSources = Array.isArray(record.relatedSources) ? record.relatedSources.slice(0, 12).map(sanitizeRelatedSource) : [];
+  return safe;
+}
+function selectedResultIdFrom(searchResult, requested) {
+  if (requested && searchResult.results?.some((r) => r.id === requested || r.sourceRef === requested)) {
+    return requested;
+  }
+  const first = searchResult.results?.[0];
+  return first?.id ?? first?.sourceRef ?? null;
+}
+playgroundRouter.post("/dry-run", async (c) => {
+  let body;
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ error: "Invalid JSON body" }, 400);
+  }
+  const query = body.query?.trim();
+  if (!query) {
+    return c.json({ error: "Query is required" }, 400);
+  }
+  const useFastStrategy = body.options?.strategy === "fast";
+  const memoryService = useFastStrategy ? getLightweightServiceFromQuery(c) : getServiceFromQuery(c);
+  const replayTrace = [];
+  try {
+    await memoryService.initialize();
+    replayTrace.push("search");
+    const search = await memoryService.searchDisclosure(query, disclosureOptions(body.options));
+    const selectedResultId = selectedResultIdFrom(search, body.options?.selectedResultId);
+    const safeSearch = sanitizePlaygroundSearch(search);
+    if (!selectedResultId) {
+      replayTrace.push("no-results");
+      return c.json({
+        dryRun: true,
+        mutated: false,
+        query,
+        selectedResultId: null,
+        search: safeSearch,
+        expansion: null,
+        source: null,
+        replayTrace
+      });
+    }
+    const windowSize = normalizeWindowSize(body.options?.windowSize);
+    replayTrace.push(`expand:${selectedResultId}`);
+    const expansion = sanitizePlaygroundExpansion(await memoryService.expandDisclosure(selectedResultId, { windowSize }));
+    replayTrace.push(`source:${selectedResultId}`);
+    const source = sanitizePlaygroundSource(await memoryService.sourceDisclosure(selectedResultId));
+    return c.json({
+      dryRun: true,
+      mutated: false,
+      query,
+      selectedResultId,
+      search: safeSearch,
+      expansion,
+      source,
+      replayTrace
+    });
+  } catch (error) {
+    return c.json({ error: safeSourcePreview(error.message), dryRun: true, mutated: false, replayTrace }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
 // src/apps/server/api/index.ts
-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);
+var apiRouter = new Hono11().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).route("/playground", playgroundRouter);
 export {
   apiRouter
 };