claude-memory-layer 1.0.26 → 1.0.28

package/src/adapters/claude/hooks/semantic-daemon.ts

@@ -0,0 +1,283 @@
+import * as fs from 'fs';
+import * as net from 'net';
+import * as os from 'os';
+import * as path from 'path';
+import { DISABLED_SHARED_STORE_CONFIG, MemoryService } from '../../../services/memory-service.js';
+import { getProjectStoragePath } from '../../../core/registry/project-path.js';
+import { getSessionProject } from '../../../core/registry/session-registry.js';
+
+export interface SemanticDaemonRequest {
+  type?: 'retrieve';
+  sessionId?: string;
+  prompt?: string;
+  topK?: number;
+  minScore?: number;
+}
+
+export interface SemanticMemory {
+  type: string;
+  content: string;
+  id?: string;
+  score?: number;
+}
+
+export 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;
+let processHandlersInstalled = false;
+
+function scheduleIdleShutdown(): void {
+  if (idleTimer) {
+    clearTimeout(idleTimer);
+  }
+
+  idleTimer = setTimeout(() => {
+    shutdown(0).catch(() => {
+      process.exit(0);
+    });
+  }, IDLE_TIMEOUT_MS);
+  idleTimer.unref();
+}
+
+export function parseSemanticDaemonRequest(raw: string): SemanticDaemonRequest {
+  try {
+    return JSON.parse(raw) as SemanticDaemonRequest;
+  } catch {
+    return {};
+  }
+}
+
+export function isValidSemanticDaemonRequest(
+  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);
+}
+
+export function makeSemanticDaemonErrorResponse(error: unknown): SemanticDaemonResponse {
+  return { ok: false, error: error instanceof Error ? error.message : 'unknown daemon error' };
+}
+
+export 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: DISABLED_SHARED_STORE_CONFIG
+  });
+
+  serviceCache.set(key, service);
+  return service;
+}
+
+export async function handleSemanticDaemonRequest(raw: string): Promise<SemanticDaemonResponse> {
+  const input = parseSemanticDaemonRequest(raw);
+  if (!isValidSemanticDaemonRequest(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 makeSemanticDaemonErrorResponse(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 handleSemanticDaemonRequest(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);
+  }
+  idleTimer = null;
+
+  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());
+    });
+  }
+  server = null;
+
+  if (fs.existsSync(SOCKET_PATH)) {
+    try {
+      fs.unlinkSync(SOCKET_PATH);
+    } catch {
+      // Ignore socket cleanup failure.
+    }
+  }
+
+  process.exit(code);
+}
+
+function installProcessHandlers(): void {
+  if (processHandlersInstalled) return;
+  processHandlersInstalled = true;
+
+  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)); });
+}
+
+export async function main(): Promise<void> {
+  installProcessHandlers();
+  await listenServer();
+  scheduleIdleShutdown();
+}

package/src/adapters/claude/hooks/session-end.ts

@@ -0,0 +1,59 @@
+/**
+ * Session End Hook
+ * Called when session ends - generates and stores session summary
+ */
+
+import { getLightweightMemoryService } from '../../../services/memory-service.js';
+import type { SessionEndInput } from '../../../core/types.js';
+import { generateSessionSummary } from '../transcript/turn-reconstructor.js';
+
+export async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: SessionEndInput = JSON.parse(inputData);
+
+  // Use lightweight service (SQLite only, no embedder/vector - FAST!)
+  const memoryService = getLightweightMemoryService(input.session_id);
+
+  try {
+    // Get session history
+    const sessionEvents = await memoryService.getSessionHistory(input.session_id);
+
+    if (sessionEvents.length > 0) {
+      // Generate a simple session summary
+      const summary = generateSessionSummary(sessionEvents);
+
+      // Store session summary
+      await memoryService.storeSessionSummary(input.session_id, summary);
+
+      // End session with summary
+      await memoryService.endSession(input.session_id, summary);
+
+      // Evaluate helpfulness of memory retrievals in this session
+      try {
+        await memoryService.evaluateSessionHelpfulness(input.session_id);
+      } catch { /* non-critical */ }
+
+      // Process any pending embeddings
+      await memoryService.processPendingEmbeddings();
+    }
+
+    console.log(JSON.stringify({}));
+  } catch (error) {
+    console.error('Memory hook error:', error);
+    console.log(JSON.stringify({}));
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}

package/src/adapters/claude/hooks/session-start.ts

