claude-memory-layer 1.0.6 → 1.0.8

package/src/server/api/stats.ts

@@ -4,16 +4,109 @@
  */
 
 import { Hono } from 'hono';
-import { getDefaultMemoryService } from '../../services/memory-service.js';
+import { getReadOnlyMemoryService, getMemoryServiceForProject } from '../../services/memory-service.js';
 
 export const statsRouter = new Hono();
 
+// GET /api/stats/shared - Get shared store statistics
+statsRouter.get('/shared', async (c) => {
+  const memoryService = getReadOnlyMemoryService();
+  try {
+    await memoryService.initialize();
+    const sharedStats = await memoryService.getSharedStoreStats();
+    return c.json({
+      troubleshooting: sharedStats?.troubleshooting || 0,
+      bestPractices: sharedStats?.bestPractices || 0,
+      commonErrors: sharedStats?.commonErrors || 0,
+      totalUsageCount: sharedStats?.totalUsageCount || 0,
+      lastUpdated: sharedStats?.lastUpdated || null
+    });
+  } catch (error) {
+    return c.json({
+      troubleshooting: 0,
+      bestPractices: 0,
+      commonErrors: 0,
+      totalUsageCount: 0,
+      lastUpdated: null
+    });
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+// GET /api/stats/endless - Get endless mode status
+statsRouter.get('/endless', async (c) => {
+  const projectPath = c.req.query('project') || process.cwd();
+  const memoryService = getMemoryServiceForProject(projectPath);
+  try {
+    await memoryService.initialize();
+    const status = await memoryService.getEndlessModeStatus();
+    return c.json({
+      mode: status.mode,
+      continuityScore: status.continuityScore,
+      workingSetSize: status.workingSetSize,
+      consolidatedCount: status.consolidatedCount,
+      lastConsolidation: status.lastConsolidation?.toISOString() || null
+    });
+  } catch (error) {
+    return c.json({
+      mode: 'session',
+      continuityScore: 0,
+      workingSetSize: 0,
+      consolidatedCount: 0,
+      lastConsolidation: null
+    });
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+// GET /api/stats/levels/:level - Get events by memory level
+statsRouter.get('/levels/:level', async (c) => {
+  const { level } = c.req.param();
+  const limit = parseInt(c.req.query('limit') || '20', 10);
+  const offset = parseInt(c.req.query('offset') || '0', 10);
+
+  // Validate level
+  const validLevels = ['L0', 'L1', 'L2', 'L3', 'L4'];
+  if (!validLevels.includes(level)) {
+    return c.json({ error: `Invalid level. Must be one of: ${validLevels.join(', ')}` }, 400);
+  }
+
+  const memoryService = getReadOnlyMemoryService();
+  try {
+    await memoryService.initialize();
+    const events = await memoryService.getEventsByLevel(level, { limit, offset });
+    const stats = await memoryService.getStats();
+    const levelStat = stats.levelStats.find(s => s.level === level);
+
+    return c.json({
+      level,
+      events: events.map(e => ({
+        id: e.id,
+        eventType: e.eventType,
+        sessionId: e.sessionId,
+        timestamp: e.timestamp.toISOString(),
+        content: e.content.slice(0, 500) + (e.content.length > 500 ? '...' : ''),
+        metadata: e.metadata
+      })),
+      total: levelStat?.count || 0,
+      limit,
+      offset,
+      hasMore: events.length === limit
+    });
+  } catch (error) {
+    return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
 // GET /api/stats - Get overall statistics
 statsRouter.get('/', async (c) => {
+  const memoryService = getReadOnlyMemoryService();
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
-
     const stats = await memoryService.getStats();
     const recentEvents = await memoryService.getRecentEvents(10000);
 
@@ -58,17 +151,51 @@ statsRouter.get('/', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+// GET /api/stats/most-accessed - Get most accessed memories
+statsRouter.get('/most-accessed', async (c) => {
+  const limit = parseInt(c.req.query('limit') || '10', 10);
+  const projectPath = c.req.query('project') || process.cwd();
+  const memoryService = getMemoryServiceForProject(projectPath);
+
+  try {
+    await memoryService.initialize();
+    const memories = await memoryService.getMostAccessedMemories(limit);
+
+    return c.json({
+      memories: memories.map(m => ({
+        memoryId: m.memoryId,
+        summary: m.summary,
+        topics: m.topics,
+        accessCount: m.accessCount,
+        lastAccessed: m.accessedAt?.toISOString() || null,
+        confidence: m.confidence,
+        createdAt: m.createdAt.toISOString()
+      })),
+      total: memories.length
+    });
+  } catch (error) {
+    return c.json({
+      memories: [],
+      total: 0,
+      error: (error as Error).message
+    });
+  } finally {
+    await memoryService.shutdown();
   }
 });
 
 // GET /api/stats/timeline - Get activity timeline
 statsRouter.get('/timeline', async (c) => {
   const days = parseInt(c.req.query('days') || '7', 10);
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
-
     const recentEvents = await memoryService.getRecentEvents(10000);
 
     const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
@@ -93,5 +220,48 @@ statsRouter.get('/timeline', async (c) => {
     });
   } catch (error) {
     return c.json({ 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();
+  try {
+    await memoryService.initialize();
+    const result = await memoryService.forceGraduation();
+
+    return c.json({
+      success: true,
+      evaluated: result.evaluated,
+      graduated: result.graduated,
+      byLevel: result.byLevel
+    });
+  } catch (error) {
+    return c.json({
+      success: false,
+      error: (error as Error).message
+    }, 500);
+  } finally {
+    await memoryService.shutdown();
+  }
+});
+
+// GET /api/stats/graduation - Get graduation criteria info
+statsRouter.get('/graduation', async (c) => {
+  return c.json({
+    criteria: {
+      L0toL1: { minAccessCount: 1, minConfidence: 0.5, minCrossSessionRefs: 0, maxAgeDays: 30 },
+      L1toL2: { minAccessCount: 3, minConfidence: 0.7, minCrossSessionRefs: 1, maxAgeDays: 60 },
+      L2toL3: { minAccessCount: 5, minConfidence: 0.85, minCrossSessionRefs: 2, maxAgeDays: 90 },
+      L3toL4: { minAccessCount: 10, minConfidence: 0.92, minCrossSessionRefs: 3, maxAgeDays: 180 }
+    },
+    description: {
+      accessCount: 'Number of times the memory was retrieved/referenced',
+      confidence: 'Match confidence score when retrieved (0.0-1.0)',
+      crossSessionRefs: 'Number of different sessions that referenced this memory',
+      maxAgeDays: 'Maximum days since last access (prevents stale promotion)'
+    }
+  });
+});

package/src/server/index.ts

@@ -3,12 +3,18 @@
  * Provides REST API and serves static UI files
  */
 
+// These are injected by the esbuild banner
+declare const __dirname: string;
+declare const __filename: string;
+
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import { logger } from 'hono/logger';
-import { serveStatic } from 'hono/bun';
+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 type { Server } from 'http';
 
 import { apiRouter } from './api/index.js';
 
@@ -25,7 +31,7 @@ app.route('/api', apiRouter);
 app.get('/health', (c) => c.json({ status: 'ok', timestamp: new Date().toISOString() }));
 
 // Static files (UI)
-const uiPath = path.join(import.meta.dir, '../../dist/ui');
+const uiPath = path.join(__dirname, '../../dist/ui');
 if (fs.existsSync(uiPath)) {
   app.use('/*', serveStatic({ root: uiPath }));
 }
@@ -41,20 +47,20 @@ app.get('*', (c) => {
 
 export { app };
 
-let serverInstance: ReturnType<typeof Bun.serve> | null = null;
+let serverInstance: Server | null = null;
 
 /**
  * Start the HTTP server
  */
-export function startServer(port: number = 37777): ReturnType<typeof Bun.serve> {
+export function startServer(port: number = 37777): Server {
   if (serverInstance) {
     return serverInstance;
   }
 
-  serverInstance = Bun.serve({
-    hostname: '127.0.0.1',
+  serverInstance = serve({
+    fetch: app.fetch,
     port,
-    fetch: app.fetch
+    hostname: '127.0.0.1'
   });
 
   console.log(`🧠 Code Memory viewer started at http://localhost:${port}`);
@@ -67,7 +73,7 @@ export function startServer(port: number = 37777): ReturnType<typeof Bun.serve>
  */
 export function stopServer(): void {
   if (serverInstance) {
-    serverInstance.stop();
+    serverInstance.close();
     serverInstance = null;
   }
 }
@@ -85,7 +91,10 @@ export async function isServerRunning(port: number = 37777): Promise<boolean> {
 }
 
 // Start server if run directly
-if (import.meta.main) {
+// 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);
 }

package/src/services/memory-service.ts

@@ -42,10 +42,12 @@ import { WorkingSetStore, createWorkingSetStore } from '../core/working-set-stor
 import { ConsolidatedStore, createConsolidatedStore } from '../core/consolidated-store.js';
 import { ConsolidationWorker, createConsolidationWorker } from '../core/consolidation-worker.js';
 import { ContinuityManager, createContinuityManager } from '../core/continuity-manager.js';
+import { GraduationWorker, createGraduationWorker, GraduationRunResult } from '../core/graduation-worker.js';
 
 export interface MemoryServiceConfig {
   storagePath: string;
   embeddingModel?: string;
+  readOnly?: boolean;
 }
 
 // ============================================================
@@ -170,6 +172,7 @@ export class MemoryService {
   private readonly retriever: Retriever;
   private readonly graduation: GraduationPipeline;
   private vectorWorker: VectorWorker | null = null;
+  private graduationWorker: GraduationWorker | null = null;
   private initialized = false;
 
   // Endless Mode components
@@ -187,11 +190,14 @@ export class MemoryService {
   private sharedStoreConfig: SharedStoreConfig | null = null;
   private projectHash: string | null = null;
 
+  private readonly readOnly: boolean;
+
   constructor(config: MemoryServiceConfig & { projectHash?: string; sharedStoreConfig?: SharedStoreConfig }) {
     const storagePath = this.expandPath(config.storagePath);
+    this.readOnly = config.readOnly ?? false;
 
-    // Ensure storage directory exists
-    if (!fs.existsSync(storagePath)) {
+    // Ensure storage directory exists (only if not read-only)
+    if (!this.readOnly && !fs.existsSync(storagePath)) {
       fs.mkdirSync(storagePath, { recursive: true });
     }
 
@@ -201,7 +207,7 @@ export class MemoryService {
     this.sharedStoreConfig = config.sharedStoreConfig ?? { enabled: true };
 
     // Initialize components
-    this.eventStore = new EventStore(path.join(storagePath, 'events.duckdb'));
+    this.eventStore = new EventStore(path.join(storagePath, 'events.duckdb'), { readOnly: this.readOnly });
     this.vectorStore = new VectorStore(path.join(storagePath, 'vectors'));
     this.embedder = config.embeddingModel
       ? new Embedder(config.embeddingModel)
@@ -226,24 +232,37 @@ export class MemoryService {
     await this.vectorStore.initialize();
     await this.embedder.initialize();
 
-    // Start vector worker
-    this.vectorWorker = createVectorWorker(
-      this.eventStore,
-      this.vectorStore,
-      this.embedder
-    );
-    this.vectorWorker.start();
+    // Skip write-related workers in read-only mode
+    if (!this.readOnly) {
+      // Start vector worker
+      this.vectorWorker = createVectorWorker(
+        this.eventStore,
+        this.vectorStore,
+        this.embedder
+      );
+      this.vectorWorker.start();
 
-    // Load endless mode setting
-    const savedMode = await this.eventStore.getEndlessConfig('mode') as MemoryMode | null;
-    if (savedMode === 'endless') {
-      this.endlessMode = 'endless';
-      await this.initializeEndlessMode();
-    }
+      // Connect graduation pipeline to retriever for access tracking
+      this.retriever.setGraduationPipeline(this.graduation);
+
+      // Start graduation worker for automatic level promotion
+      this.graduationWorker = createGraduationWorker(
+        this.eventStore,
+        this.graduation
+      );
+      this.graduationWorker.start();
 
-    // Initialize shared store (enabled by default)
-    if (this.sharedStoreConfig?.enabled !== false) {
-      await this.initializeSharedStore();
+      // Load endless mode setting
+      const savedMode = await this.eventStore.getEndlessConfig('mode') as MemoryMode | null;
+      if (savedMode === 'endless') {
+        this.endlessMode = 'endless';
+        await this.initializeEndlessMode();
+      }
+
+      // Initialize shared store (enabled by default)
+      if (this.sharedStoreConfig?.enabled !== false) {
+        await this.initializeSharedStore();
+      }
     }
 
     this.initialized = true;
@@ -499,6 +518,22 @@ export class MemoryService {
     return 0;
   }
 
+  /**
+   * Get events by memory level
+   */
+  async getEventsByLevel(level: string, options?: { limit?: number; offset?: number }): Promise<MemoryEvent[]> {
+    await this.initialize();
+    return this.eventStore.getEventsByLevel(level, options);
+  }
+
+  /**
+   * Get memory level for a specific event
+   */
+  async getEventLevel(eventId: string): Promise<string | null> {
+    await this.initialize();
+    return this.eventStore.getEventLevel(eventId);
+  }
+
   /**
    * Format retrieval results as context for Claude
    */
@@ -713,6 +748,22 @@ export class MemoryService {
     return this.consolidatedStore.getAll({ limit });
   }
 
+  /**
+   * Get most accessed consolidated memories
+   */
+  async getMostAccessedMemories(limit: number = 10): Promise<ConsolidatedMemory[]> {
+    if (!this.consolidatedStore) return [];
+    return this.consolidatedStore.getMostAccessed(limit);
+  }
+
+  /**
+   * Mark a consolidated memory as accessed
+   */
+  async markMemoryAccessed(memoryId: string): Promise<void> {
+    if (!this.consolidatedStore) return;
+    await this.consolidatedStore.markAccessed(memoryId);
+  }
+
   /**
    * Calculate continuity score for current context
    */
@@ -822,10 +873,32 @@ export class MemoryService {
     return parts.join('\n');
   }
 
+  /**
+   * Force a graduation evaluation run
+   */
+  async forceGraduation(): Promise<GraduationRunResult> {
+    if (!this.graduationWorker) {
+      return { evaluated: 0, graduated: 0, byLevel: {} };
+    }
+    return this.graduationWorker.forceRun();
+  }
+
+  /**
+   * Record access to a memory event (for graduation scoring)
+   */
+  recordMemoryAccess(eventId: string, sessionId: string, confidence: number = 1.0): void {
+    this.graduation.recordAccess(eventId, sessionId, confidence);
+  }
+
   /**
    * Shutdown service
    */
   async shutdown(): Promise<void> {
+    // Stop graduation worker
+    if (this.graduationWorker) {
+      this.graduationWorker.stop();
+    }
+
     // Stop endless mode components
     if (this.consolidationWorker) {
       this.consolidationWorker.stop();
@@ -861,6 +934,7 @@ export class MemoryService {
 // Instance cache: Map from project hash (or '__global__') to MemoryService
 const serviceCache = new Map<string, MemoryService>();
 const GLOBAL_KEY = '__global__';
+const GLOBAL_READONLY_KEY = '__global_readonly__';
 
 /**
  * Get the global memory service (backward compatibility)
@@ -875,6 +949,20 @@ export function getDefaultMemoryService(): MemoryService {
   return serviceCache.get(GLOBAL_KEY)!;
 }
 
+/**
+ * Get a read-only global memory service
+ * Use this for web server/dashboard that only needs to read data
+ * Creates a fresh connection each time to avoid blocking the main writer process
+ */
+export function getReadOnlyMemoryService(): MemoryService {
+  // Don't cache - create fresh instance each time to avoid holding locks
+  // The connection will be closed when the request completes
+  return new MemoryService({
+    storagePath: '~/.claude-code/memory',
+    readOnly: true
+  });
+}
+
 /**
  * Get memory service for a specific project path
  * Creates isolated storage at ~/.claude-code/memory/projects/{hash}/