claude-memory-layer 1.0.23 → 1.0.25

package/src/hooks/user-prompt-submit.ts

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
 /**
  * User Prompt Submit Hook
- * Called when user submits a prompt - retrieves relevant memories using fast keyword search
+ * Called when user submits a prompt - retrieves relevant memories.
  *
- * Uses SQLite FTS5 for fast keyword-based search (no ML model needed)
- * Much faster than vector search (~100ms vs 3-5s)
+ * Retrieval mode (CLAUDE_MEMORY_RETRIEVAL_MODE):
+ *   - keyword (default-fast): SQLite FTS5 only, no ML model (~10ms)
+ *   - semantic: vector search via long-running semantic daemon (~15-20ms warm)
+ *   - hybrid: semantic first, keyword fallback (default)
+ *
+ * The semantic daemon keeps the embedding model in memory across hook invocations,
+ * avoiding per-request model initialization (~730ms cold start).
  *
  * Turn Grouping: Generates a turn_id and persists it to a state file
  * so PostToolUse and Stop hooks can associate their events with this turn.
@@ -14,8 +19,9 @@ import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { getLightweightMemoryService, getMemoryServiceForSession } from '../services/memory-service.js';
-import { writeTurnState } from '../core/turn-state.js';
+import { getLightweightMemoryService } from '../services/memory-service.js';
+import { writeTurnState, readLastAssistantSnippet } from '../core/turn-state.js';
+import { retrieveSemanticMemories } from './semantic-daemon-client.js';
 import type { UserPromptSubmitInput, UserPromptSubmitOutput } from '../core/types.js';
 
 // Configuration
@@ -25,7 +31,7 @@ const BASE_MIN_SCORE = parseFloat(process.env.CLAUDE_MEMORY_MIN_SCORE || '0.4');
 const FALLBACK_MIN_SCORE = parseFloat(process.env.CLAUDE_MEMORY_FALLBACK_MIN_SCORE || '0.3');
 const ENABLE_SEARCH = process.env.CLAUDE_MEMORY_SEARCH !== 'false';
 const RETRIEVAL_MODE = (process.env.CLAUDE_MEMORY_RETRIEVAL_MODE || 'hybrid') as 'keyword' | 'semantic' | 'hybrid';
-const SEMANTIC_TIMEOUT_MS = parseInt(process.env.CLAUDE_MEMORY_SEMANTIC_TIMEOUT_MS || '1200');
+const SEMANTIC_TIMEOUT_MS = parseInt(process.env.CLAUDE_MEMORY_SEMANTIC_TIMEOUT_MS || '2000');
 const ADHERENCE_INTERVAL_TURNS = parseInt(process.env.CLAUDE_MEMORY_ADHERENCE_INTERVAL_TURNS || '3');
 
 const ADHERENCE_STATE_DIR = path.join(os.homedir(), '.claude-code', 'memory');
@@ -59,21 +65,6 @@ function getDynamicMinScore(prompt: string): number {
   return BASE_MIN_SCORE;
 }
 
-function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error(`semantic retrieval timeout (${timeoutMs}ms)`)), timeoutMs);
-    promise
-      .then((result) => {
-        clearTimeout(timer);
-        resolve(result);
-      })
-      .catch((error) => {
-        clearTimeout(timer);
-        reject(error);
-      });
-  });
-}
-
 function formatMemoryContext(items: Array<{ type: string; content: string }>): string {
   if (items.length === 0) return '';
   const lines = items.map((m) => {
@@ -196,6 +187,12 @@ async function main(): Promise<void> {
     const adherenceDecision = shouldRunAdherenceCheck(currentTurn, input.prompt, adherenceState);
     logAdherenceDecision(input.session_id, currentTurn, adherenceDecision.run, adherenceDecision.reason);
 
+    // On first turn of a new session, backfill helpfulness for sessions
+    // that ended without Stop hook (crash, force-close, etc.)
+    if (currentTurn === 1) {
+      memoryService.evaluatePendingSessions(input.session_id).catch(() => {});
+    }
+
     // Store only non-trivial prompts (skip /commands, short inputs)
     if (shouldStorePrompt(input.prompt)) {
       await memoryService.storeUserPrompt(
@@ -214,32 +211,30 @@ async function main(): Promise<void> {
 
     // Search strategy: turn-1 always enforce adherence check,
     // then adaptively enforce on write-intent/topic-shift/interval
-    if (ENABLE_SEARCH && input.prompt.length > 10 && adherenceDecision.run) {
+    const isSlashCommand = input.prompt.trimStart().startsWith('/');
+    if (ENABLE_SEARCH && !isSlashCommand && input.prompt.length > 10 && adherenceDecision.run) {
       const minScore = getDynamicMinScore(input.prompt);
       let mergedMemories: Array<{ type: string; content: string; id?: string; score?: number }> = [];
 
+      // On turn 2+, enrich the retrieval query with the previous assistant response
+      // so short/ambiguous follow-ups ("그거 고쳐줘") resolve correctly.
+      const lastSnippet = currentTurn > 1 ? readLastAssistantSnippet(input.session_id) : null;
+      const retrievalQuery = lastSnippet
+        ? `${lastSnippet}\n\n${input.prompt}`
+        : input.prompt;
+
       const canUseSemantic = RETRIEVAL_MODE === 'semantic' || RETRIEVAL_MODE === 'hybrid';
       if (canUseSemantic) {
         try {
-          const semanticService = getMemoryServiceForSession(input.session_id);
-          const semantic = await withTimeout(
-            semanticService.retrieveMemories(input.prompt, {
-              topK: MAX_MEMORIES,
-              minScore,
+          mergedMemories = await retrieveSemanticMemories(
+            {
               sessionId: input.session_id,
-              intentRewrite: true,
-              adaptiveRerank: true,
-              projectScopeMode: 'strict'
-            }),
+              prompt: retrievalQuery,
+              topK: MAX_MEMORIES,
+              minScore
+            },
             SEMANTIC_TIMEOUT_MS
           );
-
-          mergedMemories = semantic.memories.map((m) => ({
-            type: m.event.eventType,
-            content: m.event.content,
-            id: m.event.id,
-            score: m.score
-          }));
         } catch {
           // Semantic retrieval is best-effort; fallback below handles the rest
         }
@@ -251,14 +246,14 @@ async function main(): Promise<void> {
         mergedMemories.length === 0;
 
       if (shouldUseKeywordFallback && mergedMemories.length < MAX_MEMORIES) {
-        let results = await memoryService.keywordSearch(input.prompt, {
+        let results = await memoryService.keywordSearch(retrievalQuery, {
           topK: MAX_MEMORIES,
           minScore
         });
 
         // recall rescue: if nothing found at tuned threshold, retry with fallback floor
         if (results.length === 0 && FALLBACK_MIN_SCORE < minScore) {
-          results = await memoryService.keywordSearch(input.prompt, {
+          results = await memoryService.keywordSearch(retrievalQuery, {
             topK: MAX_MEMORIES,
             minScore: FALLBACK_MIN_SCORE
           });
@@ -299,6 +294,19 @@ async function main(): Promise<void> {
 
         context = formatMemoryContext(mergedMemories);
       }
+
+      // Record query-level trace for dashboard stats (retrieval_traces table)
+      const allCandidateIds = mergedMemories.map((m) => m.id).filter((v): v is string => Boolean(v));
+      try {
+        await memoryService.recordQueryTrace({
+          sessionId: input.session_id,
+          queryText: retrievalQuery,
+          strategy: RETRIEVAL_MODE,
+          candidateEventIds: allCandidateIds,
+          selectedEventIds: allCandidateIds,
+          confidence: mergedMemories.length > 0 ? 'medium' : 'none'
+        });
+      } catch { /* non-critical */ }
     }
 
     writeAdherenceState({

package/src/services/memory-service.ts

@@ -10,7 +10,6 @@ import * as crypto from 'crypto';
 
 import { EventStore } from '../core/event-store.js';
 import { SQLiteEventStore } from '../core/sqlite-event-store.js';
-import { SyncWorker } from '../core/sync-worker.js';
 import { VectorStore } from '../core/vector-store.js';
 import { Embedder, getDefaultEmbedder } from '../core/embedder.js';
 import { VectorWorker, createVectorWorker } from '../core/vector-worker.js';
@@ -61,6 +60,8 @@ export interface MemoryServiceConfig {
   analyticsEnabled?: boolean;
   /** Lightweight mode for hooks - skip heavy initialization (default: false) */
   lightweightMode?: boolean;
+  /** Start only VectorWorker, skip GraduationWorker and SyncWorker (default: false) */
+  embeddingOnly?: boolean;
 }
 
 // ============================================================
@@ -180,9 +181,6 @@ export function getSessionProject(sessionId: string): SessionRegistryEntry | nul
 export class MemoryService {
   // Primary store: SQLite (WAL mode) - for hooks, always available
   private readonly sqliteStore: SQLiteEventStore;
-  // Analytics store: DuckDB - for server reads (optional, synced from SQLite)
-  private readonly analyticsStore: EventStore | null;
-  private syncWorker: SyncWorker | null = null;
 
   private readonly vectorStore: VectorStore;
   private readonly embedder: Embedder;
@@ -212,6 +210,7 @@ export class MemoryService {
 
   private readonly readOnly: boolean;
   private readonly lightweightMode: boolean;
+  private readonly embeddingOnly: boolean;
   private readonly mdMirror: MarkdownMirror;
   private readonly storagePath: string;
 
@@ -220,6 +219,7 @@ export class MemoryService {
     this.storagePath = storagePath;
     this.readOnly = config.readOnly ?? false;
     this.lightweightMode = config.lightweightMode ?? false;
+    this.embeddingOnly = config.embeddingOnly ?? false;
     this.mdMirror = new MarkdownMirror(process.cwd());
 
     // Ensure storage directory exists (only if not read-only)
@@ -243,32 +243,6 @@ export class MemoryService {
       }
     );
 
-    // Initialize ANALYTICS store: DuckDB (optional, for server reads)
-    // Hooks set analyticsEnabled=false to avoid DuckDB lock conflicts
-    const analyticsEnabled = config.analyticsEnabled ?? this.readOnly; // Default: enabled only for read-only (server)
-
-    if (!analyticsEnabled) {
-      // Hook mode: skip DuckDB entirely to avoid lock conflicts
-      this.analyticsStore = null;
-    } else if (this.readOnly) {
-      // Server mode: try to use DuckDB for analytics, will fallback to SQLite
-      try {
-        this.analyticsStore = new EventStore(
-          path.join(storagePath, 'analytics.duckdb'),
-          { readOnly: true }
-        );
-      } catch {
-        // DuckDB not available, will use SQLite for reads
-        this.analyticsStore = null;
-      }
-    } else {
-      // Writer mode with analytics: create DuckDB for sync target
-      this.analyticsStore = new EventStore(
-        path.join(storagePath, 'analytics.duckdb'),
-        { readOnly: false }
-      );
-    }
-
     this.vectorStore = new VectorStore(path.join(storagePath, 'vectors'));
     const embeddingModel = config.embeddingModel || process.env.CLAUDE_MEMORY_EMBEDDING_MODEL;
     this.embedder = embeddingModel
@@ -302,16 +276,6 @@ export class MemoryService {
       return;
     }
 
-    // Initialize analytics store if available (DuckDB)
-    if (this.analyticsStore) {
-      try {
-        await this.analyticsStore.initialize();
-      } catch (error) {
-        console.warn('[MemoryService] Analytics store (DuckDB) initialization failed, using SQLite for reads:', error);
-        // Continue without analytics - SQLite will be used for reads
-      }
-    }
-
     await this.vectorStore.initialize();
     await this.embedder.initialize();
 
@@ -325,24 +289,17 @@ export class MemoryService {
       );
       this.vectorWorker.start();
 
-      // Connect graduation pipeline to retriever for access tracking
-      this.retriever.setGraduationPipeline(this.graduation);
+      if (!this.embeddingOnly) {
+        // Connect graduation pipeline to retriever for access tracking
+        this.retriever.setGraduationPipeline(this.graduation);
 
-      // Start graduation worker for automatic level promotion
-      this.graduationWorker = createGraduationWorker(
-        this.sqliteStore as unknown as EventStore,
-        this.graduation
-      );
-      this.graduationWorker.start();
-
-      // Start sync worker (SQLite -> DuckDB) if analytics store is available
-      if (this.analyticsStore) {
-        this.syncWorker = new SyncWorker(
-          this.sqliteStore,
-          this.analyticsStore,
-          { intervalMs: 30000, batchSize: 500 }
+        // Start graduation worker for automatic level promotion
+        this.graduationWorker = createGraduationWorker(
+          this.sqliteStore as unknown as EventStore,
+          this.graduation
         );
-        this.syncWorker.start();
+        this.graduationWorker.start();
+
       }
 
       // Load endless mode setting
@@ -596,6 +553,67 @@ export class MemoryService {
     );
   }
 
+  /**
+   * Backfill session summaries for recent sessions that are missing them.
+   * Called from session-start hook to catch sessions that ended without Stop hook.
+   */
+  async backfillMissingSummaries(currentSessionId: string, limit = 5): Promise<void> {
+    await this.initialize();
+
+    // Get recent sessions that don't have a summary event
+    const recentSessionIds = await this.sqliteStore.getSessionsWithoutSummary(currentSessionId, limit);
+    for (const sid of recentSessionIds) {
+      try {
+        await this.generateSessionSummary(sid);
+      } catch {
+        // non-critical
+      }
+    }
+  }
+
+  /**
+   * Generate a rule-based session summary from stored events.
+   * Called at session end (Stop hook) when no LLM-generated summary exists.
+   * Skips if a summary already exists for this session.
+   */
+  async generateSessionSummary(sessionId: string): Promise<void> {
+    await this.initialize();
+
+    const events = await this.sqliteStore.getSessionEvents(sessionId);
+    if (events.length < 3) return; // Too short to summarize
+
+    // Skip if summary already exists
+    const hasSummary = events.some((e) => e.eventType === 'session_summary');
+    if (hasSummary) return;
+
+    const prompts = events.filter((e) => e.eventType === 'user_prompt');
+    const toolObs = events.filter((e) => e.eventType === 'tool_observation');
+    const toolNames = [...new Set(
+      toolObs.map((e) => (e.metadata as Record<string, unknown>)?.toolName as string).filter(Boolean)
+    )];
+    const errorObs = toolObs.filter((e) => {
+      const meta = e.metadata as Record<string, unknown>;
+      return meta?.exitCode !== undefined && meta.exitCode !== 0;
+    });
+
+    const datePart = events[0].timestamp.toISOString().split('T')[0];
+    const parts: string[] = [`[${datePart}] ${prompts.length}턴 세션.`];
+
+    if (prompts.length > 0) {
+      const firstPrompt = prompts[0].content.slice(0, 120).replace(/\n/g, ' ');
+      parts.push(`주요 작업: ${firstPrompt}`);
+    }
+    if (toolNames.length > 0) {
+      parts.push(`사용 툴: ${toolNames.slice(0, 6).join(', ')}`);
+    }
+    if (errorObs.length > 0) {
+      parts.push(`오류 ${errorObs.length}건 발생`);
+    }
+
+    const summary = parts.join('. ');
+    await this.storeSessionSummary(sessionId, summary, { generated: 'rule-based', eventCount: events.length });
+  }
+
   /**
    * Store a tool observation
    */
@@ -1254,6 +1272,28 @@ export class MemoryService {
     await this.sqliteStore.recordRetrieval(eventId, sessionId, score, query);
   }
 
+  /**
+   * Record a query-level retrieval trace (used by user-prompt-submit hook).
+   * Feeds the retrieval_traces table that powers dashboard stats.
+   */
+  async recordQueryTrace(input: {
+    sessionId: string;
+    queryText: string;
+    strategy: string;
+    candidateEventIds: string[];
+    selectedEventIds: string[];
+    confidence: string;
+  }): Promise<void> {
+    await this.initialize();
+    await this.sqliteStore.recordRetrievalTrace({
+      ...input,
+      projectHash: this.projectHash || undefined,
+      candidateDetails: [],
+      selectedDetails: [],
+      fallbackTrace: [],
+    });
+  }
+
   /**
    * Evaluate helpfulness of retrievals in a session (called at session end)
    */
@@ -1262,6 +1302,22 @@ export class MemoryService {
     await this.sqliteStore.evaluateSessionHelpfulness(sessionId);
   }
 
+  /**
+   * Backfill helpfulness evaluation for sessions that ended without Stop hook.
+   * Call on first turn of a new session to catch missed evaluations.
+   */
+  async evaluatePendingSessions(currentSessionId: string): Promise<void> {
+    await this.initialize();
+    const sessions = await this.sqliteStore.getUnevaluatedSessions(currentSessionId, 5);
+    for (const sid of sessions) {
+      try {
+        await this.sqliteStore.evaluateSessionHelpfulness(sid);
+      } catch {
+        // non-critical, skip failed
+      }
+    }
+  }
+
   /**
    * Get most helpful memories ranked by helpfulness score
    */
@@ -1609,11 +1665,6 @@ export class MemoryService {
       this.vectorWorker.stop();
     }
 
-    // Stop sync worker
-    if (this.syncWorker) {
-      this.syncWorker.stop();
-    }
-
     // Close shared store
     if (this.sharedEventStore) {
       await this.sharedEventStore.close();
@@ -1622,10 +1673,6 @@ export class MemoryService {
     // Close primary store (SQLite)
     await this.sqliteStore.close();
 
-    // Close analytics store (DuckDB)
-    if (this.analyticsStore) {
-      await this.analyticsStore.close();
-    }
   }
 
   /**

package/src/services/session-history-importer.ts

@@ -59,6 +59,18 @@ export interface ClaudeMessage {
  * - 'thinking': Assistant thinking (thinking blocks)
  * - 'skip': Everything else (progress, system, summary, etc.)
  */
+/**
+ * Filter trivial user inputs that aren't worth storing.
+ * Mirrors the shouldStorePrompt() logic from user-prompt-submit.ts.
+ */
+function isWorthStoringPrompt(content: string): boolean {
+  const trimmed = content.trim();
+  if (trimmed.startsWith('/')) return false;
+  if (trimmed.length < 15) return false;
+  if (!/[a-zA-Z가-힣]{2,}/.test(trimmed)) return false;
+  return true;
+}
+
 function classifyEntry(entry: ClaudeMessage): 'user_prompt' | 'tool_result' | 'agent_text' | 'tool_use' | 'thinking' | 'skip' {
   if (entry.type !== 'user' && entry.type !== 'assistant') {
     return 'skip';
@@ -283,6 +295,12 @@ export class SessionHistoryImporter {
           const content = this.extractContent(entry);
           if (!content) continue;
 
+          // Skip trivial inputs: slash commands, very short, no real words
+          if (!isWorthStoringPrompt(content)) {
+            result.skippedDuplicates++;
+            continue;
+          }
+
           // New turn starts with each real user prompt
           currentTurnId = randomUUID();
 

package/src/ui/app.js

@@ -388,9 +388,20 @@ function updateStatsUI() {
   const sharedCount = state.sharedStats ?
     ((state.sharedStats.troubleshooting || 0) + (state.sharedStats.bestPractices || 0) + (state.sharedStats.commonErrors || 0)) : 0;
 
-  document.getElementById('stat-shared').textContent = formatNumber(sharedCount);
   document.getElementById('stat-vectors').textContent = formatNumber(vectorCount);
 
+  // Retrieval quality stat card
+  const rtStats = state.retrievalTraces?.stats;
+  const totalQueries = rtStats?.totalQueries || 0;
+  const selRate = rtStats ? ((rtStats.selectionRate || 0) * 100).toFixed(0) : null;
+  document.getElementById('stat-retrieval-queries').textContent = formatNumber(totalQueries);
+  const rateEl = document.getElementById('stat-retrieval-rate');
+  if (rateEl) {
+    rateEl.textContent = totalQueries > 0 && selRate !== null
+      ? `${selRate}% selection rate`
+      : totalQueries > 0 ? '' : 'no queries yet';
+  }
+
   const levelCounts = {};
   if (state.stats.levelStats) {
     state.stats.levelStats.forEach(item => { levelCounts[item.level] = item.count; });
@@ -596,10 +607,46 @@ function updateEventsListUI() {
 
 // --- Memory Usage ---
 
+function updateTopAccessedEventsUI() {
+  const container = document.getElementById('top-accessed-events-list');
+  if (!container) return;
+
+  const events = (state.mostAccessed?.events || state.mostAccessed?.memories || []);
+  const filtered = events.filter(e => (e.accessCount || 0) > 0).slice(0, 5);
+
+  if (filtered.length === 0) {
+    container.innerHTML = '<div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">No accessed memories yet</div>';
+    return;
+  }
+
+  container.innerHTML = filtered.map((m, i) => {
+    const type = m.eventType || m.type || 'memory';
+    const preview = (m.summary || m.preview || m.content || '').replace(/<[^>]*>/g, '').slice(0, 80);
+    const lastAccessed = m.lastAccessedAt ? new Date(m.lastAccessedAt).toLocaleDateString() : (m.lastAccessed ? new Date(m.lastAccessed).toLocaleDateString() : '-');
+    const id = m.id || m.memoryId || '';
+    return `
+      <div class="shared-item" style="cursor:pointer;" ${id ? `onclick="openDetailModal('${id}')"` : ''}>
+        <div class="shared-info" style="flex-direction:column; align-items:flex-start; gap:2px;">
+          <div style="display:flex; gap:6px; align-items:center;">
+            <span class="event-type-badge type-${type.replace('_','-')}">${type}</span>
+            <span style="font-size:10px; color:var(--text-muted);">last: ${lastAccessed}</span>
+          </div>
+          <span style="font-size:12px; color:var(--text-secondary); white-space:nowrap; overflow:hidden; text-overflow:ellipsis; max-width:200px;" title="${escapeHtml(preview)}">${escapeHtml(preview) || '(no preview)'}</span>
+        </div>
+        <div style="display:flex; flex-direction:column; align-items:flex-end; gap:2px; min-width:40px;">
+          <span style="font-size:15px; font-weight:700; color:var(--accent-primary);">${m.accessCount}</span>
+          <span style="font-size:10px; color:var(--text-muted);">hits</span>
+        </div>
+      </div>
+    `;
+  }).join('');
+}
+
 function updateMemoryUsageUI() {
   updateGraduationBars();
   updateHelpfulnessUI();
   updateMostHelpfulList();
+  updateTopAccessedEventsUI();
   updateAdherenceSummaryUI();
   updateRetrievalTraceUI();
 }

package/src/ui/index.html

@@ -110,11 +110,12 @@
               <i class="ri-discuss-line"></i> Active Sessions
             </div>
           </div>
-          <div class="stat-card" data-stat="shared">
-            <div class="stat-value" id="stat-shared">0</div>
+          <div class="stat-card" data-stat="retrieval">
+            <div class="stat-value" id="stat-retrieval-queries">0</div>
             <div class="stat-label">
-              <i class="ri-share-forward-line"></i> Shared Items
+              <i class="ri-search-eye-line"></i> Retrieval Queries
             </div>
+            <div id="stat-retrieval-rate" style="font-size:11px; color:var(--text-muted); margin-top:2px;">-</div>
           </div>
           <div class="stat-card" data-stat="vectors">
             <div class="stat-value" id="stat-vectors">0</div>
@@ -327,6 +328,13 @@
                 <div id="adherence-summary" style="padding:8px 0; font-size:13px; color:var(--text-muted);">Loading...</div>
               </div>
 
+              <div style="margin-top:20px;">
+                <div class="section-label">Top Accessed Events</div>
+                <div id="top-accessed-events-list" class="shared-list">
+                  <div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">Loading...</div>
+                </div>
+              </div>
+
               <div style="margin-top:20px;">
                 <div class="section-label">Retrieval Trace (1:1)</div>
                 <div id="retrieval-trace-summary" style="padding:8px 0; font-size:13px; color:var(--text-muted);">Loading...</div>