memory-pulse 0.1.9 → 0.2.0

package/README.md

@@ -107,6 +107,13 @@ to respect the guard.
   (`.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.
+- **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

package/package.json

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

@@ -22,6 +22,7 @@
 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";
@@ -132,6 +133,32 @@ export function telemetryFooter(c) {
   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
@@ -142,10 +169,14 @@ export function telemetryFooter(c) {
 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, "content-length": Buffer.byteLength(payload), connection: "close" },
+      headers: { ...headers, ...(gz ? { "content-encoding": "gzip" } : {}), "content-length": body.length, connection: "close" },
     }, (res) => {
       let data = "";
       res.setEncoding("utf8");
@@ -153,7 +184,7 @@ function postJson(url, headers, payload) {
       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(payload);
+    req.end(body);
   });
 }
 
@@ -171,7 +202,9 @@ async function postJsonRetry(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 postJsonRetry(`${API}${route}`, { "content-type": "application/json", ...(KEY ? { "x-mp-key": KEY } : {}) }, JSON.stringify(body));
@@ -184,6 +217,7 @@ async function callApi(route, body) {
   }
   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}`;
@@ -291,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.9" },
+      serverInfo: { name: "memory-pulse", version: "0.2.0" },
     });
   }
   if (method === "notifications/initialized" || method === "initialized") return;