claude-memory-layer 1.0.22 → 1.0.24

package/src/hooks/semantic-daemon.ts

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+
+import * as fs from 'fs';
+import * as net from 'net';
+import * as os from 'os';
+import * as path from 'path';
+import { MemoryService, getProjectStoragePath, getSessionProject } from '../services/memory-service.js';
+
+interface SemanticDaemonRequest {
+  type?: 'retrieve';
+  sessionId?: string;
+  prompt?: string;
+  topK?: number;
+  minScore?: number;
+}
+
+interface SemanticMemory {
+  type: string;
+  content: string;
+  id?: string;
+  score?: number;
+}
+
+interface SemanticDaemonResponse {
+  ok: boolean;
+  memories?: SemanticMemory[];
+  error?: string;
+}
+
+const SOCKET_PATH = process.env.CLAUDE_MEMORY_SEMANTIC_SOCKET || path.join(
+  os.homedir(),
+  '.claude-code',
+  'memory',
+  'semantic-daemon.sock'
+);
+
+const IDLE_TIMEOUT_MS = parseInt(process.env.CLAUDE_MEMORY_SEMANTIC_DAEMON_IDLE_MS || '600000');
+const serviceCache = new Map<string, MemoryService>();
+
+let server: net.Server | null = null;
+let idleTimer: NodeJS.Timeout | null = null;
+let shuttingDown = false;
+
+function scheduleIdleShutdown(): void {
+  if (idleTimer) {
+    clearTimeout(idleTimer);
+  }
+
+  idleTimer = setTimeout(() => {
+    shutdown(0).catch(() => {
+      process.exit(0);
+    });
+  }, IDLE_TIMEOUT_MS);
+  idleTimer.unref();
+}
+
+function parseRequest(raw: string): SemanticDaemonRequest {
+  try {
+    return JSON.parse(raw) as SemanticDaemonRequest;
+  } catch {
+    return {};
+  }
+}
+
+function isValidRequest(input: SemanticDaemonRequest): input is Required<SemanticDaemonRequest> {
+  return input.type === 'retrieve'
+    && typeof input.sessionId === 'string'
+    && input.sessionId.length > 0
+    && typeof input.prompt === 'string'
+    && input.prompt.length > 0
+    && Number.isFinite(input.topK)
+    && Number.isFinite(input.minScore);
+}
+
+function makeErrorResponse(error: unknown): SemanticDaemonResponse {
+  return { ok: false, error: error instanceof Error ? error.message : 'unknown daemon error' };
+}
+
+function isVectorSessionFilterError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message.toLowerCase() : '';
+  return message.includes('no field named sessionid');
+}
+
+function getServiceForSession(sessionId: string): MemoryService {
+  const projectInfo = getSessionProject(sessionId);
+  const key = projectInfo?.projectHash || '__global__';
+
+  if (serviceCache.has(key)) {
+    return serviceCache.get(key)!;
+  }
+
+  const service = new MemoryService({
+    storagePath: projectInfo
+      ? getProjectStoragePath(projectInfo.projectPath)
+      : path.join(os.homedir(), '.claude-code', 'memory'),
+    projectHash: projectInfo?.projectHash,
+    projectPath: projectInfo?.projectPath,
+    readOnly: false,
+    embeddingOnly: true,
+    analyticsEnabled: false,
+    sharedStoreConfig: { enabled: false }
+  });
+
+  serviceCache.set(key, service);
+  return service;
+}
+
+async function handleRequest(raw: string): Promise<SemanticDaemonResponse> {
+  const input = parseRequest(raw);
+  if (!isValidRequest(input)) {
+    return { ok: false, error: 'invalid request' };
+  }
+
+  try {
+    const service = getServiceForSession(input.sessionId);
+    let result;
+    try {
+      result = await service.retrieveMemories(input.prompt, {
+        topK: input.topK,
+        minScore: input.minScore,
+        sessionId: input.sessionId,
+        intentRewrite: true,
+        adaptiveRerank: true,
+        projectScopeMode: 'strict'
+      });
+    } catch (error) {
+      if (!isVectorSessionFilterError(error)) {
+        throw error;
+      }
+
+      // LanceDB field-case mismatch can fail sessionId filtering.
+      // Retry without session filter and keep project strict scoping.
+      result = await service.retrieveMemories(input.prompt, {
+        topK: input.topK,
+        minScore: input.minScore,
+        intentRewrite: true,
+        adaptiveRerank: true,
+        projectScopeMode: 'strict'
+      });
+    }
+
+    const memories = result.memories.map((m) => ({
+      type: m.event.eventType,
+      content: m.event.content,
+      id: m.event.id,
+      score: m.score
+    }));
+
+    return { ok: true, memories };
+  } catch (error) {
+    return makeErrorResponse(error);
+  }
+}
+
+function createServer(): net.Server {
+  return net.createServer({ allowHalfOpen: true }, (socket) => {
+    scheduleIdleShutdown();
+    socket.setEncoding('utf8');
+
+    let requestRaw = '';
+
+    socket.on('data', (chunk) => {
+      requestRaw += chunk;
+      if (requestRaw.length > 1024 * 1024) {
+        socket.end(JSON.stringify({ ok: false, error: 'request too large' }));
+      }
+    });
+
+    socket.on('end', async () => {
+      const response = await handleRequest(requestRaw);
+      socket.end(JSON.stringify(response));
+      scheduleIdleShutdown();
+    });
+
+    socket.on('error', () => {
+      // Ignore per-socket errors to keep daemon process alive.
+    });
+  });
+}
+
+async function socketInUse(p: string): Promise<boolean> {
+  if (!fs.existsSync(p)) return false;
+  return new Promise((resolve) => {
+    let settled = false;
+    const client = net.createConnection(p);
+    const done = (alive: boolean) => {
+      if (settled) return;
+      settled = true;
+      client.destroy();
+      resolve(alive);
+    };
+    client.on('connect', () => done(true));
+    client.on('error', () => done(false));
+    setTimeout(() => done(false), 120).unref();
+  });
+}
+
+async function listenServer(): Promise<void> {
+  const socketDir = path.dirname(SOCKET_PATH);
+  if (!fs.existsSync(socketDir)) {
+    fs.mkdirSync(socketDir, { recursive: true });
+  }
+
+  if (await socketInUse(SOCKET_PATH)) {
+    process.exit(0);
+  }
+
+  if (fs.existsSync(SOCKET_PATH)) {
+    try {
+      fs.unlinkSync(SOCKET_PATH);
+    } catch {
+      // Ignore stale socket unlink failures.
+    }
+  }
+
+  server = createServer();
+
+  await new Promise<void>((resolve, reject) => {
+    if (!server) {
+      reject(new Error('daemon server not initialized'));
+      return;
+    }
+
+    server.once('error', reject);
+    server.listen(SOCKET_PATH, () => {
+      server?.off('error', reject);
+      resolve();
+    });
+  });
+}
+
+async function shutdown(code: number): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  if (idleTimer) {
+    clearTimeout(idleTimer);
+  }
+
+  const closePromises: Promise<void>[] = [];
+  for (const service of serviceCache.values()) {
+    closePromises.push(service.shutdown().catch(() => undefined));
+  }
+  await Promise.all(closePromises);
+  serviceCache.clear();
+
+  if (server) {
+    await new Promise<void>((resolve) => {
+      server?.close(() => resolve());
+    });
+  }
+
+  if (fs.existsSync(SOCKET_PATH)) {
+    try {
+      fs.unlinkSync(SOCKET_PATH);
+    } catch {
+      // Ignore socket cleanup failure.
+    }
+  }
+
+  process.exit(code);
+}
+
+async function main(): Promise<void> {
+  await listenServer();
+  scheduleIdleShutdown();
+}
+
+process.on('SIGINT', () => { shutdown(0).catch(() => process.exit(0)); });
+process.on('SIGTERM', () => { shutdown(0).catch(() => process.exit(0)); });
+process.on('uncaughtException', () => { shutdown(1).catch(() => process.exit(1)); });
+process.on('unhandledRejection', () => { shutdown(1).catch(() => process.exit(1)); });
+
+main().catch(() => {
+  process.exit(1);
+});

