claude-memory-layer 1.0.7 → 1.0.8

package/src/cli/index.ts

@@ -6,6 +6,9 @@
 
 import { Command } from 'commander';
 import { exec } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
 import {
   getDefaultMemoryService,
   getMemoryServiceForProject
@@ -13,6 +16,92 @@ import {
 import { createSessionHistoryImporter } from '../services/session-history-importer.js';
 import { startServer, stopServer, isServerRunning } from '../server/index.js';
 
+// ============================================================
+// Hook Installation Utilities
+// ============================================================
+
+const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+
+interface ClaudeSettings {
+  hooks?: {
+    UserPromptSubmit?: Array<{ matcher: string; hooks: Array<{ type: string; command: string }> }>;
+    PostToolUse?: Array<{ matcher: string; hooks: Array<{ type: string; command: string }> }>;
+    SessionStart?: Array<{ matcher: string; hooks: Array<{ type: string; command: string }> }>;
+    Stop?: Array<{ matcher: string; hooks: Array<{ type: string; command: string }> }>;
+  };
+  [key: string]: unknown;
+}
+
+function getPluginPath(): string {
+  // Try to find the dist directory
+  const possiblePaths = [
+    path.join(__dirname, '..'),  // When running from dist/cli
+    path.join(__dirname, '../..', 'dist'),  // When running from src
+    path.join(process.cwd(), 'dist'),  // Current working directory
+  ];
+
+  for (const p of possiblePaths) {
+    const hooksPath = path.join(p, 'hooks', 'user-prompt-submit.js');
+    if (fs.existsSync(hooksPath)) {
+      return p;
+    }
+  }
+
+  // Fallback to npm global installation path
+  return path.join(os.homedir(), '.npm-global', 'lib', 'node_modules', 'claude-memory-layer', 'dist');
+}
+
+function loadClaudeSettings(): ClaudeSettings {
+  try {
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+      const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    console.error('Warning: Could not read existing settings:', error);
+  }
+  return {};
+}
+
+function saveClaudeSettings(settings: ClaudeSettings): void {
+  const dir = path.dirname(CLAUDE_SETTINGS_PATH);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Atomic write
+  const tempPath = CLAUDE_SETTINGS_PATH + '.tmp';
+  fs.writeFileSync(tempPath, JSON.stringify(settings, null, 2));
+  fs.renameSync(tempPath, CLAUDE_SETTINGS_PATH);
+}
+
+function getHooksConfig(pluginPath: string): ClaudeSettings['hooks'] {
+  return {
+    UserPromptSubmit: [
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `node ${path.join(pluginPath, 'hooks', 'user-prompt-submit.js')}`
+          }
+        ]
+      }
+    ],
+    PostToolUse: [
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `node ${path.join(pluginPath, 'hooks', 'post-tool-use.js')}`
+          }
+        ]
+      }
+    ]
+  };
+}
+
 const program = new Command();
 
 program
@@ -20,6 +109,143 @@ program
   .description('Claude Code Memory Plugin CLI')
   .version('1.0.0');
 
