claude-memory-layer 1.0.6 → 1.0.8

package/src/core/graduation-worker.ts

@@ -0,0 +1,171 @@
+/**
+ * Graduation Worker
+ * Periodically evaluates memory events for promotion to higher levels
+ * L0 → L1 → L2 → L3 → L4 based on access patterns and confidence
+ */
+
+import type { MemoryLevel } from './types.js';
+import { EventStore } from './event-store.js';
+import { GraduationPipeline } from './graduation.js';
+
+export interface GraduationWorkerConfig {
+  /** How often to run graduation evaluation (ms) */
+  evaluationIntervalMs: number;
+  /** Batch size for graduation evaluation */
+  batchSize: number;
+  /** Minimum time between evaluations of the same event (ms) */
+  cooldownMs: number;
+}
+
+const DEFAULT_CONFIG: GraduationWorkerConfig = {
+  evaluationIntervalMs: 300000, // 5 minutes
+  batchSize: 50,
+  cooldownMs: 3600000 // 1 hour cooldown between evaluations
+};
+
+export class GraduationWorker {
+  private running = false;
+  private timeout: NodeJS.Timeout | null = null;
+  private lastEvaluated: Map<string, number> = new Map();
+
+  constructor(
+    private eventStore: EventStore,
+    private graduation: GraduationPipeline,
+    private config: GraduationWorkerConfig = DEFAULT_CONFIG
+  ) {}
+
+  /**
+   * Start the graduation worker
+   */
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.scheduleNext();
+  }
+
+  /**
+   * Stop the graduation worker
+   */
+  stop(): void {
+    this.running = false;
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+      this.timeout = null;
+    }
+  }
+
+  /**
+   * Check if currently running
+   */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Force a graduation evaluation run
+   */
+  async forceRun(): Promise<GraduationRunResult> {
+    return await this.runGraduation();
+  }
+
+  /**
+   * Schedule the next graduation check
+   */
+  private scheduleNext(): void {
+    if (!this.running) return;
+
+    this.timeout = setTimeout(
+      () => this.run(),
+      this.config.evaluationIntervalMs
+    );
+  }
+
+  /**
+   * Run graduation evaluation
+   */
+  private async run(): Promise<void> {
+    if (!this.running) return;
+
+    try {
+      await this.runGraduation();
+    } catch (error) {
+      console.error('Graduation error:', error);
+    }
+
+    this.scheduleNext();
+  }
+
+  /**
+   * Perform graduation evaluation across all levels
+   */
+  private async runGraduation(): Promise<GraduationRunResult> {
+    const result: GraduationRunResult = {
+      evaluated: 0,
+      graduated: 0,
+      byLevel: {}
+    };
+
+    const levels: MemoryLevel[] = ['L0', 'L1', 'L2', 'L3'];
+    const now = Date.now();
+
+    for (const level of levels) {
+      const events = await this.eventStore.getEventsByLevel(level, {
+        limit: this.config.batchSize
+      });
+
+      let levelGraduated = 0;
+
+      for (const event of events) {
+        // Check cooldown
+        const lastEval = this.lastEvaluated.get(event.id);
+        if (lastEval && (now - lastEval) < this.config.cooldownMs) {
+          continue;
+        }
+
+        result.evaluated++;
+        this.lastEvaluated.set(event.id, now);
+
+        const gradResult = await this.graduation.evaluateGraduation(event.id, level);
+
+        if (gradResult.success) {
+          result.graduated++;
+          levelGraduated++;
+        }
+      }
+
+      if (levelGraduated > 0) {
+        result.byLevel[level] = levelGraduated;
+      }
+    }
+
+    // Clean up old cooldown entries (keep last 1000)
+    if (this.lastEvaluated.size > 1000) {
+      const entries = Array.from(this.lastEvaluated.entries());
+      entries.sort((a, b) => b[1] - a[1]);
+      this.lastEvaluated = new Map(entries.slice(0, 1000));
+    }
+
+    return result;
+  }
+}
+
+export interface GraduationRunResult {
+  evaluated: number;
+  graduated: number;
+  byLevel: Record<string, number>;
+}
+
+/**
+ * Create a Graduation Worker instance
+ */
+export function createGraduationWorker(
+  eventStore: EventStore,
+  graduation: GraduationPipeline,
+  config?: Partial<GraduationWorkerConfig>
+): GraduationWorker {
+  return new GraduationWorker(
+    eventStore,
+    graduation,
+    { ...DEFAULT_CONFIG, ...config }
+  );
+}

