wontopos 2.2.46 → 2.2.47

package/README.md

@@ -29,7 +29,42 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 
 ## Methods
 
-`add` · `addTurn` · `addBulk` · `update` · `search` · `searchFull` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
+| Method | What it does |
+|---|---|
+| **Write** | |
+| `add(content, userId?, metadata?, opts?)` | Store one memory. Alias `store`. `opts.image` attaches a photo. |
+| `addTurn(userMsg, assistantMsg, userId?)` | Store one exchange of a conversation. |
+| `addBulk(content, userId?, category?, timestamp?)` | Backfill a long history in one call. |
+| `update(oldMemoryId, newContent, userId?)` | Replace a fact that changed. The old version stays in its history. |
+| **Read** | |
+| `recall(query, userId?, opts?)` | The recent turns, the memories that match and the conversation around the best one, in one call. |
+| `search(query, userId?, limit?, opts?)` | The memories that match, best first. |
+| `searchFull(...)` | The same search with each part kept apart, `images` and `verify_used` included. |
+| `searchSelf(...)` | The assistant's own words, kept apart from what others said. |
+| `history(userId?)` | The recent conversation. |
+| `get(userId, memoryId)` | One memory by id. |
+| `listMemories` · `iterMemories` · `exportMemories` | Every memory in a store: a page at a time, as a stream, or all at once. |
+| `lineage(userId, memoryId)` | The edits that followed one memory. |
+| `revisions(userId?, opts?)` | How many of a store's memories were edited, and which. |
+| `stats(userId?)` | Counts for a store. |
+| `engram(name, query, userId?)` · `listEngrams()` | Built-in retrieval routines, and the ones a model can run. |
+| **Photos** | |
+| `listImages` · `iterImages` · `exportImages` | A store's image memories, newest first. |
+| `getImage(userId, memoryId)` | The bytes of one image. |
+| `forgetImage(userId, memoryId, { preview })` | Remove the photo from a memory. `preview: true` first says whether the memory itself stays. |
+| **People** | |
+| `addSpeaker` · `listSpeakers` · `removeSpeaker` | Register, list and unregister the people a store hears from. |
+| `bySpeaker(speaker, userId?)` | What one person said, newest first. |
+| **Stores** | |
+| `createStore` · `listStores` · `deleteStore` | One isolated memory space per end-user, agent or topic. |
+| `delete(userId, memoryId)` · `deleteAll(userId)` | Delete one memory, or every memory in a store. |
+| **Account** | |
+| `listModels()` | The models you can use, and what each can do. |
+| `usage(days?)` | What this key, its workspace and its stores have spent. Free. |
+| `ping()` | Check the key and the connection. |
+| **Client** | |
+| `withModel` · `withUser` · `withDeadline` · `withTimeout` · `withRetries` · `withSignal` | A copy of the client with another model, store, budget, timeout, retry count or cancel signal. |
+| `Client.fromEnv()` · `rateLimit` | A client with the key from the environment; the last call's rate-limit numbers. |
 
 Where the store id goes depends on whether the method takes a payload. A method that
 writes or searches puts the payload first and the store second — `mem.add("...", "alice")`,
@@ -41,6 +76,29 @@ an explicit `undefined` there, because a second required argument follows it. Py
 omits it in all five, and Rust takes it positionally (`None` for the default store, where there is one).
 Let your editor confirm the order: every signature is typed. A store is one isolated memory space per end-user, agent, or topic. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
 
+## Putting recall into a prompt
+
+```ts
+const ctx = await mem.recall(userMessage, "alice");
+
+const system = [
+  "What you remember about this user, most relevant first:",
+  ...ctx.long_term.memories.map((m) => `- ${m.content}`),
+  "",
+  "Around the most relevant memory:",
+  ...ctx.context.around_top_memory,
+  "",
+  "The conversation so far:",
+  ...ctx.short_term.turns.map((t) => `${t.role}: ${t.content}`),
+].join("\n");
+
+// Call your language model with `system` and the user's message, then store the exchange:
+await mem.addTurn(userMessage, reply, "alice");
+```
+
+Each row of `around_top_memory` starts with `[before] `, `[match] ` or `[after] `: where it
+sits next to the best memory. Keep every list in the order it arrives.
+
 ## Who said it (speakers)
 
 Every memory can carry a speaker: `"me"` for the assistant's own words, or a
