claude-memory-layer 1.0.27 → 1.0.28

package/src/apps/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/apps/server/api/utils.ts

@@ -0,0 +1,65 @@
+/**
+ * API Utilities
+ * Shared helpers for API endpoints
+ */
+
+import type { Context } from 'hono';
+import {
+  DISABLED_SHARED_STORE_CONFIG,
+  getReadOnlyMemoryService,
+  MemoryService
+} from '../../../services/memory-service.js';
+import { resolveProjectStoragePath } from '../../../core/registry/project-path.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') || c.req.query('projectId');
+  if (project) {
+    const storagePath = resolveProjectStoragePath(project);
+
+    return new MemoryService({
+      storagePath,
+      readOnly: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: DISABLED_SHARED_STORE_CONFIG
+    });
+  }
+  return getReadOnlyMemoryService();
+}
+
+
+/**
+ * Read-only lightweight service for API paths that only need sqlite/keyword reads.
+ * This avoids per-request vector/embedder/shared-store initialization for stats and
+ * explicit fast searches while preserving the same project query resolution rules.
+ */
+export function getLightweightServiceFromQuery(c: Context): MemoryService {
+  const project = c.req.query('project') || c.req.query('projectId');
+  if (project) {
+    const storagePath = resolveProjectStoragePath(project);
+
+    return new MemoryService({
+      storagePath,
+      readOnly: true,
+      lightweightMode: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: DISABLED_SHARED_STORE_CONFIG
+    });
+  }
+
+  return new MemoryService({
+    storagePath: '~/.claude-code/memory',
+    readOnly: true,
+    lightweightMode: true,
+    analyticsEnabled: false,
+    sharedStoreConfig: DISABLED_SHARED_STORE_CONFIG
+  });
+}

package/src/apps/server/index.ts

@@ -0,0 +1,111 @@
+/**
+ * Web Viewer HTTP Server
+ * Provides REST API and serves static UI files
+ */
+
+import { Hono } from 'hono';
+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 path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath as fileUrlToPath } from 'url';
+
+import { apiRouter } from './api/index.js';
+
+const app = new Hono();
+const moduleDir = path.dirname(fileUrlToPath(import.meta.url));
+
+// Middleware
+app.use('/*', cors());
+app.use('/*', logger());
+
+// API routes
+app.route('/api', apiRouter);
+
+// Health check
+app.get('/health', (c) => c.json({ status: 'ok', timestamp: new Date().toISOString() }));
+
+function resolveUiPath(): string {
+  const candidates = [
+    // Built server: dist/server/index.js -> dist/ui
+    path.resolve(moduleDir, '../ui'),
+    // Source/dev server: src/apps/server/index.ts -> src/apps/dashboard
+    path.resolve(moduleDir, '../dashboard'),
+    // Fallback when running from a repository root.
+    path.resolve(process.cwd(), 'dist/ui'),
+    path.resolve(process.cwd(), 'src/apps/dashboard')
+  ];
+
+  return candidates.find((candidate) => fs.existsSync(path.join(candidate, 'index.html'))) ?? candidates[0];
+}
+
+// Static files (UI)
+const uiPath = resolveUiPath();
+if (fs.existsSync(uiPath)) {
+  app.use('/*', serveStatic({ root: uiPath }));
+}
+
+// Fallback for SPA routing
+app.get('*', (c) => {
+  const indexPath = path.join(uiPath, 'index.html');
+  if (fs.existsSync(indexPath)) {
+    return c.html(fs.readFileSync(indexPath, 'utf-8'));
+  }
+  return c.text('UI not built. Run "npm run build:ui" first.', 404);
+});
+
+export { app };
+
+let serverInstance: ReturnType<typeof serve> | null = null;
+
+/**
+ * Start the HTTP server
+ */
+export function startServer(port: number = 37777): NonNullable<ReturnType<typeof serve>> {
+  if (serverInstance) {
+    return serverInstance;
+  }
+
+  serverInstance = serve({
+    fetch: app.fetch,
+    port,
+    hostname: '127.0.0.1'
+  });
+
+  console.log(`🧠 Code Memory viewer started at http://localhost:${port}`);
+
+  return serverInstance;
+}
+
+/**
+ * Stop the HTTP server
+ */
+export function stopServer(): void {
+  if (serverInstance) {
+    serverInstance.close();
+    serverInstance = null;
+  }
+}
+
+/**
+ * Check if server is running on given port
+ */
+export async function isServerRunning(port: number = 37777): Promise<boolean> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/health`);
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+// Start server if run directly
+// Check if this file is being run directly (not imported)
+const 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);
+}