package/src/core/graduation.ts

@@ -84,18 +84,31 @@ export class GraduationPipeline {
     };
   }
 
+  // Track which sessions have accessed each event
+  private readonly sessionAccesses: Map<string, Set<string>> = new Map();
+
   /**
    * Record an access to an event (used for graduation scoring)
    */
   recordAccess(eventId: string, fromSessionId: string, confidence: number = 1.0): void {
     const existing = this.metrics.get(eventId);
 
+    // Track sessions that have accessed this event
+    if (!this.sessionAccesses.has(eventId)) {
+      this.sessionAccesses.set(eventId, new Set());
+    }
+    const sessions = this.sessionAccesses.get(eventId)!;
+    const isNewSession = !sessions.has(fromSessionId);
+    sessions.add(fromSessionId);
+
     if (existing) {
       existing.accessCount++;
       existing.lastAccessed = new Date();
       existing.confidence = Math.max(existing.confidence, confidence);
-      // Track cross-session references
-      // This would need more sophisticated tracking in production
+      // Update cross-session references count
+      if (isNewSession && sessions.size > 1) {
+        existing.crossSessionRefs = sessions.size - 1;
+      }
     } else {
       this.metrics.set(eventId, {
         eventId,

package/src/core/index.ts

@@ -27,6 +27,7 @@ export * from './evidence-aligner.js';
 // Retrieval & Graduation
 export * from './retriever.js';
 export * from './graduation.js';
+export * from './graduation-worker.js';
 
 // Task Entity System
 export * from './task/index.js';

package/src/core/retriever.ts

@@ -9,6 +9,7 @@ import { Embedder } from './embedder.js';
 import { Matcher } from './matcher.js';
 import { SharedStore } from './shared-store.js';
 import { SharedVectorStore } from './shared-vector-store.js';
+import { GraduationPipeline } from './graduation.js';
 import type { MemoryEvent, MatchResult, Config, SharedTroubleshootingEntry } from './types.js';
 
 export interface RetrievalOptions {
@@ -60,6 +61,7 @@ export class Retriever {
   private readonly matcher: Matcher;
   private sharedStore?: SharedStore;
   private sharedVectorStore?: SharedVectorStore;
+  private graduation?: GraduationPipeline;
 
   constructor(
     eventStore: EventStore,
@@ -76,6 +78,13 @@ export class Retriever {
     this.sharedVectorStore = sharedOptions?.sharedVectorStore;
   }
 
+  /**
+   * Set graduation pipeline for access tracking
+   */
+  setGraduationPipeline(graduation: GraduationPipeline): void {
+    this.graduation = graduation;
+  }
+
   /**
    * Set shared stores after construction
    */
@@ -237,6 +246,15 @@ export class Retriever {
       const event = await this.eventStore.getEvent(result.eventId);
       if (!event) continue;
 
+      // Record access for graduation scoring
+      if (this.graduation) {
+        this.graduation.recordAccess(
+          event.id,
+          options.sessionId || 'unknown',
+          result.score
+        );
+      }
+
       let sessionContext: string | undefined;
       if (options.includeSessionContext) {
         sessionContext = await this.getSessionContext(event.sessionId, event.id);

package/src/core/types.ts

@@ -1,5 +1,5 @@
 /**
- * Core types for code-memory plugin
+ * Core types for claude-memory-layer plugin
  * Idris2 inspired: Complete, immutable type definitions with Zod validation
  */
 

package/src/mcp/index.ts

@@ -16,7 +16,7 @@ import { handleToolCall } from './handlers.js';
 
 const server = new Server(
   {
-    name: 'code-memory-mcp',
+    name: 'claude-memory-layer-mcp',
     version: '1.0.0'
   },
   {
@@ -41,7 +41,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error('code-memory MCP server started');
+  console.error('claude-memory-layer MCP server started');
 }
 
 main().catch(console.error);

package/src/mcp/tools.ts

@@ -8,7 +8,7 @@ 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.',
+    description: 'Search claude-memory-layer for relevant past conversations and insights. Returns a compact index of results - use mem-details to get full content.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/server/api/citations.ts

@@ -4,7 +4,7 @@
  */
 
 import { Hono } from 'hono';
-import { getDefaultMemoryService } from '../../services/memory-service.js';
+import { getReadOnlyMemoryService } from '../../services/memory-service.js';
 import { generateCitationId, parseCitationId } from '../../core/citation-generator.js';
 
 export const citationsRouter = new Hono();
@@ -15,9 +15,9 @@ citationsRouter.get('/:id', async (c) => {
 
   // Support both formats: "a7Bc3x" or "mem:a7Bc3x"
   const citationId = parseCitationId(id) || id;
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     // Search through recent events to find the one matching this citation ID
@@ -48,6 +48,8 @@ citationsRouter.get('/:id', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });
 
@@ -55,9 +57,9 @@ citationsRouter.get('/:id', async (c) => {
 citationsRouter.get('/:id/related', async (c) => {
   const { id } = c.req.param();
   const citationId = parseCitationId(id) || id;
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     const recentEvents = await memoryService.getRecentEvents(10000);
@@ -97,5 +99,7 @@ citationsRouter.get('/:id/related', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });

package/src/server/api/events.ts

@@ -4,7 +4,7 @@
  */
 
 import { Hono } from 'hono';
-import { getDefaultMemoryService } from '../../services/memory-service.js';
+import { getReadOnlyMemoryService } from '../../services/memory-service.js';
 
 export const eventsRouter = new Hono();
 
@@ -14,9 +14,9 @@ eventsRouter.get('/', async (c) => {
   const eventType = c.req.query('type');
   const limit = parseInt(c.req.query('limit') || '100', 10);
   const offset = parseInt(c.req.query('offset') || '0', 10);
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     let events = await memoryService.getRecentEvents(limit + offset + 1000);
@@ -51,15 +51,17 @@ eventsRouter.get('/', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });
 
 // GET /api/events/:id - Get event details
 eventsRouter.get('/:id', async (c) => {
   const { id } = c.req.param();
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     const recentEvents = await memoryService.getRecentEvents(10000);
@@ -97,5 +99,7 @@ eventsRouter.get('/:id', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });

package/src/server/api/search.ts

@@ -4,7 +4,7 @@
  */
 
 import { Hono } from 'hono';
-import { getDefaultMemoryService } from '../../services/memory-service.js';
+import { getReadOnlyMemoryService } from '../../services/memory-service.js';
 
 export const searchRouter = new Hono();
 
@@ -20,6 +20,7 @@ interface SearchRequest {
 
 // POST /api/search - Search memories
 searchRouter.post('/', async (c) => {
+  const memoryService = getReadOnlyMemoryService();
   try {
     const body = await c.req.json<SearchRequest>();
 
@@ -27,7 +28,6 @@ searchRouter.post('/', async (c) => {
       return c.json({ error: 'Query is required' }, 400);
     }
 
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     const startTime = Date.now();
@@ -60,6 +60,8 @@ searchRouter.post('/', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });
 
@@ -72,9 +74,9 @@ searchRouter.get('/', async (c) => {
   }
 
   const topK = parseInt(c.req.query('topK') || '5', 10);
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     const result = await memoryService.retrieveMemories(query, { topK });
@@ -94,5 +96,7 @@ searchRouter.get('/', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });

package/src/server/api/sessions.ts

@@ -4,7 +4,7 @@
  */
 
 import { Hono } from 'hono';
-import { getDefaultMemoryService } from '../../services/memory-service.js';
+import { getReadOnlyMemoryService } from '../../services/memory-service.js';
 
 export const sessionsRouter = new Hono();
 
@@ -12,9 +12,9 @@ export const sessionsRouter = new Hono();
 sessionsRouter.get('/', async (c) => {
   const page = parseInt(c.req.query('page') || '1', 10);
   const pageSize = parseInt(c.req.query('pageSize') || '20', 10);
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     // Get recent events and extract sessions
@@ -65,15 +65,17 @@ sessionsRouter.get('/', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });
 
 // GET /api/sessions/:id - Get session details
 sessionsRouter.get('/:id', async (c) => {
   const { id } = c.req.param();
+  const memoryService = getReadOnlyMemoryService();
 
   try {
-    const memoryService = getDefaultMemoryService();
     await memoryService.initialize();
 
     const events = await memoryService.getSessionHistory(id);
@@ -107,5 +109,7 @@ sessionsRouter.get('/:id', async (c) => {
     });
   } catch (error) {
     return c.json({ error: (error as Error).message }, 500);
+  } finally {
+    await memoryService.shutdown();
   }
 });