claude-memory-layer 1.0.10 → 1.0.12

package/src/server/api/stats.ts

@@ -4,13 +4,14 @@
  */
 
 import { Hono } from 'hono';
-import { getReadOnlyMemoryService, getMemoryServiceForProject } from '../../services/memory-service.js';
+import { getMemoryServiceForProject } from '../../services/memory-service.js';
+import { getServiceFromQuery } from './utils.js';
 
 export const statsRouter = new Hono();
 
 // GET /api/stats/shared - Get shared store statistics
 statsRouter.get('/shared', async (c) => {
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const sharedStats = await memoryService.getSharedStoreStats();
@@ -74,7 +75,7 @@ statsRouter.get('/levels/:level', async (c) => {
     return c.json({ error: `Invalid level. Must be one of: ${validLevels.join(', ')}` }, 400);
   }
 
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     let events = await memoryService.getEventsByLevel(level, { limit: limit * 2, offset });
@@ -131,7 +132,7 @@ statsRouter.get('/levels/:level', async (c) => {
 
 // GET /api/stats - Get overall statistics
 statsRouter.get('/', async (c) => {
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const stats = await memoryService.getStats();
@@ -157,6 +158,8 @@ statsRouter.get('/', async (c) => {
         return acc;
       }, {} as Record<string, number>);
 
+    const retrievalTrace = await memoryService.getRetrievalTraceStats();
+
     return c.json({
       storage: {
         eventCount: stats.totalEvents,
@@ -174,7 +177,8 @@ statsRouter.get('/', async (c) => {
         heapUsed: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
         heapTotal: Math.round(process.memoryUsage().heapTotal / 1024 / 1024)
       },
-      levelStats: stats.levelStats
+      levelStats: stats.levelStats,
+      retrievalTrace
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
@@ -187,7 +191,7 @@ statsRouter.get('/', async (c) => {
 statsRouter.get('/most-accessed', async (c) => {
   const limit = parseInt(c.req.query('limit') || '10', 10);
   // Use the same read-only service that other stats endpoints use
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
 
   try {
     await memoryService.initialize();
@@ -222,7 +226,7 @@ statsRouter.get('/most-accessed', async (c) => {
 // GET /api/stats/timeline - Get activity timeline
 statsRouter.get('/timeline', async (c) => {
   const days = parseInt(c.req.query('days') || '7', 10);
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
 
   try {
     await memoryService.initialize();
@@ -255,9 +259,86 @@ statsRouter.get('/timeline', async (c) => {
   }
 });
 
+// GET /api/stats/helpfulness - Get helpfulness statistics and top helpful memories
+statsRouter.get('/helpfulness', async (c) => {
+  const limit = parseInt(c.req.query('limit') || '10', 10);
+  const memoryService = getServiceFromQuery(c);
+
+  try {
+    await memoryService.initialize();
+    const stats = await memoryService.getHelpfulnessStats();
+    const topMemories = await memoryService.getHelpfulMemories(limit);
+
+    return c.json({
+      ...stats,
+      topMemories: topMemories.map(m => ({
+        eventId: m.eventId,
+        summary: m.summary,
+        helpfulnessScore: m.helpfulnessScore,
+        accessCount: m.accessCount,
+        evaluationCount: m.evaluationCount
+      }))
+    });
+  } catch (error) {
+    return c.json({
+      avgScore: 0,
+      totalEvaluated: 0,
+      totalRetrievals: 0,
+      helpful: 0,
+      neutral: 0,
+      unhelpful: 0,
+      topMemories: []
+    });
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+
+
+// GET /api/stats/retrieval-traces - Get recent retrieval traces (query -> selected context)
+statsRouter.get('/retrieval-traces', async (c) => {
+  const limit = parseInt(c.req.query('limit') || '50', 10);
+  const memoryService = getServiceFromQuery(c);
+
+  try {
+    await memoryService.initialize();
+    const traces = await memoryService.getRecentRetrievalTraces(limit);
+    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()
+      }))
+    });
+  } catch (error) {
+    return c.json({
+      stats: { totalQueries: 0, avgCandidateCount: 0, avgSelectedCount: 0, selectionRate: 0 },
+      traces: [],
+      error: (error as Error).message
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
 // POST /api/stats/graduation/run - Force graduation evaluation
 statsRouter.post('/graduation/run', async (c) => {
-  const memoryService = getReadOnlyMemoryService();
+  const memoryService = getServiceFromQuery(c);
   try {
     await memoryService.initialize();
     const result = await memoryService.forceGraduation();

package/src/server/api/turns.ts

@@ -0,0 +1,143 @@
+/**
+ * Turns API
+ * Endpoints for viewing events grouped by conversation turn
+ *
+ * A "turn" groups a user_prompt with its associated tool_observations
+ * and the final agent_response into a single logical unit.
+ */
+
+import { Hono } from 'hono';
+import { getServiceFromQuery } from './utils.js';
+
+export const turnsRouter = new Hono();
+
+// GET /api/turns?sessionId=xxx - List turns for a session
+turnsRouter.get('/', async (c) => {
+  const sessionId = c.req.query('sessionId');
+  const limit = parseInt(c.req.query('limit') || '20', 10);
+  const offset = parseInt(c.req.query('offset') || '0', 10);
+
+  if (!sessionId) {
+    return c.json({ error: 'sessionId is required' }, 400);
+  }
+
+  const memoryService = getServiceFromQuery(c);
+
+  try {
+    await memoryService.initialize();
+
+    const turns = await memoryService.getSessionTurns(sessionId, { limit, offset });
+    const totalTurns = await memoryService.countSessionTurns(sessionId);
+
+    return c.json({
+      turns: turns.map(t => ({
+        turnId: t.turnId,
+        startedAt: t.startedAt.toISOString(),
+        promptPreview: t.promptPreview,
+        eventCount: t.eventCount,
+        toolCount: t.toolCount,
+        hasResponse: t.hasResponse,
+        events: t.events.map(e => ({
+          id: e.id,
+          eventType: e.eventType,
+          timestamp: e.timestamp instanceof Date ? e.timestamp.toISOString() : e.timestamp,
+          preview: e.content.slice(0, 300) + (e.content.length > 300 ? '...' : ''),
+          contentLength: e.content.length
+        }))
+      })),
+      total: totalTurns,
+      limit,
+      offset,
+      hasMore: offset + limit < totalTurns
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+// GET /api/turns/:turnId - Get full turn details
+turnsRouter.get('/:turnId', async (c) => {
+  const { turnId } = c.req.param();
+  const memoryService = getServiceFromQuery(c);
+
+  try {
+    await memoryService.initialize();
+
+    const events = await memoryService.getEventsByTurn(turnId);
+
+    if (events.length === 0) {
+      return c.json({ error: 'Turn not found' }, 404);
+    }
+
+    const promptEvent = events.find(e => e.eventType === 'user_prompt');
+    const toolEvents = events.filter(e => e.eventType === 'tool_observation');
+    const responseEvents = events.filter(e => e.eventType === 'agent_response');
+
+    return c.json({
+      turnId,
+      sessionId: events[0].sessionId,
+      startedAt: events[0].timestamp instanceof Date
+        ? events[0].timestamp.toISOString()
+        : events[0].timestamp,
+      prompt: promptEvent ? {
+        id: promptEvent.id,
+        content: promptEvent.content,
+        timestamp: promptEvent.timestamp instanceof Date
+          ? promptEvent.timestamp.toISOString()
+          : promptEvent.timestamp
+      } : null,
+      tools: toolEvents.map(e => {
+        let toolName = '';
+        let success = true;
+        try {
+          const parsed = JSON.parse(e.content);
+          toolName = parsed.toolName || '';
+          success = parsed.success !== false;
+        } catch { /* ignore */ }
+
+        return {
+          id: e.id,
+          toolName,
+          success,
+          timestamp: e.timestamp instanceof Date ? e.timestamp.toISOString() : e.timestamp,
+          preview: e.content.slice(0, 500) + (e.content.length > 500 ? '...' : '')
+        };
+      }),
+      responses: responseEvents.map(e => ({
+        id: e.id,
+        content: e.content,
+        timestamp: e.timestamp instanceof Date ? e.timestamp.toISOString() : e.timestamp
+      })),
+      totalEvents: events.length
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+// POST /api/turns/backfill - Backfill turn_ids from metadata
+turnsRouter.post('/backfill', async (c) => {
+  const memoryService = getServiceFromQuery(c);
+
+  try {
+    await memoryService.initialize();
+    const updated = await memoryService.backfillTurnIds();
+
+    return c.json({
+      success: true,
+      updated,
+      message: `Backfilled turn_id for ${updated} events`
+    });
+  } catch (error) {
+    return c.json({
+      success: false,
+      error: (error as Error).message
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});

package/src/server/api/utils.ts

@@ -0,0 +1,46 @@
+/**
+ * API Utilities
+ * Shared helpers for API endpoints
+ */
+
+import type { Context } from 'hono';
+import * as path from 'path';
+import * as os from 'os';
+import { getReadOnlyMemoryService } from '../../services/memory-service.js';
+import { MemoryService } from '../../services/memory-service.js';
+
+/**
+ * Get the appropriate MemoryService based on the ?project= query parameter.
+ * - If ?project=<hash> is set (8 hex chars), resolves directly to project storage
+ * - If ?project=<path> is set, computes hash from path
+ * - Otherwise, returns the global read-only service
+ *
+ * Always creates read-only services for the dashboard API to avoid
+ * VectorWorker lifecycle issues with per-request services.
+ */
+export function getServiceFromQuery(c: Context): MemoryService {
+  const project = c.req.query('project');
+  if (project) {
+    // Check if it's a hash (8 hex chars) or a path
+    const isHash = /^[a-f0-9]{8}$/.test(project);
+    let storagePath: string;
+
+    if (isHash) {
+      storagePath = path.join(os.homedir(), '.claude-code', 'memory', 'projects', project);
+    } else {
+      // Import hashProjectPath dynamically to compute the hash from path
+      const crypto = require('crypto');
+      const normalized = project.replace(/\/+$/, '') || '/';
+      const hash = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 8);
+      storagePath = path.join(os.homedir(), '.claude-code', 'memory', 'projects', hash);
+    }
+
+    return new MemoryService({
+      storagePath,
+      readOnly: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: { enabled: false }
+    });
+  }
+  return getReadOnlyMemoryService();
+}