memory-pulse 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-pulse",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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": {
@@ -34,4 +34,4 @@
     "node": ">=18"
   },
   "mcpName": "io.github.t-crew/memory-pulse"
-}
+}

package/server.mjs

@@ -63,11 +63,39 @@ function appendEvent({ cause, effect, note, kind, tags, pinned }) {
   if (Array.isArray(tags) && tags.length) event.tags = tags;
   if (pinned) event.pinned = true;
   appendFileSync(path, JSON.stringify(event) + "\n");
-  return { written: true, t, ledger: path };
+  // 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
+  // actually holds without re-reading the file.
+  return { written: true, t, ledger: path, stored: event };
+}
+
+// ------------------------------------------------------------- telemetry ----
+// The engine keeps no database, so telemetry lives HERE, beside your ledger,
+// as a signed capsule the engine advances on every read call and hands back.
+// You own it; delete the file and it restarts from zero.
+const telemetryPath = () => join(dirname(ledgerPath()), "telemetry.rain");
+function readTelemetry() {
+  try { return JSON.parse(readFileSync(telemetryPath(), "utf8")); } catch { return null; }
+}
+function writeTelemetry(capsule) {
+  if (!capsule || typeof capsule !== "object") return;
+  try {
+    mkdirSync(dirname(telemetryPath()), { recursive: true });
+    writeFileSync(telemetryPath(), JSON.stringify(capsule, null, 2) + "\n");
+  } catch { /* telemetry is a convenience; a read-only checkout must not break a read call */ }
+}
+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) {
+  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)`;
 }
 
 // ------------------------------------------------------------------- api ----
 async function callApi(route, body) {
+  const prior = readTelemetry();
+  body = { ...body, project: projectName(), ...(prior ? { telemetry: prior } : {}) };
   let res;
   try {
     res = await fetch(`${API}${route}`, {
@@ -82,6 +110,7 @@ async function callApi(route, body) {
     );
   }
   const out = await res.json().catch(() => ({}));
+  if (res.ok && out.telemetry) { writeTelemetry(out.telemetry); }
   if (!res.ok) {
     let msg = out.error ?? `API error ${res.status}`;
     if (out.upgrade) msg += ` — upgrade: ${out.upgrade}`;
@@ -187,7 +216,7 @@ async function dispatch(msg) {
     return ok(id, {
       protocolVersion: SUPPORTED.includes(wanted) ? wanted : SUPPORTED[0],
       capabilities: { tools: {} },
-      serverInfo: { name: "memory-pulse", version: "0.1.2" },
+      serverInfo: { name: "memory-pulse", version: "0.1.4" },
     });
   }
   if (method === "notifications/initialized" || method === "initialized") return;
@@ -205,6 +234,76 @@ async function dispatch(msg) {
   if (id !== undefined) fail(id, -32601, `method not found: ${method}`);
 }
 
+// ------------------------------------------------------------------ cli ----
+// `npx memory-pulse brief` — print the re-entry brief and exit. Built for
+// SessionStart hooks: SILENT no-op (exit 0) when the project has no ledger,
+// so installing the hook never adds noise to projects that don't use this.
+async function cliBrief() {
+  const { events } = readEvents();
+  if (!events.length) return;
+  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");
+    const foot = telemetryFooter(out.telemetry);
+    if (foot) process.stdout.write(foot + "\n");
+  } catch (e) {
+    // A dead network must not break session start — say so in one line.
+    process.stdout.write(`memory-pulse: brief unavailable (${String(e?.message ?? e).split(".")[0]})\n`);
+  }
+}
+
+// `npx memory-pulse stats` — the signed telemetry capsule, verified keylessly
+// against the engine so the numbers you share are numbers we signed.
+async function cliStats() {
+  const c = readTelemetry();
+  if (!c) { console.log("no telemetry yet — run a pulse first"); return; }
+  const k = c.counters;
+  console.log(`memory-pulse telemetry for "${c.project}" (${c.since.slice(0, 10)} → ${c.updated.slice(0, 10)})`);
+  console.log(`  re-entries (pulse)      ${k.pulse}`);
+  console.log(`  recall / execute        ${k.recall} / ${k.execute}`);
+  console.log(`  corrections recorded    ${k.correctionsRecorded}`);
+  console.log(`  corrections surfaced    ${k.correctionsSurfaced}`);
+  console.log(`  largest ledger seen     ${k.maxEvents} events`);
+  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 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"); }
+}
+
+// `npx memory-pulse badge` — a README badge from your own signed numbers.
+function cliBadge() {
+  const c = readTelemetry();
+  const n = c?.counters?.tokensSavedEst ?? 0;
+  const label = `${fmtK(n)}_tokens_saved`.replace(/-/g, "--");
+  console.log(`[![memory-pulse](https://img.shields.io/badge/memory--pulse-${label}-6366f1)](https://pulse.strategic-innovations.ai)`);
+}
+
+// `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");
+  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 }] });
+  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.");
+}
+
 // Importable for tests; the transport runs only when this file is the entry
 // point. Compared by REALPATH, not by name: npm invokes the bin through a
 // .bin/memory-pulse symlink, and a basename comparison silently failed there —
@@ -215,6 +314,12 @@ try {
   isMain = Boolean(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
 } catch { /* argv[1] missing or unreadable — we are being imported */ }
 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 === "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); }
   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