engramx 0.3.1 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@
   <a href="https://github.com/NickCirv/engram/actions"><img src="https://github.com/NickCirv/engram/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node">
-  <img src="https://img.shields.io/badge/tests-439%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-486%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/LLM%20cost-$0-green" alt="Zero LLM cost">
   <img src="https://img.shields.io/badge/native%20deps-zero-green" alt="Zero native deps">
   <img src="https://img.shields.io/badge/token%20reduction-82%25-orange" alt="82% token reduction">
@@ -110,6 +110,37 @@ engram hook-enable             # re-enable
 engram uninstall-hook          # surgical removal, preserves other hooks
 ```
 
+## Experience Tiers
+
+Each tier builds on the previous. You can stop at any level — each one works standalone.
+
+| Tier | What you run | What you get | Token savings |
+|---|---|---|---|
+| **1. Graph only** | `engram init` | CLI queries, MCP server, `engram gen` for CLAUDE.md | ~6x per query vs reading files |
+| **2. + Sentinel hooks** | `engram install-hook` | Automatic Read interception, Edit landmine warnings, session-start briefs, prompt pre-query | ~82% per session (measured) |
+| **3. + Skills index** | `engram init --with-skills` | Graph includes your `~/.claude/skills/` — queries surface relevant skills alongside code | ~23% overhead on graph size |
+| **4. + Git hooks** | `engram hooks install` | Auto-rebuild graph on every `git commit` — graph never goes stale | Zero token cost |
+
+**Recommended full setup** (one-time, per project):
+
+```bash
+npm install -g engramx         # install globally
+cd ~/my-project
+engram init --with-skills      # build graph + index skills
+engram install-hook            # wire Sentinel into Claude Code
+engram hooks install           # auto-rebuild on commit
+```
+
+After this, every Claude Code session in the project automatically gets structural context, landmine warnings, and session briefs — with no manual queries needed.
+
+**Optional — MEMORY.md integration** (v0.3.1+):
+
+```bash
+engram gen --memory-md         # write structural facts into Claude's native MEMORY.md
+```
+
+This writes a marker-bounded block into `~/.claude/projects/.../memory/MEMORY.md` with your project's core entities and structure. Claude's Auto-Dream owns the prose; engram owns the structure. They complement each other — engram never touches content outside its markers.
+
 ## All Commands
 
 ### Core (v0.1/v0.2 — unchanged)

package/dist/{chunk-IYO4HETA.js → chunk-ESPAWLH6.js}

@@ -310,7 +310,7 @@ function writeToFile(filePath, summary) {
   writeFileSync2(filePath, newContent);
 }
 async function autogen(projectRoot, target, task) {
-  const { getStore } = await import("./core-2TWPNHRQ.js");
+  const { getStore } = await import("./core-WTKXDUDO.js");
   const store = await getStore(projectRoot);
   try {
     let view = VIEWS.general;

package/dist/{chunk-RGDHLGWQ.js → chunk-R46DNLNR.js}

@@ -65,7 +65,8 @@ var GraphStore = class _GraphStore {
       "CREATE INDEX IF NOT EXISTS idx_nodes_source_file ON nodes(source_file)",
       "CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source)",
       "CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target)",
-      "CREATE INDEX IF NOT EXISTS idx_edges_relation ON edges(relation)"
+      "CREATE INDEX IF NOT EXISTS idx_edges_relation ON edges(relation)",
+      "CREATE INDEX IF NOT EXISTS idx_edges_source_file ON edges(source_file)"
     ];
     for (const sql of indexes) {
       try {
@@ -113,6 +114,22 @@ var GraphStore = class _GraphStore {
       ]
     );
   }
+  /**
+   * Remove all nodes and edges associated with a specific source file.
+   * Used by the file watcher for incremental re-indexing — old nodes for
+   * a changed file are cleared before re-extracting.
+   */
+  deleteBySourceFile(sourceFile) {
+    this.db.run("BEGIN TRANSACTION");
+    try {
+      this.db.run("DELETE FROM edges WHERE source_file = ?", [sourceFile]);
+      this.db.run("DELETE FROM nodes WHERE source_file = ?", [sourceFile]);
+      this.db.run("COMMIT");
+    } catch (e) {
+      this.db.run("ROLLBACK");
+      throw e;
+    }
+  }
   bulkUpsert(nodes, edges) {
     this.db.run("BEGIN TRANSACTION");
     for (const node of nodes) this.upsertNode(node);
@@ -627,6 +644,12 @@ function renderFileStructure(store, relativeFilePath, tokenBudget = 600) {
   };
 }
 
+// src/graph/path-utils.ts
+function toPosixPath(p) {
+  if (!p) return p;
+  return p.replace(/\\/g, "/");
+}
+
 // src/miners/ast-miner.ts
 import { readFileSync as readFileSync2, readdirSync, realpathSync } from "fs";
 import { basename, extname, join, relative } from "path";
@@ -716,7 +739,7 @@ function extractFile(filePath, rootDir) {
   if (!lang) return { nodes: [], edges: [] };
   const content = readFileSync2(filePath, "utf-8");
   const lines = content.split("\n");
-  const relPath = relative(rootDir, filePath);
+  const relPath = toPosixPath(relative(rootDir, filePath));
   const stem = basename(filePath, ext);
   const now = Date.now();
   const nodes = [];
@@ -1230,7 +1253,7 @@ function parseFrontmatter(content) {
 }
 function parseYaml(block) {
   const data = {};
-  const lines = block.split("\n");
+  const lines = block.replace(/\r/g, "").split("\n");
   let i = 0;
   while (i < lines.length) {
     const line = lines[i];
@@ -1606,7 +1629,7 @@ async function getFileContext(projectRoot, absFilePath) {
   try {
     const root = resolve2(projectRoot);
     const abs = resolve2(absFilePath);
-    const relPath = relative2(root, abs);
+    const relPath = toPosixPath(relative2(root, abs));
     if (relPath.startsWith("..") || relPath === "") {
       return empty;
     }
@@ -1801,6 +1824,7 @@ export {
   MAX_MISTAKE_LABEL_CHARS,
   queryGraph,
   shortestPath,
+  toPosixPath,
   SUPPORTED_EXTENSIONS,
   extractFile,
   extractDirectory,

package/dist/cli.js

@@ -4,25 +4,29 @@ import {
   install,
   status,
   uninstall
-} from "./chunk-IYO4HETA.js";
+} from "./chunk-ESPAWLH6.js";
 import {
   benchmark,
   computeKeywordIDF,
+  extractFile,
+  getDbPath,
   getFileContext,
+  getStore,
   godNodes,
   init,
   learn,
   mistakes,
   path,
   query,
-  stats
-} from "./chunk-RGDHLGWQ.js";
+  stats,
+  toPosixPath
+} from "./chunk-R46DNLNR.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import chalk from "chalk";
 import {
-  existsSync as existsSync6,
+  existsSync as existsSync7,
   readFileSync as readFileSync4,
   writeFileSync as writeFileSync2,
   mkdirSync,
@@ -30,7 +34,7 @@ import {
   copyFileSync,
   renameSync as renameSync3
 } from "fs";
-import { dirname as dirname3, join as join6, resolve as pathResolve } from "path";
+import { dirname as dirname3, join as join7, resolve as pathResolve } from "path";
 import { homedir } from "os";
 
 // src/intercept/safety.ts
@@ -40,8 +44,8 @@ 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);
+  const timeout = new Promise((resolve6) => {
+    timer = setTimeout(() => resolve6(PASSTHROUGH), ms);
   });
   try {
     return await Promise.race([promise, timeout]);
@@ -104,6 +108,10 @@ function isHardSystemPath(absPath) {
   const p = absPath.replaceAll(sep, "/");
   if (p === "/" || p.startsWith("/dev/") || p.startsWith("/proc/")) return true;
   if (p.startsWith("/sys/")) return true;
+  const upper = p.toUpperCase();
+  if (upper.startsWith("//./") || upper.startsWith("//?/")) return true;
+  if (/^[A-Z]:\/WINDOWS(\/|$)/.test(upper)) return true;
+  if (/^[A-Z]:\/(PROGRAM FILES|PROGRAMDATA)(\/|$)/.test(upper)) return true;
   return false;
 }
 var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -257,6 +265,9 @@ function isValidCwd(cwd) {
 }
 function resolveInterceptContext(filePath, cwd) {
   if (!filePath) return { proceed: false, reason: "empty-path" };
+  if (isHardSystemPath(filePath)) {
+    return { proceed: false, reason: "system-path" };
+  }
   const absPath = normalizePath(filePath, cwd);
   if (!absPath) return { proceed: false, reason: "normalize-failed" };
   if (isHardSystemPath(absPath)) {
@@ -371,7 +382,9 @@ async function handleEditOrWrite(payload) {
   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);
+  const relPath = toPosixPath(
+    relative(resolvePath(ctx.projectRoot), ctx.absPath)
+  );
   if (!relPath || relPath.startsWith("..")) return PASSTHROUGH;
   let found;
   try {
@@ -430,7 +443,10 @@ async function handleBash(payload) {
 
 // src/intercept/handlers/session-start.ts
 import { existsSync as existsSync3, readFileSync } from "fs";
+import { execFile } from "child_process";
+import { promisify } from "util";
 import { basename, dirname as dirname2, join as join3, resolve as resolve2 } from "path";
+var execFileAsync = promisify(execFile);
 var MAX_GOD_NODES = 10;
 var MAX_LANDMINES_IN_BRIEF = 3;
 function readGitBranch(projectRoot) {
@@ -484,6 +500,37 @@ function formatBrief(args) {
   );
   return lines.join("\n");
 }
+async function queryMempalace(projectName) {
+  try {
+    const { stdout } = await execFileAsync(
+      "mcp-mempalace",
+      ["mempalace-search", "--query", projectName],
+      { timeout: 1500, encoding: "utf-8" }
+    );
+    const trimmed = stdout.trim();
+    if (!trimmed || trimmed.length < 20) return null;
+    try {
+      const parsed = JSON.parse(trimmed);
+      const results = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.results) ? parsed.results : [];
+      if (results.length === 0) return null;
+      const lines = ["[mempalace] Recent context:"];
+      for (const r of results.slice(0, 3)) {
+        const content = typeof r === "string" ? r : typeof r?.content === "string" ? r.content : typeof r?.document === "string" ? r.document : null;
+        if (content) {
+          const short = content.length > 120 ? content.slice(0, 117) + "..." : content;
+          lines.push(`  - ${short}`);
+        }
+      }
+      return lines.length > 1 ? lines.join("\n") : null;
+    } catch {
+      const maxLen = 400;
+      const capped = trimmed.length > maxLen ? trimmed.slice(0, maxLen - 3) + "..." : trimmed;
+      return `[mempalace] ${capped}`;
+    }
+  } catch {
+    return null;
+  }
+}
 function describeAgo(ms) {
   if (ms < 0) return "just now";
   const s = Math.floor(ms / 1e3);
@@ -505,7 +552,9 @@ async function handleSessionStart(payload) {
   if (projectRoot === null) return PASSTHROUGH;
   if (isHookDisabled(projectRoot)) return PASSTHROUGH;
   try {
-    const [gods, mistakeList, graphStats] = await Promise.all([
+    const branch = readGitBranch(projectRoot);
+    const projectName = basename(projectRoot);
+    const [gods, mistakeList, graphStats, mempalaceContext] = await Promise.all([
       godNodes(projectRoot, MAX_GOD_NODES).catch(() => []),
       mistakes(projectRoot, { limit: MAX_LANDMINES_IN_BRIEF }).catch(
         () => []
@@ -519,11 +568,10 @@ async function handleSessionStart(payload) {
         ambiguousPct: 0,
         lastMined: 0,
         totalQueryTokensSaved: 0
-      }))
+      })),
+      queryMempalace(projectName)
     ]);
     if (graphStats.nodes === 0 && gods.length === 0) return PASSTHROUGH;
-    const branch = readGitBranch(projectRoot);
-    const projectName = basename(projectRoot);
     const text = formatBrief({
       projectName,
       branch,
@@ -539,7 +587,8 @@ async function handleSessionStart(payload) {
         sourceFile: m.sourceFile
       }))
     });
-    return buildSessionContextResponse("SessionStart", text);
+    const fullText = mempalaceContext ? text + "\n\n" + mempalaceContext : text;
+    return buildSessionContextResponse("SessionStart", fullText);
   } catch {
     return PASSTHROUGH;
   }
@@ -799,6 +848,123 @@ async function handlePostTool(payload) {
   return PASSTHROUGH;
 }
 
+// src/intercept/handlers/pre-compact.ts
+import { basename as basename2, resolve as resolve3 } from "path";
+var MAX_GOD_NODES_COMPACT = 5;
+var MAX_LANDMINES_COMPACT = 3;
+function formatCompactBrief(args) {
+  const lines = [];
+  lines.push(
+    `[engram] Compaction survival \u2014 ${args.projectName} (${args.nodeCount} nodes, ${args.edgeCount} edges)`
+  );
+  if (args.godNodes.length > 0) {
+    lines.push("Key entities:");
+    for (const g of args.godNodes) {
+      lines.push(`  - ${g.label} [${g.kind}] \u2014 ${g.sourceFile}`);
+    }
+  }
+  if (args.landmines.length > 0) {
+    lines.push("Active landmines:");
+    for (const m of args.landmines) {
+      lines.push(`  - ${m.sourceFile}: ${m.label}`);
+    }
+  }
+  lines.push(
+    "engram is active \u2014 Read/Edit/Write interception continues after compaction."
+  );
+  return lines.join("\n");
+}
+async function handlePreCompact(payload) {
+  if (payload.hook_event_name !== "PreCompact") 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_COMPACT).catch(() => []),
+      mistakes(projectRoot, { limit: MAX_LANDMINES_COMPACT }).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 projectName = basename2(resolve3(projectRoot));
+    const text = formatCompactBrief({
+      projectName,
+      nodeCount: graphStats.nodes,
+      edgeCount: graphStats.edges,
+      godNodes: gods.map((g) => ({
+        label: g.label,
+        kind: g.kind,
+        sourceFile: g.sourceFile
+      })),
+      landmines: mistakeList.map((m) => ({
+        label: m.label,
+        sourceFile: m.sourceFile
+      }))
+    });
+    return buildSessionContextResponse("SessionStart", text);
+  } catch {
+    return PASSTHROUGH;
+  }
+}
+
+// src/intercept/handlers/cwd-changed.ts
+import { basename as basename3, resolve as resolve4 } from "path";
+var MAX_GOD_NODES_SWITCH = 5;
+async function handleCwdChanged(payload) {
+  if (payload.hook_event_name !== "CwdChanged") 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, graphStats] = await Promise.all([
+      godNodes(projectRoot, MAX_GOD_NODES_SWITCH).catch(() => []),
+      stats(projectRoot).catch(() => ({
+        nodes: 0,
+        edges: 0,
+        communities: 0,
+        extractedPct: 0,
+        inferredPct: 0,
+        ambiguousPct: 0,
+        lastMined: 0,
+        totalQueryTokensSaved: 0
+      }))
+    ]);
+    if (graphStats.nodes === 0) return PASSTHROUGH;
+    const projectName = basename3(resolve4(projectRoot));
+    const lines = [];
+    lines.push(
+      `[engram] Project switched to ${projectName} (${graphStats.nodes} nodes, ${graphStats.edges} edges)`
+    );
+    if (gods.length > 0) {
+      lines.push("Core entities:");
+      for (const g of gods.slice(0, MAX_GOD_NODES_SWITCH)) {
+        lines.push(`  - ${g.label} [${g.kind}] \u2014 ${g.sourceFile}`);
+      }
+    }
+    lines.push(
+      "engram interception is active for this project."
+    );
+    return buildSessionContextResponse("SessionStart", lines.join("\n"));
+  } catch {
+    return PASSTHROUGH;
+  }
+}
+
 // src/intercept/dispatch.ts
 function validatePayload(raw) {
   if (raw === null || typeof raw !== "object") return null;
@@ -829,6 +995,14 @@ async function dispatchHook(rawPayload) {
       return runHandler(
         () => handlePostTool(payload)
       );
+    case "PreCompact":
+      return runHandler(
+        () => handlePreCompact(payload)
+      );
+    case "CwdChanged":
+      return runHandler(
+        () => handleCwdChanged(payload)
+      );
     default:
       return PASSTHROUGH;
   }
@@ -888,6 +1062,106 @@ function extractPreToolDecision(result) {
   return "passthrough";
 }
 
+// src/watcher.ts
+import { watch, existsSync as existsSync5, statSync as statSync3 } from "fs";
+import { resolve as resolve5, relative as relative2, extname } from "path";
+var WATCHABLE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".c",
+  ".cpp",
+  ".cs",
+  ".rb"
+]);
+var IGNORED_DIRS = /* @__PURE__ */ new Set([
+  ".engram",
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "__pycache__",
+  ".venv",
+  "target",
+  "vendor"
+]);
+var DEBOUNCE_MS = 300;
+function shouldIgnore(relPath) {
+  const parts = relPath.split(/[/\\]/);
+  return parts.some((p) => IGNORED_DIRS.has(p));
+}
+async function reindexFile(absPath, projectRoot) {
+  const ext = extname(absPath).toLowerCase();
+  if (!WATCHABLE_EXTENSIONS.has(ext)) return 0;
+  if (!existsSync5(absPath)) return 0;
+  try {
+    if (statSync3(absPath).isDirectory()) return 0;
+  } catch {
+    return 0;
+  }
+  const relPath = toPosixPath(relative2(projectRoot, absPath));
+  if (shouldIgnore(relPath)) return 0;
+  const store = await getStore(projectRoot);
+  try {
+    store.deleteBySourceFile(relPath);
+    const { nodes, edges } = extractFile(absPath, projectRoot);
+    if (nodes.length > 0 || edges.length > 0) {
+      store.bulkUpsert(nodes, edges);
+    }
+    return nodes.length;
+  } finally {
+    store.close();
+  }
+}
+function watchProject(projectRoot, options = {}) {
+  const root = resolve5(projectRoot);
+  const controller = new AbortController();
+  if (!existsSync5(getDbPath(root))) {
+    throw new Error(
+      `engram: no graph found at ${root}. Run 'engram init' first.`
+    );
+  }
+  const debounceTimers = /* @__PURE__ */ new Map();
+  const watcher = watch(root, { recursive: true, signal: controller.signal });
+  watcher.on("change", (_eventType, filename) => {
+    if (typeof filename !== "string") return;
+    const absPath = resolve5(root, filename);
+    const relPath = toPosixPath(relative2(root, absPath));
+    if (shouldIgnore(relPath)) return;
+    const ext = extname(filename).toLowerCase();
+    if (!WATCHABLE_EXTENSIONS.has(ext)) return;
+    const existing = debounceTimers.get(absPath);
+    if (existing) clearTimeout(existing);
+    debounceTimers.set(
+      absPath,
+      setTimeout(async () => {
+        debounceTimers.delete(absPath);
+        try {
+          const count = await reindexFile(absPath, root);
+          if (count > 0) {
+            options.onReindex?.(relPath, count);
+          }
+        } catch (err) {
+          options.onError?.(
+            err instanceof Error ? err : new Error(String(err))
+          );
+        }
+      }, DEBOUNCE_MS)
+    );
+  });
+  watcher.on("error", (err) => {
+    options.onError?.(err instanceof Error ? err : new Error(String(err)));
+  });
+  options.onReady?.();
+  return controller;
+}
+
 // src/intercept/cursor-adapter.ts
 var ALLOW = { permission: "allow" };
 function toClaudeReadPayload(cursorPayload) {
@@ -931,7 +1205,9 @@ var ENGRAM_HOOK_EVENTS = [
   "PreToolUse",
   "PostToolUse",
   "SessionStart",
-  "UserPromptSubmit"
+  "UserPromptSubmit",
+  "PreCompact",
+  "CwdChanged"
 ];
 var ENGRAM_PRETOOL_MATCHER = "Read|Edit|Write|Bash";
 var DEFAULT_ENGRAM_COMMAND = "engram intercept";
@@ -959,6 +1235,14 @@ function buildEngramHookEntries(command = DEFAULT_ENGRAM_COMMAND, timeout = DEFA
     UserPromptSubmit: {
       // No matcher — UserPromptSubmit has no tool name.
       hooks: [baseCmd]
+    },
+    PreCompact: {
+      // No matcher — PreCompact has no tool name.
+      hooks: [baseCmd]
+    },
+    CwdChanged: {
+      // No matcher — CwdChanged has no tool name.
+      hooks: [baseCmd]
     }
   };
 }
@@ -1142,13 +1426,13 @@ function formatStatsSummary(summary) {
 
 // src/intercept/memory-md.ts
 import {
-  existsSync as existsSync5,
+  existsSync as existsSync6,
   readFileSync as readFileSync3,
   writeFileSync,
   renameSync as renameSync2,
-  statSync as statSync3
+  statSync as statSync4
 } from "fs";
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 var ENGRAM_MARKER_START = "<!-- engram:structural-facts:start -->";
 var ENGRAM_MARKER_END = "<!-- engram:structural-facts:end -->";
 var MAX_MEMORY_FILE_BYTES = 1e6;
@@ -1219,11 +1503,11 @@ function writeEngramSectionToMemoryMd(projectRoot, engramSection) {
   if (engramSection.length > MAX_ENGRAM_SECTION_BYTES) {
     return false;
   }
-  const memoryPath = join5(projectRoot, "MEMORY.md");
+  const memoryPath = join6(projectRoot, "MEMORY.md");
   try {
     let existing = "";
-    if (existsSync5(memoryPath)) {
-      const st = statSync3(memoryPath);
+    if (existsSync6(memoryPath)) {
+      const st = statSync4(memoryPath);
       if (st.size > MAX_MEMORY_FILE_BYTES) {
         return false;
       }
@@ -1240,7 +1524,7 @@ function writeEngramSectionToMemoryMd(projectRoot, engramSection) {
 }
 
 // src/cli.ts
-import { basename as basename2 } from "path";
+import { basename as basename4 } from "path";
 var program = new Command();
 program.name("engram").description(
   "Context as infra for AI coding tools \u2014 hook-based Read/Edit interception + structural graph summaries"
@@ -1276,6 +1560,48 @@ program.command("init").description("Scan codebase and build knowledge graph (ze
   }
   console.log(chalk.green("\n\u2705 Ready. Your AI now has persistent memory."));
   console.log(chalk.dim("   Graph stored in .engram/graph.db"));
+  const resolvedProject = pathResolve(projectPath);
+  const localSettings = join7(resolvedProject, ".claude", "settings.local.json");
+  const projectSettings = join7(resolvedProject, ".claude", "settings.json");
+  const hasHooks = existsSync7(localSettings) && readFileSync4(localSettings, "utf-8").includes("engram intercept") || existsSync7(projectSettings) && readFileSync4(projectSettings, "utf-8").includes("engram intercept");
+  if (!hasHooks) {
+    console.log(
+      chalk.yellow("\n\u{1F4A1} Next step: ") + chalk.white("engram install-hook") + chalk.dim(
+        " \u2014 enables automatic Read interception (82% token savings)"
+      )
+    );
+    console.log(
+      chalk.dim(
+        "   Also recommended: " + chalk.white("engram hooks install") + " \u2014 auto-rebuild graph on git commit"
+      )
+    );
+  }
+});
+program.command("watch").description("Watch project for file changes and re-index incrementally").argument("[path]", "Project directory", ".").action(async (projectPath) => {
+  const resolvedPath = pathResolve(projectPath);
+  console.log(
+    chalk.dim("\u{1F441}  Watching ") + chalk.white(resolvedPath) + chalk.dim(" for changes...")
+  );
+  const controller = watchProject(resolvedPath, {
+    onReindex: (filePath, nodeCount) => {
+      console.log(
+        chalk.green("  \u21BB ") + chalk.white(filePath) + chalk.dim(` (${nodeCount} nodes)`)
+      );
+    },
+    onError: (err) => {
+      console.error(chalk.red("  \u2717 ") + err.message);
+    },
+    onReady: () => {
+      console.log(chalk.green("  \u2713 Watcher active.") + chalk.dim(" Press Ctrl+C to stop."));
+    }
+  });
+  process.on("SIGINT", () => {
+    controller.abort();
+    console.log(chalk.dim("\n  Watcher stopped."));
+    process.exit(0);
+  });
+  await new Promise(() => {
+  });
 });
 program.command("query").description("Query the knowledge graph").argument("<question>", "Natural language question or keywords").option("--dfs", "Use DFS traversal", false).option("-d, --depth <n>", "Traversal depth", "3").option("-b, --budget <n>", "Token budget", "2000").option("-p, --project <path>", "Project directory", ".").action(async (question, opts) => {
   const result = await query(opts.project, question, {
@@ -1402,11 +1728,11 @@ function resolveSettingsPath(scope, projectPath) {
   const absProject = pathResolve(projectPath);
   switch (scope) {
     case "local":
-      return join6(absProject, ".claude", "settings.local.json");
+      return join7(absProject, ".claude", "settings.local.json");
     case "project":
-      return join6(absProject, ".claude", "settings.json");
+      return join7(absProject, ".claude", "settings.json");
     case "user":
-      return join6(homedir(), ".claude", "settings.json");
+      return join7(homedir(), ".claude", "settings.json");
     default:
       return null;
   }
@@ -1417,23 +1743,28 @@ program.command("intercept").description(
   const stdinTimeout = setTimeout(() => {
     process.exit(0);
   }, 3e3);
+  stdinTimeout.unref();
   let input = "";
+  let stdinFailed = false;
   try {
     for await (const chunk of process.stdin) {
       input += chunk;
       if (input.length > 1e6) break;
     }
   } catch {
-    clearTimeout(stdinTimeout);
-    process.exit(0);
+    stdinFailed = true;
   }
   clearTimeout(stdinTimeout);
-  if (!input.trim()) process.exit(0);
+  if (stdinFailed || !input.trim()) {
+    process.exitCode = 0;
+    return;
+  }
   let payload;
   try {
     payload = JSON.parse(input);
   } catch {
-    process.exit(0);
+    process.exitCode = 0;
+    return;
   }
   try {
     const result = await dispatchHook(payload);
@@ -1442,7 +1773,7 @@ program.command("intercept").description(
     }
   } catch {
   }
-  process.exit(0);
+  process.exitCode = 0;
 });
 program.command("cursor-intercept").description(
   "Cursor beforeReadFile hook entry point (experimental). Reads JSON from stdin, writes Cursor-shaped response JSON to stdout."
@@ -1495,7 +1826,7 @@ program.command("install-hook").description("Install engram hook entries into Cl
       process.exit(1);
     }
     let existing = {};
-    if (existsSync6(settingsPath)) {
+    if (existsSync7(settingsPath)) {
       try {
         const raw = readFileSync4(settingsPath, "utf-8");
         existing = raw.trim() ? JSON.parse(raw) : {};
@@ -1543,7 +1874,7 @@ program.command("install-hook").description("Install engram hook entries into Cl
     }
     try {
       mkdirSync(dirname3(settingsPath), { recursive: true });
-      if (existsSync6(settingsPath)) {
+      if (existsSync7(settingsPath)) {
         const backupPath = `${settingsPath}.engram-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.bak`;
         copyFileSync(settingsPath, backupPath);
         console.log(chalk.dim(`   Backup: ${backupPath}`));
@@ -1587,7 +1918,7 @@ program.command("uninstall-hook").description("Remove engram hook entries from C
     console.error(chalk.red(`Unknown scope: ${opts.scope}`));
     process.exit(1);
   }
-  if (!existsSync6(settingsPath)) {
+  if (!existsSync7(settingsPath)) {
     console.log(
       chalk.yellow(`No settings file at ${settingsPath} \u2014 nothing to remove.`)
     );
@@ -1703,7 +2034,7 @@ program.command("hook-disable").description("Disable engram hooks via kill switc
     console.error(chalk.dim("Run 'engram init' first."));
     process.exit(1);
   }
-  const flagPath = join6(projectRoot, ".engram", "hook-disabled");
+  const flagPath = join7(projectRoot, ".engram", "hook-disabled");
   try {
     writeFileSync2(flagPath, (/* @__PURE__ */ new Date()).toISOString());
     console.log(
@@ -1727,8 +2058,8 @@ program.command("hook-enable").description("Re-enable engram hooks (remove kill
     console.error(chalk.red(`Not an engram project: ${absProject}`));
     process.exit(1);
   }
-  const flagPath = join6(projectRoot, ".engram", "hook-disabled");
-  if (!existsSync6(flagPath)) {
+  const flagPath = join7(projectRoot, ".engram", "hook-disabled");
+  if (!existsSync7(flagPath)) {
     console.log(
       chalk.yellow(`engram hooks already enabled for ${projectRoot}`)
     );
@@ -1770,8 +2101,8 @@ program.command("memory-sync").description(
     }
     let branch = null;
     try {
-      const headPath = join6(projectRoot, ".git", "HEAD");
-      if (existsSync6(headPath)) {
+      const headPath = join7(projectRoot, ".git", "HEAD");
+      if (existsSync7(headPath)) {
         const content = readFileSync4(headPath, "utf-8").trim();
         const m = content.match(/^ref:\s+refs\/heads\/(.+)$/);
         if (m) branch = m[1];
@@ -1779,7 +2110,7 @@ program.command("memory-sync").description(
     } catch {
     }
     const section = buildEngramSection({
-      projectName: basename2(projectRoot),
+      projectName: basename4(projectRoot),
       branch,
       stats: {
         nodes: graphStats.nodes,
@@ -1798,7 +2129,7 @@ program.command("memory-sync").description(
 \u{1F4DD} engram memory-sync`)
     );
     console.log(
-      chalk.dim(`   Target: ${join6(projectRoot, "MEMORY.md")}`)
+      chalk.dim(`   Target: ${join7(projectRoot, "MEMORY.md")}`)
     );
     if (opts.dryRun) {
       console.log(chalk.cyan("\n   Section to write (dry-run):\n"));

package/dist/{core-2TWPNHRQ.js → core-WTKXDUDO.js}

@@ -11,7 +11,7 @@ import {
   path,
   query,
   stats
-} from "./chunk-RGDHLGWQ.js";
+} from "./chunk-R46DNLNR.js";
 export {
   benchmark,
   computeKeywordIDF,

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   generateSummary,
   install,
   uninstall
-} from "./chunk-IYO4HETA.js";
+} from "./chunk-ESPAWLH6.js";
 import {
   GraphStore,
   SUPPORTED_EXTENSIONS,
@@ -23,7 +23,7 @@ import {
   sliceGraphemeSafe,
   stats,
   truncateGraphemeSafe
-} from "./chunk-RGDHLGWQ.js";
+} from "./chunk-R46DNLNR.js";
 export {
   GraphStore,
   SUPPORTED_EXTENSIONS,

package/dist/serve.js

@@ -8,7 +8,7 @@ import {
   query,
   stats,
   truncateGraphemeSafe
-} from "./chunk-RGDHLGWQ.js";
+} from "./chunk-R46DNLNR.js";
 
 // src/serve.ts
 function clampInt(value, defaultValue, min, max) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "The structural code graph your AI agent can't forget to use. A Claude Code hook layer that intercepts Read/Edit/Write/Bash and replaces file contents with ~300-token structural graph summaries. 82% measured token reduction. Context rot is empirically solved — cite Chroma. Local SQLite, zero LLM cost, zero cloud, zero native deps.",
   "type": "module",
   "bin": {