claude-memory-layer 1.0.31 → 1.0.33

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

@@ -1,361 +0,0 @@
-/**
- * User Prompt Submit Hook
- * Called when user submits a prompt - retrieves relevant memories.
- *
- * 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.
- */
-
-import { randomUUID } from 'crypto';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-import { getLightweightMemoryService } from '../../../services/memory-service.js';
-import { writeTurnState, readLastAssistantSnippet } from '../../../core/turn-state.js';
-import { retrieveSemanticMemories } from './semantic-daemon-client.js';
-import {
-  filterHookInjectableMemories,
-  getHookInjectionPolicy,
-  summarizeHookInjectionConfidence,
-  type HookMemoryCandidate
-} from './prompt-injection-policy.js';
-import type { UserPromptSubmitInput, UserPromptSubmitOutput } from '../../../core/types.js';
-
-// Configuration
-const MAX_MEMORIES = parseInt(process.env.CLAUDE_MEMORY_MAX_COUNT || '5');
-// Tuned default for noise/recall balance on shopping_assistant-like corpus
-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 || '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');
-
-interface AdherenceState {
-  sessionId: string;
-  turnCount: number;
-  lastCheckedTurn: number;
-  lastPrompt: string;
-  lastReason?: string;
-  updatedAt: string;
-}
-
-/**
- * Determine if a prompt is worth storing as a memory.
- * Filters slash commands, very short inputs, and trivial patterns.
- */
-function shouldStorePrompt(prompt: string): boolean {
-  const trimmed = prompt.trim();
-  if (trimmed.startsWith('/')) return false;
-  if (trimmed.length < 15) return false;
-  if (!/[a-zA-Z가-힣]{2,}/.test(trimmed)) return false;
-  return true;
-}
-
-
-function getDynamicMinScore(prompt: string): number {
-  const len = prompt.trim().length;
-  if (len <= 20) return Math.min(0.55, BASE_MIN_SCORE + 0.1);   // short query → stricter
-  if (len >= 80) return Math.max(0.3, BASE_MIN_SCORE - 0.05);    // long query → slightly looser
-  return BASE_MIN_SCORE;
-}
-
-function formatMemoryContext(items: Array<{ type: string; content: string }>): string {
-  if (items.length === 0) return '';
-  const lines = items.map((m) => {
-    const preview = m.content.length > 300 ? m.content.substring(0, 300) + '...' : m.content;
-    return `- [${m.type}] ${preview}`;
-  });
-  return `💡 **Related memories found:**\n\n${lines.join('\n\n')}`;
-}
-
-function getAdherenceStatePath(sessionId: string): string {
-  return path.join(ADHERENCE_STATE_DIR, `.adherence-state-${sessionId}.json`);
-}
-
-function readAdherenceState(sessionId: string): AdherenceState {
-  try {
-    const filePath = getAdherenceStatePath(sessionId);
-    if (!fs.existsSync(filePath)) {
-      return {
-        sessionId,
-        turnCount: 0,
-        lastCheckedTurn: 0,
-        lastPrompt: '',
-        lastReason: 'init',
-        updatedAt: new Date().toISOString()
-      };
-    }
-
-    const data = fs.readFileSync(filePath, 'utf8');
-    const parsed = JSON.parse(data) as AdherenceState;
-    if (parsed.sessionId !== sessionId) throw new Error('session mismatch');
-    return parsed;
-  } catch {
-    return {
-      sessionId,
-      turnCount: 0,
-      lastCheckedTurn: 0,
-      lastPrompt: '',
-      lastReason: 'init',
-      updatedAt: new Date().toISOString()
-    };
-  }
-}
-
-function writeAdherenceState(state: AdherenceState): void {
-  try {
-    if (!fs.existsSync(ADHERENCE_STATE_DIR)) {
-      fs.mkdirSync(ADHERENCE_STATE_DIR, { recursive: true });
-    }
-    const filePath = getAdherenceStatePath(state.sessionId);
-    const tempPath = filePath + '.tmp';
-    fs.writeFileSync(tempPath, JSON.stringify(state));
-    fs.renameSync(tempPath, filePath);
-  } catch {
-    // non-critical
-  }
-}
-
-function hasWriteIntent(prompt: string): boolean {
-  return /(fix|refactor|implement|change|modify|edit|update|rewrite|patch|create|add|remove|delete|버그|수정|리팩터|구현|추가|삭제|개선)/i.test(prompt);
-}
-
-function tokenize(text: string): string[] {
-  const stopwords = new Set(['the', 'and', 'for', 'with', 'that', 'this', 'from', 'have', 'what', 'when', 'where', 'how', 'why', '그리고', '그리고요', '이거', '그거', '해주세요', '해줘', '좀', '에서', '으로', '하는', '해']);
-  return text
-    .toLowerCase()
-    .replace(/[^a-z0-9가-힣\s]/g, ' ')
-    .split(/\s+/)
-    .filter((w) => w.length >= 2 && !stopwords.has(w));
-}
-
-function isTopicShift(currentPrompt: string, lastPrompt: string): boolean {
-  if (!lastPrompt || lastPrompt.length < 10) return false;
-  const a = new Set(tokenize(currentPrompt));
-  const b = new Set(tokenize(lastPrompt));
-  if (a.size === 0 || b.size === 0) return false;
-
-  let intersection = 0;
-  for (const token of a) {
-    if (b.has(token)) intersection++;
-  }
-  const union = a.size + b.size - intersection;
-  const similarity = union > 0 ? intersection / union : 0;
-  return similarity < 0.2;
-}
-
-function shouldRunAdherenceCheck(turnCount: number, prompt: string, state: AdherenceState): { run: boolean; reason: string } {
-  if (turnCount === 1) return { run: true, reason: 'first-turn' };
-  if (hasWriteIntent(prompt)) return { run: true, reason: 'write-intent' };
-  if (isTopicShift(prompt, state.lastPrompt)) return { run: true, reason: 'topic-shift' };
-  if (turnCount - state.lastCheckedTurn >= ADHERENCE_INTERVAL_TURNS) return { run: true, reason: 'interval' };
-  return { run: false, reason: 'skip' };
-}
-
-function logAdherenceDecision(sessionId: string, turn: number, run: boolean, reason: string): void {
-  if (!process.env.CLAUDE_MEMORY_DEBUG) return;
-  const mode = run ? 'enforced' : 'skipped';
-  console.error(`[adherence] session=${sessionId} turn=${turn} mode=${mode} reason=${reason}`);
-}
-
-export async function main(): Promise<void> {
-  // Read input from stdin
-  const inputData = await readStdin();
-  const input: UserPromptSubmitInput = JSON.parse(inputData);
-
-  // Generate a new turn_id for this user prompt
-  // This groups the prompt with subsequent tool calls and the final agent response
-  const turnId = randomUUID();
-
-  // Persist turn state so PostToolUse and Stop hooks can read it
-  writeTurnState(input.session_id, turnId);
-
-  // Use lightweight service (SQLite only, no embedder/vector - FAST!)
-  const memoryService = getLightweightMemoryService(input.session_id);
-
-  try {
-    let context = '';
-
-    const adherenceState = readAdherenceState(input.session_id);
-    const currentTurn = adherenceState.turnCount + 1;
-    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(
-        input.session_id,
-        input.prompt,
-        {
-          turnId,
-          adherence: {
-            checked: adherenceDecision.run,
-            reason: adherenceDecision.reason,
-            turn: currentTurn
-          }
-        }
-      );
-    }
-
-    // Search strategy: turn-1 always enforce adherence check,
-    // then adaptively enforce on write-intent/topic-shift/interval
-    const isSlashCommand = input.prompt.trimStart().startsWith('/');
-    if (ENABLE_SEARCH && !isSlashCommand && input.prompt.length > 10 && adherenceDecision.run) {
-      const minScore = getDynamicMinScore(input.prompt);
-      let mergedMemories: HookMemoryCandidate[] = [];
-
-      // 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 semanticMemories = await retrieveSemanticMemories(
-            {
-              sessionId: input.session_id,
-              prompt: retrievalQuery,
-              topK: MAX_MEMORIES,
-              minScore
-            },
-            SEMANTIC_TIMEOUT_MS
-          );
-          mergedMemories = semanticMemories.map((memory) => ({
-            ...memory,
-            source: 'semantic'
-          }));
-        } catch {
-          // Semantic retrieval is best-effort; fallback below handles the rest
-        }
-      }
-
-      const shouldUseKeywordFallback =
-        RETRIEVAL_MODE === 'keyword' ||
-        RETRIEVAL_MODE === 'hybrid' ||
-        mergedMemories.length === 0;
-
-      if (shouldUseKeywordFallback && mergedMemories.length < MAX_MEMORIES) {
-        let usedFallbackFloor = false;
-        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) {
-          usedFallbackFloor = true;
-          results = await memoryService.keywordSearch(retrievalQuery, {
-            topK: MAX_MEMORIES,
-            minScore: FALLBACK_MIN_SCORE
-          });
-        }
-
-        const existingIds = new Set(mergedMemories.map((m) => m.id).filter(Boolean));
-        for (const r of results) {
-          if (existingIds.has(r.event.id)) continue;
-          mergedMemories.push({
-            type: r.event.eventType,
-            content: r.event.content,
-            id: r.event.id,
-            score: r.score,
-            source: 'keyword',
-            fallback: usedFallbackFloor
-          });
-          if (mergedMemories.length >= MAX_MEMORIES) break;
-        }
-      }
-
-      const injectableMemories = filterHookInjectableMemories(
-        mergedMemories,
-        getHookInjectionPolicy()
-      );
-
-      if (injectableMemories.length > 0) {
-        // Increment access count only for high-confidence memories injected into the prompt.
-        const eventIds = injectableMemories.map((m) => m.id).filter((v): v is string => Boolean(v));
-        if (eventIds.length > 0) {
-          await memoryService.incrementMemoryAccess(eventIds);
-        }
-
-        // Record each injected retrieval for helpfulness tracking.
-        for (const m of injectableMemories) {
-          if (!m.id) continue;
-          try {
-            await memoryService.recordRetrieval(
-              m.id,
-              input.session_id,
-              m.score ?? minScore,
-              input.prompt
-            );
-          } catch { /* non-critical */ }
-        }
-
-        context = formatMemoryContext(injectableMemories);
-      }
-
-      // Record query-level trace for dashboard stats (retrieval_traces table)
-      const allCandidateIds = mergedMemories.map((m) => m.id).filter((v): v is string => Boolean(v));
-      const selectedIds = injectableMemories.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: selectedIds,
-          confidence: summarizeHookInjectionConfidence(injectableMemories)
-        });
-      } catch { /* non-critical */ }
-    }
-
-    writeAdherenceState({
-      sessionId: input.session_id,
-      turnCount: currentTurn,
-      lastCheckedTurn: adherenceDecision.run ? currentTurn : adherenceState.lastCheckedTurn,
-      lastPrompt: input.prompt,
-      lastReason: adherenceDecision.reason,
-      updatedAt: new Date().toISOString()
-    });
-
-    const output: UserPromptSubmitOutput = { context };
-    console.log(JSON.stringify(output));
-  } catch (error) {
-    if (process.env.CLAUDE_MEMORY_DEBUG) {
-      console.error('Memory hook error:', error);
-    }
-    console.log(JSON.stringify({ context: '' }));
-  }
-}
-
-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/index.ts

