memory-pulse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Travis Crew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# memory-pulse
+
+Causal project memory for coding agents — built for the thing MCP memory
+servers usually get wrong: **the cost of having it installed.**
+
+All four tools together cost **~2.5 KB (≈670 tokens) of definitions**
+(cert_c71bba29493a). A test in this repo fails if they ever exceed 4 KB. Compare that to what a typical
+MCP setup already burns before you type your first prompt — independent
+measurements put 5–10 installed servers at [50–67k tokens of tool definitions](https://getunblocked.com/blog/mcp-token-budget-autopsy/),
+a third of a 200k context window.
+
+## What it does
+
+Your agent's session ends and everything it learned dies with it. memory-pulse
+gives it a ledger of **cause → effect** events in a local file, and four tools:
+
+| tool | what it does | runs |
+|---|---|---|
+| `remember` | record a finding (or a **correction**) | locally, offline |
+| `pulse` | re-enter the project: a ranked brief instead of re-reading history | hosted engine |
+| `recall` | what caused X? what did X cause? when was the link strongest? | hosted engine |
+| `execute` | run JS against memory in a sandbox; only the return value enters context | hosted engine |
+
+Two design decisions do the heavy lifting:
+
+**Corrections come first, always.** An event recorded with
+`kind: "correction"` outranks everything at every brief size and never decays.
+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.
+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):
+
+```
+/plugin marketplace add t-crew/memory-pulse
+/plugin install memory-pulse@memory-pulse
+```
+
+**Codex CLI / Cursor / any MCP client** — clone this repo and point at it
+(zero dependencies, nothing to build):
+
+```
+git clone https://github.com/t-crew/memory-pulse
+```
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.memory-pulse]
+command = "node"
+args = ["/path/to/memory-pulse/server.mjs"]
+```
+
+For other clients: stdio server, command `node /path/to/memory-pulse/server.mjs`.
+
+Then just tell your agent to remember things, and start sessions with "pulse
+the memory". It figures the rest out from the tool descriptions.
+
+## What runs where (the privacy contract)
+
+- Your ledger is a **local file**: `.memory-pulse/events.jsonl` in your
+  project. Commit it, grep it, delete it — it's yours.
+- `remember` writes to it directly and **works offline**.
+- Read operations send the ledger's events to the hosted engine over TLS,
+  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.
+
+## Pricing
+
+- **Free** — ledgers up to 500 events, 200 reads/day. No account, no key.
+- **Pro ($19/mo)** — ledgers to 20,000 events, unlimited reads. One env var:
+  `MEMORY_PULSE_KEY`.
+
+Local writes are free forever either way.
+
+## Measured, on our own ledger
+
+We run memory-pulse on the 767-event, 1.08 MB ledger of the project that
+builds it. On that corpus (pinned run cert_c71bba29493a):
+
+- A cross-referencing question answered through `execute` returned **124
+  chars** against the 1,080,983-char full dump — the intermediates never
+  entered context.
+- Re-entry briefs at the smallest tier run **~99% smaller** than reading the
+  ledger in.
+- On our recall benchmark (351 distinct causes), the noise-floor gate returned
+  **zero wrong top answers** — when it couldn't clear the floor, it returned
+  nothing instead.
+
+Your ratios scale with ledger size — a ledger ten events old has nothing to
+compress. The methodology lives in the engine's benchmark suite and the
+numbers above are from pinned run cert_c71bba29493a, not a projection.
+
+## FAQ
+
+**Why is the engine hosted?** The ranking engine is the part that took the
+research. The tradeoff we chose: local ledger + thin auditable client +
+hosted engine, over shipping a weaker local ranker. If the engine being remote
+is a dealbreaker, `MEMORY_PULSE_API` points the client anywhere.
+
+**What about team memory?** Commit `.memory-pulse/` to the repo. Your
+teammates' agents pulse the same ledger. (Shared hosted ledgers are on the
+roadmap.)
+
+**License?** Client: MIT. Engine: proprietary, hosted.
+
+MIT © Travis Crew

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "memory-pulse",
+  "version": "0.1.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": { "memory-pulse": "./server.mjs" },
+  "files": ["server.mjs", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test test/*.test.js" },
+  "keywords": ["mcp", "modelcontextprotocol", "memory", "claude-code", "codex", "agent-memory", "context", "token-savings"],
+  "author": "Travis Crew",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/t-crew/memory-pulse.git" },
+  "engines": { "node": ">=18" }
+}

package/server.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * memory-pulse — MCP server (stdio) for Claude Code, Codex, Cursor, and any
+ * MCP client.
+ *
+ * What runs where, stated plainly because it is the privacy contract:
+ *
+ *   - Your ledger is a local file: .memory-pulse/events.jsonl in your project.
+ *     `remember` writes to it directly and works offline.
+ *   - Read operations (pulse / recall / execute) send the ledger's events to
+ *     the hosted engine over TLS, 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. No SDK, no dependencies, ~300 lines
+ *     you can read in one sitting.
+ *
+ * Config (env):
+ *   MEMORY_PULSE_KEY     license key (optional — free tier without one)
+ *   MEMORY_PULSE_API     override the API base (default: hosted service)
+ *   MEMORY_PULSE_LEDGER  override the ledger path (default: ./.memory-pulse/events.jsonl)
+ */
+import readline from "node:readline";
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+
+const API = (process.env.MEMORY_PULSE_API ?? "https://memory-pulse.strategic-innovations.workers.dev").replace(/\/$/, "");
+const KEY = process.env.MEMORY_PULSE_KEY ?? null;
+
+// ---------------------------------------------------------------- ledger ----
+function ledgerPath() {
+  const env = process.env.MEMORY_PULSE_LEDGER;
+  if (env) return isAbsolute(env) ? env : join(process.cwd(), env);
+  return join(process.cwd(), ".memory-pulse", "events.jsonl");
+}
+
+function readEvents() {
+  const path = ledgerPath();
+  if (!existsSync(path)) return { path, events: [] };
+  const events = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const s = line.trim();
+    if (!s) continue;
+    try {
+      const e = JSON.parse(s);
+      if (typeof e.cause === "string" && typeof e.effect === "string") events.push(e);
+    } catch { /* a torn line does not take the ledger down */ }
+  }
+  return { path, events };
+}
+
+function appendEvent({ cause, effect, note, kind, tags, pinned }) {
+  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 };
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, "");
+  }
+  const t = events.reduce((m, e) => Math.max(m, e.t ?? 0), 0) + 1;
+  const event = { t, cause, effect, kind: kind || "event" };
+  if (note) event.note = note;
+  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 };
+}
+
+// ------------------------------------------------------------------- api ----
+async function callApi(route, body) {
+  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 {
+    throw new Error(
+      "memory-pulse API unreachable. `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) {
+    let msg = out.error ?? `API error ${res.status}`;
+    if (out.upgrade) msg += ` — upgrade: ${out.upgrade}`;
+    throw new Error(msg);
+  }
+  return out;
+}
+
+// ----------------------------------------------------------------- tools ----
+const TIERS = ["index", "brief", "notes", "full"];
+export const TOOLS = [
+  {
+    name: "pulse",
+    description:
+      "Re-enter a project without reading its history into context. Returns a salience-ranked brief " +
+      "that ALWAYS carries every recorded correction first, so a superseded number cannot be quoted by " +
+      "accident. Call this before answering questions about prior work.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tier: { type: "string", enum: TIERS, description: "index (smallest) → full. Default brief." },
+        root: { type: "string", description: "Entity to centre the causal front on." },
+      },
+    },
+  },
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        op: { type: "string", enum: ["effects", "causes", "pulse", "when"] },
+        subject: { type: "string", description: "Entity to query." },
+        object: { type: "string", description: "Second entity — required by 'when', which scores an edge." },
+        topk: { type: "number", description: "Max hits. Default 5." },
+      },
+      required: ["op", "subject"],
+    },
+  },
+  {
+    name: "remember",
+    description:
+      "Record a finding so the next session starts with it. Use kind='correction' when a claim is " +
+      "withdrawn or a number is superseded — corrections are surfaced first at every tier and never decay. " +
+      "Cheap, idempotent, and fully local (works offline).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cause: { type: "string" },
+        effect: { type: "string" },
+        note: { type: "string", description: "What was measured, and how." },
+        kind: { type: "string", enum: ["event", "correction"], description: "Default event." },
+        tags: { type: "array", items: { type: "string" } },
+        pinned: { type: "boolean", description: "Never decays out of the brief." },
+      },
+      required: ["cause", "effect"],
+    },
+  },
+  {
+    name: "execute",
+    description:
+      "Run a JavaScript program against memory in a sandbox; ONLY its return value enters context. " +
+      "Use for questions needing many lookups — filtering, counting, cross-referencing — where the " +
+      "intermediates would otherwise cost more than the answer. `ctx.memory.effects|causes|pulse|when` " +
+      "are available and async. Example: return (await ctx.memory.effects('x')).hits.length",
+    inputSchema: {
+      type: "object",
+      properties: { program: { type: "string", description: "Body of an async function; must return." } },
+      required: ["program"],
+    },
+  },
+];
+
+export async function handleCall(name, args = {}) {
+  if (name === "remember") {
+    if (!args.cause || !args.effect) throw new Error("remember needs both cause and effect");
+    return appendEvent(args);
+  }
+
+  const { path, events } = readEvents();
+  if (!events.length) return { empty: true, ledger: path, hint: "Nothing recorded yet — use `remember` to start." };
+
+  if (name === "pulse") return callApi("/v1/pulse", { events, tier: args.tier, root: args.root });
+  if (name === "recall") return callApi("/v1/recall", { events, op: args.op, subject: args.subject, object: args.object, topk: args.topk });
+  if (name === "execute") return callApi("/v1/execute", { events, program: args.program });
+  throw new Error(`unknown tool: ${name}`);
+}
+
+// ------------------------------------------------------- stdio transport ----
+// STDOUT IS THE PROTOCOL. Never console.log here; diagnostics go to stderr.
+const SUPPORTED = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const ok = (id, result) => send({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+async function dispatch(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    const wanted = params?.protocolVersion;
+    return ok(id, {
+      protocolVersion: SUPPORTED.includes(wanted) ? wanted : SUPPORTED[0],
+      capabilities: { tools: {} },
+      serverInfo: { name: "memory-pulse", version: "0.1.0" },
+    });
+  }
+  if (method === "notifications/initialized" || method === "initialized") return;
+  if (method === "ping") return ok(id, {});
+  if (method === "tools/list") return ok(id, { tools: TOOLS });
+  if (method === "tools/call") {
+    const { name, arguments: args } = params || {};
+    try {
+      const result = await handleCall(name, args || {});
+      return ok(id, { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });
+    } catch (e) {
+      return ok(id, { content: [{ type: "text", text: String(e?.message ?? e) }], isError: true });
+    }
+  }
+  if (id !== undefined) fail(id, -32601, `method not found: ${method}`);
+}
+
+// Importable for tests; only run the transport when invoked as a binary.
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop())) {
+  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
+  // would kill network requests mid-flight and swallow their responses — found
+  // by piping a scripted session rather than assuming the happy path.
+  const inflight = new Set();
+  rl.on("line", (line) => {
+    const s = line.trim();
+    if (!s) return;
+    let msg;
+    try { msg = JSON.parse(s); }
+    catch { process.stderr.write("memory-pulse: dropped malformed line\n"); return; }
+    const job = dispatch(msg)
+      .catch((e) => { if (msg && msg.id !== undefined) fail(msg.id, -32603, String(e?.message ?? e)); })
+      .finally(() => inflight.delete(job));
+    inflight.add(job);
+  });
+  rl.on("close", async () => {
+    await Promise.allSettled([...inflight]);
+    process.exit(0);
+  });
+  process.on("uncaughtException", (e) => process.stderr.write(`memory-pulse: ${e.stack}\n`));
+}