engramx 0.3.0 → 0.3.2

package/README.md

@@ -15,20 +15,36 @@
   <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">
 </p>
 
 ---
 
-**Context as infra for your AI coding tools.**
+# The structural code graph your AI agent can't forget to use.
 
-engram installs a Claude Code hook layer that intercepts every `Read`, `Edit`, `Write`, and `Bash cat` — replacing full file reads with ~300-token structural graph summaries *before the agent even sees them*. No more re-exploring the codebase every session. No more agents forgetting to use the tool you gave them.
+**Context rot is empirically solved.** Chroma's July 2025 research proved that even Claude Opus 4.6 scores only 76% on MRCR v2 8-needle at 1M tokens. Long context windows don't save you — they drown you. engram is the answer: a **structural graph** of your codebase that replaces file reads with ~300-token summaries *before the agent sees them*.
 
-**v0.3 "Sentinel":** the agent can't forget to use engram because engram sits between the agent and the filesystem.
+engram installs a Claude Code hook layer at the tool-call boundary. Every `Read`, `Edit`, `Write`, and `Bash cat` gets intercepted. When the graph has confident coverage of a file, the raw read never happens — the agent sees a structural summary instead.
 
-Zero LLM cost. Zero cloud. Zero native deps. Works today in Claude Code.
+Not a memory tool. Not a RAG layer. Not a context manager. **A structural code graph with a Claude Code hook layer that turns it into the memory your agent can't forget to exist.**
+
+| What it is | What it isn't |
+|---|---|
+| Structural code graph (AST + git + session miners) | Prose memory like Anthropic's MEMORY.md |
+| Local SQLite, zero cloud, zero native deps | Vector RAG that phones home |
+| Hook-based interception at the tool boundary | A tool the agent has to remember to call |
+| 82% measured token reduction on real code | Another LongMemEval chatbot benchmark |
+| Complements native Claude memory | Competes with native Claude memory |
+
+```bash
+npm install -g engramx
+cd ~/my-project
+engram init             # scan codebase → .engram/graph.db (~40 ms, 0 tokens)
+engram install-hook     # wire the Sentinel into Claude Code
+```
 
 ```bash
 npm install -g engramx
@@ -45,6 +61,13 @@ That's it. The next Claude Code session in that directory automatically:
 - **Injects a project brief at session start** (SessionStart additionalContext)
 - **Logs every decision for `engram hook-stats`** (PostToolUse observer)
 
+## Architecture Diagram
+
+An 11-page visual walkthrough of the full lifecycle — the four hook events, the Read handler's 9-branch decision tree (with a real JSON response), the six-layer ecosystem substrate, and measured numbers from engram's own code.
+
+- 📄 **[View the PDF](docs/engram-sentinel-ecosystem.pdf)** — A3 landscape, 11 pages, 1 MB. GitHub renders it inline when clicked.
+- 🌐 **[HTML source](docs/engram-sentinel-ecosystem.html)** — single self-contained file. Download raw and open in any browser for the interactive scroll-reveal version.
+
 ## The Problem
 
 Every Claude Code session burns ~52,500 tokens on things you already told the agent yesterday. Reading the same files, re-exploring the same modules, re-discovering the same patterns. Even with a great CLAUDE.md, the agent still falls back to `Read` because `Read` is what it knows.
@@ -87,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-NYFDM4FR.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;
     }
@@ -1660,6 +1666,41 @@ async function getFileContext(projectRoot, absFilePath) {
     return empty;
   }
 }
+async function computeKeywordIDF(projectRoot, keywords) {
+  if (keywords.length === 0) return [];
+  try {
+    const root = resolve2(projectRoot);
+    const dbPath = getDbPath(root);
+    if (!existsSync5(dbPath)) return [];
+    const store = await getStore(root);
+    try {
+      const allNodes = store.getAllNodes();
+      const total = allNodes.length;
+      if (total === 0) return [];
+      const labels = allNodes.map((n) => n.label.toLowerCase());
+      const results = [];
+      for (const kw of keywords) {
+        const kwLower = kw.toLowerCase();
+        let df = 0;
+        for (const label of labels) {
+          if (label.includes(kwLower)) df += 1;
+        }
+        const idf = df === 0 ? 0 : Math.log(total / df);
+        results.push({
+          keyword: kw,
+          documentFrequency: df,
+          idf
+        });
+      }
+      results.sort((a, b) => b.idf - a.idf);
+      return results;
+    } finally {
+      store.close();
+    }
+  } catch {
+    return [];
+  }
+}
 async function learn(projectRoot, text, sourceLabel = "manual") {
   const { nodes, edges } = learnFromSession(text, sourceLabel);
   if (nodes.length === 0 && edges.length === 0) return { nodesAdded: 0 };
@@ -1766,6 +1807,7 @@ export {
   MAX_MISTAKE_LABEL_CHARS,
   queryGraph,
   shortestPath,
+  toPosixPath,
   SUPPORTED_EXTENSIONS,
   extractFile,
   extractDirectory,
@@ -1778,6 +1820,7 @@ export {
   godNodes,
   stats,
   getFileContext,
+  computeKeywordIDF,
   learn,
   mistakes,
   benchmark

package/dist/{chunk-7KYR4SPZ.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-MPNNCPFW.js");
+  const { getStore } = await import("./core-AJD3SS6U.js");
   const store = await getStore(projectRoot);
   try {
     let view = VIEWS.general;

package/dist/cli.js

@@ -4,9 +4,10 @@ import {
   install,
   status,
   uninstall
-} from "./chunk-7KYR4SPZ.js";
+} from "./chunk-JXJNXQUM.js";
 import {
   benchmark,
+  computeKeywordIDF,
   getFileContext,
   godNodes,
   init,
@@ -14,22 +15,23 @@ import {
   mistakes,
   path,
   query,
-  stats
-} from "./chunk-NYFDM4FR.js";
+  stats,
+  toPosixPath
+} from "./chunk-3NUHMLRV.js";
 
 // src/cli.ts
 import { Command } from "commander";
 import chalk from "chalk";
 import {
-  existsSync as existsSync5,
-  readFileSync as readFileSync3,
-  writeFileSync,
+  existsSync as existsSync6,
+  readFileSync as readFileSync4,
+  writeFileSync as writeFileSync2,
   mkdirSync,
   unlinkSync,
   copyFileSync,
-  renameSync as renameSync2
+  renameSync as renameSync3
 } from "fs";
-import { dirname as dirname3, join as join5, resolve as pathResolve } from "path";
+import { dirname as dirname3, join as join6, resolve as pathResolve } from "path";
 import { homedir } from "os";
 
 // src/intercept/safety.ts
@@ -103,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([
@@ -256,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)) {
@@ -370,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 {
@@ -548,6 +559,8 @@ async function handleSessionStart(payload) {
 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",
@@ -642,13 +655,32 @@ async function handleUserPromptSubmit(payload) {
   const prompt = payload.prompt;
   if (!prompt || typeof prompt !== "string") return PASSTHROUGH;
   if (prompt.length > 8e3) return PASSTHROUGH;
-  const keywords = extractKeywords(prompt);
-  if (keywords.length < MIN_SIGNIFICANT_TERMS) 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(" "), {
@@ -866,6 +898,44 @@ function extractPreToolDecision(result) {
   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",
@@ -1080,7 +1150,107 @@ function formatStatsSummary(summary) {
   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(
   "Context as infra for AI coding tools \u2014 hook-based Read/Edit interception + structural graph summaries"
@@ -1116,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, {
@@ -1242,11 +1428,11 @@ function resolveSettingsPath(scope, projectPath) {
   const absProject = pathResolve(projectPath);
   switch (scope) {
     case "local":
-      return join5(absProject, ".claude", "settings.local.json");
+      return join6(absProject, ".claude", "settings.local.json");
     case "project":
-      return join5(absProject, ".claude", "settings.json");
+      return join6(absProject, ".claude", "settings.json");
     case "user":
-      return join5(homedir(), ".claude", "settings.json");
+      return join6(homedir(), ".claude", "settings.json");
     default:
       return null;
   }
@@ -1257,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);
@@ -1282,6 +1473,45 @@ program.command("intercept").description(
     }
   } catch {
   }
+  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."
+).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(
@@ -1296,9 +1526,9 @@ program.command("install-hook").description("Install engram hook entries into Cl
       process.exit(1);
     }
     let existing = {};
-    if (existsSync5(settingsPath)) {
+    if (existsSync6(settingsPath)) {
       try {
-        const raw = readFileSync3(settingsPath, "utf-8");
+        const raw = readFileSync4(settingsPath, "utf-8");
         existing = raw.trim() ? JSON.parse(raw) : {};
       } catch (err) {
         console.error(
@@ -1344,17 +1574,17 @@ program.command("install-hook").description("Install engram hook entries into Cl
     }
     try {
       mkdirSync(dirname3(settingsPath), { recursive: true });
-      if (existsSync5(settingsPath)) {
+      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";
-      writeFileSync(
+      writeFileSync2(
         tmpPath,
         JSON.stringify(result.updated, null, 2) + "\n"
       );
-      renameSync2(tmpPath, settingsPath);
+      renameSync3(tmpPath, settingsPath);
     } catch (err) {
       console.error(
         chalk.red(`
