openzoo 0.2.0 → 0.3.0

package/README.md

@@ -89,13 +89,42 @@ Tools:
 npx openzoo demo
 ```
 
-Builds a ~965k-token document with one planted fact, shows that buying direct refuses it (*"The input token count exceeds the maximum number of tokens allowed."* — recorded, see [benches.openzoo.fun](https://benches.openzoo.fun)), then fetches the live x402 quote for the same body — the quote is free:
+Builds a ~965k-token document with one planted fact, shows that buying direct refuses it (*"The input token count exceeds the maximum number of tokens allowed."* — recorded, see [benches.openzoo.fun](https://benches.openzoo.fun)), binds the body ONCE to the zoo's holographic memory, then pays for a question that ships alone:
 
 ```
-quote: $0.009747 · pricing=counterfactual · direct would be $0.097474 · savesVsDirect=10.0×
+bound once in 14.8s: 3.7MB → context ctx_01KZZY8YQE…
+quote for the ask: $0.000480 · pricing=markup (3× a tiny body — the 3.7MB corpus is not re-priced)
 ```
 
-If the wallet is funded with USDC it pays (capped at `OPENZOO_DEMO_MAX_USD`, default $0.01) and prints the answer, the tokens the model actually read, and the receipt. If not, it prints exactly what to fund. Long waits (the multi-MB upload, pricing, payment, the answer) show a live progress line with stage + elapsed seconds.
+If the wallet is funded with USDC it pays (capped at `OPENZOO_DEMO_MAX_USD`, default $0.01) and prints the answer, the tokens the model actually read, and the receipt. If not, it prints exactly what to fund. Long waits (the one-time upload, pricing, payment, the answer) show a live progress line with stage + elapsed seconds.
+
+**Run it twice.** The second run finds the corpus in the local manifest and never uploads it:
+
+```
+★ corpus already bound (context ctx_01KZZY8YQE…) — skipped the 3.7MB upload entirely.
+...
+★ corpus already bound — skipped 3.7MB upload; whole run took 4.3s and cost $0.000480
+```
+
+## Repeat calls are near-free (0.3.0: the body never ships twice)
+
+The zoo keeps your corpus in leCore holographic memory; the shim keeps a manifest at `~/.openzoo/contexts.json` (chmod 600) mapping `sha256(corpus)` → the zoo's `context_id`, scoped per API base. When a request carries a corpus the manifest already knows:
+
+- **nothing big is uploaded** — the ask ships alone with an `X-HRR-Context` header,
+- **the 402 prices the tiny ask** (markup basis, honestly labeled `pricing=markup`), typically a few hundredths of a cent instead of re-pricing megabytes,
+- **the answer still comes from your corpus** — the zoo recalls the relevant slices server-side.
+
+This works in all three fronts: the **proxy** (a big pasted body in the last message is split at its last blank line, bound once, and reused on every later call — even with a different question), the **MCP** `zoo_ask` `corpus` parameter, and the **demo**. If the zoo ever forgets a context (sidecar wipe), the gateway answers 404 *before* any payment and the shim transparently re-binds once and retries — a stale manifest never fails a call.
+
+Manage it:
+
+```bash
+npx openzoo contexts                  # list bound corpora (hash, context id, age, api base)
+npx openzoo contexts --forget 60464d  # drop one by hash prefix
+npx openzoo contexts --forget all     # drop everything
+```
+
+Opt out with `OPENZOO_NO_CONTEXT_CACHE=1` (always ship the full body); tune the threshold with `OPENZOO_CONTEXT_MIN_CHARS` (default 16384 chars).
 
 ## The wallet model
 
@@ -110,6 +139,7 @@ If the wallet is funded with USDC it pays (capped at `OPENZOO_DEMO_MAX_USD`, def
 Two bases, reported per call in the 402 (`extra.pricing`):
 - **Short prompts price at a markup** (3× provider cost) — there's nothing to spill, you're paying for passthrough.
 - **Big bodies price at a counterfactual discount** (~10× cheaper than buying the same call direct) — the zoo's leCore memory means it never forwards your whole body upstream, and passes the savings on. Measured numbers at [benches.openzoo.fun](https://benches.openzoo.fun).
+- **Asks against a bound corpus price on the markup basis** (3× a tiny body — the receipt says `pricing=markup`). That is not a discount trick: 3× of a few hundred tokens is normally far below even the counterfactual price of shipping the corpus, which is the whole point of binding once.
 
 The receipt names which base you got; `extra.directUsd` / `extra.savesVsDirect` let you check the math.
 
@@ -134,12 +164,13 @@ The rail is chosen from the 402's `accepts[]` itself (Solana first). Amounts are
 | `OPENZOO_WALLET` | `~/.openzoo/wallet.json` | wallet path |
 | `OPENZOO_MAX_USD_PER_CALL` | `0.5` | refuse quotes above this |
 | `OPENZOO_DEMO_MAX_USD` | `0.01` | demo spend cap |
+| `OPENZOO_CONTEXT_MIN_CHARS` | `16384` | bodies bigger than this bind once + reuse |
+| `OPENZOO_NO_CONTEXT_CACHE` | `0` | set `1` to always ship the full body |
 | `OPENZOO_ENABLE_RH` | `0` | allow the Robinhood rail |
 
 ## What's tested
 
 - Unit tests run against a **captured production 402 body** (`test/fixtures/live-402.json`): parsing, rail selection, and byte-level verification of the signed Solana transaction and the EVM typed-data payload.
-- Live-verified: `/v1/models` through the proxy (200), 402 parse + quote + wallet check against mainnet, on-chain mint/decimals read, and full payment construction (signed, not broadcast) against a production quote.
-- **Not yet live-verified: an actual settled paid call** — this session's wallet was unfunded, so settlement (the facilitator accepting the signed transfer) is untested from this client. The construction matches the gateway's own documented flow byte-for-byte.
+- Live-verified: `/v1/models` through the proxy (200), 402 parse + quote against mainnet, on-chain mint/decimals read, the internal USDC conversion (funded from plain USDC, settled on mainnet), and **a real settled paid call** — the full demo ran end-to-end against the production gateway: quote, automatic top-up from USDC, payment accepted by the facilitator, answer + receipt returned.
 
 MIT

package/bin/openzoo.js

@@ -7,6 +7,9 @@ usage:
   npx openzoo            start the proxy on http://localhost:8402/v1
   npx openzoo mcp        stdio MCP server (tools: zoo_ask, zoo_models, zoo_wallet)
   npx openzoo demo       ~1M-token needle demo: direct refuses, the zoo answers
+                         (run it twice — the second run reuses the bound corpus and is near-free)
+  npx openzoo contexts   list corpora bound to the zoo (never re-uploaded)
+  npx openzoo contexts --forget <hash|all>   drop manifest entries
   npx openzoo balance    wallet balance (USDC + SOL, with USD value)
   npx openzoo address    print the funding address
   npx openzoo help       this text
@@ -19,6 +22,8 @@ env:
   OPENZOO_PORT (8402)  OPENZOO_API_BASE (https://x402-tokens.fly.dev)
   OPENZOO_RPC (mainnet-beta)  OPENZOO_TOKEN (402 rail preference)  OPENZOO_WALLET (~/.openzoo/wallet.json)
   OPENZOO_MAX_USD_PER_CALL (0.5)  OPENZOO_DEMO_MAX_USD (0.01)
+  OPENZOO_CONTEXT_MIN_CHARS (16384 — bodies bigger than this bind once + reuse)
+  OPENZOO_NO_CONTEXT_CACHE (0 — set 1 to always ship the full body)
   OPENZOO_ENABLE_RH (0 — Robinhood Chain rail, experimental)`;
 
 async function main() {
@@ -33,6 +38,30 @@ async function main() {
     case 'demo':
       await (await import('../lib/demo.js')).runDemo();
       break;
+    case 'contexts': {
+      const { listContexts, forgetContexts } = await import('../lib/contexts.js');
+      const fi = process.argv.indexOf('--forget');
+      if (fi !== -1) {
+        const sel = process.argv[fi + 1];
+        if (!sel) throw new Error('usage: openzoo contexts --forget <hash-prefix|all>');
+        console.log(`forgot ${forgetContexts(sel)} context(s)`);
+        break;
+      }
+      const all = listContexts();
+      if (!all.length) {
+        console.log('no bound corpora yet — run `npx openzoo demo` or ask with a big body.');
+        break;
+      }
+      const age = (iso) => {
+        const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+        return s < 3600 ? `${Math.round(s / 60)}m` : s < 86400 ? `${(s / 3600).toFixed(1)}h` : `${(s / 86400).toFixed(1)}d`;
+      };
+      for (const c of all) {
+        console.log(`${c.hash.slice(0, 12)}  ${c.context_id}  bound ${age(c.boundAt)} ago  ${c.apiBase}`);
+      }
+      console.log('\nthese corpora never ship again — asks against them send only the question + X-HRR-Context.');
+      break;
+    }
     case 'balance':
       await (await import('../lib/info.js')).printBalance();
       break;

package/lib/contexts.js

@@ -0,0 +1,102 @@
+/**
+ * Context manifest — "the body never ships twice."
+ *
+ * ~/.openzoo/contexts.json (chmod 600) maps sha256(normalized corpus) →
+ * { context_id, boundAt } per API base. A hit means the corpus is already
+ * bound on the zoo's holographic sidecar, so an ask ships only the question
+ * plus an X-HRR-Context header instead of re-uploading megabytes.
+ *
+ * Scoped per API base: the same corpus bound on a different zoo is a
+ * different context id, and pointing OPENZOO_API_BASE elsewhere must never
+ * replay ids the new gateway has never seen.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const FILE = path.join(os.homedir(), '.openzoo', 'contexts.json');
+
+/** sha256 of the normalized corpus text. Normalization (CRLF→LF + trim) keeps
+ *  the hash stable across OSes and trailing-whitespace edits — the corpus the
+ *  sidecar chunks is semantically identical either way. */
+export function corpusHash(text) {
+  return createHash('sha256').update(String(text).replace(/\r\n/g, '\n').trim()).digest('hex');
+}
+
+function load() {
+  try {
+    const j = JSON.parse(readFileSync(FILE, 'utf8'));
+    return j && typeof j === 'object' ? j : {};
+  } catch {
+    return {};
+  }
+}
+
+function save(map) {
+  mkdirSync(path.dirname(FILE), { recursive: true });
+  // write-then-rename so a crash mid-write never truncates the manifest
+  const tmp = FILE + '.tmp';
+  writeFileSync(tmp, JSON.stringify(map, null, 2));
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, FILE);
+}
+
+/** manifest entry for (apiBase, hash) or null. */
+export function lookupContext(apiBase, hash) {
+  const map = load();
+  return map[apiBase]?.[hash] ?? null;
+}
+
+export function rememberContext(apiBase, hash, contextId) {
+  const map = load();
+  map[apiBase] = map[apiBase] || {};
+  map[apiBase][hash] = { context_id: contextId, boundAt: new Date().toISOString() };
+  save(map);
+}
+
+export function forgetContext(apiBase, hash) {
+  const map = load();
+  if (map[apiBase]?.[hash]) {
+    delete map[apiBase][hash];
+    if (!Object.keys(map[apiBase]).length) delete map[apiBase];
+    save(map);
+    return 1;
+  }
+  return 0;
+}
+
+/** Flat list of every entry: { apiBase, hash, context_id, boundAt }. */
+export function listContexts() {
+  const map = load();
+  const out = [];
+  for (const [apiBase, entries] of Object.entries(map)) {
+    for (const [hash, e] of Object.entries(entries)) {
+      out.push({ apiBase, hash, context_id: e.context_id, boundAt: e.boundAt });
+    }
+  }
+  out.sort((a, b) => String(b.boundAt).localeCompare(String(a.boundAt)));
+  return out;
+}
+
+/** Forget by hash prefix (any api base) or 'all'. Returns removed count. */
+export function forgetContexts(selector) {
+  const map = load();
+  let removed = 0;
+  if (selector === 'all') {
+    for (const entries of Object.values(map)) removed += Object.keys(entries).length;
+    save({});
+    return removed;
+  }
+  for (const [apiBase, entries] of Object.entries(map)) {
+    for (const hash of Object.keys(entries)) {
+      if (hash.startsWith(selector)) {
+        delete entries[hash];
+        removed += 1;
+      }
+    }
+    if (!Object.keys(entries).length) delete map[apiBase];
+  }
+  if (removed) save(map);
+  return removed;
+}

package/lib/demo.js

@@ -3,6 +3,8 @@ import { PayClient, UnderfundedError } from './pay.js';
 import { parse402, pickAccept, tokenBalance } from './x402.js';
 import { startSpinner, postWithUploadSignal } from './spinner.js';
 import { resolvePool, poolState, depositForShares } from './wrap.js';
+import { bindCorpus, askWithContext } from './hrr.js';
+import { forgetContext } from './contexts.js';
 
 const DEMO_MODEL = process.env.OPENZOO_DEMO_MODEL || 'nvidia/nemotron-3.5-lightning';
 const NEEDLE = 'The zebra vault code is 7-ALPHA-9243.';
@@ -29,14 +31,16 @@ function bigBody(targetTokens) {
   return parts.join('\n\n');
 }
 
-async function quoteFor(bodyObj) {
+async function quoteFor(bodyObj, headers = {}) {
   const body = JSON.stringify(bodyObj);
   const mb = (body.length / 1048576).toFixed(1);
   const approxTokens = Math.round(body.length / 4 / 1000);
-  const spin = startSpinner(`uploading ${mb}MB body`);
+  const big = body.length > 262144;
+  const spin = startSpinner(big ? `uploading ${mb}MB body` : 'asking the zoo for a live quote');
   try {
     const r = await postWithUploadSignal(`${config.apiBase}/v1/chat/completions`, body, {
-      onUploaded: () => spin.update(`zoo pricing ~${approxTokens}k tokens`),
+      headers,
+      onUploaded: () => { if (big) spin.update(`zoo pricing ~${approxTokens}k tokens`); },
     });
     if (r.status !== 402) throw new Error(`expected 402 quote, got HTTP ${r.status}: ${(await r.text()).slice(0, 300)}`);
     return parse402(await r.json());
@@ -71,64 +75,93 @@ export async function runDemo() {
   console.log('   (recorded against the same model class, 2026-08-13 — benches.openzoo.fun)');
   console.log('');
 
-  console.log('2) same body through the zoo — asking for the live x402 quote (the quote is free)...');
+  console.log('2) same body through the zoo — but the body never ships twice (0.3.0):');
   const doc = bigBody(tokens);
-  const bodyObj = {
+  const docMb = (Buffer.byteLength(doc) / 1048576).toFixed(1);
+  const askBody = {
     model: DEMO_MODEL,
-    messages: [{ role: 'user', content: `${doc}\n\n${QUESTION}` }],
-    max_tokens: 32,
+    messages: [{ role: 'user', content: QUESTION }],
+    // Reasoning models burn budget on thinking before visible output — 32 was
+    // returning empty content with finish_reason=length on nemotron.
+    max_tokens: 512,
     temperature: 0,
   };
-  const quote = await quoteFor(bodyObj);
+
+  const tRun = Date.now();
+  let bindSpin = null;
+  const bindStages = {
+    onStage: (stage, info) => {
+      if (stage === 'binding') bindSpin = startSpinner(`uploading + binding ${docMb}MB corpus (one-time)`);
+      if (stage === 'bound-uploading-done') bindSpin?.update('zoo chunking + indexing the corpus');
+    },
+  };
+  let bind = await bindCorpus(doc, bindStages);
+  bindSpin?.stop();
+  if (bind.reused) {
+    console.log(`   ★ corpus already bound (context ${bind.contextId}) — skipped the ${docMb}MB upload entirely.`);
+  } else {
+    console.log(`   bound once in ${((Date.now() - tRun) / 1000).toFixed(1)}s: ${docMb}MB → context ${bind.contextId}.`);
+    console.log('   re-run `npx openzoo demo` — this upload never happens again.');
+  }
+
+  let quote;
+  try {
+    quote = await quoteFor(askBody, { 'X-HRR-Context': bind.contextId });
+  } catch (err) {
+    // Sidecar wiped since we bound (stale manifest): 404 pre-402, nothing
+    // paid. Never fail on it — re-bind once and re-quote.
+    if (!/context_not_found/.test(err.message)) throw err;
+    console.log('   bound context is gone on the zoo — re-binding once...');
+    forgetContext(config.apiBase, bind.hash);
+    bind = await bindCorpus(doc, { ...bindStages, force: true });
+    bindSpin?.stop();
+    console.log(`   re-bound: ${docMb}MB → context ${bind.contextId}.`);
+    quote = await quoteFor(askBody, { 'X-HRR-Context': bind.contextId });
+  }
   const accept = pickAccept(quote, config.token);
   const x = accept.extra || {};
-  console.log(`   quote: $${Number(x.billedUsd).toFixed(6)} · pricing=${x.pricing}`
-    + (x.directUsd != null ? ` · direct would be $${Number(x.directUsd).toFixed(6)} · savesVsDirect=${Number(x.savesVsDirect).toFixed(1)}×` : ''));
+  console.log(`   quote for the ask: $${Number(x.billedUsd).toFixed(6)} · pricing=${x.pricing} (3× a tiny body — the ${docMb}MB corpus is not re-priced)`);
   console.log('');
 
-  // Decide what we can actually pay for under the demo cap.
-  let payBody = bodyObj;
-  let payAccept = accept;
   if (Number(x.billedUsd) > config.demoMaxUsd) {
-    const fitTokens = Math.max(20000, Math.floor(tokens * (config.demoMaxUsd / Number(x.billedUsd)) * 0.8));
-    console.log(`   (full-size quote is over the demo cap $${config.demoMaxUsd} — paying for a ${Math.round(fitTokens / 1000)}k-token slice instead;`);
-    console.log('    set OPENZOO_DEMO_MAX_USD higher to pay for the whole thing)');
-    const doc2 = bigBody(fitTokens);
-    payBody = { ...bodyObj, messages: [{ role: 'user', content: `${doc2}\n\n${QUESTION}` }] };
-    const q2 = await quoteFor(payBody);
-    payAccept = pickAccept(q2, config.token);
+    console.log(`   quote is over the demo cap $${config.demoMaxUsd} — set OPENZOO_DEMO_MAX_USD higher to pay it.`);
+    return;
   }
 
-  const cov = await coverage(connection, keypair.publicKey, payAccept);
+  const cov = await coverage(connection, keypair.publicKey, accept);
   if (!cov.covered) {
     console.log('3) wallet not funded yet, so stopping before payment.');
-    console.log(`   quote : ≈ $${Number(payAccept.extra?.billedUsd).toFixed(6)}`);
+    console.log(`   quote : ≈ $${Number(x.billedUsd).toFixed(6)}`);
     console.log(`   wallet: $${(cov.usdcUi ?? 0).toFixed(2)} USDC`);
     console.log(`   fund  : send a few cents of USDC to ${pub}`);
     console.log('   then re-run `npx openzoo demo`.');
     return;
   }
 
-  console.log('3) paying and asking...');
-  const paidMb = (JSON.stringify(payBody).length / 1048576).toFixed(1);
-  const spin = startSpinner(`re-sending ${paidMb}MB body for the paid call`);
+  console.log('3) paying and asking (the question rides alone — plus one header)...');
+  const spin = startSpinner('sending the ask with X-HRR-Context');
   const t0 = Date.now();
-  let data; let receipt;
+  let out;
   try {
-    ({ data, receipt } = await client.chat(payBody, {
+    out = await askWithContext(client, doc, askBody, {
       onStage: (stage) => {
+        if (stage === 'reused') spin.update('reusing bound corpus');
+        if (stage === 'rebinding') spin.update('context was wiped upstream — re-binding once');
+        if (stage === 'binding') spin.update(`re-uploading ${docMb}MB corpus`);
         if (stage === 'quoted') spin.update('building the payment');
         if (stage === 'funding') spin.update('preparing funds (one-time)');
         if (stage === 'paying') spin.update('paying + waiting for the answer');
       },
-    }));
+    });
   } catch (err) {
     spin.stop();
     if (err instanceof UnderfundedError) { console.log(`   ${err.message}`); return; }
     throw err;
   }
   spin.stop();
+  const { data, receipt } = out;
   const secs = ((Date.now() - t0) / 1000).toFixed(1);
+  const totalSecs = ((Date.now() - tRun) / 1000).toFixed(1);
   const answer = data?.choices?.[0]?.message?.content ?? '';
   const usage = data?.usage || {};
   console.log(`   answer (${secs}s): ${answer.trim()}`);
@@ -137,4 +170,10 @@ export async function runDemo() {
     console.log(`   tokens the model actually read: ${usage.gpu_tokens ?? usage.prompt_tokens}${usage.spill_tokens ? ` (spilled: ${usage.spill_tokens})` : ''}`);
   }
   if (receipt) console.log(`   ${receipt.line}`);
+  if (bind.reused) {
+    const paidUsd = Number(receipt?.billedUsd);
+    console.log('');
+    console.log(`   ★ corpus already bound — skipped ${docMb}MB upload; whole run took ${totalSecs}s`
+      + (Number.isFinite(paidUsd) ? ` and cost $${paidUsd.toFixed(6)}` : ''));
+  }
 }

package/lib/hrr.js

@@ -0,0 +1,79 @@
+/**
+ * Client side of "the body never ships twice."
+ *
+ * bindCorpus: hash the corpus; on a manifest hit return the recorded
+ * context_id without touching the network. On a miss, POST the corpus ONCE to
+ * the zoo's free bind endpoint (the gateway chunks it with leCore server-side)
+ * and record the id.
+ *
+ * askWithContext: send the SMALL ask with X-HRR-Context. If the gateway says
+ * the context is gone (sidecar wiped — HTTP 404 code context_not_found,
+ * returned BEFORE the 402 so nothing was paid), forget the stale entry,
+ * re-bind once, and retry. A stale manifest must never fail a call.
+ */
+import { config } from './config.js';
+import { corpusHash, lookupContext, rememberContext, forgetContext } from './contexts.js';
+import { postWithUploadSignal } from './spinner.js';
+
+/** Corpora under this many chars ride inline — binding has a round-trip cost
+ *  and the reuse win only matters when the body is actually big. */
+export const BIND_MIN_CHARS = Number(process.env.OPENZOO_CONTEXT_MIN_CHARS || 16384);
+
+export const contextCacheDisabled = () => process.env.OPENZOO_NO_CONTEXT_CACHE === '1';
+
+/**
+ * Ensure `corpus` is bound on the zoo. Returns
+ * { contextId, hash, reused, bytes } — reused=true means zero bytes shipped.
+ */
+export async function bindCorpus(corpus, { onStage, force = false } = {}) {
+  const hash = corpusHash(corpus);
+  const bytes = Buffer.byteLength(corpus);
+  if (!force) {
+    const hit = lookupContext(config.apiBase, hash);
+    if (hit) {
+      onStage?.('reused', { contextId: hit.context_id, boundAt: hit.boundAt, bytes });
+      return { contextId: hit.context_id, hash, reused: true, bytes };
+    }
+  }
+  onStage?.('binding', { bytes });
+  const r = await postWithUploadSignal(`${config.apiBase}/v1/hrr/bind`, JSON.stringify({ corpus }), {
+    onUploaded: () => onStage?.('bound-uploading-done', { bytes }),
+  });
+  if (r.status !== 200) {
+    throw new Error(`bind failed: HTTP ${r.status}: ${(await r.text()).slice(0, 300)}`);
+  }
+  const j = await r.json();
+  if (!j?.context_id) throw new Error('bind returned no context_id');
+  rememberContext(config.apiBase, hash, j.context_id);
+  return { contextId: j.context_id, hash, reused: false, bytes, bound: j.bound };
+}
+
+const isContextGone = (status, text) =>
+  status === 404 && /context_not_found/.test(text);
+
+/**
+ * One paid ask against a bound corpus. bodyObj should already be SMALL (the
+ * question, not the corpus). Retries exactly once through a fresh bind when
+ * the context is gone. Returns { data, receipt, contextId, reused }.
+ */
+export async function askWithContext(client, corpus, bodyObj, { onStage } = {}) {
+  let bind = await bindCorpus(corpus, { onStage });
+  for (let attempt = 0; ; attempt++) {
+    const { response, receipt } = await client.fetch(`${config.apiBase}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'X-HRR-Context': bind.contextId },
+      body: JSON.stringify(bodyObj),
+    }, { onStage });
+    if (response.ok) {
+      return { data: await response.json(), receipt, contextId: bind.contextId, reused: bind.reused };
+    }
+    const text = (await response.text()).slice(0, 500);
+    if (attempt === 0 && isContextGone(response.status, text)) {
+      onStage?.('rebinding', { contextId: bind.contextId });
+      forgetContext(config.apiBase, bind.hash);
+      bind = await bindCorpus(corpus, { onStage, force: true });
+      continue;
+    }
+    throw new Error(`zoo returned HTTP ${response.status}: ${text}`);
+  }
+}

package/lib/mcp.js

@@ -5,6 +5,8 @@ import { z } from 'zod';
 import { config } from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
+import { askWithContext, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
+import { listContexts } from './contexts.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
@@ -33,13 +35,26 @@ export async function startMcp() {
       max_tokens: z.number().int().positive().optional().describe('Completion cap. Default 1024.'),
     },
   }, async ({ prompt, corpus, model, max_tokens }) => {
-    const content = corpus ? `${corpus}\n\n${prompt}` : prompt;
     try {
-      const { data, receipt } = await client.chat({
-        model: model || DEFAULT_MODEL,
-        messages: [{ role: 'user', content }],
-        max_tokens: max_tokens || 1024,
-      });
+      const bodyBase = { model: model || DEFAULT_MODEL, max_tokens: max_tokens || 1024 };
+      let data; let receipt; let reuse = null;
+      // "The body never ships twice": a big corpus is bound ONCE on the zoo
+      // (sha256 manifest at ~/.openzoo/contexts.json) and later asks ship only
+      // the prompt + an X-HRR-Context header. Small corpora ride inline.
+      if (corpus && corpus.length > BIND_MIN_CHARS && !contextCacheDisabled()) {
+        const out = await askWithContext(client, corpus, {
+          ...bodyBase,
+          messages: [{ role: 'user', content: prompt }],
+        });
+        ({ data, receipt } = out);
+        reuse = { contextId: out.contextId, corpusReused: out.reused };
+      } else {
+        const content = corpus ? `${corpus}\n\n${prompt}` : prompt;
+        ({ data, receipt } = await client.chat({
+          ...bodyBase,
+          messages: [{ role: 'user', content }],
+        }));
+      }
       const usage = data?.usage || {};
       return text({
         answer: data?.choices?.[0]?.message?.content ?? '',
@@ -52,6 +67,7 @@ export async function startMcp() {
         } : 'free (no 402 issued)',
         tokensRead: usage.gpu_tokens ?? usage.prompt_tokens ?? null,
         spillTokens: usage.spill_tokens ?? null,
+        ...(reuse ? { context: reuse } : {}),
       });
     } catch (err) {
       if (err instanceof UnderfundedError || err instanceof QuoteTooHighError) {
@@ -85,6 +101,16 @@ export async function startMcp() {
     });
   });
 
+  server.registerTool('zoo_contexts', {
+    description: 'List corpora already bound to the zoo\'s holographic memory (local manifest). A listed corpus is never re-uploaded — asks against it are near-free.',
+    inputSchema: {},
+  }, async () => text({
+    manifest: '~/.openzoo/contexts.json',
+    contexts: listContexts().map((c) => ({
+      hash: c.hash.slice(0, 12), context_id: c.context_id, boundAt: c.boundAt, apiBase: c.apiBase,
+    })),
+  }));
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(`openzoo mcp on stdio — wallet ${client.address} — zoo ${config.apiBase}`);

package/lib/pay.js

@@ -169,10 +169,10 @@ export class PayClient {
   }
 
   /** POST a chat completion, paying as needed. Returns { data, receipt }. */
-  async chat(bodyObj, { onStage } = {}) {
+  async chat(bodyObj, { onStage, headers } = {}) {
     const { response, receipt } = await this.fetch(`${config.apiBase}/v1/chat/completions`, {
       method: 'POST',
-      headers: { 'content-type': 'application/json' },
+      headers: { 'content-type': 'application/json', ...(headers || {}) },
       body: JSON.stringify(bodyObj),
     }, { onStage });
     if (!response.ok) {

package/lib/proxy.js

@@ -3,6 +3,8 @@ import { Readable } from 'node:stream';
 import { config } from './config.js';
 import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
+import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
+import { forgetContext } from './contexts.js';
 
 const HOP_BY_HOP = new Set([
   'host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade',
@@ -48,6 +50,58 @@ function jsonErr(res, status, message, extraFields = {}) {
   res.end(JSON.stringify({ error: { message }, ...extraFields }));
 }
 
+const mb = (n) => (n / 1048576).toFixed(1);
+
+/**
+ * "The body never ships twice" at the proxy. A chat body whose LAST message
+ * carries a huge pasted corpus gets split at its last blank line — corpus vs
+ * ask — so the corpus can be bound ONCE on the zoo and every later call ships
+ * only the ask plus X-HRR-Context. The split point is deterministic, which is
+ * what makes the sha256 manifest hit on run 2 even when the question changed.
+ *
+ * Conservative on purpose: only a single big STRING content on the final
+ * message, only when a blank-line boundary exists, and any failure falls back
+ * to sending the original body untouched — caching must never break a call.
+ * Returns null (send as-is) or { body, contextId, hash, corpus, reused, savedBytes }.
+ */
+async function maybeCacheCorpus(req, bodyBuf, log) {
+  if (contextCacheDisabled()) return null;
+  if (req.method !== 'POST' || !(req.url || '').includes('/chat/completions')) return null;
+  if (req.headers['x-hrr-context']) return null; // harness manages its own context
+  if (bodyBuf.length <= BIND_MIN_CHARS) return null;
+  let body;
+  try { body = JSON.parse(bodyBuf.toString('utf8')); } catch { return null; }
+  const msgs = Array.isArray(body?.messages) ? body.messages : null;
+  if (!msgs?.length) return null;
+  const last = msgs[msgs.length - 1];
+  if (typeof last?.content !== 'string' || last.content.length <= BIND_MIN_CHARS) return null;
+  const cut = last.content.lastIndexOf('\n\n');
+  if (cut < BIND_MIN_CHARS) return null;
+  const corpus = last.content.slice(0, cut);
+  const ask = last.content.slice(cut + 2).trim();
+  if (!ask || ask.length > 8000) return null;
+
+  const bind = await bindCorpus(corpus, {
+    onStage: (stage, info) => {
+      if (stage === 'binding') log(`binding ${mb(info.bytes)}MB corpus to holographic memory (one-time)...`);
+    },
+  });
+  if (bind.reused) {
+    log(`corpus already bound (${bind.hash.slice(0, 12)}… → ${bind.contextId}) — skipped ${mb(bind.bytes)}MB upload`);
+  } else {
+    log(`corpus bound once (${mb(bind.bytes)}MB → ${bind.contextId}) — repeats of this body are near-free`);
+  }
+  const rewritten = { ...body, messages: [...msgs.slice(0, -1), { ...last, content: ask }] };
+  return {
+    body: Buffer.from(JSON.stringify(rewritten)),
+    contextId: bind.contextId,
+    hash: bind.hash,
+    corpus,
+    reused: bind.reused,
+    savedBytes: bind.bytes,
+  };
+}
+
 export async function startProxy({ silent = false } = {}) {
   const client = new PayClient();
   const log = silent ? () => {} : (...a) => console.log(...a);
@@ -65,7 +119,39 @@ export async function startProxy({ silent = false } = {}) {
     if (req.method !== 'GET' && req.method !== 'HEAD') init.body = bodyBuf;
 
     try {
-      const { response, paid, receipt } = await client.fetch(url, init);
+      let cached = null;
+      try {
+        cached = await maybeCacheCorpus(req, bodyBuf, log);
+      } catch (err) {
+        log(`context cache skipped for this call: ${err.message}`);
+      }
+      const send = (buf, ctxId) => client.fetch(url, {
+        ...init,
+        body: buf,
+        headers: ctxId ? { ...init.headers, 'x-hrr-context': ctxId } : init.headers,
+      });
+      let result;
+      if (cached) {
+        result = await send(cached.body, cached.contextId);
+        // Sidecar wiped between runs: the gateway 404s BEFORE the 402 (nothing
+        // paid). Never fail on a stale manifest — re-bind once and retry.
+        if (result.response.status === 404) {
+          const text = await result.response.text();
+          if (/context_not_found/.test(text)) {
+            log('bound context is gone on the zoo — re-binding once...');
+            forgetContext(config.apiBase, cached.hash);
+            const rebound = await bindCorpus(cached.corpus, { force: true });
+            result = await send(cached.body, rebound.contextId);
+          } else {
+            res.writeHead(404, { 'content-type': 'application/json' });
+            res.end(text);
+            return;
+          }
+        }
+      } else {
+        result = await client.fetch(url, init);
+      }
+      const { response, paid, receipt } = result;
       if (paid && receipt) log(receipt.ok ? receipt.line : `paid retry -> HTTP ${receipt.status}`);
       await relay(res, response);
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana rail live; Base/Robinhood rails experimental.",
   "license": "MIT",
   "type": "module",