memory-pulse 0.1.5 → 0.2.0

package/README.md

@@ -65,15 +65,35 @@ Then tell your agent to remember things. Record a withdrawn number with
 `kind: "correction"` and it will outrank the history that contained it — at
 every brief size, in every session.
 
+**Enforce corrections, don't just surface them.** Showing an agent a
+correction is measurably not enough — agents re-violate corrections they were
+just shown. `install-hook` also installs a PreToolUse guard: an Edit or Write
+that writes back a withdrawn value is **blocked**, and the agent is told which
+ledger line retired it and when. A comparison that names the replacement
+("was $49, now $29") passes; only a bare reintroduction is blocked. Record
+corrections with the exact terms:
+
+```
+remember({ cause: "pricing-shipped", effect: "price-corrected", kind: "correction",
+           note: "measured willingness to pay is $29", withdrawn: ["$49"], replacement: ["$29"] })
+```
+
 ### Commands
 
 ```
-npx memory-pulse brief          # the re-entry brief (what the hook prints)
+npx memory-pulse brief          # the re-entry brief (what the SessionStart hook prints)
+npx memory-pulse guard          # PreToolUse hook: blocks edits that reintroduce withdrawn terms
+npx memory-pulse report         # correction re-violation scoreboard, computed locally
+npx memory-pulse bench          # instant measured metrics on YOUR ledger
 npx memory-pulse stats          # your telemetry capsule, signature verified by the engine
 npx memory-pulse badge          # README badge markdown from your own signed numbers
-npx memory-pulse install-hook   # Claude Code SessionStart hook
+npx memory-pulse install-hook   # installs both hooks (idempotent); --project commits them to the repo
 ```
 
+The plugin also ships a **skill** (`skills/memory-pulse/SKILL.md`) that teaches
+the agent when to pulse, how to record corrections with withdrawn terms, and
+to respect the guard.
+
 ## What runs where (the privacy contract)
 
 - Your ledger is a **local file**: `.memory-pulse/events.jsonl` in your
@@ -87,7 +107,21 @@ npx memory-pulse install-hook   # Claude Code SessionStart hook
   (`.memory-pulse/telemetry.rain`): the engine advances it on each read call
   and hands it back — it never stores it. `stats` verifies the signature;
   `badge` turns it into a README badge. Delete the file and it restarts.