@@ -1388,7 +1618,7 @@ program.command("uninstall-hook").description("Remove engram hook entries from C
     console.error(chalk.red(`Unknown scope: ${opts.scope}`));
     process.exit(1);
   }
-  if (!existsSync5(settingsPath)) {
+  if (!existsSync6(settingsPath)) {
     console.log(
       chalk.yellow(`No settings file at ${settingsPath} \u2014 nothing to remove.`)
     );
@@ -1396,7 +1626,7 @@ program.command("uninstall-hook").description("Remove engram hook entries from C
   }
   let existing;
   try {
-    const raw = readFileSync3(settingsPath, "utf-8");
+    const raw = readFileSync4(settingsPath, "utf-8");
     existing = raw.trim() ? JSON.parse(raw) : {};
   } catch (err) {
     console.error(
@@ -1416,8 +1646,8 @@ program.command("uninstall-hook").description("Remove engram hook entries from C
     const backupPath = `${settingsPath}.engram-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.bak`;
     copyFileSync(settingsPath, backupPath);
     const tmpPath = settingsPath + ".engram-tmp";
-    writeFileSync(tmpPath, JSON.stringify(result.updated, null, 2) + "\n");
-    renameSync2(tmpPath, settingsPath);
+    writeFileSync2(tmpPath, JSON.stringify(result.updated, null, 2) + "\n");
+    renameSync3(tmpPath, settingsPath);
     console.log(
       chalk.green(
         `
@@ -1504,9 +1734,9 @@ program.command("hook-disable").description("Disable engram hooks via kill switc
     console.error(chalk.dim("Run 'engram init' first."));
     process.exit(1);
   }
-  const flagPath = join5(projectRoot, ".engram", "hook-disabled");
+  const flagPath = join6(projectRoot, ".engram", "hook-disabled");
   try {
-    writeFileSync(flagPath, (/* @__PURE__ */ new Date()).toISOString());
+    writeFileSync2(flagPath, (/* @__PURE__ */ new Date()).toISOString());
     console.log(
       chalk.green(`\u2705 engram hooks disabled for ${projectRoot}`)
     );
@@ -1528,8 +1758,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 = join5(projectRoot, ".engram", "hook-disabled");
-  if (!existsSync5(flagPath)) {
+  const flagPath = join6(projectRoot, ".engram", "hook-disabled");
+  if (!existsSync6(flagPath)) {
     console.log(
       chalk.yellow(`engram hooks already enabled for ${projectRoot}`)
     );
@@ -1547,4 +1777,90 @@ program.command("hook-enable").description("Re-enable engram hooks (remove kill
     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();

package/dist/{core-MPNNCPFW.js → core-AJD3SS6U.js}

@@ -1,5 +1,6 @@
 import {
   benchmark,
+  computeKeywordIDF,
   getDbPath,
   getFileContext,
   getStore,
@@ -10,9 +11,10 @@ import {
   path,
   query,
   stats
-} from "./chunk-NYFDM4FR.js";
+} from "./chunk-3NUHMLRV.js";
 export {
   benchmark,
+  computeKeywordIDF,
   getDbPath,
   getFileContext,
   getStore,

package/dist/index.js

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

package/dist/serve.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "engramx",
-  "version": "0.3.0",
-  "description": "Context as infra for AI coding tools — a Claude Code hook layer that intercepts Read/Edit/Grep and replaces file reads with structural graph summaries. Persistent, local, zero LLM cost.",
+  "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": {
     "engram": "dist/cli.js",
@@ -17,16 +17,20 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
-    "ai",
-    "coding",
-    "memory",
-    "context",
-    "tree-sitter",
+    "structural-code-graph",
+    "claude-code-hooks",
+    "ai-coding",
+    "context-engineering",
     "knowledge-graph",
+    "ast",
     "mcp",
-    "claude",
+    "claude-code",
     "cursor",
-    "token-savings"
+    "token-reduction",
+    "context-rot",
+    "local-first",
+    "agent-memory",
+    "hook-interception"
   ],
   "author": "Nicholas Ashkar",
   "license": "Apache-2.0",