@@ -0,0 +1,73 @@
+/**
+ * Session Start Hook
+ * Called when a new Claude Code session starts
+ */
+
+import { getLightweightMemoryService } from '../../../services/memory-service.js';
+import { registerSession } from '../../../core/registry/session-registry.js';
+import { ensureDaemonRunning } from './semantic-daemon-client.js';
+import type { SessionStartInput, SessionStartOutput } from '../../../core/types.js';
+
+export async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: SessionStartInput = JSON.parse(inputData);
+
+  // 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);
+
+  try {
+    // Start session in memory service
+    await memoryService.startSession(input.session_id, input.cwd);
+
+    // Backfill session summaries for recent sessions that ended without Stop hook
+    // (crash, force-close, etc.). Run in background - non-blocking.
+    memoryService.backfillMissingSummaries(input.session_id, 5).catch(() => {});
+
+    // Get recent context for this project (now automatically scoped)
+    const recentEvents = await memoryService.getRecentEvents(10);
+
+    let context = '';
+    if (recentEvents.length > 0) {
+      context = `## Previous Session Context\n\nYou have worked on this project before. Here are some relevant memories:\n\n`;
+      for (const event of recentEvents.slice(0, 3)) {
+        const date = event.timestamp.toISOString().split('T')[0];
+        context += `- **${date}**: ${event.content.slice(0, 150)}...\n`;
+      }
+    }
+
+    const output: SessionStartOutput = { context };
+    console.log(JSON.stringify(output));
+  } catch (error) {
+    console.error('Memory hook error:', error);
+    console.log(JSON.stringify({ context: '' }));
+  } finally {
+    try {
+      await memoryService.close();
+    } catch {
+      // Best-effort cleanup
+    }
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}

package/src/adapters/claude/hooks/stop.ts

@@ -0,0 +1,128 @@
+/**
+ * Stop Hook
+ * Called when agent stops - reads transcript and stores assistant responses
+ *
+ * Actual Claude Code input format:
+ * {
+ *   session_id, transcript_path, cwd, permission_mode,
+ *   hook_event_name: "Stop", stop_hook_active
+ * }
+ *
+ * NOTE: Claude Code does NOT send messages in the Stop hook.
+ * We read them from the transcript JSONL file instead.
+ */
+
+import { getLightweightMemoryService } from '../../../services/memory-service.js';
+import { applyPrivacyFilter } from '../../../core/privacy/index.js';
+import { readTurnState, clearTurnState, writeLastAssistantSnippet } from '../../../core/turn-state.js';
+import type { StopInput, Config } from '../../../core/types.js';
+import { extractAssistantMessages } from '../transcript/turn-reconstructor.js';
+
+// Default privacy config
+const DEFAULT_PRIVACY_CONFIG: Config['privacy'] = {
+  excludePatterns: ['password', 'secret', 'api_key', 'token', 'bearer'],
+  anonymize: false,
+  privateTags: {
+    enabled: true,
+    marker: '[PRIVATE]',
+    preserveLineCount: false,
+    supportedFormats: ['xml']
+  }
+};
+
+export async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: StopInput = JSON.parse(inputData);
+
+  // Use lightweight service (SQLite only, no embedder/vector - FAST!)
+  const memoryService = getLightweightMemoryService(input.session_id);
+
+  try {
+    // Read current turn_id from state file
+    const turnId = readTurnState(input.session_id);
+
+    // 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 (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;
+
+      // Truncate very long responses
+      if (content.length > 5000) {
+        content = content.slice(0, 5000) + '...[truncated]';
+      }
+
+      // 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,
+        content,
+        {
+          privacy: filterResult.metadata,
+          ...(turnId ? { turnId } : {})
+        }
+      );
+    }
+
+    // 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);
+
+    // Evaluate helpfulness of retrieved memories for this session
+    try {
+      await memoryService.evaluateSessionHelpfulness(input.session_id);
+    } catch {
+      // non-critical
+    }
+
+    // Generate session summary from recent events (rule-based, no LLM needed)
+    try {
+      await memoryService.generateSessionSummary(input.session_id);
+    } catch {
+      // non-critical
+    }
+
+    // Embeddings enqueued in SQLite - will be processed by vector worker when server runs
+    await memoryService.processPendingEmbeddings();
+
+    // Output empty (stop hook doesn't return context)
+    console.log(JSON.stringify({}));
+  } catch (error) {
+    if (process.env.CLAUDE_MEMORY_DEBUG) {
+      console.error('Stop hook error:', error);
+    }
+    console.log(JSON.stringify({}));
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}