memtrace 0.3.34 → 0.3.36

package/bin/memtrace.js

@@ -92,7 +92,13 @@ if (args[0] === "uninstall" || args[0] === "cleanup") {
   let ran = false;
   for (const p of candidates) {
     try {
-      require(p);
+      // Spawn the uninstall script as its own process so its top-level
+      // `if (require.main === module)` block fires. We deliberately
+      // avoid `require(p)` here: tests for the cleanup helpers
+      // import uninstall.js for its exports and would trigger the
+      // uninstall pipeline at import time if we relied on side effect.
+      const result = spawnSync(process.execPath, [p], { stdio: "inherit" });
+      if (result.error) continue;
       ran = true;
       break;
     } catch (e) {

package/hooks/posttool-mcp-telemetry.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+#
+# Memtrace PostToolUse hook for Claude Code — adoption telemetry.
+#
+# Fires after every tool call that matched the registered matcher
+# (`mcp__memtrace__.*`). Logs the call locally to
+# `~/.memtrace/adoption.jsonl` so we can measure whether v0.3.35's
+# enforcement layers actually moved Memtrace tool-invocation rates.
+#
+# This is LOCAL adoption tracking — the file lives in the user's
+# home directory, never leaves the machine. Aggregate counts may be
+# included in opt-in telemetry pings if the user has enabled them
+# (see PRIVACY.md).
+#
+# Hook never blocks. Always exit 0.
+#
+# Override:
+#   MEMTRACE_ADOPTION_LOG=off → unconditional no-op
+#
+set -euo pipefail
+
+[[ "${MEMTRACE_ADOPTION_LOG:-on}" == "off" ]] && exit 0
+
+# Read PostToolUse input from stdin. Shape:
+#   { "session_id", "cwd", "hook_event_name", "tool_name", "tool_input", ... }
+input="$(cat)"
+
+# Cheap exit if the JSON is malformed.
+[[ -z "$input" ]] && exit 0
+
+log_dir="${MEMTRACE_ADOPTION_DIR:-$HOME/.memtrace}"
+log_file="$log_dir/adoption.jsonl"
+mkdir -p "$log_dir" 2>/dev/null || exit 0
+
+# Append a single-line JSON record. We strip `tool_input` because it
+# can be large and may contain sensitive arguments. We keep the
+# tool name + a high-resolution timestamp + session id only.
+python3 - "$input" "$log_file" <<'PY' 2>/dev/null || true
+import json, sys, os, time
+input_str = sys.argv[1]
+log_path = sys.argv[2]
+try:
+    obj = json.loads(input_str)
+except Exception:
+    sys.exit(0)
+record = {
+    "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    "session_id": obj.get("session_id", ""),
+    "tool_name": obj.get("tool_name", ""),
+    "hook_event_name": obj.get("hook_event_name", ""),
+}
+with open(log_path, "a", encoding="utf-8") as f:
+    f.write(json.dumps(record) + "\n")
+PY
+
+exit 0

package/hooks/userprompt-claude.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+#
+# Memtrace UserPromptSubmit hook for Claude Code.
+#
+# Fires once per user turn (NOT per tool call). Reads the user's
+# prompt; if it looks like a code-discovery question and the
+# Memtrace daemon is reachable, injects an `additionalContext`
+# nudge so Claude considers Memtrace MCP tools BEFORE falling back
+# to Read/Grep/Glob.
+#
+# Why UserPromptSubmit instead of PreToolUse-on-Read|Grep|Glob:
+#   - fires once per turn, not per tool call → no per-Read latency
+#   - gets the user's actual prompt → can decide based on intent,
+#     not on which file the model chose to grep
+#   - non-blocking → just adds context, never denies a tool call
+#
+# Exit codes:
+#   0  : success (stdout is parsed for hook output)
+#   2  : would block the prompt (we never want this)
+#
+# Hook output JSON shape (per code.claude.com/docs/en/hooks-guide.md):
+#   { "decision": "continue", "additionalContext": "..." }
+#
+# Override:
+#   MEMTRACE_HOOK_MODE=off    → unconditional no-op
+#   MEMTRACE_HEALTH_URL=...   → custom health endpoint (default 3030)
+#
+set -euo pipefail
+
+mode="${MEMTRACE_HOOK_MODE:-advisory}"
+[[ "$mode" == "off" ]] && exit 0
+
+# ── Daemon liveness (portable: works on macOS/Linux/Windows-WSL) ──
+#
+# We use the Memtrace UI's status endpoint instead of `pgrep` so
+# Windows + restricted-shell environments work the same way.
+# 1-second timeout — must not slow Claude down.
+health_url="${MEMTRACE_HEALTH_URL:-http://localhost:3030/api/health}"
+if ! curl -sf --max-time 1 "$health_url" >/dev/null 2>&1; then
+    # Daemon unreachable: silent no-op. We never inject memtrace
+    # nudges when memtrace itself isn't running.
+    exit 0
+fi
+
+# ── Read prompt from stdin ──────────────────────────────────────────
+input="$(cat)"
+
+# Use python3 for JSON parsing — every macOS/Linux/Windows-with-Python
+# has it; jq is more concise but less universal.
+prompt="$(printf '%s' "$input" | python3 -c '
+import json, sys
+try:
+    obj = json.load(sys.stdin)
+    print(obj.get("prompt", ""), end="")
+except Exception:
+    pass
+' 2>/dev/null || true)"
+
+# If the prompt is empty or unparseable, no-op.
+[[ -z "$prompt" ]] && exit 0
+
+# ── Match code-discovery intent ─────────────────────────────────────
+#
+# The match list is intentionally generous on the "ask Memtrace" side
+# and is anchored against directive verbs and possessive phrases that
+# a real user prompt looks like. The agent's planner also uses these
+# (e.g. "trace through", "find the function that") so this catches
+# both human-typed and agent-internal phrasings.
+shopt -s nocasematch
+should_nudge=0
+case "$prompt" in
+    *"where is"*|*"where's"*|*"how does"*|*"how is"*) should_nudge=1 ;;
+    *"what calls"*|*"who calls"*|*"callers of"*|*"callees of"*) should_nudge=1 ;;
+    *"why does"*|*"why is"*|*"why was"*) should_nudge=1 ;;
+    *"find the function"*|*"find the class"*|*"find the type"*) should_nudge=1 ;;
+    *"trace through"*|*"trace this"*|*"trace the"*) should_nudge=1 ;;
+    *"investigate"*|*"debug"*|*"diagnose"*) should_nudge=1 ;;
+    *"explain this"*|*"explain the code"*|*"understand this"*) should_nudge=1 ;;
+    *"audit"*|*"review"*|*"refactor"*) should_nudge=1 ;;
+    *"fix bug"*|*"fix the bug"*|*"broken"*|*"failing"*) should_nudge=1 ;;
+    *"impact of"*|*"what breaks if"*|*"safe to remove"*|*"safe to rename"*) should_nudge=1 ;;
+    *"locate"*|*"look up"*|*"search for "*) should_nudge=1 ;;
+    *"recent changes"*|*"what changed"*|*"evolution of"*) should_nudge=1 ;;
+    *"call graph"*|*"dependency"*|*"depend on"*|*"dependencies of"*) should_nudge=1 ;;
+esac
+shopt -u nocasematch
+
+[[ "$should_nudge" -eq 0 ]] && exit 0
+
+# ── Emit the nudge ──────────────────────────────────────────────────
+#
+# Per Anthropic's hook docs, UserPromptSubmit accepts a top-level
+# `decision: continue` (don't block) plus `additionalContext` (which
+# is injected as a system-style reminder Claude reads alongside the
+# user's prompt). The wording is concise on purpose — this is added
+# to context for every matching prompt, so token cost is real.
+cat <<'EOF'
+{
+  "decision": "continue",
+  "additionalContext": "Memtrace is active for this repository. For this code-discovery question, prefer the Memtrace MCP tools FIRST — `mcp__memtrace__find_code` for natural-language search, `mcp__memtrace__find_symbol` for exact lookup, `mcp__memtrace__get_symbol_context` for callers/callees, `mcp__memtrace__get_impact` for blast radius. They return exact file:start_line:end_line in one round-trip. Fall back to Read/Grep/Glob only for: (a) config files (.env, package.json, README, raw JSON/YAML/TOML), (b) file inventory questions, (c) paths confirmed outside any indexed repo, (d) reading exact lines you already have from a Memtrace result."
+}
+EOF