package/src/hooks/session-start.ts

@@ -8,6 +8,7 @@ import {
   getLightweightMemoryService,
   registerSession
 } from '../services/memory-service.js';
+import { ensureDaemonRunning } from './semantic-daemon-client.js';
 import type { SessionStartInput, SessionStartOutput } from '../core/types.js';
 
 async function main(): Promise<void> {
@@ -18,6 +19,12 @@ async function main(): Promise<void> {
   // Register session with project path for other hooks to find
   registerSession(input.session_id, input.cwd);
 
+  // Start semantic daemon in the background (non-blocking) so VectorWorker
+  // can process any pending embedding_outbox items immediately.
+  ensureDaemonRunning().catch(() => {
+    // Ignore - daemon will start on first prompt if needed
+  });
+
   // Use lightweight service to avoid starting background workers in hook process
   const memoryService = getLightweightMemoryService(input.session_id);
 

package/src/hooks/stop.ts

@@ -17,7 +17,7 @@ import * as fs from 'fs';
 import * as readline from 'readline';
 import { getLightweightMemoryService } from '../services/memory-service.js';
 import { applyPrivacyFilter } from '../core/privacy/index.js';
-import { readTurnState, clearTurnState } from '../core/turn-state.js';
+import { readTurnState, clearTurnState, writeLastAssistantSnippet } from '../core/turn-state.js';
 import type { StopInput, Config } from '../core/types.js';
 
 // Default privacy config
@@ -94,8 +94,16 @@ async function main(): Promise<void> {
     // Read assistant messages from transcript
     const assistantMessages = await extractAssistantMessages(input.transcript_path);
 
+    const MIN_AGENT_RESPONSE_LEN = parseInt(
+      process.env.CLAUDE_MEMORY_AGENT_RESPONSE_MIN_LEN || '150'
+    );
+    const lastIdx = assistantMessages.length - 1;
+
     // Store each assistant response
-    for (const text of assistantMessages) {
+    for (let i = 0; i < assistantMessages.length; i++) {
+      const text = assistantMessages[i];
+      const isLast = i === lastIdx;
+
       // Apply privacy filter
       const filterResult = applyPrivacyFilter(text, DEFAULT_PRIVACY_CONFIG);
       let content = filterResult.content;
@@ -105,8 +113,9 @@ async function main(): Promise<void> {
         content = content.slice(0, 5000) + '...[truncated]';
       }
 
-      // Skip very short responses (likely just tool calls)
-      if (content.trim().length < 10) continue;
+      // Skip very short responses (likely just tool calls or transition messages)
+      // Always store the last message (may be the final answer)
+      if (!isLast && content.trim().length < MIN_AGENT_RESPONSE_LEN) continue;
 
       await memoryService.storeAgentResponse(
         input.session_id,
@@ -118,6 +127,12 @@ async function main(): Promise<void> {
       );
     }
 
+    // Save last assistant response snippet for next-turn retrieval context enrichment
+    if (assistantMessages.length > 0) {
+      const lastMessage = assistantMessages[assistantMessages.length - 1];
+      writeLastAssistantSnippet(input.session_id, lastMessage);
+    }
+
     // Clean up turn state file after processing
     clearTurnState(input.session_id);
 

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

@@ -61,6 +61,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;
 }
 
 // ============================================================
@@ -212,6 +214,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 +223,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)
@@ -325,24 +329,26 @@ 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();
+
+        // 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 }
+          );
+          this.syncWorker.start();
+        }
       }
 
       // Load endless mode setting
@@ -1254,6 +1260,27 @@ 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,
+      candidateDetails: [],
+      selectedDetails: [],
+      fallbackTrace: [],
+    });
+  }
+
   /**
    * Evaluate helpfulness of retrievals in a session (called at session end)
    */
@@ -1262,6 +1289,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
    */

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