memory-pulse 0.1.3 → 0.1.5

package/README.md

@@ -32,36 +32,47 @@ Two design decisions do the heavy lifting:
 The failure this prevents: your agent confidently quotes the benchmark number
 you withdrew three sessions ago.
 
-**Silence beats a wrong answer.** Recall is gated by a measured noise floor.
+**Silence beats a wrong answer.** When recall isn't confident enough, it returns nothing rather than guessing.
 When the answer isn't there, you get nothing — not a plausible guess.
 
 ## Install
 
-**Claude Code** (plugin — no npm needed, installs straight from this repo):
+**Any MCP client, one line** (Claude Code shown):
 
 ```
-/plugin marketplace add t-crew/memory-pulse
-/plugin install memory-pulse@memory-pulse
+claude mcp add memory-pulse -- npx -y memory-pulse
 ```
 
-**Codex CLI / Cursor / any MCP client** — clone this repo and point at it
-(zero dependencies, nothing to build):
+**Make re-entry automatic** — a Claude Code SessionStart hook that runs the
+brief before your first prompt (idempotent; merges into your settings, never
+clobbers them; silent in projects that have no ledger):
 
 ```
-git clone https://github.com/t-crew/memory-pulse
+npx memory-pulse install-hook
 ```
 
-```toml
-# Codex: ~/.codex/config.toml
-[mcp_servers.memory-pulse]
-command = "node"
-args = ["/path/to/memory-pulse/server.mjs"]
+**Claude Code plugin** (installs straight from this repo, hook included):
+
+```
+/plugin marketplace add t-crew/memory-pulse
+/plugin install memory-pulse@memory-pulse
 ```
 
-For other clients: stdio server, command `node /path/to/memory-pulse/server.mjs`.
+**Codex CLI / Cursor / other clients** — stdio server, command
+`npx -y memory-pulse` (or clone this repo and run `node /path/to/server.mjs`).
+
+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.
+
+### Commands
 
-Then just tell your agent to remember things, and start sessions with "pulse
-the memory". It figures the rest out from the tool descriptions.
+```
+npx memory-pulse brief          # the re-entry brief (what the hook prints)
+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
+```
 
 ## What runs where (the privacy contract)
 
@@ -72,8 +83,11 @@ the memory". It figures the rest out from the tool descriptions.
   which computes the answer and forgets the request. **The service keeps no
   database of your memory** — state arrives in the request and leaves in the
   response.
-- This client is the entire client: ~300 lines, zero dependencies, read it in
-  one sitting.
+- Telemetry is a **signed capsule beside your ledger**
+  (`.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.
 
 ## Pricing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-pulse",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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

@@ -69,8 +69,33 @@ function appendEvent({ cause, effect, note, kind, tags, pinned }) {
   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}`, {
@@ -85,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}`;
@@ -114,8 +140,8 @@ export const TOOLS = [
     name: "recall",
     description:
       "Query the causal graph: what an event caused (effects), what caused it (causes), a multi-hop " +
-      "wavefront (pulse), or when an edge was strongest (when). Returns nothing rather than guessing " +
-      "when the answer is below the noise floor.",
+      "chain (pulse), or when a link was strongest (when). Returns nothing rather than guessing " +
+      "when the answer is not confident enough.",
     inputSchema: {
       type: "object",
       properties: {
@@ -190,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.3" },
+      serverInfo: { name: "memory-pulse", version: "0.1.5" },
     });
   }
   if (method === "notifications/initialized" || method === "initialized") return;
@@ -218,12 +244,43 @@ 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");
+    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() {
@@ -260,7 +317,9 @@ 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 && sub !== "serve") { console.error(`unknown command: ${sub} (try: brief, install-hook)`); process.exit(1); }
+  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