claude-memory-layer 1.0.17 → 1.0.19

package/memory/session_summary/uncategorized/2026-02-26.md

@@ -0,0 +1,13 @@
+
+## 2026-02-26T13:53:54.921Z | 3fa78495-3f90-45ff-a85c-43dc29ddedb7
+- type: session_summary
+- session: bench-session-2
+Session with 1 user prompts and 6 responses.
+Topics discussed:
+- 최근 변경 사항 때문에 claude code 가 느려진 원인을 분석해줘.
+## 2026-02-26T13:54:46.584Z | cb94a8e4-4a9d-4bfc-8ee5-1458f5e304e7
+- type: session_summary
+- session: bench-session-3
+Session with 1 user prompts and 6 responses.
+Topics discussed:
+- 최근 변경 사항 때문에 claude code 가 느려진 원인을 분석해줘.

package/memory/session_summary/uncategorized/2026-03-03.md

@@ -0,0 +1,5 @@
+
+## 2026-03-03T14:04:47.970Z | 7dfbcdd9-f49f-482d-a0c6-9779331cc5cf
+- type: session_summary
+- session: 3252b490-16ca-40fb-b30c-1171456e2c89
+Session with 0 user prompts and 1 responses.

package/memory/tool_observation/uncategorized/2026-02-26.md

@@ -198,4 +198,12 @@
 ## 2026-02-26T12:51:57.850Z | 3b09d82b-7fa3-4673-978e-87ec65d901dd
 - type: tool_observation
 - session: 2f324dae-7d8f-4f67-842e-acf507b79c59
-{"toolName":"Bash","toolInput":{"command":"git add src/core/sqlite-event-store.ts && git commit -m \"$(cat <<'EOF'\nfix(api): handle missing retrieval_traces table in read-only mode\n\nDashboard API creates read-only MemoryService which skips schema\ncreation. If the DB was created before retrieval_traces was added,\nqueries fail with \"no such table\". Now returns empty results gracefully.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n)\"","description":"Commit retrieval_traces fix"},"toolOutput":"[main 60d59c6] fix(api): handle missing retrieval_traces table in read-only mode\n 1 file changed, 52 insertions(+), 40 deletions(-)","durationMs":0,"success":true,"metadata":{"command":"git add","turnId":"6ee6b497-8756-43c8-a208-8830a70efc1a"}}
+{"toolName":"Bash","toolInput":{"command":"git add src/core/sqlite-event-store.ts && git commit -m \"$(cat <<'EOF'\nfix(api): handle missing retrieval_traces table in read-only mode\n\nDashboard API creates read-only MemoryService which skips schema\ncreation. If the DB was created before retrieval_traces was added,\nqueries fail with \"no such table\". Now returns empty results gracefully.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n)\"","description":"Commit retrieval_traces fix"},"toolOutput":"[main 60d59c6] fix(api): handle missing retrieval_traces table in read-only mode\n 1 file changed, 52 insertions(+), 40 deletions(-)","durationMs":0,"success":true,"metadata":{"command":"git add","turnId":"6ee6b497-8756-43c8-a208-8830a70efc1a"}}
+## 2026-02-26T13:53:54.436Z | 4ced656c-1426-44fd-9f2d-148c5432c1f8
+- type: tool_observation
+- session: bench-session-2
+{"toolName":"Bash","toolInput":{"cmd":"echo hello"},"toolOutput":"hello\n","durationMs":0,"success":true,"metadata":{"turnId":"ccd580af-30da-4227-8a48-6ce91c3bfeba"}}
+## 2026-02-26T13:54:46.108Z | 0fa770e5-f71d-4eda-be4d-7a6529171718
+- type: tool_observation
+- session: bench-session-3
+{"toolName":"Bash","toolInput":{"cmd":"echo hello"},"toolOutput":"hello\n","durationMs":0,"success":true,"metadata":{"turnId":"03e597c8-295a-43d8-9959-bc77607d30f8"}}