package/install.js

@@ -6,6 +6,7 @@ const path = require("path");
 const fs = require("fs");
 const { spawnSync } = require("child_process");
 const { platformBinary, spawnOptionsForPlatform } = require("./lib/spawn-helper");
+const { installToFs } = require("./lib/claude-integration");
 
 // ── Platform binary resolution (preserved from legacy) ───────────────────────
 
@@ -128,7 +129,40 @@ if (require.main === module) {
     console.warn("memtrace: run 'memtrace install' manually after the package is built.");
   }
 
-  // 3. Persist uninstall script to ~/.memtrace/ (survives `npm uninstall -g`)
+  // 3. Claude Code adoption layer (v0.3.35+):
+  //    - write ~/.claude/MEMTRACE.md (sidecar directive we own)
+  //    - add a breadcrumb block to ~/.claude/CLAUDE.md if it exists
+  //    - register UserPromptSubmit + PostToolUse hooks in
+  //      ~/.claude/settings.json under `_managed_by: "memtrace"`
+  //
+  //    This layer is what makes Claude Code consistently reach for
+  //    Memtrace MCP tools FIRST instead of falling back to Read/Grep
+  //    on indexed repos. Heuristic skill auto-invocation is too soft
+  //    on its own — see lib/claude-integration.js for the why.
+  try {
+    const hooksDir = path.join(__dirname, "hooks");
+    // Make hook scripts executable on Unix (npm tarballs lose +x on
+    // some pack/unpack paths; doing this defensively).
+    if (os.platform() !== "win32" && fs.existsSync(hooksDir)) {
+      for (const entry of fs.readdirSync(hooksDir)) {
+        if (entry.endsWith(".sh")) {
+          try { fs.chmodSync(path.join(hooksDir, entry), 0o755); }
+          catch { /* best-effort */ }
+        }
+      }
+    }
+    const claudeDir = path.join(os.homedir(), ".claude");
+    const summary = installToFs({ claudeDir, hooksDir });
+    if (summary.wrote.length > 0) {
+      console.log(
+        `memtrace: configured Claude Code integration (${summary.wrote.length} file(s) updated)`
+      );
+    }
+  } catch (e) {
+    console.warn(`memtrace: Claude Code integration setup skipped: ${e.message}`);
+  }
+
+  // 4. Persist uninstall script to ~/.memtrace/ (survives `npm uninstall -g`)
   try {
     const memtraceDir = path.join(os.homedir(), ".memtrace");
     fs.mkdirSync(memtraceDir, { recursive: true });

package/lib/claude-integration.js

@@ -0,0 +1,447 @@
+"use strict";
+
+// Claude Code integration for Memtrace.
+//
+// Manages three pieces of user-level Claude Code configuration:
+//
+//   1. ~/.claude/MEMTRACE.md      — durable directive that Claude
+//                                    reads as ambient context. Owned
+//                                    entirely by us. We control the
+//                                    full file content; uninstall
+//                                    removes it cleanly.
+//
+//   2. ~/.claude/CLAUDE.md        — user-authored. We DO NOT
+//                                    overwrite. We append a single
+//                                    sentinel-bracketed breadcrumb
+//                                    line pointing at MEMTRACE.md,
+//                                    only if the file already exists.
+//                                    User edits outside our markers
+//                                    are preserved on uninstall.
+//
+//   3. ~/.claude/settings.json    — JSON. We add hook entries tagged
+//                                    with `_managed_by: "memtrace"`.
+//                                    All other entries pass through
+//                                    untouched. Uninstall walks the
+//                                    hooks arrays and drops only
+//                                    entries with our tag.
+//
+// Pure functions where possible — anything that touches the filesystem
+// is wrapped at the bottom for the install.js / uninstall.js entry
+// points. Pure parts are unit + property tested in
+// `test/claude-integration.test.js`.
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ── Constants ─────────────────────────────────────────────────────────
+
+const BLOCK_BEGIN = "<!-- BEGIN MEMTRACE BLOCK · managed by `memtrace install` · remove with `memtrace uninstall` -->";
+const BLOCK_END = "<!-- END MEMTRACE BLOCK -->";
+const BLOCK_VERSION = "0.3.35";
+
+const MEMTRACE_MD_HEADER = `<!-- This file is managed by \`memtrace install\`.
+     User edits here will be overwritten on next install.
+     For your own Claude Code directives, edit CLAUDE.md instead. -->
+`;
+
+const MEMTRACE_MD_BODY = `# Memtrace is active on this machine
+
+For ANY code-discovery question — finding symbols, callers, impacts,
+evolution, "where is", "how does", "what calls", "why does",
+"trace through", "find the function that…" — invoke
+\`mcp__memtrace__find_symbol\` or \`mcp__memtrace__find_code\` FIRST.
+Memtrace returns exact \`file:start_line:end_line\` in one call.
+
+After a search hit, follow up with the graph tools that file/grep can't
+match: \`mcp__memtrace__get_symbol_context\` for callers/callees,
+\`mcp__memtrace__get_impact\` for blast radius,
+\`mcp__memtrace__get_evolution\` for history. Read source ONLY at the
+exact spans Memtrace returned, with a few lines of context.
+
+\`Read\` / \`Grep\` / \`Glob\` remain correct ONLY for:
+
+- Config files (\`.env\`, \`package.json\`, README, raw JSON/YAML/TOML)
+- File-inventory questions ("how many \`*.test.ts\` files exist")
+- Files confirmed outside every indexed repo
+- Reading exact lines you already have from a Memtrace result
+
+If Memtrace returns 0 results, broaden the query or call
+\`mcp__memtrace__list_indexed_repositories\` to confirm scope. Zero
+results, missing language stats, or partial-looking output are NOT
+permission to silently fall back to \`Grep\`.
+
+This file is generated by \`memtrace install\` and removed by
+\`memtrace uninstall\`. Edit CLAUDE.md for your own Claude Code rules
+— that file is not touched (we only append a single breadcrumb line
+pointing here, inside our marker block).
+`;
+
+const CLAUDE_MD_BREADCRUMB_LINES = [
+    BLOCK_BEGIN,
+    `<!-- block-version: ${BLOCK_VERSION} -->`,
+    "> 🧠 Memtrace is installed on this machine. **For code-discovery questions, call \\`mcp__memtrace__find_symbol\\` or \\`mcp__memtrace__find_code\\` BEFORE \\`Read\\` / \\`Grep\\` / \\`Glob\\`** — see [`MEMTRACE.md`](./MEMTRACE.md) for the full rule.",
+    BLOCK_END,
+];
+const CLAUDE_MD_BREADCRUMB = CLAUDE_MD_BREADCRUMB_LINES.join("\n");
+
+const HOOK_MANAGED_TAG = "memtrace";
+
+// ── Pure functions: MEMTRACE.md content ───────────────────────────────
+
+/**
+ * Build the canonical MEMTRACE.md body. Pure.
+ * @returns {string}
+ */
+function buildMemtraceMdContent() {
+    return MEMTRACE_MD_HEADER + "\n" + MEMTRACE_MD_BODY;
+}
+
+// ── Pure functions: CLAUDE.md sentinel-block management ───────────────
+
+/**
+ * Add or refresh the Memtrace breadcrumb block in an existing
+ * CLAUDE.md. Pure — takes current content, returns new content.
+ *
+ * Strict-symmetry design: the bytes WE own are exactly
+ *   `CLAUDE_MD_BREADCRUMB + "\n"`
+ * and we always append them at the very end of the file (or
+ * replace an existing block in place with the same shape). We
+ * never add a leading separator; the user's content is left
+ * byte-identical above us. This makes `apply` and `remove` exact
+ * inverses for any user content (idempotency + round-trip
+ * byte-identity hold).
+ *
+ *   - No existing block: append `CLAUDE_MD_BREADCRUMB + "\n"`.
+ *   - Existing block:    replace the inclusive span
+ *                        BLOCK_BEGIN..BLOCK_END(+optional \n)
+ *                        with `CLAUDE_MD_BREADCRUMB + "\n"`.
+ *
+ * @param {string} existing
+ * @returns {string}
+ */
+function applyClaudeMdBreadcrumb(existing) {
+    const beginIdx = existing.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1) {
+        return existing + CLAUDE_MD_BREADCRUMB + "\n";
+    }
+    const endIdx = existing.indexOf(BLOCK_END, beginIdx);
+    if (endIdx === -1) {
+        throw new Error(
+            "CLAUDE.md contains a BEGIN MEMTRACE BLOCK marker without a matching END marker. " +
+            "Repair the file manually or delete the partial block before retrying."
+        );
+    }
+    const blockEnd = endIdx + BLOCK_END.length;
+    const tailNewline = existing.charAt(blockEnd) === "\n" ? 1 : 0;
+    return (
+        existing.slice(0, beginIdx) +
+        CLAUDE_MD_BREADCRUMB + "\n" +
+        existing.slice(blockEnd + tailNewline)
+    );
+}
+
+/**
+ * Remove the Memtrace breadcrumb block from CLAUDE.md content.
+ * Pure. Idempotent. Strict inverse of `applyClaudeMdBreadcrumb`:
+ * removes exactly the bytes apply added, leaving everything else
+ * byte-identical.
+ *
+ * @param {string} existing
+ * @returns {string}
+ */
+function removeClaudeMdBreadcrumb(existing) {
+    const beginIdx = existing.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1) return existing;
+    const endIdx = existing.indexOf(BLOCK_END, beginIdx);
+    if (endIdx === -1) {
+        throw new Error(
+            "CLAUDE.md contains a BEGIN MEMTRACE BLOCK marker without a matching END marker. " +
+            "Repair the file manually before retrying."
+        );
+    }
+    const blockEnd = endIdx + BLOCK_END.length;
+    const tailNewline = existing.charAt(blockEnd) === "\n" ? 1 : 0;
+    return existing.slice(0, beginIdx) + existing.slice(blockEnd + tailNewline);
+}
+
+// ── Pure functions: settings.json hook merge ──────────────────────────
+
+/**
+ * Add Memtrace's hook entries to a parsed settings.json object.
+ * Pure — does NOT touch the filesystem; works on objects.
+ *
+ * The added hook entries carry `_managed_by: "memtrace"` so the
+ * uninstall path can identify and remove only our entries.
+ *
+ * @param {object} settings   parsed contents of settings.json (may be {})
+ * @param {string} hooksDir   absolute directory containing the hook scripts
+ * @returns {object}          new settings object (deep-copied)
+ */
+function applySettingsHooks(settings, hooksDir) {
+    const out = JSON.parse(JSON.stringify(settings || {}));
+    out.hooks = out.hooks || {};
+
+    const userPromptHook = {
+        type: "command",
+        command: path.join(hooksDir, "userprompt-claude.sh"),
+        _managed_by: HOOK_MANAGED_TAG,
+        _hook_kind: "userprompt-advisory",
+    };
+    const postToolHook = {
+        type: "command",
+        command: path.join(hooksDir, "posttool-mcp-telemetry.sh"),
+        _managed_by: HOOK_MANAGED_TAG,
+        _hook_kind: "posttool-mcp-telemetry",
+    };
+
+    // UserPromptSubmit — single matcher-less entry.
+    out.hooks.UserPromptSubmit = mergeHookList(
+        out.hooks.UserPromptSubmit || [],
+        { hooks: [userPromptHook] },
+        userPromptHook,
+    );
+
+    // PostToolUse — matcher narrowed to our MCP tools.
+    out.hooks.PostToolUse = mergeHookList(
+        out.hooks.PostToolUse || [],
+        { matcher: "mcp__memtrace__.*", hooks: [postToolHook] },
+        postToolHook,
+    );
+
+    return out;
+}
+
+/**
+ * Merge our hook into an existing hooks array. If a memtrace-managed
+ * entry already exists in any of the matchers, we update it in place
+ * (keep the surrounding matcher block) instead of duplicating.
+ *
+ * @param {Array} existing
+ * @param {object} ourEntry  shape `{ matcher?, hooks: [...] }`
+ * @param {object} ourHook   the inner hook object (with _managed_by)
+ * @returns {Array}
+ */
+function mergeHookList(existing, ourEntry, ourHook) {
+    const out = existing.map((block) => ({ ...block }));
+    let foundManagedBlock = -1;
+    for (let i = 0; i < out.length; i++) {
+        const block = out[i];
+        if (!block.hooks) continue;
+        const hasOurs = block.hooks.some(
+            (h) => h && h._managed_by === HOOK_MANAGED_TAG && h._hook_kind === ourHook._hook_kind,
+        );
+        if (hasOurs) {
+            foundManagedBlock = i;
+            break;
+        }
+    }
+    if (foundManagedBlock === -1) {
+        // Add our block as a new entry.
+        out.push(ourEntry);
+        return out;
+    }
+    // Replace just our hook entries inside the existing block, keep
+    // any user-added hooks in the same matcher untouched.
+    const block = { ...out[foundManagedBlock] };
+    block.hooks = block.hooks.filter(
+        (h) => !(h && h._managed_by === HOOK_MANAGED_TAG && h._hook_kind === ourHook._hook_kind),
+    );
+    block.hooks.push(ourHook);
+    out[foundManagedBlock] = block;
+    return out;
+}
+
+/**
+ * Remove all memtrace-managed hook entries from a parsed settings.json.
+ * Pure. Walks every hooks event type, drops entries tagged
+ * `_managed_by: "memtrace"`, and prunes empty containers.
+ *
+ * @param {object} settings
+ * @returns {object}
+ */
+function removeSettingsHooks(settings) {
+    const out = JSON.parse(JSON.stringify(settings || {}));
+    if (!out.hooks) return out;
+
+    for (const eventName of Object.keys(out.hooks)) {
+        const blocks = out.hooks[eventName];
+        if (!Array.isArray(blocks)) continue;
+        const cleaned = [];
+        for (const block of blocks) {
+            if (!block || !Array.isArray(block.hooks)) {
+                cleaned.push(block);
+                continue;
+            }
+            const filteredHooks = block.hooks.filter(
+                (h) => !(h && h._managed_by === HOOK_MANAGED_TAG),
+            );
+            if (filteredHooks.length === 0) {
+                // Block was entirely ours — drop it.
+                continue;
+            }
+            cleaned.push({ ...block, hooks: filteredHooks });
+        }
+        if (cleaned.length === 0) {
+            delete out.hooks[eventName];
+        } else {
+            out.hooks[eventName] = cleaned;
+        }
+    }
+    if (out.hooks && Object.keys(out.hooks).length === 0) {
+        delete out.hooks;
+    }
+    return out;
+}
+
+// ── Side-effecting wrappers for the installer entry point ─────────────
+
+/**
+ * Install Memtrace's Claude Code integration: write MEMTRACE.md,
+ * breadcrumb CLAUDE.md if it exists, register hooks in settings.json.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.claudeDir]   default `~/.claude`
+ * @param {string} [opts.hooksDir]    absolute dir where hook scripts live
+ * @returns {object}                  summary `{ wrote: [...], skipped: [...] }`
+ */
+function installToFs(opts = {}) {
+    const claudeDir = opts.claudeDir || path.join(os.homedir(), ".claude");
+    const hooksDir = opts.hooksDir;
+    if (!hooksDir) {
+        throw new Error("installToFs: opts.hooksDir is required (absolute path to hooks/)");
+    }
+
+    const summary = { wrote: [], skipped: [] };
+
+    fs.mkdirSync(claudeDir, { recursive: true });
+
+    // 1. Write MEMTRACE.md (always overwrite — we own this file).
+    const memtraceMdPath = path.join(claudeDir, "MEMTRACE.md");
+    fs.writeFileSync(memtraceMdPath, buildMemtraceMdContent());
+    summary.wrote.push(memtraceMdPath);
+
+    // 2. Breadcrumb in CLAUDE.md (only if file exists; we don't create it).
+    const claudeMdPath = path.join(claudeDir, "CLAUDE.md");
+    if (fs.existsSync(claudeMdPath)) {
+        const existing = fs.readFileSync(claudeMdPath, "utf8");
+        const updated = applyClaudeMdBreadcrumb(existing);
+        if (updated !== existing) {
+            fs.writeFileSync(claudeMdPath, updated);
+            summary.wrote.push(claudeMdPath);
+        } else {
+            summary.skipped.push(claudeMdPath + " (already up to date)");
+        }
+    } else {
+        summary.skipped.push(claudeMdPath + " (does not exist; not creating)");
+    }
+
+    // 3. Register hooks in settings.json.
+    const settingsPath = path.join(claudeDir, "settings.json");
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        } catch (e) {
+            throw new Error(
+                `Failed to parse ${settingsPath}: ${e.message}. ` +
+                "Repair manually before retrying."
+            );
+        }
+    }
+    const updated = applySettingsHooks(settings, hooksDir);
+    fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
+    summary.wrote.push(settingsPath);
+
+    return summary;
+}
+
+/**
+ * Reverse of installToFs. Removes MEMTRACE.md, removes our
+ * breadcrumb from CLAUDE.md, removes our hooks from settings.json.
+ * Leaves all user-authored content intact.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.claudeDir]   default `~/.claude`
+ * @returns {object}                  summary `{ removed: [...], skipped: [...] }`
+ */
+function uninstallFromFs(opts = {}) {
+    const claudeDir = opts.claudeDir || path.join(os.homedir(), ".claude");
+    const summary = { removed: [], skipped: [] };
+
+    // 1. Remove MEMTRACE.md.
+    const memtraceMdPath = path.join(claudeDir, "MEMTRACE.md");
+    if (fs.existsSync(memtraceMdPath)) {
+        fs.unlinkSync(memtraceMdPath);
+        summary.removed.push(memtraceMdPath);
+    } else {
+        summary.skipped.push(memtraceMdPath + " (not present)");
+    }
+
+    // 2. Strip breadcrumb from CLAUDE.md.
+    const claudeMdPath = path.join(claudeDir, "CLAUDE.md");
+    if (fs.existsSync(claudeMdPath)) {
+        const existing = fs.readFileSync(claudeMdPath, "utf8");
+        const updated = removeClaudeMdBreadcrumb(existing);
+        if (updated === "") {
+            // Our breadcrumb was the only content — remove the file.
+            fs.unlinkSync(claudeMdPath);
+            summary.removed.push(claudeMdPath + " (file was empty after cleanup)");
+        } else if (updated !== existing) {
+            fs.writeFileSync(claudeMdPath, updated);
+            summary.removed.push(claudeMdPath + " (breadcrumb removed)");
+        } else {
+            summary.skipped.push(claudeMdPath + " (no memtrace breadcrumb found)");
+        }
+    } else {
+        summary.skipped.push(claudeMdPath + " (not present)");
+    }
+
+    // 3. Strip our hooks from settings.json.
+    const settingsPath = path.join(claudeDir, "settings.json");
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+            const updated = removeSettingsHooks(settings);
+            const before = JSON.stringify(settings);
+            const after = JSON.stringify(updated);
+            if (before !== after) {
+                if (Object.keys(updated).length === 0) {
+                    fs.unlinkSync(settingsPath);
+                    summary.removed.push(settingsPath + " (file was empty after cleanup)");
+                } else {
+                    fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
+                    summary.removed.push(settingsPath + " (memtrace hook entries removed)");
+                }
+            } else {
+                summary.skipped.push(settingsPath + " (no memtrace hook entries found)");
+            }
+        } catch (e) {
+            summary.skipped.push(settingsPath + ` (parse error: ${e.message})`);
+        }
+    } else {
+        summary.skipped.push(settingsPath + " (not present)");
+    }
+
+    return summary;
+}
+
+module.exports = {
+    // Constants — exported for tests
+    BLOCK_BEGIN,
+    BLOCK_END,
+    BLOCK_VERSION,
+    HOOK_MANAGED_TAG,
+    CLAUDE_MD_BREADCRUMB,
+
+    // Pure functions
+    buildMemtraceMdContent,
+    applyClaudeMdBreadcrumb,
+    removeClaudeMdBreadcrumb,
+    applySettingsHooks,
+    removeSettingsHooks,
+
+    // Side-effecting entry points
+    installToFs,
+    uninstallFromFs,
+};