web-TTT: browser-native test-time-trainable memory toolkit

README.md

@@ -0,0 +1,71 @@
+---
+license: mit
+tags:
+- web-ttt
+- test-time-training
+- in-browser
+- webgpu
+- associative-memory
+- minilm
+- transformers-js
+library_name: transformers.js
+---
+
+# web-TTT — a browser-native, test-time-TRAINABLE memory
+
+A tiny method + toolkit for an associative memory that **learns from use, entirely in the browser** — no server, no API, no backend. To our knowledge, the first published browser-trainable **TTT (test-time training)** memory.
+
+It is the memory layer behind a fully in-browser AI companion, extracted here as a clean, reusable method you can drop onto **any** corpus (it does **not** contain anyone's private data — just the process + a generic demo).
+
+## The idea
+
+- **Embed** each fact with `Xenova/all-MiniLM-L6-v2` (via [transformers.js](https://github.com/huggingface/transformers.js)) → a 384-d vector.
+- **Recall** a query as `score(fact) = cosine( normalize(W · embed(query)) , fact_vec )`, top-K — where **W** is a learnable 384×384 projection matrix (identity at first).
+- **Train at test time:** clicking a result runs ~25 steps of cross-entropy gradient descent on **W**, pulling that query toward that fact. The matrix learns which queries should surface which memories — **on the user's device, in the browser.** `W` persists in `localStorage`, so the memory keeps what you taught it across sessions.
+
+That's the whole thing: a frozen embedder + a small matrix you train by example, live, client-side. It runs on WebGPU/WASM and needs nothing but a browser.
+
+## Files
+
+- `web-ttt.js` — the toolkit (ES module). `WebTTT` class: `init()`, `load(corpus)`, `recall(query, k)`, `teach(query, targetIndex)`, `exportW()/importW()/resetW()`.
+- `demo/index.html` + `demo/facts.json` — a working demo on a generic corpus.
+
+## Quick start
+
+```js
+import { WebTTT } from "./web-ttt.js";
+
+const ttt = new WebTTT({ storageKey: "my_ttt" });
+await ttt.init();                                   // loads MiniLM (CDN by default)
+await ttt.load([
+  { key: "the sun", text: "The Sun is the star at the center of the Solar System." },
+  { key: "the moon", text: "The Moon is Earth's only natural satellite." },
+]);
+
+const hits = await ttt.recall("what's at the center of the solar system?", 3);
+// → [{ key: "the sun", score: 0.6x, index: 0, ... }, ...]
+
+await ttt.teach("center of the solar system", 0);   // reinforce: 25-step W update, persists
+```
+
+Run the demo: serve the folder over `http://localhost` (WebGPU/transformers.js need a real origin, not `file://`) and open `demo/index.html` in Chrome/Edge/Brave.
+
+### Fully offline
+
+Pass local asset paths to `init()`:
+
+```js
+await ttt.init({
+  transformersUrl: "./vendor/transformers/transformers.min.js",
+  localModelPath: "./models/",          // contains Xenova/all-MiniLM-L6-v2
+  wasmPaths: "./vendor/transformers/",  // ort-wasm*.wasm
+});
+```
+
+## Format / publishing your own TTT
+
+A "trained TTT" is just: your corpus (`[{key, text}]`), optionally the precomputed 384-d `vec` per fact, and the learned `W` (384×384, from `exportW()`). Ship those three and any browser can load and keep training it. That's the publishable artifact — **the method, on your data, your choice.**
+
+## License
+
+MIT. The embedder (`Xenova/all-MiniLM-L6-v2`) and transformers.js carry their own licenses.

demo/facts.json

@@ -0,0 +1,10 @@
+[
+  { "key": "what is web-ttt", "text": "web-TTT is a browser-native, test-time-trainable associative memory: MiniLM embeddings plus a learnable projection matrix you train by example, in the browser, with no server." },
+  { "key": "how recall works", "text": "A query is embedded, projected through the learned matrix W, then matched by cosine similarity against each stored fact's embedding. The top matches are returned." },
+  { "key": "how training works", "text": "Click a fact to teach it: 25 steps of cross-entropy gradient descent run on W, pulling that query toward that fact. This is real test-time training, on the user's GPU/CPU." },
+  { "key": "where memory lives", "text": "Fact embeddings live in memory; the learned matrix W persists in the browser's localStorage. Nothing leaves the device." },
+  { "key": "the sun", "text": "The Sun is the star at the center of the Solar System, a near-perfect ball of hot plasma." },
+  { "key": "the moon", "text": "The Moon is Earth's only natural satellite and the brightest object in the night sky after the Sun." },
+  { "key": "photosynthesis", "text": "Photosynthesis is how plants convert light, water, and carbon dioxide into glucose and oxygen." },
+  { "key": "the ocean", "text": "Oceans cover about 71 percent of Earth's surface and hold the vast majority of its water." }
+]

demo/index.html

@@ -0,0 +1,53 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>web-TTT demo</title>
+  <style>
+    body { font: 15px/1.5 ui-sans-serif, system-ui, sans-serif; max-width: 760px; margin: 32px auto; padding: 0 16px; color: #1a1a1a; }
+    h1 { font-size: 20px; } code { background: #f0f0f0; padding: 1px 5px; border-radius: 4px; }
+    input { width: 70%; padding: 8px; } button { padding: 8px 12px; cursor: pointer; }
+    .hit { border: 1px solid #ddd; border-left: 4px solid #2f6f67; border-radius: 6px; padding: 8px 10px; margin: 8px 0; }
+    .hit b { display:block; } .hit .s { color:#888; font-size:12px; } .teach { color:#2f6f67; cursor:pointer; font-size:12px; }
+    #status { color:#888; }
+  </style>
+</head>
+<body>
+  <h1>web-TTT — browser-trainable memory</h1>
+  <p id="status">loading MiniLM…</p>
+  <div><input id="q" placeholder="ask something…" /> <button id="go" disabled>recall</button></div>
+  <div id="hits"></div>
+  <script type="module">
+    import { WebTTT } from "../web-ttt.js";
+    const status = document.getElementById("q.status") || document.getElementById("status");
+    const ttt = new WebTTT({ storageKey: "web_ttt_demo" });
+    let lastQuery = "";
+    (async () => {
+      await ttt.init();                                   // MiniLM from CDN
+      const facts = await (await fetch("./facts.json")).json();
+      await ttt.load(facts);
+      status.textContent = `ready — ${facts.length} facts embedded. Recall, then click "teach" on a result to reinforce it (trains W in your browser).`;
+      document.getElementById("go").disabled = false;
+    })();
+    async function run() {
+      lastQuery = document.getElementById("q").value.trim();
+      if (!lastQuery) return;
+      const hits = await ttt.recall(lastQuery, 5);
+      document.getElementById("hits").innerHTML = hits.map(h =>
+        `<div class="hit"><b>${h.key}</b><span class="s">score ${h.score.toFixed(3)}</span>
+         <p>${h.text}</p><span class="teach" data-i="${h.index}">teach ↩ (pull this query toward this memory)</span></div>`
+      ).join("");
+    }
+    document.getElementById("go").onclick = run;
+    document.getElementById("q").addEventListener("keydown", e => { if (e.key === "Enter") run(); });
+    document.getElementById("hits").addEventListener("click", async e => {
+      const t = e.target.closest(".teach"); if (!t) return;
+      status.textContent = "teaching…";
+      await ttt.teach(lastQuery, Number(t.dataset.i));
+      status.textContent = "learned — re-running recall.";
+      run();
+    });
+  </script>
+</body>
+</html>

web-ttt.js

@@ -0,0 +1,105 @@
+// web-ttt.js — a browser-native, test-time-TRAINABLE associative memory.
+//
+// MiniLM sentence embeddings + a learnable 384x384 projection matrix W.
+// Recall: score(fact) = cosine( normalize(W · embed(query)) , fact_vec ) -> top-K.
+// Train (test-time training): pull a query toward a target fact by cross-entropy
+// gradient descent on W, ~25 steps, ENTIRELY IN THE BROWSER. W persists in localStorage.
+// No server, no API, no backend. The memory learns from use, on the user's device.
+//
+// Usage:
+//   import { WebTTT } from "./web-ttt.js";
+//   const ttt = new WebTTT({ storageKey: "my_ttt" });
+//   await ttt.init();                          // loads MiniLM (transformers.js)
+//   await ttt.load([{ key, text }, ...]);      // embeds your corpus
+//   const hits = await ttt.recall("a query", 5);
+//   await ttt.teach("a query", hits[0].index); // 25-step W update, then persists
+//
+// Embeddings come from Xenova/all-MiniLM-L6-v2 via transformers.js. By default both
+// load from CDN; pass localModelPath/transformersUrl to run fully offline.
+
+const DIM = 384;
+const TEMP = 0.1;
+
+export class WebTTT {
+  constructor({ storageKey = "web_ttt" } = {}) {
+    this.facts = [];
+    this.W = null;
+    this.embed = null;
+    this.storageKey = storageKey;
+  }
+
+  async init({
+    transformersUrl = "https://cdn.jsdelivr.net/npm/@xenova/transformers@2.17.2",
+    model = "Xenova/all-MiniLM-L6-v2",
+    localModelPath = null,
+    wasmPaths = null,
+  } = {}) {
+    const mod = await import(transformersUrl);
+    const { pipeline, env } = mod;
+    if (localModelPath) { env.allowRemoteModels = false; env.localModelPath = localModelPath; }
+    if (wasmPaths) env.backends.onnx.wasm.wasmPaths = wasmPaths;
+    const ext = await pipeline("feature-extraction", model);
+    this.embed = async (t) =>
+      Array.from((await ext(t, { pooling: "mean", normalize: true })).data);
+    this.W = this._loadW() || this._eye();
+    return this;
+  }
+
+  // corpus: [{ key, text, vec? }]. If vec (384 floats) is provided it's used as-is.
+  async load(corpus) {
+    this.facts = [];
+    for (const f of corpus) {
+      const vec = Array.isArray(f.vec) && f.vec.length === DIM
+        ? f.vec
+        : await this.embed(`${f.key}. ${f.text || ""}`.slice(0, 512));
+      this.facts.push({ key: f.key, text: f.text || "", vec });
+    }
+    return this.facts.length;
+  }
+
+  async recall(query, k = 5) {
+    const q = this._l2(this._matvec(this.W, await this.embed(query)));
+    return this.facts
+      .map((f, i) => ({ key: f.key, text: f.text, index: i, score: this._dot(f.vec, q) }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, k);
+  }
+
+  // Reinforce: make `query` retrieve facts[targetIndex] more strongly. Real gradient descent on W.
+  async teach(query, targetIndex, steps = 25, lr = 0.3) {
+    if (targetIndex == null || targetIndex < 0 || targetIndex >= this.facts.length) return;
+    const qe = await this.embed(query);
+    for (let s = 0; s < steps; s++) this._teachStep(qe, targetIndex, lr);
+    this._saveW();
+  }
+
+  _teachStep(qe, target, lr) {
+    const qq = this._l2(this._matvec(this.W, qe));
+    const scores = this.facts.map((f) => this._dot(f.vec, qq));
+    const p = this._softmax(scores);
+    const g = new Float32Array(DIM);
+    for (let j = 0; j < this.facts.length; j++) {
+      const c = (p[j] - (j === target ? 1 : 0)) / TEMP;
+      const Kj = this.facts[j].vec;
+      for (let d = 0; d < DIM; d++) g[d] += c * Kj[d];
+    }
+    for (let r = 0; r < DIM; r++) {
+      const gr = lr * g[r];
+      if (gr === 0) continue;
+      const Wr = this.W[r];
+      for (let c = 0; c < DIM; c++) Wr[c] -= gr * qe[c];
+    }
+  }
+
+  exportW() { return this.W.map((r) => Array.from(r)); }       // the learned weights
+  importW(arr) { if (arr && arr.length === DIM) { this.W = arr.map((r) => Float32Array.from(r)); this._saveW(); } }
+  resetW() { this.W = this._eye(); this._saveW(); }
+
+  _eye() { const W = []; for (let r = 0; r < DIM; r++) { const row = new Float32Array(DIM); row[r] = 1; W.push(row); } return W; }
+  _loadW() { try { const s = localStorage.getItem(this.storageKey); if (s) { const a = JSON.parse(s); if (a.length === DIM) return a.map((r) => Float32Array.from(r)); } } catch (e) {} return null; }
+  _saveW() { try { localStorage.setItem(this.storageKey, JSON.stringify(this.W.map((r) => Array.from(r, (x) => Math.round(x * 1e4) / 1e4)))); } catch (e) {} }
+  _dot(a, b) { let s = 0; for (let i = 0; i < DIM; i++) s += a[i] * b[i]; return s; }
+  _matvec(W, v) { const o = new Float32Array(DIM); for (let r = 0; r < DIM; r++) o[r] = this._dot(W[r], v); return o; }
+  _l2(v) { let s = 0; for (let i = 0; i < DIM; i++) s += v[i] * v[i]; s = Math.sqrt(s) || 1; const o = new Float32Array(DIM); for (let i = 0; i < DIM; i++) o[i] = v[i] / s; return o; }
+  _softmax(s) { let m = -Infinity; for (const x of s) if (x > m) m = x; let z = 0; const p = s.map((x) => { const e = Math.exp((x - m) / TEMP); z += e; return e; }); return p.map((x) => x / z); }
+}