package/memory/tool_observation/uncategorized/2026-03-03.md

@@ -0,0 +1,21 @@
+
+## 2026-03-03T14:03:38.204Z | 46d8dc3c-a7ce-4602-ae18-daf4ed0266f1
+- type: tool_observation
+- session: 3252b490-16ca-40fb-b30c-1171456e2c89
+{"toolName":"Skill","toolInput":{"skill":"commit"},"toolOutput":"{\"success\":true,\"commandName\":\"commit\"}","durationMs":0,"success":true,"metadata":{"turnId":"5eaeff19-dda2-4bd7-a905-9009b5786672"}}
+## 2026-03-03T14:03:43.897Z | ae933ad8-5f37-4a0b-9028-85bb29bdb6fc
+- type: tool_observation
+- session: 3252b490-16ca-40fb-b30c-1171456e2c89
+{"toolName":"Bash","toolInput":{"command":"git status && git diff && git log --oneline -5","description":"Check git status, diff, and recent commits"},"toolOutput":"On branch main\nYour branch is up to date with 'origin/main'.\n\nChanges not staged for commit:\n  (use \"git add <file>...\" to update what will be committed)\n  (use \"git restore <file>...\" to discard changes in working directory)\n\tmodified:   package-lock.json\n\tmodified:   package.json\n\tmodified:   src/cli/index.ts\n\nUntracked files:\n  (use \"git add <file>...\" to include in what will be committed)\n\t.npm-cache/\n\tbootstrap-kb/\n\tclaude-memory-layer-1.0.14.tgz\n\td.sh\n\tdeploy.sh\n\tmemory/\n\tscripts/delete-unknown-projects.js\n\tyarn.lock\n\nno changes added to commit (use \"git add\" and/or \"git commit -a\")\ndiff --git package-lock.json package-lock.json\nindex c01b2e9..1181958 100644\n--- package-lock.json\n+++ package-lock.json\n@@ -1,12 +1,12 @@\n {\n   \"name\": \"claude-memory-layer\",\n-  \"version\": \"1.0.15\",\n+  \"version\": \"1.0.18\",\n   \"lockfileVersion\": 3,\n   \"requires\": true,\n   \"packages\": {\n     \"\": {\n       \"name\": \"claude-memory-layer\",\n-      \"version\": \"1.0.15\",\n+      \"version\": \"1.0.18\",\n       \"license\": \"MIT\",\n       \"dependencies\": {\n         \"@hono/node-server\": \"^1.13.0\",\ndiff --git package.json package.json\nindex bd41ac1..453d235 100644\n--- package.json\n+++ package.json\n@@ -1,6 +1,6 @@\n {\n   \"name\": \"claude-memory-layer\",\n-  \"version\": \"1.0.15\",\n+  \"version\": \"1.0.18\",\n\n... [121 lines truncated] ...\n\n       delete settings.hooks.PostToolUse;\n+      delete settings.hooks.Stop;\n+      delete settings.hooks.SessionEnd;\n \n       // Clean up empty hooks object\n       if (Object.keys(settings.hooks).length === 0) {\n@@ -219,19 +238,22 @@ program\n       console.log('\\n🧠 Claude Memory Layer Status\\n');\n \n       // Check hooks\n-      const hasUserPromptHook = settings.hooks?.UserPromptSubmit?.some(h =>\n-        h.hooks?.some(hook => hook.command?.includes('user-prompt-submit'))\n-      );\n-      const hasPostToolHook = settings.hooks?.PostToolUse?.some(h =>\n-        h.hooks?.some(hook => hook.command?.includes('post-tool-use'))\n-      );\n+      const hasSessionStartHook = hasHook(settings, 'SessionStart', 'session-start');\n+      const hasUserPromptHook = hasHook(settings, 'UserPromptSubmit', 'user-prompt-submit');\n+      const hasPostToolHook = hasHook(settings, 'PostToolUse', 'post-tool-use');\n+      const hasStopHook = hasHook(settings, 'Stop', 'stop');\n+      const hasSessionEndHook = hasHook(settings, 'SessionEnd', 'session-end');\n \n       console.log('Hooks:');\n+      console.log(`  SessionStart: ${hasSessionStartHook ? '✅ Installed' : '❌ Not installed'}`);\n       console.log(`  UserPromptSubmit: ${hasUserPromptHook ? '✅ Installed' : '❌ Not installed'}`);\n       console.log(`  PostToolUse: ${hasPostToolHook ? '✅ Installed' : '❌ Not installed'}`);\n+      console.log(`  Stop: ${hasStopHook ? '✅ Installed' : '❌ Not installed'}`);\n+      console.log(`  SessionEnd: ${hasSessionEndHook ? '✅ Installed' : '❌ Not installed'}`);\n \n       // Check plugin files\n-      const hooksExist = fs.existsSync(path.join(pluginPath, 'hooks', 'user-prompt-submit.js'));\n+      const hooksExist = REQUIRED_HOOK_FILES\n+        .every((file) => fs.existsSync(path.join(pluginPath, 'hooks', file)));\n       console.log(`\\nPlugin files: ${hooksExist ? '✅ Found' : '❌ Not found'}`);\n       console.log(`  Path: ${pluginPath}`);\n \n@@ -239,7 +261,7 @@ program\n       const dashboardRunning = await isServerRunning(37777);\n       console.log(`\\nDashboard: ${dashboardRunning ? '✅ Running at http://localhost:37777' : '⏹️  Not running'}`);\n \n-      if (!hasUserPromptHook || !hasPostToolHook) {\n+      if (!hasSessionStartHook || !hasUserPromptHook || !hasPostToolHook || !hasStopHook || !hasSessionEndHook) {\n         console.log('\\n💡 Run \"claude-memory-layer install\" to set up hooks.\\n');\n       } else {\n         console.log('\\n✅ Plugin is fully installed and configured.\\n');\n257241b fix(hook): use lightweight service in session-start\n60d59c6 fix(api): handle missing retrieval_traces table in read-only mode\n1ab58f2 feat(build): inject version from package.json at build time\n4d48779 tune(hook): raise default injection threshold with fallback retry for recall\n3c618db fix(import): normalize underscore/hyphen path variants for project folder matching","durationMs":0,"success":true,"metadata":{"command":"git status","turnId":"5eaeff19-dda2-4bd7-a905-9009b5786672"}}
+## 2026-03-03T14:03:55.698Z | 101afa33-2fd1-4008-88b8-c824465ccd69
+- type: tool_observation
+- session: 3252b490-16ca-40fb-b30c-1171456e2c89
+{"toolName":"Bash","toolInput":{"command":"cat scripts/delete-unknown-projects.js","description":"Check new script content"},"toolOutput":"#!/usr/bin/env node\nimport fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\n\nfunction parseArgs(argv) {\n  const result = {\n    apply: false,\n    hashes: []\n  };\n\n  for (let i = 0; i < argv.length; i += 1) {\n    const arg = argv[i];\n    if (arg === '--apply') {\n      result.apply = true;\n      continue;\n    }\n    if (arg === '--hash' && i + 1 < argv.length) {\n      result.hashes.push(String(argv[i + 1]).trim().toLowerCase());\n      i += 1;\n      continue;\n    }\n    if (arg.startsWith('--hash=')) {\n      result.hashes.push(arg.slice('--hash='.length).trim().toLowerCase());\n    }\n  }\n\n  return result;\n}\n\nfunction loadRegistryHashes(registryPath) {\n  if (!fs.existsSync(registryPath)) return new Set();\n  try {\n    const raw = JSON.parse(fs.readFileSync(registryPath, 'utf8'));\n    const sessions = raw && typeof raw === 'object' ? raw.sessions : null;\n    if (!sessions || typeof sessions !== 'object') return new Set();\n\n    const hashes = new Set();\n    for (const entry of Object.values(sessions)) {\n      if (!entry || typeof entry !== 'object') continue;\n      const hash = entry.projectHash;\n      if (typeof hash === 'string' && /^[a-f0-9]{8}$/.test(hash)) {\n        hashes.add(hash);\n      }\n    }\n    return hashes;\n  } catch {\n    return new Set();\n  }\n}\n\n... [54 lines truncated] ...\n\n    .map((entry) => entry.name)\n    .filter((name) => /^[a-f0-9]{8}$/.test(name))\n    .filter((hash) => !knownHashes.has(hash))\n    .filter((hash) => filterHashes.size === 0 || filterHashes.has(hash));\n\n  const projectInfo = candidates.map((hash) => {\n    const fullPath = path.join(projectsDir, hash);\n    const sizeBytes = getDirSizeBytes(fullPath);\n    return {\n      hash,\n      path: fullPath,\n      sizeBytes,\n      sizeHuman: formatBytes(sizeBytes)\n    };\n  });\n\n  const totalBytes = projectInfo.reduce((sum, item) => sum + item.sizeBytes, 0);\n\n  if (!args.apply) {\n    console.log(JSON.stringify({\n      status: 'dry-run',\n      message: 'Run with --apply to delete the directories below.',\n      memoryRoot,\n      projectsDir,\n      registryPath,\n      unknownCount: projectInfo.length,\n      totalSizeBytes: totalBytes,\n      totalSizeHuman: formatBytes(totalBytes),\n      projects: projectInfo\n    }, null, 2));\n    process.exit(0);\n  }\n\n  let deleted = 0;\n  for (const item of projectInfo) {\n    fs.rmSync(item.path, { recursive: true, force: true });\n    deleted += 1;\n  }\n\n  console.log(JSON.stringify({\n    status: 'ok',\n    mode: 'apply',\n    deletedCount: deleted,\n    deletedSizeBytes: totalBytes,\n    deletedSizeHuman: formatBytes(totalBytes),\n    deletedHashes: projectInfo.map((item) => item.hash)\n  }, null, 2));\n}\n\nmain();","durationMs":0,"success":true,"metadata":{"command":"cat","turnId":"5eaeff19-dda2-4bd7-a905-9009b5786672"}}
+## 2026-03-03T14:04:06.818Z | e92edb69-bd60-41e4-a490-08a7c50deadd
+- type: tool_observation
+- session: 3252b490-16ca-40fb-b30c-1171456e2c89
+{"toolName":"Bash","toolInput":{"command":"git add package.json package-lock.json src/cli/index.ts scripts/delete-unknown-projects.js","description":"Stage relevant changed and new files"},"toolOutput":"","durationMs":0,"success":true,"metadata":{"command":"git add","turnId":"5eaeff19-dda2-4bd7-a905-9009b5786672"}}
+## 2026-03-03T14:04:29.483Z | bff186d2-1eba-4fb3-bbb4-98a5dccbc508
+- type: tool_observation
+- session: 3252b490-16ca-40fb-b30c-1171456e2c89
+{"toolName":"Bash","toolInput":{"command":"git commit -m \"$(cat <<'EOF'\nfeat(cli): expand hook coverage to all lifecycle events\n\n- Add SessionStart, Stop, SessionEnd hooks alongside existing UserPromptSubmit and PostToolUse\n- Refactor getHooksConfig with makeHook helper to reduce repetition\n- Add REQUIRED_HOOK_FILES constant and hasHook helper for validation\n- Update install/uninstall/status commands to handle all 5 hooks\n- Add scripts/delete-unknown-projects.js for cleaning orphaned project dirs\n- Add ops:projects:clean-unknown npm script\n- Bump version to 1.0.18\n\nCo-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>\nEOF\n)\"","description":"Commit all staged changes"},"toolOutput":"[main b37aa13] feat(cli): expand hook coverage to all lifecycle events\n 4 files changed, 214 insertions(+), 37 deletions(-)\n create mode 100755 scripts/delete-unknown-projects.js","durationMs":0,"success":true,"metadata":{"command":"git commit","turnId":"5eaeff19-dda2-4bd7-a905-9009b5786672"}}