-- This client is the entire client, zero dependencies, read it in one sitting.
+- **State persistence, no database.** After a read the engine hands back a
+  signed **memory key** (`.memory-pulse/memory.rain`, git-ignored). The next
+  read presents it and the engine resumes from it, ingesting only the events
+  recorded since — the answer is byte-identical to a full rebuild, and any
+  mismatch (edited history, a stepped ledger size, a bad signature) falls back
+  to a rebuild and says why. Lose the file and you lose nothing but one
+  rebuild. `MEMORY_PULSE_MEMORY_KEY=off` disables it.
+- **Memory integrity.** A note that reads like an instruction ("ignore previous
+  instructions", "run this command", a fake system tag) is refused by
+  `remember` and, if one is already in a ledger, quarantined at read time and
+  reported — memory is never rendered into your agent's context as an
+  instruction. The signed capsule also raises a **drift alert** when a ledger
+  loses corrections, shrinks, or its usage shape jumps; the brief footer
+  shows it. Both checks are deterministic lists you can read, not a model.
+- This client is the entire client: one file, zero dependencies, readable in one sitting.
 
 ## Pricing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-pulse",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Causal memory for coding agents that costs ~670 tokens, not your context window. Four MCP tools: re-enter a project, recall what caused what, record findings, run code against memory.",
   "type": "module",
   "bin": {

package/server.mjs

@@ -20,11 +20,14 @@
  *   MEMORY_PULSE_LEDGER  override the ledger path (default: ./.memory-pulse/events.jsonl)
  */
 import readline from "node:readline";
+import http from "node:http";
+import https from "node:https";
+import { gzipSync } from "node:zlib";
 import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const API = (process.env.MEMORY_PULSE_API ?? "https://memory-pulse.strategic-innovations.workers.dev").replace(/\/$/, "");
+const API = (process.env.MEMORY_PULSE_API ?? "https://pulse.strategic-innovations.ai").replace(/\/$/, "");
 const KEY = process.env.MEMORY_PULSE_KEY ?? null;
 
 // ---------------------------------------------------------------- ledger ----
@@ -49,7 +52,31 @@ function readEvents() {
   return { path, events };
 }
 
-function appendEvent({ cause, effect, note, kind, tags, pinned }) {
+// The engine's injection-through-memory list, mirrored so a refusal happens
+// before the write. Keep in step with the engine; the engine is authoritative.
+const INSTRUCTION_PATTERNS = [
+  ["override", /\b(ignore|disregard|forget)\b[^.\n]{0,40}\b(previous|prior|above|all|earlier)\b[^.\n]{0,20}\b(instructions?|rules?|prompts?)\b/i],
+  ["persona", /\byou are now\b|\bfrom now on,? you\b|\bact as (an?|the) (system|admin|developer)\b/i],
+  ["fake-role-tag", /<\/?\s*(system|assistant|tool|user|human|developer)\s*>|\[(system|assistant|tool)\s*:?\s*\]/i],
+  ["system-prompt", /\b(reveal|print|show|dump)\b[^.\n]{0,30}\b(system prompt|hidden prompt|your instructions)\b/i],
+  ["command-exec", /\b(run|execute|paste)\b[^.\n]{0,25}\b(this|the following)\b[^.\n]{0,15}\b(command|script|shell|code)\b/i],
+  ["shell-pipe", /\b(curl|wget)\b[^\n]{0,120}\|\s*(sudo\s+)?(sh|bash|zsh)\b/i],
+  ["destructive", /\b(rm\s+-rf\s+[\/~]|drop\s+table|truncate\s+table|format\s+c:)/i],
+  ["secret-exfil", /\b(send|post|upload|exfiltrat\w*|leak)\b[^.\n]{0,40}\b(api[\s_-]?keys?|secrets?|tokens?|passwords?|credentials?)\b/i],
+  ["hide-from-user", /\b(do not|don't|never)\b[^.\n]{0,20}\b(tell|show|mention|reveal)\b[^.\n]{0,20}\b(the )?(user|human|operator)\b/i],
+];
+export function instructionLike(text) {
+  if (typeof text !== "string" || !text) return [];
+  return INSTRUCTION_PATTERNS.filter(([, re]) => re.test(text)).map(([id]) => id);
+}
+
+function appendEvent({ cause, effect, note, kind, tags, pinned, withdrawn, replacement }) {
+  // Instruction-like notes are refused at the write. The engine quarantines
+  // them at read time too (and reports it), but a note that would be rendered
+  // into every future session as an instruction should never reach the ledger.
+  // Same deterministic list as the engine; no model in the loop.
+  const hits = instructionLike(note);
+  if (hits.length) return { written: false, reason: "instruction-like note refused", patterns: hits, hint: "Record what happened, not what to do. Rephrase as a finding." };
   const { path, events } = readEvents();
   const dup = events.find((e) => e.cause === cause && e.effect === effect && (e.note ?? "") === (note ?? ""));
   if (dup) return { written: false, reason: "duplicate", t: dup.t, ledger: path };
@@ -62,6 +89,19 @@ function appendEvent({ cause, effect, note, kind, tags, pinned }) {
   if (note) event.note = note;
   if (Array.isArray(tags) && tags.length) event.tags = tags;
   if (pinned) event.pinned = true;
+  // Withdrawn terms are what the guard enforces: exact strings that must not
+  // be written again. Only explicit terms count — the guard never guesses.
+  if (Array.isArray(withdrawn)) {
+    const terms = withdrawn.map((w) => String(w).trim()).filter((w) => w.length >= 2);
+    if (terms.length) event.withdrawn = terms;
+  }
+  // Replacement terms let the guard tell a REINTRODUCTION ("price is $49")
+  // apart from a DISAVOWAL or comparison ("was $49, now $29"): an edit that
+  // carries a replacement alongside the withdrawn term is allowed.
+  if (Array.isArray(replacement)) {
+    const terms = replacement.map((w) => String(w).trim()).filter((w) => w.length >= 1);
+    if (terms.length) event.replacement = terms;
+  }
   appendFileSync(path, JSON.stringify(event) + "\n");
   // Echo the canonical stored event back. A shell-quoting accident once ate a
   // word from a note SILENTLY; the caller must be able to see what the ledger
@@ -86,31 +126,98 @@ function writeTelemetry(capsule) {
 }
 const projectName = () => process.env.MEMORY_PULSE_PROJECT || process.cwd().split(/[\\/]/).filter(Boolean).pop() || "project";
 const fmtK = (n) => (n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 1000 ? `${Math.round(n / 1000)}k` : String(n));
-function telemetryFooter(c) {
+export function telemetryFooter(c) {
   const k = c?.counters;
   if (!k || !k.calls) return "";
-  return `— memory-pulse · ${k.pulse} re-entries · ${k.correctionsSurfaced} corrections surfaced · ~${fmtK(k.tokensSavedEst)} tokens saved (est., signed)`;
+  const drift = c.drift?.reasons?.length ? ` · ⚠ drift: ${c.drift.reasons.join("; ")}` : "";
+  return `— memory-pulse · ${k.pulse} re-entries · ${k.correctionsSurfaced} corrections surfaced · ~${fmtK(k.tokensSavedEst)} tokens saved (est., signed)${drift}`;
+}
+
+// ------------------------------------------------------------ memory key ----
+// State persistence without a database. After a read the engine hands back a
+// signed memory key; presenting it on the next read resumes the memory and
+// ingests only the events recorded since (measured: a full re-entry on an
+// 825-event ledger went from 4.5 s to 1.5 s). It lives beside your ledger as
+// memory.rain, it is yours, and a lost or stale key costs one rebuild — never
+// data. It never enters the agent's context. MEMORY_PULSE_MEMORY_KEY=off disables it.
+const memoryKeyPath = () => join(dirname(ledgerPath()), "memory.rain");
+const memoryKeyOn = () => (process.env.MEMORY_PULSE_MEMORY_KEY || "on") !== "off";
+function readMemoryKey() {
+  if (!memoryKeyOn()) return null;
+  try { return JSON.parse(readFileSync(memoryKeyPath(), "utf8")); } catch { return null; }
+}
+function writeMemoryKey(k) {
+  if (!memoryKeyOn() || !k || typeof k !== "object") return;
+  try {
+    const dir = dirname(memoryKeyPath());
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(memoryKeyPath(), JSON.stringify(k));
+    // The ledger is the source of truth; the key is a rebuildable cache and
+    // has no business in version control.
+    const gi = join(dir, ".gitignore");
+    if (!existsSync(gi)) writeFileSync(gi, "memory.rain\n");
+  } catch { /* a read-only checkout must not break a read call */ }
 }
 
 // ------------------------------------------------------------------- api ----
+// Transport: Node's own http(s) on a FRESH HTTP/1.1 connection per call.
+// The global fetch pools an HTTP/2 session that the edge retires after a
+// few large requests, and undici then throws ERR_HTTP2_INVALID_SESSION on
+// reuse instead of reconnecting — `bench` on an 822-event ledger lost 11 of
+// 12 sequential calls to it, and a retry reused the same dead session. No
+// pooling, no session, no dependency.
+function postJson(url, headers, payload) {
+  const u = new URL(url);
+  const mod = u.protocol === "http:" ? http : https;
+  // Ledgers compress 5-10x (notes are prose); anything past 4 KB goes up
+  // gzipped. The engine inflates it; a small body is not worth the header.
+  const gz = Buffer.byteLength(payload) >= 4096;
+  const body = gz ? gzipSync(payload) : Buffer.from(payload);
+  return new Promise((resolve, reject) => {
+    const req = mod.request(u, {
+      method: "POST", agent: false,
+      headers: { ...headers, ...(gz ? { "content-encoding": "gzip" } : {}), "content-length": body.length, connection: "close" },
+    }, (res) => {
+      let data = "";
+      res.setEncoding("utf8");
+      res.on("data", (c) => { data += c; });
+      res.on("end", () => resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, json: async () => JSON.parse(data) }));
+    });
+    req.on("error", reject);
+    req.end(body);
+  });
+}
+
+// Transient transport failures on a fresh connection (a TLS record hiccup, a
+// reset) get exactly one retry — a new connection each time, so the retry
+// means something. Anything else surfaces immediately with its real cause.
+const TRANSIENT = /ERR_SSL|ECONNRESET|EPIPE|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN/;
+async function postJsonRetry(url, headers, payload) {
+  try { return await postJson(url, headers, payload); }
+  catch (first) {
+    if (!TRANSIENT.test(String(first?.code || first?.message || ""))) throw first;
+    return postJson(url, headers, payload);
+  }
+}
+
 async function callApi(route, body) {
   const prior = readTelemetry();
-  body = { ...body, project: projectName(), ...(prior ? { telemetry: prior } : {}) };
+  const mk = readMemoryKey();
+  const wantKey = !mk && memoryKeyOn() && Array.isArray(body.events) && body.events.length >= 500;
+  body = { ...body, project: projectName(), ...(prior ? { telemetry: prior } : {}), ...(mk ? { key: mk } : wantKey ? { wantKey: true } : {}) };
   let res;
   try {
-    res = await fetch(`${API}${route}`, {
-      method: "POST",
-      headers: { "content-type": "application/json", ...(KEY ? { "x-mp-key": KEY } : {}) },
-      body: JSON.stringify(body),
-    });
-  } catch {
+    res = await postJsonRetry(`${API}${route}`, { "content-type": "application/json", ...(KEY ? { "x-mp-key": KEY } : {}) }, JSON.stringify(body));
+  } catch (err) {
+    const why = err?.cause?.code || err?.code || err?.message || String(err);
     throw new Error(
-      "memory-pulse API unreachable. `remember` still works (it writes locally); " +
+      `memory-pulse API unreachable (${why}). \`remember\` still works (it writes locally); ` +
       "pulse/recall/execute need the network. Check connectivity or MEMORY_PULSE_API.",
     );
   }
   const out = await res.json().catch(() => ({}));
   if (res.ok && out.telemetry) { writeTelemetry(out.telemetry); }
+  if (res.ok && out.key) { writeMemoryKey(out.key); delete out.key; }
   if (!res.ok) {
     let msg = out.error ?? `API error ${res.status}`;
     if (out.upgrade) msg += ` — upgrade: ${out.upgrade}`;
@@ -140,8 +247,8 @@ export const TOOLS = [
     name: "recall",
     description:
       "Query the causal graph: what an event caused (effects), what caused it (causes), a multi-hop " +
-      "chain (pulse), or when a link was strongest (when). Returns nothing rather than guessing " +
-      "when the answer is not confident enough.",
+      "chain (pulse), or when a link was strongest (when). Hits carry a confidence; `exact` lists the " +
+      "recorded links verbatim, so a weak read never hides a correction. Returns nothing rather than guessing.",
     inputSchema: {
       type: "object",
       properties: {
@@ -166,6 +273,8 @@ export const TOOLS = [
         effect: { type: "string" },
         note: { type: "string", description: "What was measured, and how." },
         kind: { type: "string", enum: ["event", "correction"], description: "Default event." },
+        withdrawn: { type: "array", items: { type: "string" }, description: "For corrections: the exact strings that were withdrawn (a number, a name, a claim). The guard hook blocks an edit that writes them back." },
+        replacement: { type: "array", items: { type: "string" }, description: "For corrections: the corrected value(s). An edit containing both a withdrawn term and a replacement (a comparison or disavowal) is allowed through the guard." },
         tags: { type: "array", items: { type: "string" } },
         pinned: { type: "boolean", description: "Never decays out of the brief." },
       },
@@ -216,7 +325,7 @@ async function dispatch(msg) {
     return ok(id, {
       protocolVersion: SUPPORTED.includes(wanted) ? wanted : SUPPORTED[0],
       capabilities: { tools: {} },
-      serverInfo: { name: "memory-pulse", version: "0.1.5" },
+      serverInfo: { name: "memory-pulse", version: "0.2.0" },
     });
   }
   if (method === "notifications/initialized" || method === "initialized") return;
@@ -244,6 +353,9 @@ async function cliBrief() {
   try {
     const out = await callApi("/v1/pulse", { events, tier: process.env.MEMORY_PULSE_BRIEF_TIER || "brief" });
     if (out.text) process.stdout.write(out.text + "\n");
+    if (Array.isArray(out.quarantined) && out.quarantined.length) {
+      process.stdout.write(`⚠ ${out.quarantined.length} note(s) quarantined — instruction-like content was not rendered (t=${out.quarantined.map((q) => q.t).join(", ")})\n`);
+    }
     const foot = telemetryFooter(out.telemetry);
     if (foot) process.stdout.write(foot + "\n");
   } catch (e) {
@@ -267,7 +379,7 @@ async function cliStats() {
   console.log(`  tokens saved (est.)     ~${k.tokensSavedEst.toLocaleString()}`);
   if (c.reset) console.log(`  note: ${c.reset}`);
   try {
-    const res = await fetch(`${API}/v1/verify-telemetry`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ telemetry: c }) });
+    const res = await postJson(`${API}/v1/verify-telemetry`, { "content-type": "application/json" }, JSON.stringify({ telemetry: c }));
     const v = await res.json();
     console.log(v.valid ? "  signature               ✓ verified by the engine (keyless check anyone can repeat)" : `  signature               ✗ ${v.reason ?? "invalid"}`);
   } catch { console.log("  signature               ? engine unreachable"); }
@@ -281,27 +393,138 @@ function cliBadge() {
   console.log(`[![memory-pulse](https://img.shields.io/badge/memory--pulse-${label}-6366f1)](https://pulse.strategic-innovations.ai)`);
 }
 
+// ---------------------------------------------------------------- guard ----
+// `npx memory-pulse guard` — a Claude Code PreToolUse hook for Edit/Write.
+// Surfacing a correction is not enough (agents re-violate corrections they
+// were just shown); this ENFORCES it: an edit that writes back a withdrawn
+// term is blocked (exit 2) and the agent is told which ledger line retired
+// it and when. Deterministic, offline, only explicit `withdrawn` terms count.
+const violationsPath = () => join(dirname(ledgerPath()), "violations.jsonl");
+function textOfToolInput(input) {
+  if (!input || typeof input !== "object") return "";
+  const parts = [];
+  if (typeof input.new_string === "string") parts.push(input.new_string);
+  if (typeof input.content === "string") parts.push(input.content);
+  if (Array.isArray(input.edits)) for (const e of input.edits) if (typeof e?.new_string === "string") parts.push(e.new_string);
+  return parts.join("\n");
+}
+export function findViolations(events, text, filePath = "") {
+  const hits = [];
+  if (!text) return hits;
+  // The ledger and its sidecars are where corrections are RECORDED; guarding
+  // them would block the act of correcting.
+  if (/(^|[\\/])\.memory-pulse([\\/]|$)/.test(filePath)) return hits;
+  for (const e of events) {
+    if (e.kind !== "correction" || !Array.isArray(e.withdrawn)) continue;
+    // A comparison or disavowal names the old value next to the new one;
+    // only a bare reintroduction is blocked. (Adversarial review, 2026-08-31:
+    // a guard that fires on "the $49 figure is withdrawn" livelocks the agent.)
+    const disavowed = Array.isArray(e.replacement) && e.replacement.some((r) => r && text.includes(r));
+    if (disavowed) continue;
+    for (const term of e.withdrawn) if (term && text.includes(term)) hits.push({ term, t: e.t, cause: e.cause, effect: e.effect, note: e.note ?? "", replacement: e.replacement ?? [] });
+  }
+  return hits;
+}
+async function cliGuard() {
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+  let payload; try { payload = JSON.parse(raw); } catch { return; } // not a hook call: allow
+  const text = textOfToolInput(payload.tool_input);
+  const { events } = readEvents();
+  const file = payload.tool_input?.file_path ?? "";
+  const hits = findViolations(events, text, file);
+  if (!hits.length) return;
+  try { appendFileSync(violationsPath(), JSON.stringify({ at: new Date().toISOString(), file, hits: hits.map((h) => ({ term: h.term, t: h.t })) }) + "\n"); } catch { /* reporting is best effort */ }
+  const lines = hits.map((h) => `  • "${h.term}" was withdrawn at ledger t${h.t} (${h.cause} -> ${h.effect})${h.note ? `: ${h.note}` : ""}${h.replacement?.length ? ` — use ${h.replacement.join(" / ")}` : ""}`);
+  process.stderr.write(`memory-pulse guard: this edit reintroduces a withdrawn value.\n${lines.join("\n")}\nUse the corrected value (mentioning both old and new in a comparison is fine), or record a new correction if the old one is wrong.\n`);
+  process.exit(2);
+}
+
+// `npx memory-pulse report` — correction re-violation scoreboard, computed
+// on your machine from files you own. Nothing is sent anywhere.
+function cliReport() {
+  const { events } = readEvents();
+  const corrections = events.filter((e) => e.kind === "correction");
+  let blocks = [];
+  try { blocks = readFileSync(violationsPath(), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)); } catch { /* none yet */ }
+  const byT = new Map();
+  for (const b of blocks) for (const h of b.hits) byT.set(h.t, (byT.get(h.t) ?? 0) + 1);
+  console.log(`memory-pulse report — ${corrections.length} corrections recorded, ${corrections.filter((c) => c.withdrawn?.length).length} with enforceable withdrawn terms`);
+  console.log(`  edits blocked by the guard: ${blocks.reduce((n, b) => n + b.hits.length, 0)}${blocks.length ? ` (last: ${blocks[blocks.length - 1].at.slice(0, 10)})` : ""}`);
+  const top = [...byT.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+  for (const [t, n] of top) { const c = corrections.find((x) => x.t === t); console.log(`  ${n}× t${t} ${c ? `${c.cause} -> ${c.effect}` : ""} — withdrawn: ${c?.withdrawn?.join(", ")}`); }
+  const unenforced = corrections.filter((c) => !c.withdrawn?.length);
+  if (unenforced.length) console.log(`  ${unenforced.length} correction(s) have no withdrawn terms and cannot be enforced — add them with remember(withdrawn: [...])`);
+}
+
+// `npx memory-pulse bench` — instant measured metrics on YOUR ledger: how much
+// re-entry saves, whether every correction surfaces first, whether the guard
+// would block each withdrawn term, and recall self-consistency on your own
+// causal links. Numbers, not adjectives.
+async function cliBench() {
+  const { events } = readEvents();
+  if (!events.length) { console.log("no ledger — nothing to measure yet"); return; }
+  const corrections = events.filter((e) => e.kind === "correction");
+  const dump = JSON.stringify(events).length;
+  const pulse = await callApi("/v1/pulse", { events, tier: "brief" }).catch((e) => ({ error: e.message }));
+  console.log(`memory-pulse bench — ${events.length} events, ${corrections.length} corrections`);
+  if (pulse.error) { console.log(`  brief: unavailable (${pulse.error})`); }
+  else {
+    const lines = pulse.text.split("\n");
+    const first = lines.findIndex((l) => l.startsWith("CORRECTIONS"));
+    const headerN = Number((lines[first] ?? "").match(/CORRECTIONS \((\d+)\)/)?.[1] ?? 0);
+    const listed = corrections.filter((c) => pulse.text.includes(`${c.cause} -> ${c.effect}`)).length;
+    console.log(`  re-entry brief: ${pulse.chars.toLocaleString()} chars vs ${dump.toLocaleString()} char dump (${pulse.savedVsFullDump ?? "no saving on a ledger this small"})`);
+    console.log(`  corrections: ${headerN}/${corrections.length} counted in the block${first === 0 ? " (block is first)" : first > 0 ? ` (block at line ${first + 1})` : " (NO BLOCK — check this)"}, ${listed} listed at this tier${headerN > listed ? ` (${headerN - listed} elided — a bigger tier lists them all)` : ""}`);
+  }
+  const enforceable = corrections.filter((c) => c.withdrawn?.length);
+  const guardHits = enforceable.filter((c) => findViolations(events, c.withdrawn.join(" ")).length > 0).length;
+  console.log(`  guard: ${guardHits}/${enforceable.length} withdrawn-term sets would be blocked if rewritten${corrections.length > enforceable.length ? ` (${corrections.length - enforceable.length} corrections lack withdrawn terms)` : ""}`);
+  const sample = events.filter((e) => e.kind !== "correction").slice(-12);
+  let ok = 0, tried = 0, errors = 0, lastErr = "";
+  for (const e of sample) {
+    tried++;
+    // An API error is NOT a miss. Counting failures as misses would let a
+    // broken network read as a broken memory — report them separately.
+    let r;
+    try { r = await callApi("/v1/recall", { events, op: "effects", subject: e.cause, topk: 3 }); }
+    catch (err) { errors++; lastErr = String(err?.message ?? err); continue; }
+    if (r?.result?.hits?.some((h) => h.entity === e.effect)) ok++;
+  }
+  if (tried) console.log(`  recall self-consistency: ${ok}/${tried - errors} recent links recovered (top-5 effects of the cause include the recorded effect)${errors ? ` — ${errors} call(s) errored: ${lastErr.slice(0, 80)}` : ""}`);
+  console.log(`  telemetry: ${readTelemetry()?.counters ? "signed capsule present — run `stats`" : "none yet"}`);
+}
+
 // `npx memory-pulse install-hook` — make re-entry automatic: a Claude Code
 // SessionStart hook that runs the brief. Idempotent; merges, never clobbers.
 function cliInstallHook() {
-  const home = process.env.MEMORY_PULSE_SETTINGS_DIR || join(process.env.HOME || "", ".claude");
+  // --project writes to <repo>/.claude/settings.json so the hooks TRAVEL WITH
+  // THE REPO: a teammate who clones is guarded without installing anything.
+  // (Adversarial review, 2026-08-31: a user-scope hook does not spread.)
+  const project = process.argv.includes("--project");
+  const home = process.env.MEMORY_PULSE_SETTINGS_DIR || (project ? join(process.cwd(), ".claude") : join(process.env.HOME || "", ".claude"));
   const file = join(home, "settings.json");
   let settings = {};
   if (existsSync(file)) {
     try { settings = JSON.parse(readFileSync(file, "utf8")); }
     catch { console.error(`refusing to touch ${file}: it is not valid JSON`); process.exit(1); }
   }
-  const CMD = "npx -y memory-pulse brief";
   settings.hooks = settings.hooks || {};
-  const list = (settings.hooks.SessionStart = settings.hooks.SessionStart || []);
-  const present = JSON.stringify(list).includes(CMD);
-  if (present) { console.log("hook already installed — nothing to do"); return; }
-  list.push({ hooks: [{ type: "command", command: CMD }] });
+  let changed = 0;
+  const BRIEF = "npx -y memory-pulse brief";
+  const start = (settings.hooks.SessionStart = settings.hooks.SessionStart || []);
+  if (!JSON.stringify(start).includes(BRIEF)) { start.push({ hooks: [{ type: "command", command: BRIEF }] }); changed++; }
+  const GUARD = "npx -y memory-pulse guard";
+  const pre = (settings.hooks.PreToolUse = settings.hooks.PreToolUse || []);
+  if (!JSON.stringify(pre).includes(GUARD)) { pre.push({ matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: GUARD }] }); changed++; }
+  if (!changed) { console.log("hooks already installed — nothing to do"); return; }
   mkdirSync(home, { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
-  console.log(`installed SessionStart hook in ${file}`);
-  console.log("Every Claude Code session now re-enters through the ledger automatically.");
-  console.log("Remove it any time by deleting the memory-pulse entry from hooks.SessionStart.");
+  console.log(`installed ${changed} hook(s) in ${file}`);
+  console.log("SessionStart: every session re-enters through the ledger automatically.");
+  console.log("PreToolUse (Edit/Write): an edit that writes back a withdrawn value is blocked and explained.");
+  console.log(project ? "Project-scoped: commit .claude/settings.json and every clone is guarded." : "Tip: `install-hook --project` writes the hooks into this repo so teammates inherit them.");
+  console.log("Remove either by deleting the memory-pulse entries from hooks.");
 }
 
 // Importable for tests; the transport runs only when this file is the entry
@@ -317,9 +540,12 @@ if (isMain) {
   const sub = process.argv[2];
   if (sub === "brief") { await cliBrief(); process.exit(0); }
   if (sub === "install-hook") { cliInstallHook(); process.exit(0); }
+  if (sub === "guard") { await cliGuard(); process.exit(0); }
+  if (sub === "report") { cliReport(); process.exit(0); }
+  if (sub === "bench") { await cliBench(); process.exit(0); }
   if (sub === "stats") { await cliStats(); process.exit(0); }
   if (sub === "badge") { cliBadge(); process.exit(0); }
-  if (sub && sub !== "serve") { console.error(`unknown command: ${sub} (try: brief, stats, badge, install-hook)`); process.exit(1); }
+  if (sub && sub !== "serve") { console.error(`unknown command: ${sub} (try: brief, guard, report, bench, stats, badge, install-hook)`); process.exit(1); }
   process.stderr.write(`memory-pulse: ledger ${ledgerPath()} — api ${API}\n`);
   const rl = readline.createInterface({ input: process.stdin, terminal: false });
   // In-flight calls are drained before exit. Exiting the moment stdin closes