memory-pulse 0.1.9 → 0.2.1

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.1",
   "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";
@@ -51,18 +52,18 @@ function readEvents() {
   return { path, events };
 }
 
-// The engine's injection-through-memory list, mirrored so a refusal happens
+// The engine's memory-safety checks, 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],
+  ["protect-instructions", /\b(ignore|disregard|forget)\b[^.\n]{0,40}\b(previous|prior|above|all|earlier)\b[^.\n]{0,20}\b(instructions?|rules?|prompts?)\b/i],
+  ["protect-role", /\byou are now\b|\bfrom now on,? you\b|\bact as (an?|the) (system|admin|developer)\b/i],
+  ["protect-boundaries", /<\/?\s*(system|assistant|tool|user|human|developer)\s*>|\[(system|assistant|tool)\s*:?\s*\]/i],
+  ["protect-configuration", /\b(reveal|print|show|dump)\b[^.\n]{0,30}\b(system prompt|hidden prompt|your instructions)\b/i],
+  ["protect-execution", /\b(run|execute|paste)\b[^.\n]{0,25}\b(this|the following)\b[^.\n]{0,15}\b(command|script|shell|code)\b/i],
+  ["protect-installs", /\b(curl|wget)\b[^\n]{0,120}\|\s*(sudo\s+)?(sh|bash|zsh)\b/i],
+  ["protect-data", /\b(rm\s+-rf\s+[\/~]|drop\s+table|truncate\s+table|format\s+c:)/i],
+  ["protect-credentials", /\b(send|post|upload|exfiltrat\w*|leak|forward|email)\b[^.\n]{0,40}\b(api[\s_-]?keys?|secrets?|tokens?|passwords?|credentials?)\b[^.\n]{0,40}\b(to|via|at)\b[^.\n]{0,4}(https?:\/\/|[\w.-]+@[\w.-]+\b|this\b|the following\b|that (address|url|endpoint|server)\b|me\b)|\b(send|give|show|tell) me\b[^.\n]{0,30}\b(api[\s_-]?keys?|secrets?|tokens?|passwords?|credentials?)\b/i ],
+  ["protect-transparency", /\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 [];
@@ -128,10 +129,41 @@ const fmtK = (n) => (n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 10
 export function telemetryFooter(c) {
   const k = c?.counters;
   if (!k || !k.calls) return "";
-  const drift = c.drift?.reasons?.length ? ` · ⚠ drift: ${c.drift.reasons.join("; ")}` : "";
+  // Quarantine is printed on its own line by the brief; the footer carries
+  // the drift reasons that are actually about the ledger changing.
+  const reasons = (c.drift?.reasons ?? []).filter((r) => !/quarantined/.test(r));
+  const drift = reasons.length ? ` · ⚠ 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.
+    // Only in the default layout: a custom ledger directory is the user's to
+    // manage, and this client does not leave files in it uninvited.
+    const gi = join(dir, ".gitignore");
+    if (dir.endsWith(".memory-pulse") && !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 +174,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 +189,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 +207,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 +222,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 +330,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.1" },
     });
   }
   if (method === "notifications/initialized" || method === "initialized") return;