package/memory/user_prompt/uncategorized/2026-02-26.md

@@ -14,3 +14,12 @@ api/stats/retrieval-traces?limit=20
 suggested_actions 를 생성할때 
 "각 색상·사이즈별 재고 가능 여부 확인해줘"
 같이 없는 기능은 생성하지 않도록 프롬프트 개선해줘 
+
+## 2026-02-26T13:53:54.228Z | efefccef-1a9a-4e89-b1fa-b855fd8fdc85
+- type: user_prompt
+- session: bench-session-2
+최근 변경 사항 때문에 claude code 가 느려진 원인을 분석해줘.
+## 2026-02-26T13:54:45.879Z | f7fca9e1-5169-4732-8845-34fdb5e699c5
+- type: user_prompt
+- session: bench-session-3
+최근 변경 사항 때문에 claude code 가 느려진 원인을 분석해줘.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-layer",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "Claude Code plugin that learns from conversations to provide personalized assistance",
   "main": "dist/index.js",
   "bin": {
@@ -19,7 +19,8 @@
     "ops:sync-gap:heal": "bash scripts/sync-gap-auto-heal.sh",
     "ops:review:resolve": "node scripts/review-queue-auto-resolve.js",
     "ops:heartbeat": "bash scripts/heartbeat-memory-orchestrator.sh",
-    "ops:health": "npm run ops:sync-gap:report && npm run ops:sync-gap:heal && npm run ops:review:resolve"
+    "ops:health": "npm run ops:sync-gap:report && npm run ops:sync-gap:heal && npm run ops:review:resolve",
+    "ops:projects:clean-unknown": "node scripts/delete-unknown-projects.js"
   },
   "keywords": [
     "claude-code",

package/scripts/delete-unknown-projects.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const result = {
+    apply: false,
+    hashes: []
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--apply') {
+      result.apply = true;
+      continue;
+    }
+    if (arg === '--hash' && i + 1 < argv.length) {
+      result.hashes.push(String(argv[i + 1]).trim().toLowerCase());
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--hash=')) {
+      result.hashes.push(arg.slice('--hash='.length).trim().toLowerCase());
+    }
+  }
+
+  return result;
+}
+
+function loadRegistryHashes(registryPath) {
+  if (!fs.existsSync(registryPath)) return new Set();
+  try {
+    const raw = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    const sessions = raw && typeof raw === 'object' ? raw.sessions : null;
+    if (!sessions || typeof sessions !== 'object') return new Set();
+
+    const hashes = new Set();
+    for (const entry of Object.values(sessions)) {
+      if (!entry || typeof entry !== 'object') continue;
+      const hash = entry.projectHash;
+      if (typeof hash === 'string' && /^[a-f0-9]{8}$/.test(hash)) {
+        hashes.add(hash);
+      }
+    }
+    return hashes;
+  } catch {
+    return new Set();
+  }
+}
+
+function getDirSizeBytes(targetPath) {
+  if (!fs.existsSync(targetPath)) return 0;
+  const stat = fs.statSync(targetPath);
+  if (stat.isFile()) return stat.size;
+  if (!stat.isDirectory()) return 0;
+
+  let total = 0;
+  const entries = fs.readdirSync(targetPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const child = path.join(targetPath, entry.name);
+    if (entry.isDirectory()) {
+      total += getDirSizeBytes(child);
+    } else if (entry.isFile()) {
+      total += fs.statSync(child).size;
+    }
+  }
+  return total;
+}
+
+function formatBytes(bytes) {
+  if (bytes <= 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let value = bytes;
+  let unitIdx = 0;
+  while (value >= 1024 && unitIdx < units.length - 1) {
+    value /= 1024;
+    unitIdx += 1;
+  }
+  return `${value.toFixed(1)} ${units[unitIdx]}`;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const memoryRoot = process.env.CML_MEMORY_ROOT || path.join(os.homedir(), '.claude-code', 'memory');
+  const projectsDir = path.join(memoryRoot, 'projects');
+  const registryPath = path.join(memoryRoot, 'session-registry.json');
+
+  if (!fs.existsSync(projectsDir)) {
+    console.log(JSON.stringify({
+      status: 'skip',
+      reason: 'projects_dir_not_found',
+      projectsDir
+    }, null, 2));
+    process.exit(0);
+  }
+
+  const knownHashes = loadRegistryHashes(registryPath);
+  const filterHashes = new Set(
+    args.hashes.filter((h) => /^[a-f0-9]{8}$/.test(h))
+  );
+
+  const candidates = fs.readdirSync(projectsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => /^[a-f0-9]{8}$/.test(name))
+    .filter((hash) => !knownHashes.has(hash))
+    .filter((hash) => filterHashes.size === 0 || filterHashes.has(hash));
+
+  const projectInfo = candidates.map((hash) => {
+    const fullPath = path.join(projectsDir, hash);
+    const sizeBytes = getDirSizeBytes(fullPath);
+    return {
+      hash,
+      path: fullPath,
+      sizeBytes,
+      sizeHuman: formatBytes(sizeBytes)
+    };
+  });
+
+  const totalBytes = projectInfo.reduce((sum, item) => sum + item.sizeBytes, 0);
+
+  if (!args.apply) {
+    console.log(JSON.stringify({
+      status: 'dry-run',
+      message: 'Run with --apply to delete the directories below.',
+      memoryRoot,
+      projectsDir,
+      registryPath,
+      unknownCount: projectInfo.length,
+      totalSizeBytes: totalBytes,
+      totalSizeHuman: formatBytes(totalBytes),
+      projects: projectInfo
+    }, null, 2));
+    process.exit(0);
+  }
+
+  let deleted = 0;
+  for (const item of projectInfo) {
+    fs.rmSync(item.path, { recursive: true, force: true });
+    deleted += 1;
+  }
+
+  console.log(JSON.stringify({
+    status: 'ok',
+    mode: 'apply',
+    deletedCount: deleted,
+    deletedSizeBytes: totalBytes,
+    deletedSizeHuman: formatBytes(totalBytes),
+    deletedHashes: projectInfo.map((item) => item.hash)
+  }, null, 2));
+}
+
+main();

package/src/hooks/session-start.ts

@@ -5,7 +5,7 @@
  */
 
 import {
-  getMemoryServiceForProject,
+  getLightweightMemoryService,
   registerSession
 } from '../services/memory-service.js';
 import type { SessionStartInput, SessionStartOutput } from '../core/types.js';
@@ -18,8 +18,8 @@ async function main(): Promise<void> {
   // Register session with project path for other hooks to find
   registerSession(input.session_id, input.cwd);
 
-  // Get project-specific memory service
-  const memoryService = getMemoryServiceForProject(input.cwd);
+  // Use lightweight service to avoid starting background workers in hook process
+  const memoryService = getLightweightMemoryService(input.session_id);
 
   try {
     // Start session in memory service
@@ -42,6 +42,12 @@ async function main(): Promise<void> {
   } catch (error) {
     console.error('Memory hook error:', error);
     console.log(JSON.stringify({ context: '' }));
+  } finally {
+    try {
+      await memoryService.close();
+    } catch {
+      // Best-effort cleanup
+    }
   }
 }
 

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

@@ -11,7 +11,10 @@
  */
 
 import { randomUUID } from 'crypto';
-import { getLightweightMemoryService } from '../services/memory-service.js';
+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 type { UserPromptSubmitInput, UserPromptSubmitOutput } from '../core/types.js';
 
@@ -21,6 +24,20 @@ const MAX_MEMORIES = parseInt(process.env.CLAUDE_MEMORY_MAX_COUNT || '5');
 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 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.
@@ -42,6 +59,120 @@ 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) => {
+    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}`);
+}
+
 async function main(): Promise<void> {
   // Read input from stdin
   const inputData = await readStdin();
@@ -58,62 +189,127 @@ async function main(): Promise<void> {
   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);
+
     // Store only non-trivial prompts (skip /commands, short inputs)
     if (shouldStorePrompt(input.prompt)) {
       await memoryService.storeUserPrompt(
         input.session_id,
         input.prompt,
-        { turnId }
+        {
+          turnId,
+          adherence: {
+            checked: adherenceDecision.run,
+            reason: adherenceDecision.reason,
+            turn: currentTurn
+          }
+        }
       );
     }
 
-    let context = '';
-
-    // Fast keyword search if enabled
-    if (ENABLE_SEARCH && input.prompt.length > 10) {
+    // 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 minScore = getDynamicMinScore(input.prompt);
-      let results = await memoryService.keywordSearch(input.prompt, {
-        topK: MAX_MEMORIES,
-        minScore
-      });
+      let mergedMemories: Array<{ type: string; content: string; id?: string; score?: number }> = [];
+
+      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,
+              sessionId: input.session_id,
+              intentRewrite: true,
+              adaptiveRerank: true,
+              projectScopeMode: 'strict'
+            }),
+            SEMANTIC_TIMEOUT_MS
+          );
 
-      // 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, {
+          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
+        }
+      }
+
+      const shouldUseKeywordFallback =
+        RETRIEVAL_MODE === 'keyword' ||
+        RETRIEVAL_MODE === 'hybrid' ||
+        mergedMemories.length === 0;
+
+      if (shouldUseKeywordFallback && mergedMemories.length < MAX_MEMORIES) {
+        let results = await memoryService.keywordSearch(input.prompt, {
           topK: MAX_MEMORIES,
-          minScore: FALLBACK_MIN_SCORE
+          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, {
+            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
+          });
+          if (mergedMemories.length >= MAX_MEMORIES) break;
+        }
       }
 
-      if (results.length > 0) {
+      if (mergedMemories.length > 0) {
         // Increment access count for found memories
-        const eventIds = results.map(r => r.event.id);
-        await memoryService.incrementMemoryAccess(eventIds);
+        const eventIds = mergedMemories.map((m) => m.id).filter((v): v is string => Boolean(v));
+        if (eventIds.length > 0) {
+          await memoryService.incrementMemoryAccess(eventIds);
+        }
 
         // Record each retrieval for helpfulness tracking
-        for (const r of results) {
+        for (const m of mergedMemories) {
+          if (!m.id) continue;
           try {
             await memoryService.recordRetrieval(
-              r.event.id,
+              m.id,
               input.session_id,
-              r.score,
+              m.score ?? minScore,
               input.prompt
             );
           } catch { /* non-critical */ }
         }
 
-        // Format context
-        const memories = results.map(r => {
-          const preview = r.event.content.length > 300
-            ? r.event.content.substring(0, 300) + '...'
-            : r.event.content;
-          return `- [${r.event.eventType}] ${preview}`;
-        });
-
-        context = `💡 **Related memories found:**\n\n${memories.join('\n\n')}`;
+        context = formatMemoryContext(mergedMemories);
       }
     }
 
+    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) {

package/src/server/api/events.ts

@@ -66,6 +66,7 @@ eventsRouter.get('/', async (c) => {
         sessionId: e.sessionId,
         preview: e.content.slice(0, 200) + (e.content.length > 200 ? '...' : ''),
         contentLength: e.content.length,
+        metadata: e.metadata,
         accessCount: (e as any).access_count || 0,
         lastAccessedAt: (e as any).last_accessed_at || null
       })),