@@ -60,6 +118,40 @@ await mem.search("what did Bob say about deadlines?", "alice", 10, { speaker: "B
 up to 50 people to start (a limit we plan to raise); `"me"` never needs
 registration and never counts against it.
 
+## Photos
+
+On a model whose `listModels()` capabilities include `images`, a memory can carry a photo.
+The caption is still required.
+
+```ts
+import { readFileSync, writeFileSync } from "node:fs";
+
+const data = readFileSync("beach.jpg").toString("base64");
+const stored = await mem.add("At the beach with Bob", "alice", {}, { image: { data, taken_at: "2026-08-14" } });
+
+const { bytes, contentType } = await mem.getImage("alice", stored.id!);
+writeFileSync(`beach.${contentType.split("/")[1]}`, bytes);
+```
+
+Both edges must be 700px or more, the long edge at most 2500px and the file at most 7MB;
+anything else is refused (400) with the reason. A long edge over 1568px is stored at
+1568px, so keep your own copy of the original. `search` returns image memories after
+the others, and `listImages` pages through them newest first. `forgetImage` removes the
+photo, and it can remove the whole memory with it: call it with `preview: true` first,
+and `memory_kept` says whether the memory stays.
+
+## Export, edit history and usage
+
+- **Export:** `exportMemories(userId)` returns every memory in a store, the text you
+  stored and its metadata; `exportImages(userId)` every image memory. For a large store,
+  `iterMemories` and `iterImages` stream them a page at a time.
+- **Edit history:** `update` replaces a fact that changed. `lineage(userId, memoryId)` lists
+  the versions from the id you pass forward, oldest first, and marks the one in force with
+  `is_current`; pass the first version's id to see the whole history. `revisions()` counts
+  how many of a store's memories were edited.
+- **Usage:** `usage(days)` reports this key's spend, the workspace's spend over the window,
+  the stores that spent the most, and the balance. It is free, and works at a zero balance.
+
 ## Recall caching
 
 Opt in per search and a repeated query reuses the previous result at 10% of the
@@ -85,12 +177,22 @@ Built in, no configuration needed:
 
 - **Automatic retries** — 429 and a 409 for a write already in flight always, and 408 /
   502 / 503 / 504 or a connection error only when a retry cannot double-process a write.
-  A write may already have landed when any of those four comes back, so a POST write gets
-  429, that 409 and connect-level failures only. The calls that are safe to send again
-  retry all four: the reads sent as POST (`search`, `recall`, `get`, `listMemories`,
-  `stats`, ...) and the GET and DELETE calls (`ping`, `listStores`, `listSpeakers`,
-  `listModels`, `listEngrams`, `usage`, `deleteStore`, `removeSpeaker`, `forgetImage`). Twice, with exponential backoff + jitter, honoring the server's
-  `Retry-After` up to 30s. Tune with `new Client({ maxRetries })`; `0` disables.
+  The calls that are safe to send again retry all four: the reads sent as POST (`search`,
+  `recall`, `get`, `listMemories`, `stats`, ...), the GET and DELETE calls (`ping`,
+  `listStores`, `listSpeakers`, `listModels`, `listEngrams`, `usage`, `deleteStore`,
+  `removeSpeaker`, `forgetImage`), and the memory writes (`add`, `addTurn`, `addBulk`,
+  `update`). Those carry an idempotency key, so the service answers a repeat with the
+  first attempt's result instead of storing again. The other writes sent as POST
+  (`createStore`, `addSpeaker`, `delete`, `deleteAll`) get 429, that 409 and
+  connect-level failures only. Twice, with exponential backoff + jitter, honoring the
+  server's `Retry-After` up to 30s. Tune with `new Client({ maxRetries })`; `0` disables.
+- **Your own retries** — pass `idempotencyKey` when the retry is yours (a job that is
+  re-run, a queue that redelivers). The service keeps a key for 24 hours and answers a
+  repeat with the first response, marked `replayed: true`. When the first attempt did
+  not come back with an answer, so whether it was applied is not known, a repeat
+  is refused with a `ConflictError` (409) rather than stored twice: check before sending
+  it again under a new key. Derive the key from what you store
+  (`` `import:${row.id}` ``), never a constant.
 - **Redirects refused** — the API key never follows a 3xx to another host.
 - **Timeouts** — 30s per attempt by default (`timeoutMs`), and a total budget for
   the whole call across every retry with `deadlineMs` / `withDeadline(ms)`. At the
@@ -131,8 +233,13 @@ timeouts, redirect refusal and the response cap all still apply.
 
 ## Security
 
-Built in, none of it configurable off:
+Built in:
 
+- **No key in a browser page** — anyone who opens a page can read a key in it, and with
+  it every memory in its workspace. A client in a browser page that would send the key to
+  the service is refused: call Wontopos from your server, or point `baseUrl` at a proxy of
+  your own that holds the key. `dangerouslyAllowBrowser: true` turns the refusal off, for
+  a local demo with a key you will revoke.
 - **Redirects refused** — a 3xx is an error, so the key never follows one to
   another host.
 - **Response size cap** — anything over 64MB is refused instead of buffered.
@@ -188,7 +295,8 @@ try {
 
 A retired model answers `410`, thrown as `GoneError`: retrying cannot succeed, so name a
 live model (`listModels()` lists them, with `retires_at` on one that is scheduled to
-retire). `deleteStore` still works under a retired model.
+retire). Before the day, the client warns once with the date the model you use retires.
+`deleteStore` still works under a retired model.
 
 ## A different API host
 
@@ -219,7 +327,7 @@ data to fix it.
 ## Changelog
 
 The three clients release in lockstep — same version, same surface, same day. Patch
-releases are additive. Nine inside 2.2 were not, deliberately and each with its
+releases are additive. Ten inside 2.2 were not, deliberately and each with its
 reason; the changelog lists them.
 
 See [CHANGELOG.md](https://github.com/wontopos/wontopos-node/blob/main/CHANGELOG.md).

package/dist/cjs/wontopos.d.cts

@@ -28,9 +28,10 @@
  * Reliability: every call retries transient failures with exponential backoff +
  * jitter, honoring `Retry-After` up to 30s — 429 and a 409 that says another write
  * to the store was in flight, always; 408/502/503/504 and connection errors only when
- * a retry can never double-process a write (reads, the DELETE calls, or a failure at
- * connect time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
- * the `withTimeout()` / `withRetries()` clones.
+ * a retry can never double-process a write (reads, the DELETE calls, the memory writes,
+ * which carry an idempotency key, or a failure at connect time). Tune with `maxRetries`
+ * (0 disables) and `timeoutMs`, or per call site via the `withTimeout()` /
+ * `withRetries()` clones.
  *
  * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
  * to stderr — never memory content, request bodies, or the API key.
@@ -48,6 +49,8 @@ export declare const SEARCH_LIMIT_MAX = 20;
 /** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
 export declare const CONTEXT_LIMIT_MIN = 0;
 export declare const CONTEXT_LIMIT_MAX = 20;
+/** @deprecated Test hook. The warn-once set is process-global by design. */
+export declare function _resetRetirementWarnings(): void;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -100,8 +103,11 @@ export declare class PermissionDeniedError extends WosError {
 /** 404 — the store or resource doesn't exist. */
 export declare class NotFoundError extends WosError {
 }
-/** 409: another write to this store was in flight (retried automatically; nothing was
- *  stored), or the store id collides with an existing one (not retried). */
+/** 409: another write to this store was in flight, or the first request under this
+ *  write's idempotency key is still running (both retried automatically; nothing was
+ *  stored); the store id collides with an existing one (not retried); or the first
+ *  request under the key did not come back with an answer, so whether it was stored is
+ *  not known (not retried: check before sending it again under a new key). */
 export declare class ConflictError extends WosError {
     /** The existing store id this one collides with. Set only on a collision, which
      *  retrying cannot fix. */
@@ -184,7 +190,9 @@ export interface StoreResult {
     note?: string;
     /** `true` when this response was REPLAYED from a previous request with the same
      *  `idempotencyKey` — nothing new was stored. Absent on a fresh write. Read it to
-     *  tell "my retry landed" from "my retry was a no-op". */
+     *  tell "my retry landed" from "my retry was a no-op". This client sets it only for
+     *  a key you passed, and then the earlier request can also be an attempt of this same
+     *  call that the client sent again after an answer that left the outcome open. */
     replayed?: boolean;
     [key: string]: unknown;
 }
@@ -371,17 +379,25 @@ export interface SearchResult {
     [key: string]: unknown;
 }
 export interface RecallResult {
+    /** The recent conversation, oldest first. */
     short_term: {
-        turns: unknown[];
+        turns: HistoryTurn[];
         count: number;
+        [key: string]: unknown;
     };
+    /** The stored memories that match the query, best first. */
     long_term: {
         memories: Memory[];
         count: number;
+        [key: string]: unknown;
     };
+    /** The conversation around the best memory, in the order it was said. Each row is
+     *  text that starts with where it sits next to that memory: `[before] `, `[match] `
+     *  or `[after] `. Empty when there is no best memory or `context_limit` is 0. */
     context: {
-        around_top_memory: unknown[];
+        around_top_memory: string[];
         count: number;
+        [key: string]: unknown;
     };
     [key: string]: unknown;
 }
@@ -396,7 +412,7 @@ export interface EngramResult {
     usage?: Usage;
     [key: string]: unknown;
 }
-/** One turn of the short-term window, as `history()` returns it. */
+/** One turn of the short-term window, as `history()` and `recall()` return it. */
 export interface HistoryTurn {
     /** `"user"` or `"assistant"`. */
     role?: string;
@@ -636,25 +652,24 @@ export interface SearchOptions {
 /**
  * Per-call options for a write.
  *
- * `idempotencyKey` makes repeating THIS EXACT write safe: the API replays the first
- * response instead of storing again, for up to 10 minutes, and answers 422 if the
- * same key arrives with a different body. Use it when a retry is your own (a job that
- * died and was re-run, a queue that redelivers). The SDK retries a write on 429, and
- * on a 409 that says another write to the store was in flight: the service answers
- * both before it processes anything, so nothing was stored. It never retries a write
- * on 408 / 502 / 503 / 504 or a dropped body, where the write may already have been
- * applied — without a key the client cannot know whether it was.
+ * Every memory write (`add`, `addTurn`, `addBulk`, `update`) carries an idempotency key:
+ * `idempotencyKey` when you pass one, otherwise one this client makes for the call. With
+ * it the client retries the write on 408 / 502 / 503 / 504 and on a dropped connection,
+ * as it does a read: the service answers a repeat with the first attempt's result instead
+ * of storing again, and one that arrives while the first is still running with a 409 to
+ * wait, which is retried as well.
  *
- * The key covers a retry sent after the first attempt finished. A retry that overlaps
- * a first attempt still running can run twice, so wait for the first to fail before
- * re-sending.
+ * Pass your own key when the retry is yours: a job that died and was re-run, a queue
+ * that redelivers. The service keeps a key for 24 hours and answers a repeat with the
+ * first successful response, marked `replayed: true`; the same key with a different body
+ * is refused (422). A first attempt that failed is not kept, so a repeat of it runs,
+ * unless it did not come back with an answer, so whether it was applied is not known:
+ * then the repeat is refused with a `ConflictError` (409) instead of storing it twice.
+ * Check before sending it again under a new key.
  *
  * The key must be UNIQUE PER LOGICAL WRITE — derive it from the thing being stored
  * (`` `import:${row.id}` ``), never a constant, or the second write replays the first
  * and is silently lost. Format: 1-128 chars of `[A-Za-z0-9._:-]`, checked locally.
- *
- * The window is best-effort and can be shorter than 10 minutes; it is not a durable
- * de-duplication record.
  */
 export interface WriteOptions {
     idempotencyKey?: string;
@@ -782,6 +797,12 @@ export interface ClientOptions {
      *  (`res.redirected`) is refused. A fetch that sends the request to another URL
      *  on purpose, such as a proxy that rewrites it, is fine. */
     fetch?: FetchLike;
+    /** Run in a browser page anyway. Off by default: an API key in a page is readable by
+     *  everyone who opens it, and with it every memory in its workspace, so a client in a
+     *  page that would send the key to the service itself is refused. A `baseUrl` of your
+     *  own, a proxy that holds the real key, is not refused. Turn this on only for a local
+     *  demo with a key you will revoke. */
+    dangerouslyAllowBrowser?: boolean;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -803,6 +824,8 @@ export declare class Client {
     private readonly pageRelative;
     /** Whether the caller supplied `fetch`. */
     private readonly customFetch;
+    /** Whether the caller asked to run in a browser page anyway. */
+    private readonly allowBrowser;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     private _rateLimit;
@@ -1022,10 +1045,10 @@ export declare class Client {
      */
     getImage(userId: string | undefined, memoryId: string): Promise<ImageBytes>;
     /**
-     * Remove the PHOTO from a memory, keeping its text.
+     * Remove the PHOTO from a memory. It can take the whole memory with it.
      *
-     * `preview: true` reports what would happen, including `memory_kept`, and changes
-     * nothing. Retried like `deleteStore`; without `preview`, a 404 after an ambiguous
+     * `preview: true` reports what would happen, including `memory_kept` (`false` when
+     * the memory itself would go), and changes nothing. Retried like `deleteStore`; without `preview`, a 404 after an ambiguous
      * failure carries the same note.
      *
      *     const p = await mem.forgetImage(undefined, id, { preview: true });
@@ -1182,6 +1205,11 @@ export declare class Client {
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId: string): Promise<StatusResult>;
     private post;
+    /** A memory write. It always carries an `Idempotency-Key`, the caller's or one made
+     *  for this call, so an answer that leaves the outcome open (408/502/503/504, a
+     *  dropped connection) can be retried: the service answers the retry with the first
+     *  attempt's result instead of storing again. */
+    private write;
     /** A DELETE that removes something: a 404 after an ambiguous failure says an earlier
      *  attempt may already have removed it. */
     private remove;
@@ -1223,7 +1251,8 @@ export declare class Client {
      * Retried: 429, and a 409 whose error carries `retry_after_ms` (another write to the
      * store was in flight; nothing was stored), on every method; 408/502/503/504 and
      * dropped connections on a call that only reads (an idempotent method, or a POST
-     * that only reads); connect failures on every method. A retry whose wait is over the
+     * that only reads) or a write that carries an idempotency key; connect failures on
+     * every method. A retry whose wait is over the
      * cap, or does not fit the deadline, is not made: the call fails with the error of
      * the response it has. So does a retry the deadline leaves no time to send, and the
      * retry of a call that only reads that the deadline cuts short. Any other retry cut

package/dist/cjs/wontopos.js

@@ -2,8 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WME = exports.Client = exports.ServerError = exports.RateLimitError = exports.GoneError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.PaymentRequiredError = exports.AuthenticationError = exports.BadRequestError = exports.APIConnectionError = exports.WosError = exports.CONTEXT_LIMIT_MAX = exports.CONTEXT_LIMIT_MIN = exports.SEARCH_LIMIT_MAX = exports.SEARCH_LIMIT_MIN = void 0;
 exports._resetStoreIdWarnings = _resetStoreIdWarnings;
+exports._resetRetirementWarnings = _resetRetirementWarnings;
 exports._resetFilterWarnings = _resetFilterWarnings;
-const VERSION = "2.2.46";
+const VERSION = "2.2.47";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -268,12 +269,7 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 const IMF_FIXDATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) ([A-Z][a-z]{2}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
 const RFC850_DATE = /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-([A-Z][a-z]{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
 const ASCTIME_DATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) ([A-Z][a-z]{2}) ([ \d]\d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
-function retryAfterMs(v, now = Date.now()) {
-    if (v == null)
-        return undefined;
-    const s = v.trim();
-    if (/^\d+$/.test(s))
-        return Math.min(Number(s), Number.MAX_SAFE_INTEGER / 1000) * 1000;
+function httpDateMs(s, now = Date.now()) {
     let parts;
     let m;
     if ((m = IMF_FIXDATE.exec(s)))
@@ -293,7 +289,37 @@ function retryAfterMs(v, now = Date.now()) {
     const d = Number(day), h = Number(hh), mi = Number(mm), se = Number(ss);
     if (month < 0 || d < 1 || d > 31 || h > 23 || mi > 59 || se > 60)
         return undefined;
-    return Math.max(0, Date.UTC(year, month, d, h, mi, se) - now);
+    return Date.UTC(year, month, d, h, mi, se);
+}
+function retryAfterMs(v, now = Date.now()) {
+    if (v == null)
+        return undefined;
+    const s = v.trim();
+    if (/^\d+$/.test(s))
+        return Math.min(Number(s), Number.MAX_SAFE_INTEGER / 1000) * 1000;
+    const at = httpDateMs(s, now);
+    return at === undefined ? undefined : Math.max(0, at - now);
+}
+const warnedRetirements = new Set();
+const WARNED_RETIREMENTS_MAX = 64;
+function warnIfRetiring(model, h) {
+    const v = h.get("Sunset");
+    if (!v)
+        return;
+    const at = httpDateMs(v.trim());
+    if (at === undefined)
+        return;
+    const day = new Date(at).toISOString().slice(0, 10);
+    const k = `${model}|${day}`;
+    if (warnedRetirements.has(k) || warnedRetirements.size >= WARNED_RETIREMENTS_MAX)
+        return;
+    warnedRetirements.add(k);
+    const which = model ? `model ${JSON.stringify(model)}` : "the model this client uses";
+    console.warn(`wontopos: ${which} retires on ${day} (UTC). From then on its calls answer 410, except ` +
+        "deleteStore. listModels() lists the models you can move to.");
+}
+function _resetRetirementWarnings() {
+    warnedRetirements.clear();
 }
 const BRIEF_BODY_MS = 1_000;
 class SlowBody extends Error {
@@ -318,6 +344,23 @@ function tryUrl(s, base) {
         return undefined;
     }
 }
+function inBrowserPage() {
+    try {
+        const g = globalThis;
+        return typeof g.window !== "undefined" && typeof g.window.document !== "undefined" && typeof g.navigator !== "undefined";
+    }
+    catch {
+        return false;
+    }
+}
+function isServiceHost(host) {
+    const h = host.toLowerCase();
+    return h === "wontopos.com" || h.endsWith(".wontopos.com");
+}
+const BROWSER_REFUSAL = "wontopos: refusing to run in a browser page. The API key would be readable by anyone who " +
+    "opens the page, and with it every memory in its workspace. Call Wontopos from your server, " +
+    "or put a proxy of your own in front of it and point baseUrl there. For a local demo with a " +
+    "key you will revoke, pass dangerouslyAllowBrowser: true.";
 function pageHref() {
     try {
         const href = globalThis.location?.href;
@@ -394,6 +437,18 @@ const memoryFromGet = (r) => {
         return o.memory;
     return typeof o.id === "string" ? o : {};
 };
+function recallShape(r) {
+    const o = asObj(r);
+    const st = asObj(o.short_term);
+    const lt = asObj(o.long_term);
+    const cx = asObj(o.context);
+    return {
+        ...o,
+        short_term: { ...st, turns: asRecords(st.turns) },
+        long_term: { ...lt, memories: asRecords(lt.memories) },
+        context: { ...cx, around_top_memory: asList(cx.around_top_memory).filter((x) => typeof x === "string") },
+    };
+}
 function mergeResults(r) {
     const out = asRecords(r?.memories);
     const seen = new Set(out.map((m) => m.id).filter((id) => typeof id === "string"));
@@ -569,6 +624,15 @@ function writeKey(opts, takesImage = false) {
         (takesImage ? "add takes idempotencyKey and image." : "This call takes idempotencyKey only."));
     return opts.idempotencyKey;
 }
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function")
+        return `sdk-${String(c.randomUUID()).replace(/-/g, "")}`;
+    let hex = "";
+    for (let i = 0; i < 4; i++)
+        hex += Math.floor(Math.random() * 0x100000000).toString(16).padStart(8, "0");
+    return `sdk-${hex}`;
+}
 function warnOnUnknownFilters(filters) {
     warnOnceUnknownKeys(filters, KNOWN_FILTER_KEYS, warnedFilterKeys, (k) => `wontopos: unknown search filter ${JSON.stringify(k)} — the API drops keys it does not know, ` +
         `so this filter has NO effect and the search is wider than you think. ` +
@@ -597,6 +661,7 @@ class Client {
     userinfo;
     pageRelative;
     customFetch;
+    allowBrowser;
     defaultUser;
     _rateLimit = null;
     get rateLimit() {
@@ -630,6 +695,10 @@ class Client {
             throw new Error(notAUrl(trimmed));
         this.pageRelative = !url;
         this.userinfo = Boolean(parsed.username || parsed.password);
+        this.allowBrowser = opts.dangerouslyAllowBrowser === true;
+        if (!this.allowBrowser && inBrowserPage() && isServiceHost(parsed.hostname)) {
+            throw new Error(BROWSER_REFUSAL);
+        }
         this.timeoutMs = checkMs(opts.timeoutMs) ?? 30_000;
         this.model = opts.model ?? DEFAULT_MODEL;
         if (this.model && !MODEL_RE.test(this.model)) {
@@ -698,6 +767,7 @@ class Client {
             fetch: this.fetchImpl,
             deadlineMs: this.deadlineMs,
             signal: this.signal,
+            dangerouslyAllowBrowser: this.allowBrowser,
             ...overrides,
         });
     }
@@ -729,22 +799,22 @@ class Client {
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         warnOnUnknownMetadata(metadata);
-        return this.post("/api/v1/memory/store", body, writeKey(opts, true));
+        return this.write("/api/v1/memory/store", body, writeKey(opts, true));
     }
     async store(content, userId, metadata = {}, opts = {}) {
         return this.add(content, userId, metadata, opts);
     }
     async addTurn(userMsg, assistantMsg, userId, opts = {}) {
-        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, writeKey(opts));
+        return this.write("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, writeKey(opts));
     }
     async addBulk(content, userId, category = "general", timestamp, opts = {}) {
         const body = { user_id: this.uid(userId), content, category: category ?? "general" };
         if (timestamp)
             body.timestamp = timestamp;
-        return this.post("/api/v1/memory/bulk-store", body, writeKey(opts));
+        return this.write("/api/v1/memory/bulk-store", body, writeKey(opts));
     }
     async update(oldMemoryId, newContent, userId, opts = {}) {
-        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, writeKey(opts));
+        return this.write("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, writeKey(opts));
     }
     async search(query, userId, limit = 10, opts = {}) {
         checkSearchOpts(opts);
@@ -789,7 +859,7 @@ class Client {
             checkContextLimit(opts.context_limit);
             body.context_limit = opts.context_limit;
         }
-        return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
+        return recallShape(await this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz)));
     }
     async engram(name, query, userId, opts = {}) {
         checkOpts(opts, KNOWN_ENGRAM_KEYS, "engram");
@@ -994,8 +1064,12 @@ class Client {
         warnIfStoreIdCollapses(userId);
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
-    post(path, body, idempotencyKey) {
-        return this.request("POST", path, body, idempotencyKey);
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    write(path, body, idempotencyKey) {
+        const made = idempotencyKey == null;
+        return this.request("POST", path, body, made ? newIdempotencyKey() : idempotencyKey, false, made);
     }
     remove(path, body) {
         return this.request("DELETE", path, body, undefined, true);
@@ -1115,6 +1189,7 @@ class Client {
         const upper = method.toUpperCase();
         const logPath = path.split("?")[0];
         const idempotent = IDEMPOTENT_METHODS.has(upper) || reads || (upper === "POST" && READ_POSTS.has(logPath));
+        const replaySafe = idempotent || extraHeaders?.["Idempotency-Key"] !== undefined;
         const deadlineAt = this.deadlineAt();
         const headers = extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers;
         let ambiguous = false;
@@ -1156,7 +1231,7 @@ class Client {
                 if (timedOut)
                     throw cutShort();
                 const connect = isConnectFailure(e);
-                if ((idempotent || connect) && !last) {
+                if ((replaySafe || connect) && !last) {
                     if (!connect)
                         ambiguous = true;
                     await pauseWithoutAnswer(e?.code ?? e?.name ?? "network error");
@@ -1173,7 +1248,7 @@ class Client {
                         throw cutShort();
                     if (e instanceof WosError)
                         throw e;
-                    if (idempotent && !last)
+                    if (replaySafe && !last)
                         return null;
                     throw this.networkError(e, path);
                 }
@@ -1200,9 +1275,10 @@ class Client {
                     throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
                 }
                 this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
+                warnIfRetiring(this.model, res.headers);
                 if (!res.ok) {
                     const ra = retryAfterMs(res.headers.get("Retry-After"));
-                    let wait = RETRY_ALWAYS.has(res.status) || (RETRY_IF_IDEMPOTENT.has(res.status) && idempotent)
+                    let wait = RETRY_ALWAYS.has(res.status) || (RETRY_IF_IDEMPOTENT.has(res.status) && replaySafe)
                         ? ra ?? this.backoffMs(attempt)
                         : undefined;
                     const retrying = wait !== undefined && !last && wait <= MAX_RETRY_WAIT_MS && this.fits(wait, deadlineAt);
@@ -1329,7 +1405,7 @@ class Client {
             clearTimeout(timer);
         }
     }
-    async request(method, path, body, idempotencyKey, removes = false) {
+    async request(method, path, body, idempotencyKey, removes = false, madeKey = false) {
         const extraHeaders = this.idemHeader(idempotencyKey);
         let payload;
         try {
@@ -1357,7 +1433,7 @@ class Client {
             const got = data === null ? "null" : Array.isArray(data) ? "array" : typeof data;
             throw new WosError(res.status, `expected a JSON object in the response, got ${got}`);
         }
-        if (res.headers.get("Idempotent-Replayed") === "true" && !("replayed" in data)) {
+        if (!madeKey && res.headers.get("Idempotent-Replayed") === "true" && !("replayed" in data)) {
             data.replayed = true;
         }
         return data;

package/dist/wontopos.d.ts

@@ -28,9 +28,10 @@
  * Reliability: every call retries transient failures with exponential backoff +
  * jitter, honoring `Retry-After` up to 30s — 429 and a 409 that says another write
  * to the store was in flight, always; 408/502/503/504 and connection errors only when
- * a retry can never double-process a write (reads, the DELETE calls, or a failure at
- * connect time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
- * the `withTimeout()` / `withRetries()` clones.
+ * a retry can never double-process a write (reads, the DELETE calls, the memory writes,
+ * which carry an idempotency key, or a failure at connect time). Tune with `maxRetries`
+ * (0 disables) and `timeoutMs`, or per call site via the `withTimeout()` /
+ * `withRetries()` clones.
  *
  * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
  * to stderr — never memory content, request bodies, or the API key.
@@ -48,6 +49,8 @@ export declare const SEARCH_LIMIT_MAX = 20;
 /** `recall`'s surrounding-context count. 0 to 20 inclusive; 0 attaches none. */
 export declare const CONTEXT_LIMIT_MIN = 0;
 export declare const CONTEXT_LIMIT_MAX = 20;
+/** @deprecated Test hook. The warn-once set is process-global by design. */
+export declare function _resetRetirementWarnings(): void;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -100,8 +103,11 @@ export declare class PermissionDeniedError extends WosError {
 /** 404 — the store or resource doesn't exist. */
 export declare class NotFoundError extends WosError {
 }
-/** 409: another write to this store was in flight (retried automatically; nothing was
- *  stored), or the store id collides with an existing one (not retried). */
+/** 409: another write to this store was in flight, or the first request under this
+ *  write's idempotency key is still running (both retried automatically; nothing was
+ *  stored); the store id collides with an existing one (not retried); or the first
+ *  request under the key did not come back with an answer, so whether it was stored is
+ *  not known (not retried: check before sending it again under a new key). */
 export declare class ConflictError extends WosError {
     /** The existing store id this one collides with. Set only on a collision, which
      *  retrying cannot fix. */
@@ -184,7 +190,9 @@ export interface StoreResult {
     note?: string;
     /** `true` when this response was REPLAYED from a previous request with the same
      *  `idempotencyKey` — nothing new was stored. Absent on a fresh write. Read it to
-     *  tell "my retry landed" from "my retry was a no-op". */
+     *  tell "my retry landed" from "my retry was a no-op". This client sets it only for
+     *  a key you passed, and then the earlier request can also be an attempt of this same
+     *  call that the client sent again after an answer that left the outcome open. */
     replayed?: boolean;
     [key: string]: unknown;
 }
@@ -371,17 +379,25 @@ export interface SearchResult {
     [key: string]: unknown;
 }
 export interface RecallResult {
+    /** The recent conversation, oldest first. */
     short_term: {
-        turns: unknown[];
+        turns: HistoryTurn[];
         count: number;
+        [key: string]: unknown;
     };
+    /** The stored memories that match the query, best first. */
     long_term: {
         memories: Memory[];
         count: number;
+        [key: string]: unknown;
     };
+    /** The conversation around the best memory, in the order it was said. Each row is
+     *  text that starts with where it sits next to that memory: `[before] `, `[match] `
+     *  or `[after] `. Empty when there is no best memory or `context_limit` is 0. */
     context: {
-        around_top_memory: unknown[];
+        around_top_memory: string[];
         count: number;
+        [key: string]: unknown;
     };
     [key: string]: unknown;
 }
@@ -396,7 +412,7 @@ export interface EngramResult {
     usage?: Usage;
     [key: string]: unknown;
 }
-/** One turn of the short-term window, as `history()` returns it. */
+/** One turn of the short-term window, as `history()` and `recall()` return it. */
 export interface HistoryTurn {
     /** `"user"` or `"assistant"`. */
     role?: string;
@@ -636,25 +652,24 @@ export interface SearchOptions {
 /**
  * Per-call options for a write.
  *
- * `idempotencyKey` makes repeating THIS EXACT write safe: the API replays the first
- * response instead of storing again, for up to 10 minutes, and answers 422 if the
- * same key arrives with a different body. Use it when a retry is your own (a job that
- * died and was re-run, a queue that redelivers). The SDK retries a write on 429, and
- * on a 409 that says another write to the store was in flight: the service answers
- * both before it processes anything, so nothing was stored. It never retries a write
- * on 408 / 502 / 503 / 504 or a dropped body, where the write may already have been
- * applied — without a key the client cannot know whether it was.
+ * Every memory write (`add`, `addTurn`, `addBulk`, `update`) carries an idempotency key:
+ * `idempotencyKey` when you pass one, otherwise one this client makes for the call. With
+ * it the client retries the write on 408 / 502 / 503 / 504 and on a dropped connection,
+ * as it does a read: the service answers a repeat with the first attempt's result instead
+ * of storing again, and one that arrives while the first is still running with a 409 to
+ * wait, which is retried as well.
  *
- * The key covers a retry sent after the first attempt finished. A retry that overlaps
- * a first attempt still running can run twice, so wait for the first to fail before
- * re-sending.
+ * Pass your own key when the retry is yours: a job that died and was re-run, a queue
+ * that redelivers. The service keeps a key for 24 hours and answers a repeat with the
+ * first successful response, marked `replayed: true`; the same key with a different body
+ * is refused (422). A first attempt that failed is not kept, so a repeat of it runs,
+ * unless it did not come back with an answer, so whether it was applied is not known:
+ * then the repeat is refused with a `ConflictError` (409) instead of storing it twice.
+ * Check before sending it again under a new key.
  *
  * The key must be UNIQUE PER LOGICAL WRITE — derive it from the thing being stored
  * (`` `import:${row.id}` ``), never a constant, or the second write replays the first
  * and is silently lost. Format: 1-128 chars of `[A-Za-z0-9._:-]`, checked locally.
- *
- * The window is best-effort and can be shorter than 10 minutes; it is not a durable
- * de-duplication record.
  */
 export interface WriteOptions {
     idempotencyKey?: string;
@@ -782,6 +797,12 @@ export interface ClientOptions {
      *  (`res.redirected`) is refused. A fetch that sends the request to another URL
      *  on purpose, such as a proxy that rewrites it, is fine. */
     fetch?: FetchLike;
+    /** Run in a browser page anyway. Off by default: an API key in a page is readable by
+     *  everyone who opens it, and with it every memory in its workspace, so a client in a
+     *  page that would send the key to the service itself is refused. A `baseUrl` of your
+     *  own, a proxy that holds the real key, is not refused. Turn this on only for a local
+     *  demo with a key you will revoke. */
+    dangerouslyAllowBrowser?: boolean;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -803,6 +824,8 @@ export declare class Client {
     private readonly pageRelative;
     /** Whether the caller supplied `fetch`. */
     private readonly customFetch;
+    /** Whether the caller asked to run in a browser page anyway. */
+    private readonly allowBrowser;
     /** The store every call uses unless one passes `userId`. */
     private readonly defaultUser;
     private _rateLimit;
@@ -1022,10 +1045,10 @@ export declare class Client {
      */
     getImage(userId: string | undefined, memoryId: string): Promise<ImageBytes>;
     /**
-     * Remove the PHOTO from a memory, keeping its text.
+     * Remove the PHOTO from a memory. It can take the whole memory with it.
      *
-     * `preview: true` reports what would happen, including `memory_kept`, and changes
-     * nothing. Retried like `deleteStore`; without `preview`, a 404 after an ambiguous
+     * `preview: true` reports what would happen, including `memory_kept` (`false` when
+     * the memory itself would go), and changes nothing. Retried like `deleteStore`; without `preview`, a 404 after an ambiguous
      * failure carries the same note.
      *
      *     const p = await mem.forgetImage(undefined, id, { preview: true });
@@ -1182,6 +1205,11 @@ export declare class Client {
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId: string): Promise<StatusResult>;
     private post;
+    /** A memory write. It always carries an `Idempotency-Key`, the caller's or one made
+     *  for this call, so an answer that leaves the outcome open (408/502/503/504, a
+     *  dropped connection) can be retried: the service answers the retry with the first
+     *  attempt's result instead of storing again. */
+    private write;
     /** A DELETE that removes something: a 404 after an ambiguous failure says an earlier
      *  attempt may already have removed it. */
     private remove;
@@ -1223,7 +1251,8 @@ export declare class Client {
      * Retried: 429, and a 409 whose error carries `retry_after_ms` (another write to the
      * store was in flight; nothing was stored), on every method; 408/502/503/504 and
      * dropped connections on a call that only reads (an idempotent method, or a POST
-     * that only reads); connect failures on every method. A retry whose wait is over the
+     * that only reads) or a write that carries an idempotency key; connect failures on
+     * every method. A retry whose wait is over the
      * cap, or does not fit the deadline, is not made: the call fails with the error of
      * the response it has. So does a retry the deadline leaves no time to send, and the
      * retry of a call that only reads that the deadline cuts short. Any other retry cut

package/dist/wontopos.js

@@ -1,4 +1,4 @@
-const VERSION = "2.2.46";
+const VERSION = "2.2.47";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -263,12 +263,7 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 const IMF_FIXDATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) ([A-Z][a-z]{2}) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
 const RFC850_DATE = /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-([A-Z][a-z]{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
 const ASCTIME_DATE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) ([A-Z][a-z]{2}) ([ \d]\d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
-function retryAfterMs(v, now = Date.now()) {
-    if (v == null)
-        return undefined;
-    const s = v.trim();
-    if (/^\d+$/.test(s))
-        return Math.min(Number(s), Number.MAX_SAFE_INTEGER / 1000) * 1000;
+function httpDateMs(s, now = Date.now()) {
     let parts;
     let m;
     if ((m = IMF_FIXDATE.exec(s)))
@@ -288,7 +283,37 @@ function retryAfterMs(v, now = Date.now()) {
     const d = Number(day), h = Number(hh), mi = Number(mm), se = Number(ss);
     if (month < 0 || d < 1 || d > 31 || h > 23 || mi > 59 || se > 60)
         return undefined;
-    return Math.max(0, Date.UTC(year, month, d, h, mi, se) - now);
+    return Date.UTC(year, month, d, h, mi, se);
+}
+function retryAfterMs(v, now = Date.now()) {
+    if (v == null)
+        return undefined;
+    const s = v.trim();
+    if (/^\d+$/.test(s))
+        return Math.min(Number(s), Number.MAX_SAFE_INTEGER / 1000) * 1000;
+    const at = httpDateMs(s, now);
+    return at === undefined ? undefined : Math.max(0, at - now);
+}
+const warnedRetirements = new Set();
+const WARNED_RETIREMENTS_MAX = 64;
+function warnIfRetiring(model, h) {
+    const v = h.get("Sunset");
+    if (!v)
+        return;
+    const at = httpDateMs(v.trim());
+    if (at === undefined)
+        return;
+    const day = new Date(at).toISOString().slice(0, 10);
+    const k = `${model}|${day}`;
+    if (warnedRetirements.has(k) || warnedRetirements.size >= WARNED_RETIREMENTS_MAX)
+        return;
+    warnedRetirements.add(k);
+    const which = model ? `model ${JSON.stringify(model)}` : "the model this client uses";
+    console.warn(`wontopos: ${which} retires on ${day} (UTC). From then on its calls answer 410, except ` +
+        "deleteStore. listModels() lists the models you can move to.");
+}
+export function _resetRetirementWarnings() {
+    warnedRetirements.clear();
 }
 const BRIEF_BODY_MS = 1_000;
 class SlowBody extends Error {
@@ -313,6 +338,23 @@ function tryUrl(s, base) {
         return undefined;
     }
 }
+function inBrowserPage() {
+    try {
+        const g = globalThis;
+        return typeof g.window !== "undefined" && typeof g.window.document !== "undefined" && typeof g.navigator !== "undefined";
+    }
+    catch {
+        return false;
+    }
+}
+function isServiceHost(host) {
+    const h = host.toLowerCase();
+    return h === "wontopos.com" || h.endsWith(".wontopos.com");
+}
+const BROWSER_REFUSAL = "wontopos: refusing to run in a browser page. The API key would be readable by anyone who " +
+    "opens the page, and with it every memory in its workspace. Call Wontopos from your server, " +
+    "or put a proxy of your own in front of it and point baseUrl there. For a local demo with a " +
+    "key you will revoke, pass dangerouslyAllowBrowser: true.";
 function pageHref() {
     try {
         const href = globalThis.location?.href;
@@ -389,6 +431,18 @@ const memoryFromGet = (r) => {
         return o.memory;
     return typeof o.id === "string" ? o : {};
 };
+function recallShape(r) {
+    const o = asObj(r);
+    const st = asObj(o.short_term);
+    const lt = asObj(o.long_term);
+    const cx = asObj(o.context);
+    return {
+        ...o,
+        short_term: { ...st, turns: asRecords(st.turns) },
+        long_term: { ...lt, memories: asRecords(lt.memories) },
+        context: { ...cx, around_top_memory: asList(cx.around_top_memory).filter((x) => typeof x === "string") },
+    };
+}
 function mergeResults(r) {
     const out = asRecords(r?.memories);
     const seen = new Set(out.map((m) => m.id).filter((id) => typeof id === "string"));
@@ -553,6 +607,15 @@ function writeKey(opts, takesImage = false) {
         (takesImage ? "add takes idempotencyKey and image." : "This call takes idempotencyKey only."));
     return opts.idempotencyKey;
 }
+function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (typeof c?.randomUUID === "function")
+        return `sdk-${String(c.randomUUID()).replace(/-/g, "")}`;
+    let hex = "";
+    for (let i = 0; i < 4; i++)
+        hex += Math.floor(Math.random() * 0x100000000).toString(16).padStart(8, "0");
+    return `sdk-${hex}`;
+}
 function warnOnUnknownFilters(filters) {
     warnOnceUnknownKeys(filters, KNOWN_FILTER_KEYS, warnedFilterKeys, (k) => `wontopos: unknown search filter ${JSON.stringify(k)} — the API drops keys it does not know, ` +
         `so this filter has NO effect and the search is wider than you think. ` +
@@ -581,6 +644,7 @@ export class Client {
     userinfo;
     pageRelative;
     customFetch;
+    allowBrowser;
     defaultUser;
     _rateLimit = null;
     get rateLimit() {
@@ -614,6 +678,10 @@ export class Client {
             throw new Error(notAUrl(trimmed));
         this.pageRelative = !url;
         this.userinfo = Boolean(parsed.username || parsed.password);
+        this.allowBrowser = opts.dangerouslyAllowBrowser === true;
+        if (!this.allowBrowser && inBrowserPage() && isServiceHost(parsed.hostname)) {
+            throw new Error(BROWSER_REFUSAL);
+        }
         this.timeoutMs = checkMs(opts.timeoutMs) ?? 30_000;
         this.model = opts.model ?? DEFAULT_MODEL;
         if (this.model && !MODEL_RE.test(this.model)) {
@@ -682,6 +750,7 @@ export class Client {
             fetch: this.fetchImpl,
             deadlineMs: this.deadlineMs,
             signal: this.signal,
+            dangerouslyAllowBrowser: this.allowBrowser,
             ...overrides,
         });
     }
@@ -713,22 +782,22 @@ export class Client {
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         warnOnUnknownMetadata(metadata);
-        return this.post("/api/v1/memory/store", body, writeKey(opts, true));
+        return this.write("/api/v1/memory/store", body, writeKey(opts, true));
     }
     async store(content, userId, metadata = {}, opts = {}) {
         return this.add(content, userId, metadata, opts);
     }
     async addTurn(userMsg, assistantMsg, userId, opts = {}) {
-        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, writeKey(opts));
+        return this.write("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, writeKey(opts));
     }
     async addBulk(content, userId, category = "general", timestamp, opts = {}) {
         const body = { user_id: this.uid(userId), content, category: category ?? "general" };
         if (timestamp)
             body.timestamp = timestamp;
-        return this.post("/api/v1/memory/bulk-store", body, writeKey(opts));
+        return this.write("/api/v1/memory/bulk-store", body, writeKey(opts));
     }
     async update(oldMemoryId, newContent, userId, opts = {}) {
-        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, writeKey(opts));
+        return this.write("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, writeKey(opts));
     }
     async search(query, userId, limit = 10, opts = {}) {
         checkSearchOpts(opts);
@@ -773,7 +842,7 @@ export class Client {
             checkContextLimit(opts.context_limit);
             body.context_limit = opts.context_limit;
         }
-        return this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz));
+        return recallShape(await this.post("/api/v1/memory/recall", withForm(body, opts.form, opts.tz)));
     }
     async engram(name, query, userId, opts = {}) {
         checkOpts(opts, KNOWN_ENGRAM_KEYS, "engram");
@@ -978,8 +1047,12 @@ export class Client {
         warnIfStoreIdCollapses(userId);
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
-    post(path, body, idempotencyKey) {
-        return this.request("POST", path, body, idempotencyKey);
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    write(path, body, idempotencyKey) {
+        const made = idempotencyKey == null;
+        return this.request("POST", path, body, made ? newIdempotencyKey() : idempotencyKey, false, made);
     }
     remove(path, body) {
         return this.request("DELETE", path, body, undefined, true);
@@ -1099,6 +1172,7 @@ export class Client {
         const upper = method.toUpperCase();
         const logPath = path.split("?")[0];
         const idempotent = IDEMPOTENT_METHODS.has(upper) || reads || (upper === "POST" && READ_POSTS.has(logPath));
+        const replaySafe = idempotent || extraHeaders?.["Idempotency-Key"] !== undefined;
         const deadlineAt = this.deadlineAt();
         const headers = extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers;
         let ambiguous = false;
@@ -1140,7 +1214,7 @@ export class Client {
                 if (timedOut)
                     throw cutShort();
                 const connect = isConnectFailure(e);
-                if ((idempotent || connect) && !last) {
+                if ((replaySafe || connect) && !last) {
                     if (!connect)
                         ambiguous = true;
                     await pauseWithoutAnswer(e?.code ?? e?.name ?? "network error");
@@ -1157,7 +1231,7 @@ export class Client {
                         throw cutShort();
                     if (e instanceof WosError)
                         throw e;
-                    if (idempotent && !last)
+                    if (replaySafe && !last)
                         return null;
                     throw this.networkError(e, path);
                 }
@@ -1184,9 +1258,10 @@ export class Client {
                     throw new WosError(res.status, "unexpected redirect — refused (the API key never follows a redirect). Check baseUrl: exact host, https://.");
                 }
                 this._rateLimit = parseRateLimit(res.headers) ?? this._rateLimit;
+                warnIfRetiring(this.model, res.headers);
                 if (!res.ok) {
                     const ra = retryAfterMs(res.headers.get("Retry-After"));
-                    let wait = RETRY_ALWAYS.has(res.status) || (RETRY_IF_IDEMPOTENT.has(res.status) && idempotent)
+                    let wait = RETRY_ALWAYS.has(res.status) || (RETRY_IF_IDEMPOTENT.has(res.status) && replaySafe)
                         ? ra ?? this.backoffMs(attempt)
                         : undefined;
                     const retrying = wait !== undefined && !last && wait <= MAX_RETRY_WAIT_MS && this.fits(wait, deadlineAt);
@@ -1313,7 +1388,7 @@ export class Client {
             clearTimeout(timer);
         }
     }
-    async request(method, path, body, idempotencyKey, removes = false) {
+    async request(method, path, body, idempotencyKey, removes = false, madeKey = false) {
         const extraHeaders = this.idemHeader(idempotencyKey);
         let payload;
         try {
@@ -1341,7 +1416,7 @@ export class Client {
             const got = data === null ? "null" : Array.isArray(data) ? "array" : typeof data;
             throw new WosError(res.status, `expected a JSON object in the response, got ${got}`);
         }
-        if (res.headers.get("Idempotent-Replayed") === "true" && !("replayed" in data)) {
+        if (!madeKey && res.headers.get("Idempotent-Replayed") === "true" && !("replayed" in data)) {
             data.replayed = true;
         }
         return data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.46",
+  "version": "2.2.47",
   "description": "Wontopos \u2014 long-term memory for AI agents. Identical recall in every language, ~100\u00d7 lower LLM bill.",
   "keywords": [
     "memory",