engramx 0.3.1 → 0.3.2

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-467%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-RGDHLGWQ.js → chunk-3NUHMLRV.js}

@@ -627,6 +627,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 +722,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 +1236,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 +1612,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 +1807,7 @@ export {
   MAX_MISTAKE_LABEL_CHARS,
   queryGraph,
   shortestPath,
+  toPosixPath,
   SUPPORTED_EXTENSIONS,
   extractFile,
   extractDirectory,

package/dist/{chunk-IYO4HETA.js → chunk-JXJNXQUM.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-AJD3SS6U.js");
   const store = await getStore(projectRoot);
   try {
     let view = VIEWS.general;

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   install,
   status,
   uninstall
-} from "./chunk-IYO4HETA.js";
+} from "./chunk-JXJNXQUM.js";
 import {
   benchmark,
   computeKeywordIDF,
@@ -15,8 +15,9 @@ import {
   mistakes,
   path,
   query,
-  stats
-} from "./chunk-RGDHLGWQ.js";
+  stats,
+  toPosixPath
+} from "./chunk-3NUHMLRV.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -104,6 +105,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 +262,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 +379,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 {
@@ -1276,6 +1286,22 @@ 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 = join6(resolvedProject, ".claude", "settings.local.json");
+  const projectSettings = join6(resolvedProject, ".claude", "settings.json");
+  const hasHooks = existsSync6(localSettings) && readFileSync4(localSettings, "utf-8").includes("engram intercept") || existsSync6(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("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, {
@@ -1417,23 +1443,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 +1473,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."

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

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

package/dist/index.js

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

package/dist/serve.js

@@ -8,7 +8,7 @@ import {
   query,
   stats,
   truncateGraphemeSafe
-} from "./chunk-RGDHLGWQ.js";
+} from "./chunk-3NUHMLRV.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.3.2",
   "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": {