claude-memory-layer 1.0.0

package/src/mcp/tools.ts

@@ -0,0 +1,78 @@
+/**
+ * MCP Tool Definitions
+ * Available tools for Claude Desktop
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const tools: Tool[] = [
+  {
+    name: 'mem-search',
+    description: 'Search code-memory for relevant past conversations and insights. Returns a compact index of results - use mem-details to get full content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Natural language search query'
+        },
+        topK: {
+          type: 'number',
+          description: 'Maximum number of results (default: 5, max: 20)'
+        },
+        sessionId: {
+          type: 'string',
+          description: 'Optional: filter by specific session ID'
+        },
+        eventType: {
+          type: 'string',
+          enum: ['user_prompt', 'agent_response', 'tool_observation', 'session_summary'],
+          description: 'Optional: filter by event type'
+        }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'mem-timeline',
+    description: 'Get chronological context around specific memories. Useful for understanding the conversation flow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Memory IDs (from mem-search) to get timeline for'
+        },
+        windowSize: {
+          type: 'number',
+          description: 'Number of items before/after each ID (default: 3)'
+        }
+      },
+      required: ['ids']
+    }
+  },
+  {
+    name: 'mem-details',
+    description: 'Get full content of specific memories. Use after mem-search to get complete information.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Memory IDs to fetch full details for'
+        }
+      },
+      required: ['ids']
+    }
+  },
+  {
+    name: 'mem-stats',
+    description: 'Get statistics about the memory storage (total events, sessions, etc.)',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  }
+];

package/src/server/api/citations.ts

@@ -0,0 +1,101 @@
+/**
+ * Citations API
+ * Endpoints for citation management
+ */
+
+import { Hono } from 'hono';
+import { getDefaultMemoryService } from '../../services/memory-service.js';
+import { generateCitationId, parseCitationId } from '../../core/citation-generator.js';
+
+export const citationsRouter = new Hono();
+
+// GET /api/citations/:id - Get citation by ID
+citationsRouter.get('/:id', async (c) => {
+  const { id } = c.req.param();
+
+  // Support both formats: "a7Bc3x" or "mem:a7Bc3x"
+  const citationId = parseCitationId(id) || id;
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    // Search through recent events to find the one matching this citation ID
+    const recentEvents = await memoryService.getRecentEvents(10000);
+
+    const event = recentEvents.find(e => {
+      const eventCitationId = generateCitationId(e.id);
+      return eventCitationId === citationId;
+    });
+
+    if (!event) {
+      return c.json({ error: 'Citation not found' }, 404);
+    }
+
+    return c.json({
+      citation: {
+        id: citationId,
+        eventId: event.id
+      },
+      event: {
+        id: event.id,
+        eventType: event.eventType,
+        timestamp: event.timestamp,
+        sessionId: event.sessionId,
+        content: event.content,
+        metadata: event.metadata
+      }
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});
+
+// GET /api/citations/:id/related - Get related citations
+citationsRouter.get('/:id/related', async (c) => {
+  const { id } = c.req.param();
+  const citationId = parseCitationId(id) || id;
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    const recentEvents = await memoryService.getRecentEvents(10000);
+
+    // Find the main event
+    const event = recentEvents.find(e => {
+      const eventCitationId = generateCitationId(e.id);
+      return eventCitationId === citationId;
+    });
+
+    if (!event) {
+      return c.json({ error: 'Citation not found' }, 404);
+    }
+
+    // Get surrounding events from same session
+    const sessionEvents = recentEvents
+      .filter(e => e.sessionId === event.sessionId)
+      .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+    const eventIndex = sessionEvents.findIndex(e => e.id === event.id);
+    const prev = eventIndex > 0 ? sessionEvents[eventIndex - 1] : null;
+    const next = eventIndex < sessionEvents.length - 1 ? sessionEvents[eventIndex + 1] : null;
+
+    return c.json({
+      previous: prev ? {
+        citationId: generateCitationId(prev.id),
+        eventType: prev.eventType,
+        timestamp: prev.timestamp,
+        preview: prev.content.slice(0, 100) + (prev.content.length > 100 ? '...' : '')
+      } : null,
+      next: next ? {
+        citationId: generateCitationId(next.id),
+        eventType: next.eventType,
+        timestamp: next.timestamp,
+        preview: next.content.slice(0, 100) + (next.content.length > 100 ? '...' : '')
+      } : null
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});

package/src/server/api/events.ts

@@ -0,0 +1,101 @@
+/**
+ * Events API
+ * Endpoints for event management
+ */
+
+import { Hono } from 'hono';
+import { getDefaultMemoryService } from '../../services/memory-service.js';
+
+export const eventsRouter = new Hono();
+
+// GET /api/events - List events with filters
+eventsRouter.get('/', async (c) => {
+  const sessionId = c.req.query('sessionId');
+  const eventType = c.req.query('type');
+  const limit = parseInt(c.req.query('limit') || '100', 10);
+  const offset = parseInt(c.req.query('offset') || '0', 10);
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    let events = await memoryService.getRecentEvents(limit + offset + 1000);
+
+    // Filter by session
+    if (sessionId) {
+      events = events.filter(e => e.sessionId === sessionId);
+    }
+
+    // Filter by type
+    if (eventType) {
+      events = events.filter(e => e.eventType === eventType);
+    }
+
+    // Pagination
+    const total = events.length;
+    events = events.slice(offset, offset + limit);
+
+    return c.json({
+      events: events.map(e => ({
+        id: e.id,
+        eventType: e.eventType,
+        timestamp: e.timestamp,
+        sessionId: e.sessionId,
+        preview: e.content.slice(0, 200) + (e.content.length > 200 ? '...' : ''),
+        contentLength: e.content.length
+      })),
+      total,
+      limit,
+      offset,
+      hasMore: offset + limit < total
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});
+
+// GET /api/events/:id - Get event details
+eventsRouter.get('/:id', async (c) => {
+  const { id } = c.req.param();
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    const recentEvents = await memoryService.getRecentEvents(10000);
+    const event = recentEvents.find(e => e.id === id);
+
+    if (!event) {
+      return c.json({ error: 'Event not found' }, 404);
+    }
+
+    // Get surrounding events for context
+    const sessionEvents = recentEvents
+      .filter(e => e.sessionId === event.sessionId)
+      .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+    const eventIndex = sessionEvents.findIndex(e => e.id === id);
+    const start = Math.max(0, eventIndex - 2);
+    const end = Math.min(sessionEvents.length, eventIndex + 3);
+    const context = sessionEvents.slice(start, end).filter(e => e.id !== id);
+
+    return c.json({
+      event: {
+        id: event.id,
+        eventType: event.eventType,
+        timestamp: event.timestamp,
+        sessionId: event.sessionId,
+        content: event.content,
+        metadata: event.metadata
+      },
+      context: context.map(e => ({
+        id: e.id,
+        eventType: e.eventType,
+        timestamp: e.timestamp,
+        preview: e.content.slice(0, 100) + (e.content.length > 100 ? '...' : '')
+      }))
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});

package/src/server/api/index.ts

@@ -0,0 +1,18 @@
+/**
+ * API Router
+ * Central router for all API endpoints
+ */
+
+import { Hono } from 'hono';
+import { sessionsRouter } from './sessions.js';
+import { eventsRouter } from './events.js';
+import { searchRouter } from './search.js';
+import { statsRouter } from './stats.js';
+import { citationsRouter } from './citations.js';
+
+export const apiRouter = new Hono()
+  .route('/sessions', sessionsRouter)
+  .route('/events', eventsRouter)
+  .route('/search', searchRouter)
+  .route('/stats', statsRouter)
+  .route('/citations', citationsRouter);

package/src/server/api/search.ts

@@ -0,0 +1,98 @@
+/**
+ * Search API
+ * Endpoints for memory search
+ */
+
+import { Hono } from 'hono';
+import { getDefaultMemoryService } from '../../services/memory-service.js';
+
+export const searchRouter = new Hono();
+
+interface SearchRequest {
+  query: string;
+  options?: {
+    topK?: number;
+    minScore?: number;
+    sessionId?: string;
+    eventType?: string;
+  };
+}
+
+// POST /api/search - Search memories
+searchRouter.post('/', async (c) => {
+  try {
+    const body = await c.req.json<SearchRequest>();
+
+    if (!body.query) {
+      return c.json({ error: 'Query is required' }, 400);
+    }
+
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    const startTime = Date.now();
+
+    const result = await memoryService.retrieveMemories(body.query, {
+      topK: body.options?.topK ?? 10,
+      minScore: body.options?.minScore ?? 0.7,
+      sessionId: body.options?.sessionId
+    });
+
+    const searchTime = Date.now() - startTime;
+
+    return c.json({
+      results: result.memories.map(m => ({
+        id: m.event.id,
+        eventType: m.event.eventType,
+        timestamp: m.event.timestamp,
+        sessionId: m.event.sessionId,
+        score: m.score,
+        content: m.event.content,
+        preview: m.event.content.slice(0, 200) + (m.event.content.length > 200 ? '...' : ''),
+        context: m.sessionContext
+      })),
+      meta: {
+        totalMatches: result.memories.length,
+        searchTime,
+        confidence: result.matchResult.confidence,
+        totalTokens: result.totalTokens
+      }
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});
+
+// GET /api/search - Simple search via query param
+searchRouter.get('/', async (c) => {
+  const query = c.req.query('q');
+
+  if (!query) {
+    return c.json({ error: 'Query parameter "q" is required' }, 400);
+  }
+
+  const topK = parseInt(c.req.query('topK') || '5', 10);
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    const result = await memoryService.retrieveMemories(query, { topK });
+
+    return c.json({
+      results: result.memories.map(m => ({
+        id: m.event.id,
+        eventType: m.event.eventType,
+        timestamp: m.event.timestamp,
+        score: m.score,
+        preview: m.event.content.slice(0, 200) + (m.event.content.length > 200 ? '...' : '')
+      })),
+      meta: {
+        totalMatches: result.memories.length,
+        confidence: result.matchResult.confidence
+      }
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});

package/src/server/api/sessions.ts

@@ -0,0 +1,111 @@
+/**
+ * Sessions API
+ * Endpoints for session management
+ */
+
+import { Hono } from 'hono';
+import { getDefaultMemoryService } from '../../services/memory-service.js';
+
+export const sessionsRouter = new Hono();
+
+// GET /api/sessions - List all sessions
+sessionsRouter.get('/', async (c) => {
+  const page = parseInt(c.req.query('page') || '1', 10);
+  const pageSize = parseInt(c.req.query('pageSize') || '20', 10);
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    // Get recent events and extract sessions
+    const recentEvents = await memoryService.getRecentEvents(1000);
+
+    // Group by session
+    const sessionMap = new Map<string, {
+      id: string;
+      startedAt: Date;
+      eventCount: number;
+      lastEventAt: Date;
+    }>();
+
+    for (const event of recentEvents) {
+      const existing = sessionMap.get(event.sessionId);
+      if (!existing) {
+        sessionMap.set(event.sessionId, {
+          id: event.sessionId,
+          startedAt: event.timestamp,
+          eventCount: 1,
+          lastEventAt: event.timestamp
+        });
+      } else {
+        existing.eventCount++;
+        if (event.timestamp < existing.startedAt) {
+          existing.startedAt = event.timestamp;
+        }
+        if (event.timestamp > existing.lastEventAt) {
+          existing.lastEventAt = event.timestamp;
+        }
+      }
+    }
+
+    const sessions = Array.from(sessionMap.values())
+      .sort((a, b) => b.lastEventAt.getTime() - a.lastEventAt.getTime());
+
+    const total = sessions.length;
+    const start = (page - 1) * pageSize;
+    const end = start + pageSize;
+    const paginatedSessions = sessions.slice(start, end);
+
+    return c.json({
+      sessions: paginatedSessions,
+      total,
+      page,
+      pageSize,
+      hasMore: end < total
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});
+
+// GET /api/sessions/:id - Get session details
+sessionsRouter.get('/:id', async (c) => {
+  const { id } = c.req.param();
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    const events = await memoryService.getSessionHistory(id);
+
+    if (events.length === 0) {
+      return c.json({ error: 'Session not found' }, 404);
+    }
+
+    const session = {
+      id,
+      startedAt: events[0].timestamp,
+      endedAt: events[events.length - 1].timestamp,
+      eventCount: events.length
+    };
+
+    const eventsByType = {
+      user_prompt: events.filter(e => e.eventType === 'user_prompt').length,
+      agent_response: events.filter(e => e.eventType === 'agent_response').length,
+      tool_observation: events.filter(e => e.eventType === 'tool_observation').length
+    };
+
+    return c.json({
+      session,
+      events: events.slice(0, 100).map(e => ({
+        id: e.id,
+        eventType: e.eventType,
+        timestamp: e.timestamp,
+        preview: e.content.slice(0, 200) + (e.content.length > 200 ? '...' : '')
+      })),
+      stats: eventsByType
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});

package/src/server/api/stats.ts

@@ -0,0 +1,97 @@
+/**
+ * Stats API
+ * Endpoints for storage statistics
+ */
+
+import { Hono } from 'hono';
+import { getDefaultMemoryService } from '../../services/memory-service.js';
+
+export const statsRouter = new Hono();
+
+// GET /api/stats - Get overall statistics
+statsRouter.get('/', async (c) => {
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    const stats = await memoryService.getStats();
+    const recentEvents = await memoryService.getRecentEvents(10000);
+
+    // Calculate event types
+    const eventsByType = recentEvents.reduce((acc, e) => {
+      acc[e.eventType] = (acc[e.eventType] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+
+    // Calculate unique sessions
+    const uniqueSessions = new Set(recentEvents.map(e => e.sessionId));
+
+    // Calculate events by day (last 7 days)
+    const now = new Date();
+    const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+    const eventsByDay = recentEvents
+      .filter(e => e.timestamp >= sevenDaysAgo)
+      .reduce((acc, e) => {
+        const day = e.timestamp.toISOString().split('T')[0];
+        acc[day] = (acc[day] || 0) + 1;
+        return acc;
+      }, {} as Record<string, number>);
+
+    return c.json({
+      storage: {
+        eventCount: stats.totalEvents,
+        vectorCount: stats.vectorCount
+      },
+      sessions: {
+        total: uniqueSessions.size
+      },
+      eventsByType,
+      activity: {
+        daily: eventsByDay,
+        total7Days: recentEvents.filter(e => e.timestamp >= sevenDaysAgo).length
+      },
+      memory: {
+        heapUsed: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+        heapTotal: Math.round(process.memoryUsage().heapTotal / 1024 / 1024)
+      },
+      levelStats: stats.levelStats
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});
+
+// GET /api/stats/timeline - Get activity timeline
+statsRouter.get('/timeline', async (c) => {
+  const days = parseInt(c.req.query('days') || '7', 10);
+
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    const recentEvents = await memoryService.getRecentEvents(10000);
+
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+    const filteredEvents = recentEvents.filter(e => e.timestamp >= cutoff);
+
+    // Group by day
+    const daily = filteredEvents.reduce((acc, e) => {
+      const day = e.timestamp.toISOString().split('T')[0];
+      if (!acc[day]) {
+        acc[day] = { date: day, total: 0, prompts: 0, responses: 0, tools: 0 };
+      }
+      acc[day].total++;
+      if (e.eventType === 'user_prompt') acc[day].prompts++;
+      if (e.eventType === 'agent_response') acc[day].responses++;
+      if (e.eventType === 'tool_observation') acc[day].tools++;
+      return acc;
+    }, {} as Record<string, { date: string; total: number; prompts: number; responses: number; tools: number }>);
+
+    return c.json({
+      days,
+      daily: Object.values(daily).sort((a, b) => a.date.localeCompare(b.date))
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  }
+});

package/src/server/index.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 { serveStatic } from 'hono/bun';
+import * as path from 'path';
+import * as fs from 'fs';
+
+import { apiRouter } from './api/index.js';
+
+const app = new Hono();
+
+// 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() }));
+
+// Static files (UI)
+const uiPath = path.join(import.meta.dir, '../../dist/ui');
+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 Bun.serve> | null = null;
+
+/**
+ * Start the HTTP server
+ */
+export function startServer(port: number = 37777): ReturnType<typeof Bun.serve> {
+  if (serverInstance) {
+    return serverInstance;
+  }
+
+  serverInstance = Bun.serve({
+    hostname: '127.0.0.1',
+    port,
+    fetch: app.fetch
+  });
+
+  console.log(`🧠 Code Memory viewer started at http://localhost:${port}`);
+
+  return serverInstance;
+}
+
+/**
+ * Stop the HTTP server
+ */
+export function stopServer(): void {
+  if (serverInstance) {
+    serverInstance.stop();
+    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
+if (import.meta.main) {
+  const port = parseInt(process.env.PORT || '37777', 10);
+  startServer(port);
+}