engramx 0.2.1 → 0.3.1

package/dist/cli.js

@@ -4,9 +4,11 @@ import {
   install,
   status,
   uninstall
-} from "./chunk-YQ3FPGPC.js";
+} from "./chunk-IYO4HETA.js";
 import {
   benchmark,
+  computeKeywordIDF,
+  getFileContext,
   godNodes,
   init,
   learn,
@@ -14,13 +16,1235 @@ import {
   path,
   query,
   stats
-} from "./chunk-22ADJYQ5.js";
+} from "./chunk-RGDHLGWQ.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import chalk from "chalk";
+import {
+  existsSync as existsSync6,
+  readFileSync as readFileSync4,
+  writeFileSync as writeFileSync2,
+  mkdirSync,
+  unlinkSync,
+  copyFileSync,
+  renameSync as renameSync3
+} from "fs";
+import { dirname as dirname3, join as join6, resolve as pathResolve } from "path";
+import { homedir } from "os";
+
+// src/intercept/safety.ts
+import { existsSync } from "fs";
+import { join } from "path";
+var PASSTHROUGH = null;
+var DEFAULT_HANDLER_TIMEOUT_MS = 2e3;
+async function withTimeout(promise, ms = DEFAULT_HANDLER_TIMEOUT_MS) {
+  let timer;
+  const timeout = new Promise((resolve3) => {
+    timer = setTimeout(() => resolve3(PASSTHROUGH), ms);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+async function wrapSafely(handler, onError) {
+  try {
+    return await handler();
+  } catch (err) {
+    if (onError) {
+      try {
+        onError(err);
+      } catch {
+      }
+    }
+    return PASSTHROUGH;
+  }
+}
+async function runHandler(handler, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_HANDLER_TIMEOUT_MS;
+  return wrapSafely(() => withTimeout(handler(), timeoutMs), opts.onError);
+}
+function isHookDisabled(projectRoot) {
+  if (projectRoot === null) return true;
+  try {
+    return existsSync(join(projectRoot, ".engram", "hook-disabled"));
+  } catch {
+    return true;
+  }
+}
+
+// src/intercept/context.ts
+import { existsSync as existsSync2, realpathSync, statSync } from "fs";
+import { dirname, isAbsolute, join as join2, resolve, sep } from "path";
+var ENGRAM_DIR = ".engram";
+var GRAPH_FILE = "graph.db";
+var MAX_WALK_DEPTH = 40;
+var projectRootCache = /* @__PURE__ */ new Map();
+function normalizePath(filePath, cwd) {
+  if (!filePath) return "";
+  try {
+    const abs = isAbsolute(filePath) ? filePath : resolve(cwd, filePath);
+    return resolve(abs);
+  } catch {
+    return "";
+  }
+}
+function isExemptPath(absPath) {
+  if (!absPath) return true;
+  const p = absPath.replaceAll(sep, "/");
+  if (p.includes("/.engram/cache/")) return true;
+  if (p.includes("/node_modules/")) return true;
+  if (p.includes("/.git/")) return true;
+  return false;
+}
+function isHardSystemPath(absPath) {
+  if (!absPath) return true;
+  const p = absPath.replaceAll(sep, "/");
+  if (p === "/" || p.startsWith("/dev/") || p.startsWith("/proc/")) return true;
+  if (p.startsWith("/sys/")) return true;
+  return false;
+}
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  // Images
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".ico",
+  ".bmp",
+  ".tiff",
+  ".svg",
+  // Documents
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".xls",
+  ".xlsx",
+  ".ppt",
+  ".pptx",
+  // Archives
+  ".zip",
+  ".tar",
+  ".gz",
+  ".tgz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+  // Compiled / binary code
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".o",
+  ".a",
+  ".class",
+  ".wasm",
+  // Audio / video
+  ".mp3",
+  ".mp4",
+  ".m4a",
+  ".wav",
+  ".flac",
+  ".ogg",
+  ".avi",
+  ".mov",
+  ".mkv",
+  ".webm",
+  // Data blobs
+  ".bin",
+  ".dat",
+  ".db",
+  ".sqlite",
+  ".parquet",
+  // Fonts
+  ".ttf",
+  ".otf",
+  ".woff",
+  ".woff2",
+  ".eot"
+]);
+function isBinaryFile(absPath) {
+  if (!absPath) return false;
+  const dot = absPath.lastIndexOf(".");
+  if (dot === -1) return false;
+  const ext = absPath.slice(dot).toLowerCase();
+  return BINARY_EXTENSIONS.has(ext);
+}
+function isSecretFile(absPath) {
+  if (!absPath) return false;
+  const idx = Math.max(absPath.lastIndexOf("/"), absPath.lastIndexOf(sep));
+  const base = idx === -1 ? absPath : absPath.slice(idx + 1);
+  const lower = base.toLowerCase();
+  if (lower === ".env") return true;
+  if (lower.startsWith(".env.")) return true;
+  if (lower === "secrets.json" || lower === "secrets.yaml" || lower === "secrets.yml") return true;
+  if (lower === "credentials" || lower === "credentials.json") return true;
+  if (lower === "config.secret.json") return true;
+  if (lower.endsWith(".pem")) return true;
+  if (lower.endsWith(".key")) return true;
+  if (lower.endsWith(".p12")) return true;
+  if (lower.endsWith(".pfx")) return true;
+  if (lower.endsWith(".keystore")) return true;
+  if (lower === "id_rsa" || lower === "id_ed25519" || lower === "id_ecdsa" || lower === "id_dsa") {
+    return true;
+  }
+  return false;
+}
+function isContentUnsafeForIntercept(absPath) {
+  return isBinaryFile(absPath) || isSecretFile(absPath);
+}
+function findProjectRoot(filePath) {
+  if (!filePath) return null;
+  let startDir;
+  try {
+    const st = statSync(filePath);
+    startDir = st.isDirectory() ? filePath : dirname(filePath);
+  } catch {
+    startDir = dirname(filePath);
+  }
+  if (projectRootCache.has(startDir)) {
+    return projectRootCache.get(startDir) ?? null;
+  }
+  let current = startDir;
+  let depth = 0;
+  while (depth < MAX_WALK_DEPTH) {
+    const candidate = join2(current, ENGRAM_DIR, GRAPH_FILE);
+    try {
+      if (existsSync2(candidate)) {
+        projectRootCache.set(startDir, current);
+        return current;
+      }
+    } catch {
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+    depth += 1;
+  }
+  projectRootCache.set(startDir, null);
+  return null;
+}
+function isInsideProject(filePath, projectRoot) {
+  if (!filePath || !projectRoot) return false;
+  try {
+    const realRoot = realpathSync(projectRoot);
+    let realFile;
+    try {
+      realFile = realpathSync(filePath);
+    } catch {
+      realFile = resolve(filePath);
+    }
+    const rootWithSep = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+    return realFile === realRoot || realFile.startsWith(rootWithSep);
+  } catch {
+    return false;
+  }
+}
+function isValidCwd(cwd) {
+  if (!cwd || typeof cwd !== "string") return false;
+  if (!isAbsolute(cwd)) return false;
+  try {
+    return statSync(cwd).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function resolveInterceptContext(filePath, cwd) {
+  if (!filePath) return { proceed: false, reason: "empty-path" };
+  const absPath = normalizePath(filePath, cwd);
+  if (!absPath) return { proceed: false, reason: "normalize-failed" };
+  if (isHardSystemPath(absPath)) {
+    return { proceed: false, reason: "system-path" };
+  }
+  const projectRoot = findProjectRoot(absPath);
+  if (projectRoot === null) {
+    return { proceed: false, reason: "no-project-root" };
+  }
+  if (!isInsideProject(absPath, projectRoot)) {
+    return { proceed: false, reason: "outside-project" };
+  }
+  if (isExemptPath(absPath)) {
+    return { proceed: false, reason: "exempt-path" };
+  }
+  return { proceed: true, absPath, projectRoot };
+}
+
+// src/intercept/formatter.ts
+var MAX_RESPONSE_CHARS = 8e3;
+var TRUNCATION_MARKER = "\n\n[... engram summary truncated to fit hook response limit ...]";
+function truncateForHook(text) {
+  if (!text) return "";
+  if (text.length <= MAX_RESPONSE_CHARS) return text;
+  const budget = MAX_RESPONSE_CHARS - TRUNCATION_MARKER.length;
+  let cut = budget;
+  const code = text.charCodeAt(cut - 1);
+  if (code >= 55296 && code <= 56319) cut -= 1;
+  return text.slice(0, cut) + TRUNCATION_MARKER;
+}
+function buildDenyResponse(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: truncateForHook(reason)
+    }
+  };
+}
+function buildAllowWithContextResponse(additionalContext) {
+  const trimmed = additionalContext?.trim() ?? "";
+  if (trimmed.length === 0) {
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow"
+      }
+    };
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow",
+      additionalContext: truncateForHook(trimmed)
+    }
+  };
+}
+function buildSessionContextResponse(eventName, additionalContext) {
+  const trimmed = additionalContext?.trim() ?? "";
+  if (trimmed.length === 0) return null;
+  return {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: truncateForHook(trimmed)
+    }
+  };
+}
+
+// src/intercept/handlers/read.ts
+var READ_CONFIDENCE_THRESHOLD = 0.7;
+async function handleRead(payload) {
+  if (payload.tool_name !== "Read") return PASSTHROUGH;
+  const filePath = payload.tool_input?.file_path;
+  if (!filePath || typeof filePath !== "string") return PASSTHROUGH;
+  const offset = payload.tool_input.offset;
+  const limit = payload.tool_input.limit;
+  if (typeof offset === "number" && offset > 0 || typeof limit === "number" && limit > 0) {
+    return PASSTHROUGH;
+  }
+  if (isContentUnsafeForIntercept(filePath)) return PASSTHROUGH;
+  const ctx = resolveInterceptContext(filePath, payload.cwd);
+  if (!ctx.proceed) return PASSTHROUGH;
+  if (isContentUnsafeForIntercept(ctx.absPath)) return PASSTHROUGH;
+  if (isHookDisabled(ctx.projectRoot)) return PASSTHROUGH;
+  const fileCtx = await getFileContext(ctx.projectRoot, ctx.absPath);
+  if (!fileCtx.found || fileCtx.codeNodeCount === 0) return PASSTHROUGH;
+  if (fileCtx.isStale) return PASSTHROUGH;
+  if (fileCtx.confidence < READ_CONFIDENCE_THRESHOLD) return PASSTHROUGH;
+  return buildDenyResponse(fileCtx.summary);
+}
+
+// src/intercept/handlers/edit-write.ts
+import { relative, resolve as resolvePath } from "path";
+var MAX_LANDMINES_IN_WARNING = 5;
+function formatLandmineWarning(projectRelativeFile, mistakeList) {
+  const header = `[engram landmines] ${mistakeList.length} past mistake${mistakeList.length === 1 ? "" : "s"} recorded for ${projectRelativeFile}:`;
+  const items = mistakeList.map((m) => {
+    const conf = m.confidence === "EXTRACTED" ? "" : ` [${m.confidence.toLowerCase()}]`;
+    return `  - ${m.label}${conf}`;
+  });
+  const footer = "Review these before editing to avoid re-introducing a known failure mode. engram recorded these from past session notes (bug:/fix: lines in your CLAUDE.md).";
+  return [header, ...items, "", footer].join("\n");
+}
+async function handleEditOrWrite(payload) {
+  if (payload.tool_name !== "Edit" && payload.tool_name !== "Write") {
+    return PASSTHROUGH;
+  }
+  const filePath = payload.tool_input?.file_path;
+  if (!filePath || typeof filePath !== "string") return PASSTHROUGH;
+  if (isContentUnsafeForIntercept(filePath)) return PASSTHROUGH;
+  const ctx = resolveInterceptContext(filePath, payload.cwd);
+  if (!ctx.proceed) return PASSTHROUGH;
+  if (isContentUnsafeForIntercept(ctx.absPath)) return PASSTHROUGH;
+  if (isHookDisabled(ctx.projectRoot)) return PASSTHROUGH;
+  const relPath = relative(resolvePath(ctx.projectRoot), ctx.absPath);
+  if (!relPath || relPath.startsWith("..")) return PASSTHROUGH;
+  let found;
+  try {
+    found = await mistakes(ctx.projectRoot, {
+      sourceFile: relPath,
+      limit: MAX_LANDMINES_IN_WARNING
+    });
+  } catch {
+    return PASSTHROUGH;
+  }
+  if (found.length === 0) return PASSTHROUGH;
+  const warning = formatLandmineWarning(relPath, found);
+  return buildAllowWithContextResponse(warning);
+}
+
+// src/intercept/handlers/bash.ts
+var READ_LIKE_COMMANDS = /* @__PURE__ */ new Set([
+  "cat",
+  "head",
+  "tail",
+  "less",
+  "more"
+]);
+var UNSAFE_SHELL_CHARS = /[|&;<>()$`\\*?[\]{}"']/;
+function parseReadLikeBashCommand(command) {
+  if (!command || typeof command !== "string") return null;
+  if (command.length > 200) return null;
+  const trimmed = command.trim();
+  if (trimmed !== command) {
+    return null;
+  }
+  if (UNSAFE_SHELL_CHARS.test(trimmed)) return null;
+  const tokens = trimmed.split(/\s+/);
+  if (tokens.length !== 2) return null;
+  const [cmd, path2] = tokens;
+  if (!READ_LIKE_COMMANDS.has(cmd)) return null;
+  if (path2.startsWith("-")) return null;
+  if (path2.length === 0) return null;
+  if (path2.includes("\0")) return null;
+  return path2;
+}
+async function handleBash(payload) {
+  if (payload.tool_name !== "Bash") return PASSTHROUGH;
+  const command = payload.tool_input?.command;
+  if (!command || typeof command !== "string") return PASSTHROUGH;
+  const filePath = parseReadLikeBashCommand(command);
+  if (filePath === null) return PASSTHROUGH;
+  return handleRead({
+    tool_name: "Read",
+    cwd: payload.cwd,
+    tool_input: {
+      file_path: filePath
+    }
+  });
+}
+
+// src/intercept/handlers/session-start.ts
+import { existsSync as existsSync3, readFileSync } from "fs";
+import { basename, dirname as dirname2, join as join3, resolve as resolve2 } from "path";
+var MAX_GOD_NODES = 10;
+var MAX_LANDMINES_IN_BRIEF = 3;
+function readGitBranch(projectRoot) {
+  try {
+    let current = resolve2(projectRoot);
+    for (let depth = 0; depth < 10; depth++) {
+      const headPath = join3(current, ".git", "HEAD");
+      if (existsSync3(headPath)) {
+        const content = readFileSync(headPath, "utf-8").trim();
+        const refMatch = content.match(/^ref:\s+refs\/heads\/(.+)$/);
+        if (refMatch) return refMatch[1];
+        if (/^[0-9a-f]{7,40}$/i.test(content)) return "detached";
+        return null;
+      }
+      const parent = dirname2(current);
+      if (parent === current) return null;
+      current = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function formatBrief(args) {
+  const lines = [];
+  const minedAgo = args.stats.lastMined > 0 ? describeAgo(Date.now() - args.stats.lastMined) : "unknown";
+  const branchStr = args.branch ? ` (branch: ${args.branch})` : "";
+  lines.push(`[engram] Project brief for ${args.projectName}${branchStr}`);
+  lines.push(
+    `Graph: ${args.stats.nodes} nodes, ${args.stats.edges} edges, ${args.stats.extractedPct}% extracted. Last mined: ${minedAgo}.`
+  );
+  lines.push("");
+  if (args.godNodes.length > 0) {
+    lines.push("Core entities (most connected):");
+    for (const g of args.godNodes) {
+      lines.push(
+        `  - ${g.label} [${g.kind}] (${g.degree} conn) \u2014 ${g.sourceFile}`
+      );
+    }
+    lines.push("");
+  }
+  if (args.landmines.length > 0) {
+    lines.push("Known landmines (past issues to watch for):");
+    for (const m of args.landmines) {
+      lines.push(`  - ${m.sourceFile}: ${m.label}`);
+    }
+    lines.push("");
+  }
+  lines.push(
+    "Tip: engram intercepts Read/Edit/Write/Bash tool calls. Code structure comes through the graph automatically; you don't need to explore files to understand layout. Use explicit offset/limit on Read if you need raw lines."
+  );
+  return lines.join("\n");
+}
+function describeAgo(ms) {
+  if (ms < 0) return "just now";
+  const s = Math.floor(ms / 1e3);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  return `${d}d ago`;
+}
+async function handleSessionStart(payload) {
+  if (payload.hook_event_name !== "SessionStart") return PASSTHROUGH;
+  const source = payload.source ?? "startup";
+  if (source === "resume") return PASSTHROUGH;
+  const cwd = payload.cwd;
+  if (!isValidCwd(cwd)) return PASSTHROUGH;
+  const projectRoot = findProjectRoot(cwd);
+  if (projectRoot === null) return PASSTHROUGH;
+  if (isHookDisabled(projectRoot)) return PASSTHROUGH;
+  try {
+    const [gods, mistakeList, graphStats] = await Promise.all([
+      godNodes(projectRoot, MAX_GOD_NODES).catch(() => []),
+      mistakes(projectRoot, { limit: MAX_LANDMINES_IN_BRIEF }).catch(
+        () => []
+      ),
+      stats(projectRoot).catch(() => ({
+        nodes: 0,
+        edges: 0,
+        communities: 0,
+        extractedPct: 0,
+        inferredPct: 0,
+        ambiguousPct: 0,
+        lastMined: 0,
+        totalQueryTokensSaved: 0
+      }))
+    ]);
+    if (graphStats.nodes === 0 && gods.length === 0) return PASSTHROUGH;
+    const branch = readGitBranch(projectRoot);
+    const projectName = basename(projectRoot);
+    const text = formatBrief({
+      projectName,
+      branch,
+      stats: {
+        nodes: graphStats.nodes,
+        edges: graphStats.edges,
+        extractedPct: graphStats.extractedPct,
+        lastMined: graphStats.lastMined
+      },
+      godNodes: gods,
+      landmines: mistakeList.map((m) => ({
+        label: m.label,
+        sourceFile: m.sourceFile
+      }))
+    });
+    return buildSessionContextResponse("SessionStart", text);
+  } catch {
+    return PASSTHROUGH;
+  }
+}
+
+// src/intercept/handlers/user-prompt.ts
+var MIN_SIGNIFICANT_TERMS = 2;
+var MIN_MATCHED_NODES = 3;
+var PROMPT_INJECTION_TOKEN_BUDGET = 500;
+var MIN_IDF_THRESHOLD = 1.386;
+var MAX_SEED_KEYWORDS = 5;
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "must",
+  "can",
+  "shall",
+  "to",
+  "of",
+  "for",
+  "in",
+  "on",
+  "at",
+  "by",
+  "with",
+  "from",
+  "and",
+  "or",
+  "but",
+  "not",
+  "no",
+  "this",
+  "that",
+  "these",
+  "those",
+  "i",
+  "you",
+  "he",
+  "she",
+  "it",
+  "we",
+  "they",
+  "my",
+  "your",
+  "his",
+  "her",
+  "its",
+  "our",
+  "their",
+  "me",
+  "him",
+  "us",
+  "them",
+  "as",
+  "if",
+  "when",
+  "where",
+  "why",
+  "how",
+  "what",
+  "which",
+  "who",
+  "whom",
+  "so",
+  "than",
+  "then",
+  "just"
+]);
+function extractKeywords(prompt) {
+  if (!prompt || typeof prompt !== "string") return [];
+  const tokens = prompt.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length >= 3).filter((t) => !STOPWORDS.has(t));
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const t of tokens) {
+    if (seen.has(t)) continue;
+    seen.add(t);
+    result.push(t);
+  }
+  return result;
+}
+async function handleUserPromptSubmit(payload) {
+  if (payload.hook_event_name !== "UserPromptSubmit") return PASSTHROUGH;
+  const prompt = payload.prompt;
+  if (!prompt || typeof prompt !== "string") return PASSTHROUGH;
+  if (prompt.length > 8e3) return PASSTHROUGH;
+  const rawKeywords = extractKeywords(prompt);
+  if (rawKeywords.length < MIN_SIGNIFICANT_TERMS) return PASSTHROUGH;
+  const cwd = payload.cwd;
+  if (!isValidCwd(cwd)) return PASSTHROUGH;
+  const projectRoot = findProjectRoot(cwd);
+  if (projectRoot === null) return PASSTHROUGH;
+  if (isHookDisabled(projectRoot)) return PASSTHROUGH;
+  let keywords;
+  try {
+    const scored = await computeKeywordIDF(projectRoot, rawKeywords);
+    if (scored.length === 0) {
+      keywords = rawKeywords;
+    } else {
+      const discriminative = scored.filter((s) => s.idf >= MIN_IDF_THRESHOLD);
+      if (discriminative.length === 0) {
+        return PASSTHROUGH;
+      }
+      keywords = scored.filter((s) => s.idf > 0).slice(0, MAX_SEED_KEYWORDS).map((s) => s.keyword);
+      if (keywords.length === 0) {
+        keywords = rawKeywords;
+      }
+    }
+  } catch {
+    keywords = rawKeywords;
+  }
+  if (keywords.length === 0) return PASSTHROUGH;
+  let result;
+  try {
+    result = await query(projectRoot, keywords.join(" "), {
+      tokenBudget: PROMPT_INJECTION_TOKEN_BUDGET,
+      depth: 2
+      // Shallower than default (3) to keep injection focused.
+    });
+  } catch {
+    return PASSTHROUGH;
+  }
+  if (result.nodesFound < MIN_MATCHED_NODES) return PASSTHROUGH;
+  const header = `[engram] Pre-query context for this message (matched ${result.nodesFound} graph nodes):`;
+  const text = `${header}
+
+${result.text}`;
+  return buildSessionContextResponse("UserPromptSubmit", text);
+}
+
+// src/intelligence/hook-log.ts
+import {
+  appendFileSync,
+  existsSync as existsSync4,
+  renameSync,
+  statSync as statSync2,
+  readFileSync as readFileSync2
+} from "fs";
+import { join as join4 } from "path";
+var HOOK_LOG_MAX_BYTES = 10 * 1024 * 1024;
+var LOG_FILENAME = "hook-log.jsonl";
+var LOG_ROTATED_FILENAME = "hook-log.jsonl.1";
+function logHookEvent(projectRoot, entry) {
+  if (!projectRoot) return;
+  try {
+    const logPath = join4(projectRoot, ".engram", LOG_FILENAME);
+    rotateIfNeeded(projectRoot);
+    const line = JSON.stringify({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      ...entry
+    }) + "\n";
+    appendFileSync(logPath, line);
+  } catch {
+  }
+}
+function rotateIfNeeded(projectRoot) {
+  try {
+    const logPath = join4(projectRoot, ".engram", LOG_FILENAME);
+    if (!existsSync4(logPath)) return;
+    const size = statSync2(logPath).size;
+    if (size < HOOK_LOG_MAX_BYTES) return;
+    const rotatedPath = join4(projectRoot, ".engram", LOG_ROTATED_FILENAME);
+    renameSync(logPath, rotatedPath);
+  } catch {
+  }
+}
+function readHookLog(projectRoot) {
+  try {
+    const logPath = join4(projectRoot, ".engram", LOG_FILENAME);
+    if (!existsSync4(logPath)) return [];
+    const raw = readFileSync2(logPath, "utf-8");
+    const entries = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        entries.push(JSON.parse(line));
+      } catch {
+      }
+    }
+    return entries;
+  } catch {
+    return [];
+  }
+}
+
+// src/intercept/handlers/post-tool.ts
+function extractFilePath(toolName, toolInput) {
+  if (!toolInput) return void 0;
+  if (toolName === "Read" || toolName === "Edit" || toolName === "Write") {
+    const fp = toolInput.file_path;
+    return typeof fp === "string" ? fp : void 0;
+  }
+  return void 0;
+}
+function estimateOutputSize(toolResponse) {
+  if (toolResponse === null || toolResponse === void 0) return 0;
+  if (typeof toolResponse === "string") return toolResponse.length;
+  if (typeof toolResponse === "object") {
+    const resp = toolResponse;
+    if (typeof resp.output === "string") return resp.output.length;
+    try {
+      return JSON.stringify(toolResponse).length;
+    } catch {
+      return 0;
+    }
+  }
+  return 0;
+}
+function detectError(toolResponse) {
+  if (toolResponse === null || toolResponse === void 0) return false;
+  if (typeof toolResponse === "object") {
+    const resp = toolResponse;
+    if (resp.error !== void 0 && resp.error !== null) return true;
+  }
+  return false;
+}
+async function handlePostTool(payload) {
+  if (payload.hook_event_name !== "PostToolUse") return PASSTHROUGH;
+  try {
+    const cwd = payload.cwd;
+    if (!isValidCwd(cwd)) return PASSTHROUGH;
+    const projectRoot = findProjectRoot(cwd);
+    if (projectRoot === null) return PASSTHROUGH;
+    if (isHookDisabled(projectRoot)) return PASSTHROUGH;
+    const toolName = payload.tool_name;
+    const filePath = extractFilePath(toolName, payload.tool_input);
+    const outputSize = estimateOutputSize(payload.tool_response);
+    const hasError = detectError(payload.tool_response);
+    logHookEvent(projectRoot, {
+      event: "PostToolUse",
+      tool: typeof toolName === "string" ? toolName : "unknown",
+      path: filePath,
+      outputSize,
+      success: !hasError
+    });
+  } catch {
+  }
+  return PASSTHROUGH;
+}
+
+// src/intercept/dispatch.ts
+function validatePayload(raw) {
+  if (raw === null || typeof raw !== "object") return null;
+  const p = raw;
+  if (typeof p.hook_event_name !== "string") return null;
+  if (typeof p.cwd !== "string") return null;
+  if (p.tool_input !== void 0 && (p.tool_input === null || typeof p.tool_input !== "object")) {
+    return null;
+  }
+  return p;
+}
+async function dispatchHook(rawPayload) {
+  const payload = validatePayload(rawPayload);
+  if (payload === null) return PASSTHROUGH;
+  const event = payload.hook_event_name;
+  switch (event) {
+    case "PreToolUse":
+      return dispatchPreToolUse(payload);
+    case "SessionStart":
+      return runHandler(
+        () => handleSessionStart(payload)
+      );
+    case "UserPromptSubmit":
+      return runHandler(
+        () => handleUserPromptSubmit(payload)
+      );
+    case "PostToolUse":
+      return runHandler(
+        () => handlePostTool(payload)
+      );
+    default:
+      return PASSTHROUGH;
+  }
+}
+async function dispatchPreToolUse(payload) {
+  const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
+  const handlerPayload = payload;
+  let result;
+  switch (tool) {
+    case "Read":
+      result = await runHandler(
+        () => handleRead(handlerPayload)
+      );
+      break;
+    case "Edit":
+    case "Write":
+      result = await runHandler(
+        () => handleEditOrWrite(handlerPayload)
+      );
+      break;
+    case "Bash":
+      result = await runHandler(
+        () => handleBash(handlerPayload)
+      );
+      break;
+    default:
+      return PASSTHROUGH;
+  }
+  try {
+    const cwd = handlerPayload.cwd;
+    if (isValidCwd(cwd)) {
+      const projectRoot = findProjectRoot(cwd);
+      if (projectRoot) {
+        const decision = extractPreToolDecision(result);
+        const filePath = typeof handlerPayload.tool_input?.file_path === "string" ? handlerPayload.tool_input.file_path : void 0;
+        logHookEvent(projectRoot, {
+          event: "PreToolUse",
+          tool,
+          path: filePath,
+          decision
+        });
+      }
+    }
+  } catch {
+  }
+  return result;
+}
+function extractPreToolDecision(result) {
+  if (result === null || result === void 0) return "passthrough";
+  try {
+    const r = result;
+    const d = r.hookSpecificOutput?.permissionDecision;
+    if (d === "deny") return "deny";
+    if (d === "allow") return "allow";
+  } catch {
+  }
+  return "passthrough";
+}
+
+// src/intercept/cursor-adapter.ts
+var ALLOW = { permission: "allow" };
+function toClaudeReadPayload(cursorPayload) {
+  const filePath = cursorPayload.file_path;
+  if (!filePath || typeof filePath !== "string") return null;
+  const workspaceRoot = Array.isArray(cursorPayload.workspace_roots) && cursorPayload.workspace_roots.length > 0 ? cursorPayload.workspace_roots[0] : process.cwd();
+  return {
+    tool_name: "Read",
+    tool_input: { file_path: filePath },
+    cwd: workspaceRoot
+  };
+}
+function extractSummaryFromClaudeResult(result) {
+  if (result === PASSTHROUGH || result === null) return null;
+  if (typeof result !== "object") return null;
+  const hookSpecific = result.hookSpecificOutput;
+  if (!hookSpecific || typeof hookSpecific !== "object") return null;
+  const reason = hookSpecific.permissionDecisionReason;
+  if (typeof reason !== "string" || reason.length === 0) return null;
+  return reason;
+}
+async function handleCursorBeforeReadFile(payload) {
+  try {
+    if (!payload || typeof payload !== "object") return ALLOW;
+    const claudePayload = toClaudeReadPayload(payload);
+    if (claudePayload === null) return ALLOW;
+    const result = await handleRead(claudePayload);
+    const summary = extractSummaryFromClaudeResult(result);
+    if (summary === null) return ALLOW;
+    return {
+      permission: "deny",
+      user_message: summary
+    };
+  } catch {
+    return ALLOW;
+  }
+}
+
+// src/intercept/installer.ts
+var ENGRAM_HOOK_EVENTS = [
+  "PreToolUse",
+  "PostToolUse",
+  "SessionStart",
+  "UserPromptSubmit"
+];
+var ENGRAM_PRETOOL_MATCHER = "Read|Edit|Write|Bash";
+var DEFAULT_ENGRAM_COMMAND = "engram intercept";
+var DEFAULT_HOOK_TIMEOUT_SEC = 5;
+function buildEngramHookEntries(command = DEFAULT_ENGRAM_COMMAND, timeout = DEFAULT_HOOK_TIMEOUT_SEC) {
+  const baseCmd = {
+    type: "command",
+    command,
+    timeout
+  };
+  return {
+    PreToolUse: {
+      matcher: ENGRAM_PRETOOL_MATCHER,
+      hooks: [baseCmd]
+    },
+    PostToolUse: {
+      // Match all tools — PostToolUse is an observer for any completion.
+      matcher: ".*",
+      hooks: [baseCmd]
+    },
+    SessionStart: {
+      // No matcher — SessionStart has no tool name.
+      hooks: [baseCmd]
+    },
+    UserPromptSubmit: {
+      // No matcher — UserPromptSubmit has no tool name.
+      hooks: [baseCmd]
+    }
+  };
+}
+function isEngramHookEntry(entry) {
+  if (entry === null || typeof entry !== "object") return false;
+  const e = entry;
+  if (!Array.isArray(e.hooks)) return false;
+  for (const h of e.hooks) {
+    if (h === null || typeof h !== "object") continue;
+    const cmd = h.command;
+    if (typeof cmd === "string" && cmd.includes("engram intercept")) {
+      return true;
+    }
+  }
+  return false;
+}
+function installEngramHooks(settings, command = DEFAULT_ENGRAM_COMMAND) {
+  const entries = buildEngramHookEntries(command);
+  const added = [];
+  const alreadyPresent = [];
+  const hooksClone = {};
+  const existingHooks = settings.hooks ?? {};
+  for (const [key, value] of Object.entries(existingHooks)) {
+    if (Array.isArray(value)) {
+      hooksClone[key] = value.map((entry) => ({ ...entry }));
+    }
+  }
+  for (const event of ENGRAM_HOOK_EVENTS) {
+    const eventArr = hooksClone[event] ?? [];
+    const hasEngram = eventArr.some((e) => isEngramHookEntry(e));
+    if (hasEngram) {
+      alreadyPresent.push(event);
+      hooksClone[event] = eventArr;
+      continue;
+    }
+    hooksClone[event] = [...eventArr, entries[event]];
+    added.push(event);
+  }
+  return {
+    updated: { ...settings, hooks: hooksClone },
+    added,
+    alreadyPresent
+  };
+}
+function uninstallEngramHooks(settings) {
+  const removed = [];
+  const existingHooks = settings.hooks ?? {};
+  const hooksClone = {};
+  for (const [event, arr] of Object.entries(existingHooks)) {
+    if (!Array.isArray(arr)) continue;
+    const filtered = arr.filter((entry) => !isEngramHookEntry(entry));
+    if (filtered.length !== arr.length && isKnownEngramEvent(event)) {
+      removed.push(event);
+    }
+    if (filtered.length > 0) {
+      hooksClone[event] = filtered;
+    }
+  }
+  const updatedSettings = { ...settings };
+  if (Object.keys(hooksClone).length === 0) {
+    delete updatedSettings.hooks;
+  } else {
+    updatedSettings.hooks = hooksClone;
+  }
+  return { updated: updatedSettings, removed };
+}
+function isKnownEngramEvent(event) {
+  return ENGRAM_HOOK_EVENTS.includes(event);
+}
+function formatInstallDiff(before, after) {
+  const lines = [];
+  const beforeHooks = before.hooks ?? {};
+  const afterHooks = after.hooks ?? {};
+  for (const event of ENGRAM_HOOK_EVENTS) {
+    const beforeArr = beforeHooks[event] ?? [];
+    const afterArr = afterHooks[event] ?? [];
+    if (beforeArr.length === afterArr.length) continue;
+    lines.push(`+ ${event}: ${beforeArr.length} \u2192 ${afterArr.length} entries`);
+    const added = afterArr.filter((entry) => isEngramHookEntry(entry));
+    const beforeHasEngram = beforeArr.some((entry) => isEngramHookEntry(entry));
+    if (!beforeHasEngram && added.length > 0) {
+      for (const entry of added) {
+        const matcher = entry.matcher ? ` matcher=${JSON.stringify(entry.matcher)}` : "";
+        const cmds = entry.hooks.map((h) => h.command).join(", ");
+        lines.push(`    + {${matcher} command="${cmds}"}`);
+      }
+    }
+  }
+  return lines.length > 0 ? lines.join("\n") : "(no changes)";
+}
+
+// src/intercept/stats.ts
+var ESTIMATED_TOKENS_PER_READ_DENY = 1200;
+function summarizeHookLog(entries) {
+  const byEvent = {};
+  const byTool = {};
+  const byDecision = {};
+  let readDenyCount = 0;
+  let firstEntryTs = null;
+  let lastEntryTs = null;
+  for (const entry of entries) {
+    const event = entry.event ?? "unknown";
+    byEvent[event] = (byEvent[event] ?? 0) + 1;
+    const tool = entry.tool ?? "unknown";
+    byTool[tool] = (byTool[tool] ?? 0) + 1;
+    if (entry.decision) {
+      byDecision[entry.decision] = (byDecision[entry.decision] ?? 0) + 1;
+    }
+    if (event === "PreToolUse" && tool === "Read" && entry.decision === "deny") {
+      readDenyCount += 1;
+    }
+    const ts = entry.ts;
+    if (typeof ts === "string") {
+      if (firstEntryTs === null || ts < firstEntryTs) firstEntryTs = ts;
+      if (lastEntryTs === null || ts > lastEntryTs) lastEntryTs = ts;
+    }
+  }
+  return {
+    totalInvocations: entries.length,
+    byEvent: Object.freeze(byEvent),
+    byTool: Object.freeze(byTool),
+    byDecision: Object.freeze(byDecision),
+    readDenyCount,
+    estimatedTokensSaved: readDenyCount * ESTIMATED_TOKENS_PER_READ_DENY,
+    firstEntry: firstEntryTs,
+    lastEntry: lastEntryTs
+  };
+}
+function formatStatsSummary(summary) {
+  if (summary.totalInvocations === 0) {
+    return "engram hook stats: no log entries yet.\n\nRun engram install-hook in a project, then use Claude Code to see interceptions.";
+  }
+  const lines = [];
+  lines.push(`engram hook stats (${summary.totalInvocations} invocations)`);
+  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  if (summary.firstEntry && summary.lastEntry) {
+    lines.push(`Time range: ${summary.firstEntry} \u2192 ${summary.lastEntry}`);
+    lines.push("");
+  }
+  lines.push("By event:");
+  const eventEntries = Object.entries(summary.byEvent).sort(
+    (a, b) => b[1] - a[1]
+  );
+  for (const [event, count] of eventEntries) {
+    const pct = (count / summary.totalInvocations * 100).toFixed(1);
+    lines.push(`  ${event.padEnd(18)} ${String(count).padStart(5)} (${pct}%)`);
+  }
+  lines.push("");
+  lines.push("By tool:");
+  const toolEntries = Object.entries(summary.byTool).filter(([k]) => k !== "unknown").sort((a, b) => b[1] - a[1]);
+  for (const [tool, count] of toolEntries) {
+    lines.push(`  ${tool.padEnd(18)} ${String(count).padStart(5)}`);
+  }
+  if (toolEntries.length === 0) {
+    lines.push("  (no tool-tagged entries)");
+  }
+  lines.push("");
+  const decisionEntries = Object.entries(summary.byDecision);
+  if (decisionEntries.length > 0) {
+    lines.push("PreToolUse decisions:");
+    for (const [decision, count] of decisionEntries.sort(
+      (a, b) => b[1] - a[1]
+    )) {
+      lines.push(`  ${decision.padEnd(18)} ${String(count).padStart(5)}`);
+    }
+    lines.push("");
+  }
+  if (summary.readDenyCount > 0) {
+    lines.push(
+      `Estimated tokens saved: ~${summary.estimatedTokensSaved.toLocaleString()}`
+    );
+    lines.push(
+      `  (${summary.readDenyCount} Read denies \xD7 ${ESTIMATED_TOKENS_PER_READ_DENY} tok/deny avg)`
+    );
+  } else {
+    lines.push("Estimated tokens saved: 0");
+    lines.push("  (no PreToolUse:Read denies recorded yet)");
+  }
+  return lines.join("\n");
+}
+
+// src/intercept/memory-md.ts
+import {
+  existsSync as existsSync5,
+  readFileSync as readFileSync3,
+  writeFileSync,
+  renameSync as renameSync2,
+  statSync as statSync3
+} from "fs";
+import { join as join5 } from "path";
+var ENGRAM_MARKER_START = "<!-- engram:structural-facts:start -->";
+var ENGRAM_MARKER_END = "<!-- engram:structural-facts:end -->";
+var MAX_MEMORY_FILE_BYTES = 1e6;
+var MAX_ENGRAM_SECTION_BYTES = 8e3;
+function buildEngramSection(facts) {
+  const lines = [];
+  lines.push("## engram \u2014 structural facts");
+  lines.push("");
+  lines.push(
+    `_Auto-maintained by engram. Do not edit inside the marker block \u2014 the next \`engram memory-sync\` overwrites it. This section complements Auto-Dream: Auto-Dream owns prose memory, engram owns the code graph._`
+  );
+  lines.push("");
+  lines.push(`**Project:** ${facts.projectName}`);
+  if (facts.branch) lines.push(`**Branch:** ${facts.branch}`);
+  lines.push(
+    `**Graph:** ${facts.stats.nodes} nodes, ${facts.stats.edges} edges, ${facts.stats.extractedPct}% extracted`
+  );
+  if (facts.lastMined > 0) {
+    lines.push(
+      `**Last mined:** ${new Date(facts.lastMined).toISOString()}`
+    );
+  }
+  lines.push("");
+  if (facts.godNodes.length > 0) {
+    lines.push("### Core entities");
+    for (const g of facts.godNodes.slice(0, 10)) {
+      lines.push(`- \`${g.label}\` [${g.kind}] \u2014 ${g.sourceFile}`);
+    }
+    lines.push("");
+  }
+  if (facts.landmines.length > 0) {
+    lines.push("### Known landmines");
+    for (const m of facts.landmines.slice(0, 5)) {
+      lines.push(`- **${m.sourceFile}** \u2014 ${m.label}`);
+    }
+    lines.push("");
+  }
+  lines.push(
+    '_For the full graph, run `engram query "..."` or `engram gods`._'
+  );
+  return lines.join("\n");
+}
+function upsertEngramSection(existingContent, engramSection) {
+  const block = `${ENGRAM_MARKER_START}
+${engramSection}
+${ENGRAM_MARKER_END}`;
+  if (!existingContent) {
+    return `# MEMORY.md
+
+${block}
+`;
+  }
+  const startIdx = existingContent.indexOf(ENGRAM_MARKER_START);
+  const endIdx = existingContent.indexOf(ENGRAM_MARKER_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+    const trimmed = existingContent.trimEnd();
+    return `${trimmed}
+
+${block}
+`;
+  }
+  const before = existingContent.slice(0, startIdx);
+  const after = existingContent.slice(endIdx + ENGRAM_MARKER_END.length);
+  return `${before}${block}${after}`;
+}
+function writeEngramSectionToMemoryMd(projectRoot, engramSection) {
+  if (!projectRoot || typeof projectRoot !== "string") return false;
+  if (engramSection.length > MAX_ENGRAM_SECTION_BYTES) {
+    return false;
+  }
+  const memoryPath = join5(projectRoot, "MEMORY.md");
+  try {
+    let existing = "";
+    if (existsSync5(memoryPath)) {
+      const st = statSync3(memoryPath);
+      if (st.size > MAX_MEMORY_FILE_BYTES) {
+        return false;
+      }
+      existing = readFileSync3(memoryPath, "utf-8");
+    }
+    const updated = upsertEngramSection(existing, engramSection);
+    const tmpPath = memoryPath + ".engram-tmp";
+    writeFileSync(tmpPath, updated);
+    renameSync2(tmpPath, memoryPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/cli.ts
+import { basename as basename2 } from "path";
 var program = new Command();
-program.name("engram").description("AI coding memory that learns from every session").version("0.2.1");
+program.name("engram").description(
+  "Context as infra for AI coding tools \u2014 hook-based Read/Edit interception + structural graph summaries"
+).version("0.3.0");
 program.command("init").description("Scan codebase and build knowledge graph (zero LLM cost)").argument("[path]", "Project directory", ".").option(
   "--with-skills [dir]",
   "Also index Claude Code skills from ~/.claude/skills/ or a given path"
@@ -174,4 +1398,438 @@ program.command("gen").description("Generate CLAUDE.md / .cursorrules section fr
     );
   }
 );
+function resolveSettingsPath(scope, projectPath) {
+  const absProject = pathResolve(projectPath);
+  switch (scope) {
+    case "local":
+      return join6(absProject, ".claude", "settings.local.json");
+    case "project":
+      return join6(absProject, ".claude", "settings.json");
+    case "user":
+      return join6(homedir(), ".claude", "settings.json");
+    default:
+      return null;
+  }
+}
+program.command("intercept").description(
+  "Hook entry point. Reads JSON from stdin, writes response JSON to stdout. Called by Claude Code."
+).action(async () => {
+  const stdinTimeout = setTimeout(() => {
+    process.exit(0);
+  }, 3e3);
+  let input = "";
+  try {
+    for await (const chunk of process.stdin) {
+      input += chunk;
+      if (input.length > 1e6) break;
+    }
+  } catch {
+    clearTimeout(stdinTimeout);
+    process.exit(0);
+  }
+  clearTimeout(stdinTimeout);
+  if (!input.trim()) process.exit(0);
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+  try {
+    const result = await dispatchHook(payload);
+    if (result && typeof result === "object") {
+      process.stdout.write(JSON.stringify(result));
+    }
+  } catch {
+  }
+  process.exit(0);
+});
+program.command("cursor-intercept").description(
+  "Cursor beforeReadFile hook entry point (experimental). Reads JSON from stdin, writes Cursor-shaped response JSON to stdout."
+).action(async () => {
+  const ALLOW_JSON = '{"permission":"allow"}';
+  const stdinTimeout = setTimeout(() => {
+    process.stdout.write(ALLOW_JSON);
+    process.exit(0);
+  }, 3e3);
+  let input = "";
+  try {
+    for await (const chunk of process.stdin) {
+      input += chunk;
+      if (input.length > 1e6) break;
+    }
+  } catch {
+    clearTimeout(stdinTimeout);
+    process.stdout.write(ALLOW_JSON);
+    process.exit(0);
+  }
+  clearTimeout(stdinTimeout);
+  if (!input.trim()) {
+    process.stdout.write(ALLOW_JSON);
+    process.exit(0);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(input);
+  } catch {
+    process.stdout.write(ALLOW_JSON);
+    process.exit(0);
+  }
+  try {
+    const result = await handleCursorBeforeReadFile(payload);
+    process.stdout.write(JSON.stringify(result));
+  } catch {
+    process.stdout.write(ALLOW_JSON);
+  }
+  process.exit(0);
+});
+program.command("install-hook").description("Install engram hook entries into Claude Code settings").option("--scope <scope>", "local | project | user", "local").option("--dry-run", "Show diff without writing", false).option("-p, --project <path>", "Project directory", ".").action(
+  async (opts) => {
+    const settingsPath = resolveSettingsPath(opts.scope, opts.project);
+    if (!settingsPath) {
+      console.error(
+        chalk.red(
+          `Unknown scope: ${opts.scope} (expected: local | project | user)`
+        )
+      );
+      process.exit(1);
+    }
+    let existing = {};
+    if (existsSync6(settingsPath)) {
+      try {
+        const raw = readFileSync4(settingsPath, "utf-8");
+        existing = raw.trim() ? JSON.parse(raw) : {};
+      } catch (err) {
+        console.error(
+          chalk.red(
+            `Failed to parse ${settingsPath}: ${err.message}`
+          )
+        );
+        console.error(
+          chalk.dim(
+            "Fix the JSON syntax and re-run install-hook, or remove the file and start fresh."
+          )
+        );
+        process.exit(1);
+      }
+    }
+    const result = installEngramHooks(existing);
+    console.log(
+      chalk.bold(`
+\u{1F4CC} engram install-hook (scope: ${opts.scope})`)
+    );
+    console.log(chalk.dim(`   Target: ${settingsPath}`));
+    if (result.added.length === 0) {
+      console.log(
+        chalk.yellow(
+          `
+   All engram hooks already installed (${result.alreadyPresent.join(", ")}).`
+        )
+      );
+      console.log(
+        chalk.dim(
+          "   Run 'engram uninstall-hook' first if you want to reinstall."
+        )
+      );
+      return;
+    }
+    console.log(chalk.cyan("\n   Changes:"));
+    console.log(
+      formatInstallDiff(existing, result.updated).split("\n").map((l) => "     " + l).join("\n")
+    );
+    if (opts.dryRun) {
+      console.log(chalk.dim("\n   (dry-run \u2014 no changes written)"));
+      return;
+    }
+    try {
+      mkdirSync(dirname3(settingsPath), { recursive: true });
+      if (existsSync6(settingsPath)) {
+        const backupPath = `${settingsPath}.engram-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.bak`;
+        copyFileSync(settingsPath, backupPath);
+        console.log(chalk.dim(`   Backup: ${backupPath}`));
+      }
+      const tmpPath = settingsPath + ".engram-tmp";
+      writeFileSync2(
+        tmpPath,
+        JSON.stringify(result.updated, null, 2) + "\n"
+      );
+      renameSync3(tmpPath, settingsPath);
+    } catch (err) {
+      console.error(
+        chalk.red(`
+   \u274C Write failed: ${err.message}`)
+      );
+      process.exit(1);
+    }
+    console.log(
+      chalk.green(
+        `
+   \u2705 Installed ${result.added.length} hook event${result.added.length === 1 ? "" : "s"}: ${result.added.join(", ")}`
+      )
+    );
+    if (result.alreadyPresent.length > 0) {
+      console.log(
+        chalk.dim(
+          `   Already present: ${result.alreadyPresent.join(", ")}`
+        )
+      );
+    }
+    console.log(
+      chalk.dim(
+        "\n   Next: open a Claude Code session and engram will start intercepting tool calls."
+      )
+    );
+  }
+);
+program.command("uninstall-hook").description("Remove engram hook entries from Claude Code settings").option("--scope <scope>", "local | project | user", "local").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
+  const settingsPath = resolveSettingsPath(opts.scope, opts.project);
+  if (!settingsPath) {
+    console.error(chalk.red(`Unknown scope: ${opts.scope}`));
+    process.exit(1);
+  }
+  if (!existsSync6(settingsPath)) {
+    console.log(
+      chalk.yellow(`No settings file at ${settingsPath} \u2014 nothing to remove.`)
+    );
+    return;
+  }
+  let existing;
+  try {
+    const raw = readFileSync4(settingsPath, "utf-8");
+    existing = raw.trim() ? JSON.parse(raw) : {};
+  } catch (err) {
+    console.error(
+      chalk.red(`Failed to parse ${settingsPath}: ${err.message}`)
+    );
+    process.exit(1);
+  }
+  const result = uninstallEngramHooks(existing);
+  if (result.removed.length === 0) {
+    console.log(
+      chalk.yellow(`
+   No engram hooks found in ${settingsPath}.`)
+    );
+    return;
+  }
+  try {
+    const backupPath = `${settingsPath}.engram-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.bak`;
+    copyFileSync(settingsPath, backupPath);
+    const tmpPath = settingsPath + ".engram-tmp";
+    writeFileSync2(tmpPath, JSON.stringify(result.updated, null, 2) + "\n");
+    renameSync3(tmpPath, settingsPath);
+    console.log(
+      chalk.green(
+        `
+   \u2705 Removed engram hooks from ${result.removed.length} event${result.removed.length === 1 ? "" : "s"}: ${result.removed.join(", ")}`
+      )
+    );
+    console.log(chalk.dim(`   Backup: ${backupPath}`));
+  } catch (err) {
+    console.error(
+      chalk.red(`
+   \u274C Write failed: ${err.message}`)
+    );
+    process.exit(1);
+  }
+});
+program.command("hook-stats").description("Summarize hook-log.jsonl for a project").option("-p, --project <path>", "Project directory", ".").option("--json", "Output as JSON", false).action(async (opts) => {
+  const absProject = pathResolve(opts.project);
+  const projectRoot = findProjectRoot(absProject) ?? absProject;
+  const entries = readHookLog(projectRoot);
+  const summary = summarizeHookLog(entries);
+  if (opts.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  console.log(formatStatsSummary(summary));
+});
+program.command("hook-preview").description("Show what the Read handler would do for a file (dry-run)").argument("<file>", "Target file path").option("-p, --project <path>", "Project directory", ".").action(async (file, opts) => {
+  const absProject = pathResolve(opts.project);
+  const absFile = pathResolve(absProject, file);
+  const payload = {
+    hook_event_name: "PreToolUse",
+    tool_name: "Read",
+    cwd: absProject,
+    tool_input: { file_path: absFile }
+  };
+  const result = await dispatchHook(payload);
+  console.log(chalk.bold(`
+\u{1F4CB} Hook preview: ${absFile}`));
+  console.log(chalk.dim(`   Project: ${absProject}`));
+  console.log();
+  if (result === null || result === void 0) {
+    console.log(
+      chalk.yellow("   Decision: PASSTHROUGH (Read would execute normally)")
+    );
+    console.log(
+      chalk.dim(
+        "   Possible reasons: file not in graph, confidence below threshold, content unsafe, outside project, stale graph."
+      )
+    );
+    return;
+  }
+  const wrapped = result;
+  const decision = wrapped.hookSpecificOutput?.permissionDecision;
+  if (decision === "deny") {
+    console.log(chalk.green("   Decision: DENY (Read would be replaced)"));
+    console.log(chalk.dim("   Summary (would be delivered to Claude):"));
+    console.log();
+    const reason = wrapped.hookSpecificOutput?.permissionDecisionReason ?? "";
+    console.log(
+      reason.split("\n").map((l) => "     " + l).join("\n")
+    );
+    return;
+  }
+  if (decision === "allow") {
+    console.log(chalk.cyan("   Decision: ALLOW (with additionalContext)"));
+    const ctx = wrapped.hookSpecificOutput?.additionalContext ?? "";
+    if (ctx) {
+      console.log(chalk.dim("   Additional context that would be injected:"));
+      console.log(
+        ctx.split("\n").map((l) => "     " + l).join("\n")
+      );
+    }
+    return;
+  }
+  console.log(chalk.yellow(`   Decision: ${decision ?? "unknown"}`));
+});
+program.command("hook-disable").description("Disable engram hooks via kill switch (does not uninstall)").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
+  const absProject = pathResolve(opts.project);
+  const projectRoot = findProjectRoot(absProject);
+  if (!projectRoot) {
+    console.error(
+      chalk.red(`Not an engram project: ${absProject}`)
+    );
+    console.error(chalk.dim("Run 'engram init' first."));
+    process.exit(1);
+  }
+  const flagPath = join6(projectRoot, ".engram", "hook-disabled");
+  try {
+    writeFileSync2(flagPath, (/* @__PURE__ */ new Date()).toISOString());
+    console.log(
+      chalk.green(`\u2705 engram hooks disabled for ${projectRoot}`)
+    );
+    console.log(chalk.dim(`   Flag: ${flagPath}`));
+    console.log(
+      chalk.dim("   Run 'engram hook-enable' to re-enable.")
+    );
+  } catch (err) {
+    console.error(
+      chalk.red(`Failed to create flag: ${err.message}`)
+    );
+    process.exit(1);
+  }
+});
+program.command("hook-enable").description("Re-enable engram hooks (remove kill switch flag)").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
+  const absProject = pathResolve(opts.project);
+  const projectRoot = findProjectRoot(absProject);
+  if (!projectRoot) {
+    console.error(chalk.red(`Not an engram project: ${absProject}`));
+    process.exit(1);
+  }
+  const flagPath = join6(projectRoot, ".engram", "hook-disabled");
+  if (!existsSync6(flagPath)) {
+    console.log(
+      chalk.yellow(`engram hooks already enabled for ${projectRoot}`)
+    );
+    return;
+  }
+  try {
+    unlinkSync(flagPath);
+    console.log(
+      chalk.green(`\u2705 engram hooks re-enabled for ${projectRoot}`)
+    );
+  } catch (err) {
+    console.error(
+      chalk.red(`Failed to remove flag: ${err.message}`)
+    );
+    process.exit(1);
+  }
+});
+program.command("memory-sync").description(
+  "Write engram's structural facts into MEMORY.md (complementary to Anthropic Auto-Dream)"
+).option("-p, --project <path>", "Project directory", ".").option("--dry-run", "Print what would be written without writing", false).action(
+  async (opts) => {
+    const absProject = pathResolve(opts.project);
+    const projectRoot = findProjectRoot(absProject);
+    if (!projectRoot) {
+      console.error(
+        chalk.red(`Not an engram project: ${absProject}`)
+      );
+      console.error(chalk.dim("Run 'engram init' first."));
+      process.exit(1);
+    }
+    const [gods, mistakeList, graphStats] = await Promise.all([
+      godNodes(projectRoot, 10).catch(() => []),
+      mistakes(projectRoot, { limit: 5 }).catch(() => []),
+      stats(projectRoot).catch(() => null)
+    ]);
+    if (!graphStats) {
+      console.error(chalk.red("Failed to read graph stats."));
+      process.exit(1);
+    }
+    let branch = null;
+    try {
+      const headPath = join6(projectRoot, ".git", "HEAD");
+      if (existsSync6(headPath)) {
+        const content = readFileSync4(headPath, "utf-8").trim();
+        const m = content.match(/^ref:\s+refs\/heads\/(.+)$/);
+        if (m) branch = m[1];
+      }
+    } catch {
+    }
+    const section = buildEngramSection({
+      projectName: basename2(projectRoot),
+      branch,
+      stats: {
+        nodes: graphStats.nodes,
+        edges: graphStats.edges,
+        extractedPct: graphStats.extractedPct
+      },
+      godNodes: gods,
+      landmines: mistakeList.map((m) => ({
+        label: m.label,
+        sourceFile: m.sourceFile
+      })),
+      lastMined: graphStats.lastMined
+    });
+    console.log(
+      chalk.bold(`
+\u{1F4DD} engram memory-sync`)
+    );
+    console.log(
+      chalk.dim(`   Target: ${join6(projectRoot, "MEMORY.md")}`)
+    );
+    if (opts.dryRun) {
+      console.log(chalk.cyan("\n   Section to write (dry-run):\n"));
+      console.log(
+        section.split("\n").map((l) => "     " + l).join("\n")
+      );
+      console.log(chalk.dim("\n   (dry-run \u2014 no changes written)"));
+      return;
+    }
+    const ok = writeEngramSectionToMemoryMd(projectRoot, section);
+    if (!ok) {
+      console.error(
+        chalk.red(
+          "\n   \u274C Write failed. MEMORY.md may be too large, or the engram section exceeded its size cap."
+        )
+      );
+      process.exit(1);
+    }
+    console.log(
+      chalk.green(
+        `
+   \u2705 Synced ${gods.length} god nodes${mistakeList.length > 0 ? ` and ${mistakeList.length} landmines` : ""} to MEMORY.md`
+      )
+    );
+    console.log(
+      chalk.dim(
+        `
+   Next: Anthropic's Auto-Dream will consolidate this alongside its prose entries.
+`
+      )
+    );
+  }
+);
 program.parse();