+// ============================================================
+// Install / Uninstall Commands
+// ============================================================
+
+/**
+ * Install command - register hooks with Claude Code
+ */
+program
+  .command('install')
+  .description('Install hooks into Claude Code settings')
+  .option('--path <path>', 'Custom plugin path (defaults to auto-detect)')
+  .action(async (options) => {
+    try {
+      const pluginPath = options.path || getPluginPath();
+
+      // Verify hooks exist
+      const userPromptHook = path.join(pluginPath, 'hooks', 'user-prompt-submit.js');
+      if (!fs.existsSync(userPromptHook)) {
+        console.error(`\n❌ Hook files not found at: ${pluginPath}`);
+        console.error('   Make sure you have built the plugin with "npm run build"');
+        process.exit(1);
+      }
+
+      // Load existing settings
+      const settings = loadClaudeSettings();
+
+      // Add hooks (merge with existing)
+      const newHooks = getHooksConfig(pluginPath);
+      settings.hooks = {
+        ...settings.hooks,
+        ...newHooks
+      };
+
+      // Save settings
+      saveClaudeSettings(settings);
+
+      console.log('\n✅ Claude Memory Layer installed!\n');
+      console.log('Hooks registered:');
+      console.log('  - UserPromptSubmit: Memory retrieval on user input');
+      console.log('  - PostToolUse: Store tool observations\n');
+      console.log('Plugin path:', pluginPath);
+      console.log('\n⚠️  Restart Claude Code for changes to take effect.\n');
+      console.log('Commands:');
+      console.log('  claude-memory-layer dashboard  - Open web dashboard');
+      console.log('  claude-memory-layer search     - Search memories');
+      console.log('  claude-memory-layer stats      - View statistics');
+      console.log('  claude-memory-layer uninstall  - Remove hooks\n');
+    } catch (error) {
+      console.error('Install failed:', error);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Uninstall command - remove hooks from Claude Code
+ */
+program
+  .command('uninstall')
+  .description('Remove hooks from Claude Code settings')
+  .action(async () => {
+    try {
+      // Load existing settings
+      const settings = loadClaudeSettings();
+
+      if (!settings.hooks) {
+        console.log('\n📋 No hooks installed.\n');
+        return;
+      }
+
+      // Remove our hooks
+      delete settings.hooks.UserPromptSubmit;
+      delete settings.hooks.PostToolUse;
+
+      // Clean up empty hooks object
+      if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+      }
+
+      // Save settings
+      saveClaudeSettings(settings);
+
+      console.log('\n✅ Claude Memory Layer uninstalled!\n');
+      console.log('Hooks removed from Claude Code settings.');
+      console.log('Your memory data is preserved and can be accessed with:');
+      console.log('  claude-memory-layer dashboard\n');
+      console.log('⚠️  Restart Claude Code for changes to take effect.\n');
+    } catch (error) {
+      console.error('Uninstall failed:', error);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Status command - check installation status
+ */
+program
+  .command('status')
+  .description('Check plugin installation status')
+  .action(async () => {
+    try {
+      const settings = loadClaudeSettings();
+      const pluginPath = getPluginPath();
+
+      console.log('\n🧠 Claude Memory Layer Status\n');
+
+      // Check hooks
+      const hasUserPromptHook = settings.hooks?.UserPromptSubmit?.some(h =>
+        h.hooks?.some(hook => hook.command?.includes('user-prompt-submit'))
+      );
+      const hasPostToolHook = settings.hooks?.PostToolUse?.some(h =>
+        h.hooks?.some(hook => hook.command?.includes('post-tool-use'))
+      );
+
+      console.log('Hooks:');
+      console.log(`  UserPromptSubmit: ${hasUserPromptHook ? '✅ Installed' : '❌ Not installed'}`);
+      console.log(`  PostToolUse: ${hasPostToolHook ? '✅ Installed' : '❌ Not installed'}`);
+
+      // Check plugin files
+      const hooksExist = fs.existsSync(path.join(pluginPath, 'hooks', 'user-prompt-submit.js'));
+      console.log(`\nPlugin files: ${hooksExist ? '✅ Found' : '❌ Not found'}`);
+      console.log(`  Path: ${pluginPath}`);
+
+      // Check dashboard
+      const dashboardRunning = await isServerRunning(37777);
+      console.log(`\nDashboard: ${dashboardRunning ? '✅ Running at http://localhost:37777' : '⏹️  Not running'}`);
+
+      if (!hasUserPromptHook || !hasPostToolHook) {
+        console.log('\n💡 Run "claude-memory-layer install" to set up hooks.\n');
+      } else {
+        console.log('\n✅ Plugin is fully installed and configured.\n');
+      }
+    } catch (error) {
+      console.error('Status check failed:', error);
+      process.exit(1);
+    }
+  });
+
 /**
  * Search command
  */

package/src/core/db-wrapper.ts

@@ -37,10 +37,17 @@ export function toDate(value: unknown): Date {
   return new Date(String(value));
 }
 
+export interface DatabaseOptions {
+  readOnly?: boolean;
+}
+
 /**
  * Creates a new DuckDB database with Promise-based API
  */
-export function createDatabase(path: string): Database {
+export function createDatabase(path: string, options?: DatabaseOptions): Database {
+  if (options?.readOnly) {
+    return new duckdb.Database(path, { access_mode: 'READ_ONLY' });
+  }
   return new duckdb.Database(path);
 }
 

package/src/core/event-store.ts

@@ -12,14 +12,20 @@ import {
   OutboxItem
 } from './types.js';
 import { makeCanonicalKey, makeDedupeKey } from './canonical-key.js';
-import { createDatabase, dbRun, dbAll, dbClose, toDate, type Database } from './db-wrapper.js';
+import { createDatabase, dbRun, dbAll, dbClose, toDate, type Database, type DatabaseOptions } from './db-wrapper.js';
+
+export interface EventStoreOptions extends DatabaseOptions {
+  // Additional options can be added here
+}
 
 export class EventStore {
   private db: Database;
   private initialized = false;
+  private readonly readOnly: boolean;
 
-  constructor(private dbPath: string) {
-    this.db = createDatabase(dbPath);
+  constructor(private dbPath: string, options?: EventStoreOptions) {
+    this.readOnly = options?.readOnly ?? false;
+    this.db = createDatabase(dbPath, { readOnly: this.readOnly });
   }
 
   /**
@@ -28,6 +34,12 @@ export class EventStore {
   async initialize(): Promise<void> {
     if (this.initialized) return;
 
+    // In read-only mode, skip schema creation (tables already exist)
+    if (this.readOnly) {
+      this.initialized = true;
+      return;
+    }
+
     // L0 EventStore: Single Source of Truth (immutable, append-only)
     await dbRun(this.db, `
       CREATE TABLE IF NOT EXISTS events (
@@ -611,6 +623,43 @@ export class EventStore {
     return rows;
   }
 
+  /**
+   * Get events by memory level
+   */
+  async getEventsByLevel(level: string, options?: { limit?: number; offset?: number }): Promise<MemoryEvent[]> {
+    await this.initialize();
+
+    const limit = options?.limit || 50;
+    const offset = options?.offset || 0;
+
+    const rows = await dbAll<Record<string, unknown>>(
+      this.db,
+      `SELECT e.* FROM events e
+       INNER JOIN memory_levels ml ON e.id = ml.event_id
+       WHERE ml.level = ?
+       ORDER BY e.timestamp DESC
+       LIMIT ? OFFSET ?`,
+      [level, limit, offset]
+    );
+
+    return rows.map(row => this.rowToEvent(row));
+  }
+
+  /**
+   * Get memory level for a specific event
+   */
+  async getEventLevel(eventId: string): Promise<string | null> {
+    await this.initialize();
+
+    const rows = await dbAll<{ level: string }>(
+      this.db,
+      `SELECT level FROM memory_levels WHERE event_id = ?`,
+      [eventId]
+    );
+
+    return rows.length > 0 ? rows[0].level : null;
+  }
+
   // ============================================================
   // Endless Mode Helper Methods
   // ============================================================

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/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();
   }
 });