@@ -1,4 +0,0 @@
-/** Claude adapter surface for Claude Code-specific integrations. */
-
-export * from './hooks/index.js';
-export * from './transcript/index.js';

package/src/adapters/claude/transcript/index.ts

@@ -1,4 +0,0 @@
-/** Claude transcript parsing and turn reconstruction layer. */
-
-export * from './transcript-reader.js';
-export * from './turn-reconstructor.js';

package/src/adapters/claude/transcript/transcript-reader.ts

@@ -1,57 +0,0 @@
-import * as fs from 'fs';
-import * as readline from 'readline';
-
-export interface ClaudeTranscriptEntry {
-  type?: string;
-  message?: {
-    content?: unknown;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
-}
-
-export interface ReadTranscriptTailOptions {
-  /** Maximum number of bytes to scan from the end of the transcript. */
-  maxBytes?: number;
-}
-
-const DEFAULT_MAX_BYTES = 200 * 1024;
-
-/**
- * Read JSONL entries from the tail of a Claude transcript.
- *
- * Claude transcripts can grow large during long sessions, so hook-time readers
- * should scan only the recent tail by default. Malformed lines are skipped to
- * tolerate starting in the middle of a JSONL record.
- */
-export async function readTranscriptTailEntries(
-  transcriptPath: string,
-  options: ReadTranscriptTailOptions = {}
-): Promise<ClaudeTranscriptEntry[]> {
-  if (!fs.existsSync(transcriptPath)) return [];
-
-  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-  const stats = fs.statSync(transcriptPath);
-  const readStart = Math.max(0, stats.size - maxBytes);
-  const entries: ClaudeTranscriptEntry[] = [];
-
-  const stream = fs.createReadStream(transcriptPath, {
-    start: readStart,
-    encoding: 'utf8'
-  });
-
-  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-
-  for await (const line of rl) {
-    try {
-      const parsed = JSON.parse(line) as unknown;
-      if (typeof parsed === 'object' && parsed !== null) {
-        entries.push(parsed as ClaudeTranscriptEntry);
-      }
-    } catch {
-      // Skip malformed lines, including a partial first line when readStart > 0.
-    }
-  }
-
-  return entries;
-}

package/src/adapters/claude/transcript/turn-reconstructor.ts

@@ -1,65 +0,0 @@
-import { readTranscriptTailEntries, type ClaudeTranscriptEntry, type ReadTranscriptTailOptions } from './transcript-reader.js';
-
-export interface SessionSummaryEvent {
-  eventType?: string;
-  content?: string;
-}
-
-function isTextContentBlock(value: unknown): value is { type: string; text: string } {
-  return typeof value === 'object'
-    && value !== null
-    && (value as { type?: unknown }).type === 'text'
-    && typeof (value as { text?: unknown }).text === 'string';
-}
-
-/** Extract assistant text messages from parsed Claude transcript entries. */
-export function extractAssistantTextMessages(entries: ClaudeTranscriptEntry[]): string[] {
-  const messages: string[] = [];
-
-  for (const entry of entries) {
-    if (entry.type !== 'assistant') continue;
-
-    const content = entry.message?.content;
-    if (!Array.isArray(content)) continue;
-
-    const textParts = content
-      .filter(isTextContentBlock)
-      .map((block) => block.text)
-      .filter(Boolean);
-
-    if (textParts.length > 0) {
-      messages.push(textParts.join('\n'));
-    }
-  }
-
-  return messages;
-}
-
-/** Read a Claude transcript tail and reconstruct assistant text messages. */
-export async function extractAssistantMessages(
-  transcriptPath: string,
-  options?: ReadTranscriptTailOptions
-): Promise<string[]> {
-  const entries = await readTranscriptTailEntries(transcriptPath, options);
-  return extractAssistantTextMessages(entries);
-}
-
-/** Generate a simple deterministic summary from stored session events. */
-export function generateSessionSummary(events: SessionSummaryEvent[]): string {
-  const userPrompts = events.filter((event) => event.eventType === 'user_prompt');
-  const responses = events.filter((event) => event.eventType === 'agent_response');
-
-  const parts: string[] = [];
-  parts.push(`Session with ${userPrompts.length} user prompts and ${responses.length} responses.`);
-
-  if (userPrompts.length > 0) {
-    parts.push('Topics discussed:');
-    for (const prompt of userPrompts.slice(0, 3)) {
-      const content = prompt.content ?? '';
-      const topic = content.slice(0, 100).replace(/\n/g, ' ');
-      parts.push(`- ${topic}${content.length > 100 ? '...' : ''}`);
-    }
-  }
-
-  return parts.join('\n');
-}

package/src/apps/cli/claude-settings-hooks.ts

@@ -1,138 +0,0 @@
-import * as path from 'path';
-
-export interface ClaudeHookCommand {
-  type: string;
-  command: string;
-}
-
-export interface ClaudeHookEntry {
-  matcher: string;
-  hooks: ClaudeHookCommand[];
-}
-
-export interface ClaudeSettingsHooks {
-  UserPromptSubmit?: ClaudeHookEntry[];
-  PostToolUse?: ClaudeHookEntry[];
-  SessionStart?: ClaudeHookEntry[];
-  Stop?: ClaudeHookEntry[];
-  SessionEnd?: ClaudeHookEntry[];
-  [key: string]: ClaudeHookEntry[] | undefined;
-}
-
-export interface ClaudeSettingsWithHooks {
-  hooks?: ClaudeSettingsHooks;
-  [key: string]: unknown;
-}
-
-export const REQUIRED_HOOK_FILES = [
-  'user-prompt-submit.js',
-  'post-tool-use.js',
-  'session-start.js',
-  'stop.js',
-  'session-end.js'
-] as const;
-
-export const PLUGIN_HOOKS = {
-  SessionStart: 'session-start.js',
-  UserPromptSubmit: 'user-prompt-submit.js',
-  PostToolUse: 'post-tool-use.js',
-  Stop: 'stop.js',
-  SessionEnd: 'session-end.js'
-} as const;
-
-export type PluginHookName = keyof typeof PLUGIN_HOOKS;
-
-export function shellQuotePathForNode(filePath: string): string {
-  return `'${filePath.replace(/'/g, `'\\''`)}'`;
-}
-
-export function buildHookCommand(pluginPath: string, fileName: string): string {
-  return `node ${shellQuotePathForNode(path.join(pluginPath, 'hooks', fileName))}`;
-}
-
-export function getHooksConfig(pluginPath: string): ClaudeSettingsHooks {
-  const makeHook = (fileName: string): ClaudeHookEntry[] => [
-    {
-      matcher: '',
-      hooks: [
-        {
-          type: 'command',
-          command: buildHookCommand(pluginPath, fileName)
-        }
-      ]
-    }
-  ];
-
-  return Object.fromEntries(
-    Object.entries(PLUGIN_HOOKS).map(([hookName, fileName]) => [hookName, makeHook(fileName)])
-  ) as ClaudeSettingsHooks;
-}
-
-export function isPluginHookCommand(command: string | undefined, pluginPath?: string): boolean {
-  if (!command) return false;
-  const normalized = command.replace(/\\/g, '/');
-  const normalizedPluginPath = pluginPath?.replace(/\\/g, '/').replace(/\/$/, '');
-
-  return REQUIRED_HOOK_FILES.some((fileName) => {
-    if (normalizedPluginPath && normalized.includes(`${normalizedPluginPath}/hooks/${fileName}`)) {
-      return true;
-    }
-    return normalized.includes('claude-memory-layer') && normalized.includes(`/hooks/${fileName}`);
-  });
-}
-
-export function hasHook(
-  settings: ClaudeSettingsWithHooks,
-  hookName: PluginHookName,
-  commandFragment: string
-): boolean {
-  const hookEntries = settings.hooks?.[hookName];
-  if (!hookEntries) return false;
-  return hookEntries.some((entry) => entry.hooks?.some((hook) => hook.command?.includes(commandFragment)));
-}
-
-export function removePluginHooksFromSettings<T extends ClaudeSettingsWithHooks>(settings: T, pluginPath?: string): T {
-  const next = { ...settings };
-  if (!settings.hooks) return next;
-
-  const hooks: ClaudeSettingsHooks = { ...settings.hooks };
-
-  for (const hookName of Object.keys(PLUGIN_HOOKS) as PluginHookName[]) {
-    const entries = hooks[hookName] ?? [];
-    const cleanedEntries = entries
-      .map((entry) => ({
-        ...entry,
-        hooks: (entry.hooks ?? []).filter((hook) => !isPluginHookCommand(hook.command, pluginPath))
-      }))
-      .filter((entry) => entry.hooks.length > 0);
-
-    if (cleanedEntries.length > 0) {
-      hooks[hookName] = cleanedEntries;
-    } else {
-      delete hooks[hookName];
-    }
-  }
-
-  if (Object.keys(hooks).length > 0) {
-    next.hooks = hooks;
-  } else {
-    delete next.hooks;
-  }
-
-  return next;
-}
-
-export function mergePluginHooksIntoSettings<T extends ClaudeSettingsWithHooks>(settings: T, pluginPath: string): T {
-  const cleaned = removePluginHooksFromSettings(settings, pluginPath);
-  const next = { ...cleaned, hooks: { ...(cleaned.hooks ?? {}) } };
-  const pluginHooks = getHooksConfig(pluginPath);
-
-  for (const hookName of Object.keys(PLUGIN_HOOKS) as PluginHookName[]) {
-    next.hooks[hookName] = [
-      ...(next.hooks[hookName] ?? []),
-      ...(pluginHooks[hookName] ?? [])
-    ];
-  }
-
-  return next;
-}