wontopos 2.2.44 → 2.2.46

package/README.md

@@ -5,7 +5,7 @@ npm install wontopos
 ```
 
 Get an API key in the [console](https://wontopos.com). Keys look like `wos-live-...`;
-the client also reads `WONTOPOS_API_KEY` from the environment.
+`Client.fromEnv()` reads `WONTOPOS_API_KEY` from the environment instead.
 
 ```ts
 import { Client } from "wontopos";
@@ -24,8 +24,8 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 ## Why
 
 - **The same in every language** — identical recall whichever language a memory was written in (Korean · Japanese · Chinese · English).
-- **No LLM in the loop** — `store` / `search` / `recall` never call a language model. You pay retrieval, not generation.
-- **Bounded retrieval** — `recall()` returns a small, fixed-size slice regardless of how much you've stored (~1,000 tokens on `tablet-2`, the default engine).
+- **No LLM reads your memories** — no language model reads your stored memories, on any model. You pay retrieval, not generation.
+- **Bounded retrieval** — `recall()` returns the recent turns, at most `limit` long-term memories (default 10, up to 20) and at most `context_limit` rows of the surrounding conversation (default 10, up to 20), however much you've stored.
 
 ## Methods
 
@@ -35,10 +35,10 @@ Where the store id goes depends on whether the method takes a payload. A method
 writes or searches puts the payload first and the store second — `mem.add("...", "alice")`,
 `mem.search("...", "alice")`. A method that only addresses a store takes it first —
 `mem.listMemories("alice")`, `mem.stats("alice")`, `mem.delete("alice", memoryId)`.
-Most of them let you leave it out for the client's default store. Four take it
-positionally and cannot — `get`, `delete`, `lineage` and `forgetImage` want an explicit
-`undefined` there, because a second required argument follows it. Python omits it in
-all four; this is the one place the three clients differ in shape rather than meaning.
+Most of them let you leave it out for the client's default store. Five take it
+positionally and cannot — `get`, `getImage`, `delete`, `lineage` and `forgetImage` want
+an explicit `undefined` there, because a second required argument follows it. Python
+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.
 
 ## Who said it (speakers)
@@ -56,19 +56,22 @@ await mem.search("what did Bob say about deadlines?", "alice", 10, { speaker: "B
 ```
 
 `listSpeakers()` shows the registered people with per-person memory counts;
-`removeSpeaker()` unregisters (memories stay, the tag goes). A store registers
+`removeSpeaker()` unregisters (memories stay; the tag goes, except on `tablet-2`, which keeps it on memories already stored). A store registers
 up to 50 people to start (a limit we plan to raise); `"me"` never needs
 registration and never counts against it.
 
 ## Recall caching
 
-Opt in per search and repeated or extended queries reuse the previous result
-at 10% of the normal rate (Tablet and Scroll models).
+Opt in per search and a repeated query reuses the previous result at 10% of the
+normal rate; an extended one reuses part of it (Tablet and Scroll models).
 
 It is not free to turn on: the FIRST call writes the cache and bills the query
-tokens at 2x for a `5m` TTL, 3x for `1h`. Only hits inside the TTL bill at 0.1x.
-So it pays for a query you repeat or extend, and costs more for one you issue
-once — do not switch it on globally. Any write to the store invalidates its cache
+tokens at 2x for a `5m` TTL, 3x for `1h`. The same query again inside the TTL bills
+its query and its results at 0.1x. A query that extends the cached one (its text plus
+more) bills the cached part at 0.1x, the new part at the write rate and its results
+at the normal rate. A store keeps one cached query per model and set of options, so a
+different query replaces it. So it pays for a query you repeat or extend, and costs
+more for one you issue once — do not switch it on globally. Any write to the store invalidates its cache
 at once, so a hit can never predate a new memory.
 
 ```ts
@@ -82,11 +85,11 @@ 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.
-  The writes and the searches are POSTs, and any of those four may have been returned
-  *after* the write already landed, so those get 429, that 409 and connect-level
-  failures only. The GET and DELETE calls — `ping`, `listStores`, `listSpeakers`,
-  `listModels`, `listEngrams`, `usage`, `deleteStore`, `removeSpeaker`, `forgetImage` —
-  retry all four. Twice, with exponential backoff + jitter, honoring the server's
+  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.
 - **Redirects refused** — the API key never follows a 3xx to another host.
 - **Timeouts** — 30s per attempt by default (`timeoutMs`), and a total budget for
@@ -112,6 +115,7 @@ This one needs `npm i undici` — Node's global `fetch` is built on undici, but
 package itself is not installed for you.
 
 ```ts
+import { Client } from "wontopos";
 import { ProxyAgent } from "undici";
 
 const agent = new ProxyAgent(process.env.HTTPS_PROXY!);
@@ -146,8 +150,9 @@ Built in, none of it configurable off:
 Every method returns a documented shape — `StoreResult`, `UpdateResult`,
 `RecallResult`, `EngramResult`, `StatsResult`, `SpeakersList`, `Memory[]`, ... —
 each with an index signature, so new server fields flow through without an SDK
-update. `search` options are typed too (`SearchOptions`: `cache_control`,
-`speaker`, plus pass-through).
+update. `searchSelf`'s result and `getImage`'s bytes are built by the client and
+carry only their own fields. `search` options are typed too (`SearchOptions`: `cache_control`,
+`speaker`, plus `extra` for pass-through).
 
 ```ts
 import { type Memory } from "wontopos";
@@ -156,7 +161,8 @@ const hits: Memory[] = await mem.search("what did Bob say?", "alice", 10, { spea
 console.log(hits[0].speaker, hits[0].time_bucket);   // typed: string | undefined
 ```
 
-`hits` arrives best-first — take it in the order given. `similarity` is a raw
+`hits` holds memories best-first, then the assistant's own words and image memories in
+their own order. Take it in the order given. `similarity` is a raw
 closeness score, not the ranking key: what produces the order is internal and is
 not returned, so sorting by `similarity` overrides the ranking and makes results
 worse. There is no `score` field.
@@ -206,14 +212,14 @@ Found something wrong, or something that looks unsafe? Tell us — every report
 - Security: <https://wontopos.com/contact?topic=security> (also published at
   [`/.well-known/security.txt`](https://wontopos.com/.well-known/security.txt))
 
-Include the SDK version (`the version in package.json`) and the language. If it involves a store id or a
+Include the SDK version (the one in package.json) and the language. If it involves a store id or a
 memory, describe the shape rather than pasting the contents — we do not need your
 data to fix it.
 
 ## Changelog
 
 The three clients release in lockstep — same version, same surface, same day. Patch
-releases are additive. Eight inside 2.2 were not, deliberately and each with its
+releases are additive. Nine 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

@@ -14,7 +14,7 @@
  * (`createStore`) or calls return 404. Every account starts with a `default` store,
  * so with no `userId` anywhere the zero-setup path just works.
  *
- * The API key picks *which memory* (your account); `model` picks *which engine*
+ * The API key picks *which memory* (your workspace); `model` picks *which engine*
  * reads it. Models on the shared pool read the same memory, so you can store with
  * one and recall with another; `listModels()` reports each model's `memory` as
  * `"shared"` or `"isolated"`, and an isolated one starts empty. Set a default in
@@ -22,14 +22,14 @@
  * `mem.withModel("tablet-1").recall(...)`.
  *
  * Recall quality does not depend on which language a memory was written in: a
- * memory stored in one language is found by a question asked in another. Storing
- * and searching call no LLM.
+ * memory stored in one language is found by a question asked in another. No language
+ * model reads your stored memories.
  *
  * 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 (idempotent calls, or a failure at connect
- * time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
+ * 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.
  *
  * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
@@ -89,7 +89,9 @@ export declare class BadRequestError extends WosError {
 /** 401 — the API key is missing, wrong, or revoked. */
 export declare class AuthenticationError extends WosError {
 }
-/** 402 — no card on file or the balance is depleted. Top up to continue. */
+/** 402 — no card on file, the balance is depleted, or the month's spend cap for the
+ *  account's tier is reached (`details.reason` is `tier_cap_reached`). Top up to
+ *  continue; a top-up also raises the tier. */
 export declare class PaymentRequiredError extends WosError {
 }
 /** 403 — the key/model isn't allowed to do this. */
@@ -194,8 +196,9 @@ export interface StatusResult {
 /**
  * An image attached to a memory, passed to `add`/`store` via `opts.image`.
  *
- * Both edges must be 700px or more; a smaller image is refused (400). A request
- * body is capped at 10MB.
+ * Both edges must be 700px or more and the long edge at most 2500px, and the image
+ * file at most 7MB; anything else is refused (400) with the reason. A request body is
+ * capped at 10MB.
  *
  * What the service keeps is NOT your original. An image whose long edge is over
  * 1568px is downscaled to 1568 before anything else happens, and that smaller
@@ -241,8 +244,9 @@ export interface ImageBytes {
      * The image as stored. Write it to a file, or wrap it in a Blob to show it.
      *
      * This is the service's copy, not necessarily your upload: anything over 1568px
-     * on its long edge was downscaled on the way in, and re-encoded to WebP unless it
-     * was a JPEG (see `ImageInput`). Take the file extension from `contentType`.
+     * on its long edge (2500 at most) was downscaled on the way in, and re-encoded to
+     * WebP unless it was a JPEG (see `ImageInput`). Take the file extension from
+     * `contentType`.
      */
     bytes: Uint8Array;
     /** Sniffed from the BYTES, not from whatever the upload was named — e.g. `image/jpeg`. */
@@ -317,7 +321,8 @@ export interface LineageStep {
     is_current?: boolean;
     [key: string]: unknown;
 }
-/** `lineage` → the full chain of edits behind one memory, oldest first. */
+/** `lineage` → the edits that followed one memory, from the id passed forward to the
+ *  version in force, oldest first. */
 export interface LineageResult {
     memory_id?: string;
     chain: LineageStep[];
@@ -360,8 +365,8 @@ export interface SearchResult {
     /** Image memories the answer carried (one by default on an image-capable model,
      *  up to `max_images`); `[]` when there were none. */
     images: Memory[];
-    /** Re-ask passes actually performed. Present only when `verify` was sent; lower
-     *  than you asked for means the store had nothing further to add. */
+    /** Re-ask passes that added memories. Present only when `verify` above 0 was sent;
+     *  lower than you asked for means a pass found nothing new, or could not run. */
     verify_used?: number;
     [key: string]: unknown;
 }
@@ -414,7 +419,7 @@ export interface UsageResult {
         output_tokens?: number;
         since?: string;
     };
-    /** The workspace this key belongs to, over the window. */
+    /** The workspace this key belongs to, over the window: every key in it, not only this one. */
     workspace?: {
         workspace_id?: string | null;
         requests?: number;
@@ -542,9 +547,8 @@ export interface SpeakersList {
     [key: string]: unknown;
 }
 /**
- * Narrow a search to part of a store. The filter chooses what is searched, not what
- * is kept afterwards — so a narrow filter still returns your full `limit` when that
- * many matches sit inside it.
+ * Narrow a search to part of a store. A narrow filter can return fewer than `limit`
+ * even when the store holds more inside it.
  *
  * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
@@ -565,7 +569,8 @@ export interface SearchFilters {
     time_from?: string;
     time_to?: string;
     /** WHEN THE CONTENT HAPPENED (`metadata.event_date`), not when it was written —
-     *  this is the one you usually want. */
+     *  this is the one you usually want. A memory stored without an `event_date` is
+     *  matched by when it was stored. */
     event_from?: string;
     event_to?: string;
     /** Drop matches the engine scored below this importance (0–1). */
@@ -578,9 +583,11 @@ export declare function _resetFilterWarnings(): void;
  *  could not be told from an option that worked. Put a genuinely new one under
  *  `extra`. */
 export interface SearchOptions {
-    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
-     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
-     *  this only pays for a query you repeat or extend. Do not enable it globally. */
+    /** Recall caching. The same query again inside the TTL bills at 0.1×; one that
+     *  extends the cached query bills only its cached part at 0.1×, the new part at the
+     *  write rate and its results at the normal rate. The FIRST call writes the cache
+     *  and bills the query tokens at 2× (`5m`) or 3× (`1h`), so this only pays for a
+     *  query you repeat or extend. Do not enable it globally. */
     cache_control?: {
         ttl: "5m" | "1h";
     };
@@ -591,9 +598,9 @@ export interface SearchOptions {
     /**
      * Re-ask passes, 0–3. After the first retrieval the service asks the engine again up
      * to this many times, each time telling it what was already returned so it skips
-     * those and reaches further back. No LLM runs at any
+     * those and reaches further back. Raising it adds no language model call at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
-     * says how many actually ran.
+     * says how many passes added memories.
      *
      * Each pass is another engine call and can add up to `limit` more memories, so it
      * costs more — you are billed for what is delivered. Default 0. Worth it on questions
@@ -652,9 +659,10 @@ export interface SearchOptions {
 export interface WriteOptions {
     idempotencyKey?: string;
     /**
-     * An image to store alongside the text. Needs a model that lists `images` in its
-     * `listModels()` capabilities; any other refuses the write rather than store the
-     * caption and quietly drop the image.
+     * An image to store alongside the text, read by `add` (and `store`) only: `addTurn`,
+     * `addBulk` and `update` warn about it and do not send it. Needs a model that lists
+     * `images` in its `listModels()` capabilities; any other refuses the write rather than
+     * store the caption and quietly drop the image.
      *
      * A caption is required: the service refuses empty `content` (400) even with an
      * image attached.
@@ -858,15 +866,16 @@ export declare class Client {
     addBulk(content: string, userId?: string, category?: string, timestamp?: string, opts?: WriteOptions): Promise<StatusResult>;
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
     update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
-    /** Search a store's memories. Returns them most relevant first.
+    /** Search a store's memories. They come most relevant first; the assistant's own
+     *  words and image memories, when there are any, follow them in their own order.
      *
      *  `limit` is 5-20, and out of range is refused rather than clamped: asking for 50
      *  and silently receiving 20 reads as "that is all there is". The default is 10.
      *
-     *  `limit` bounds `memories`, not the returned array. The assistant's own words (on
-     *  a model that lists `self_memories` in its capabilities) and image memories (one
-     *  unless `max_images` says otherwise, on a model that lists `images`) come back in
-     *  it as well, so it can hold more than `limit`. They are billed either way. Size a
+     *  `limit` bounds `memories`, not the returned array, and each `verify` pass can add
+     *  up to `limit` more. The assistant's own words (on a model that lists
+     *  `self_memories` in its capabilities) and image memories (one unless `max_images`
+     *  says otherwise, on a model that lists `images`) come back after them in it as well, so it can hold more than `limit`. They are billed either way. Size a
      *  prompt window on the array you get back, not on `limit`. `searchFull()` hands the
      *  fields back apart.
      *
@@ -890,7 +899,7 @@ export declare class Client {
      *     const r = await mem.searchFull("the day we moved", "alice", 10,
      *                                    { max_images: 3, verify: 2 });
      *     r.images.length;   // the photos, apart from the text memories
-     *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
+     *     r.verify_used;     // re-ask passes that added memories (each billed for what it added)
      *
      * Each option needs a model that lists it in its `listModels()` capabilities
      * (`images`, `re_ask`) and is refused (403) on any other rather than accepted and
@@ -927,7 +936,8 @@ export declare class Client {
     }): Promise<EngramResult>;
     /** Recent conversation turns (short-term memory). */
     history(userId?: string): Promise<HistoryTurn[]>;
-    /** Memory counts for a store: { total_memories, short_term_turns }. */
+    /** Memory counts for a store: { total_memories, short_term_turns }. `total_memories`
+     *  can be larger than the number `listMemories` lists. */
     stats(userId?: string): Promise<StatsResult>;
     /**
      * What this key has spent, and what is left — the numbers behind "can I keep going?".
@@ -935,18 +945,17 @@ export declare class Client {
      * Free: it carries no charge and skips the balance gate, because an account at zero
      * still has to be able to find out why. Rate-limited instead.
      *
-     * Scoped to THIS key: its own lifetime spend, its workspace and stores over the
-     * window. It never returns another key's spend. `balance_cents` is account-wide,
-     * because that is what gates the next call whichever key makes it.
+     * `key` is THIS key's own lifetime spend. `workspace` and `stores` cover the window
+     * for the workspace this key belongs to, every key in it included. `balance_cents` is
+     * account-wide, because that is what gates the next call whichever key makes it.
      *
      *     const u = await mem.usage(7);
      *     if (u.balance_cents! < 100) stop();
      */
     usage(days?: number): Promise<UsageResult>;
     /** Fetch ONE memory by id — the text you stored, and its metadata.
-     * The id is what `add`/`store` or `listMemories` returned. Same visibility as
-     * `listMemories`: an id from another store, an id `listMemories` does not return,
-     * or an invalidated memory rejects with `NotFoundError`. Pass `undefined` as
+     * The id is what `add`/`store` or `listMemories` returned. An unknown id or one
+     * from another store rejects with `NotFoundError`. Pass `undefined` as
      * `userId` for the default store — it is positional here. */
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** List a store's stored memories — the text you stored, plus its metadata.
@@ -992,9 +1001,10 @@ export declare class Client {
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
      *
      * Not necessarily your upload, in size OR in format: an image whose long edge was
-     * over 1568px was downscaled to 1568 on the way in and re-encoded — lossless
-     * formats as WebP, so a PNG comes back as `image/webp`; JPEG stays JPEG — and that
-     * smaller picture is what is stored and comes back here. Nothing on our side ever
+     * over 1568px (2500 at most) was downscaled to 1568 on the way in and re-encoded —
+     * lossless formats as WebP, so a PNG comes back as `image/webp`; JPEG stays JPEG;
+     * kept as sent when the re-encode came out bigger — and that smaller picture is what
+     * is stored and comes back here. Nothing on our side ever
      * uses more than 1568, so the extra pixels would be bytes nobody reads.
      * Keep your own copy for the full-resolution file.
      *
@@ -1099,11 +1109,13 @@ export declare class Client {
         skipIds?: string[];
     }): Promise<RevisionsResult>;
     /**
-     * The full chain of edits behind one memory, oldest first.
+     * The edits that followed one memory: from the id you pass forward to the version in
+     * force, oldest first.
      *
-     * `is_current` marks the version in force. Use it to answer "what did this used to
-     * say, and when did it change" — `revisions()` tells you HOW MUCH a store moved,
-     * this tells you what happened to one fact.
+     * `is_current` marks the version in force. The chain runs forward only, so to answer
+     * "what did this used to say, and when did it change" pass the first version's id;
+     * the current version's id (what `search` returns) comes back alone. `revisions()`
+     * tells you HOW MUCH a store moved, this tells you what happened to one fact.
      */
     lineage(userId: string | undefined, memoryId: string): Promise<LineageResult>;
     /**
@@ -1125,8 +1137,7 @@ export declare class Client {
      * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
      * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
     ping(): Promise<boolean>;
-    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`.
-     *  Needs no API key. */
+    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`. */
     listModels(): Promise<ModelInfo[]>;
     /**
      * The engrams (and delivery forms) the selected model can actually run.
@@ -1159,7 +1170,9 @@ export declare class Client {
     addSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** The store's registered people, each with its memory count. */
     listSpeakers(userId?: string): Promise<SpeakersList>;
-    /** Unregister a person. Their memories stay; the name tag goes. Retried like
+    /** Unregister a person. Their memories stay, and the name can no longer tag a new
+     *  memory or filter a search. The tag goes from stored memories too, except on
+     *  `tablet-2`, which keeps it on memories already stored with it. Retried like
      *  `deleteStore`, with the same note on a 404 after an ambiguous failure. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** Delete a single memory by id. Pass `undefined` as `userId` for the default
@@ -1209,12 +1222,12 @@ 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 idempotent methods; 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 an idempotent method or of a POST that
-     * only reads that the deadline cuts short. Any other retry cut short stays a status-0
-     * deadline error: a write may have been applied.
+     * 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
+     * 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
+     * short stays a status-0 deadline error: a write may have been applied.
      */
     private send;
     /**

package/dist/cjs/wontopos.js

@@ -3,7 +3,7 @@ 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._resetFilterWarnings = _resetFilterWarnings;
-const VERSION = "2.2.44";
+const VERSION = "2.2.46";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -508,7 +508,7 @@ const KNOWN_ENGRAM_KEYS = new Set(["form", "tz"]);
 function checkSearchOpts(opts) {
     checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
     const o = opts;
-    optRange(o.max_images !== undefined ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
+    optRange(o.max_images != null ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
 }
 function checkOpts(opts, known, what) {
     for (const k of Object.keys(opts)) {
@@ -558,6 +558,17 @@ function warnOnceUnknownKeys(obj, known, warned, message) {
         console.warn(message(k));
     }
 }
+function givenOpts(known) {
+    return Object.fromEntries(Object.entries(known).filter(([, v]) => v !== null));
+}
+const ADD_KEYS = new Set(["idempotencyKey", "image"]);
+const WRITE_KEYS = new Set(["idempotencyKey"]);
+const warnedWriteKeys = new Set();
+function writeKey(opts, takesImage = false) {
+    warnOnceUnknownKeys(opts, takesImage ? ADD_KEYS : WRITE_KEYS, warnedWriteKeys, (k) => `wontopos: write option ${JSON.stringify(k)} is not sent. ` +
+        (takesImage ? "add takes idempotencyKey and image." : "This call takes idempotencyKey only."));
+    return opts.idempotencyKey;
+}
 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. ` +
@@ -718,22 +729,22 @@ class Client {
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         warnOnUnknownMetadata(metadata);
-        return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
+        return this.post("/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 }, opts.idempotencyKey);
+        return this.post("/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 };
+        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, opts.idempotencyKey);
+        return this.post("/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 }, opts.idempotencyKey);
+        return this.post("/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);
@@ -741,7 +752,7 @@ class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return mergeResults(r);
     }
     async searchSelf(query, userId, limit = 10, opts = {}) {
@@ -750,7 +761,7 @@ class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
     async searchFull(query, userId, limit = 10, opts = {}) {
@@ -759,7 +770,7 @@ class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return {
             ...r,
             memories: asRecords(r.memories),
@@ -894,9 +905,13 @@ class Client {
         throw truncatedWalk(`stopped after ${MAX_PAGES} pages — the store did not end.`);
     }
     async revisions(userId, opts = {}) {
+        const inc = opts.include;
+        if (inc !== undefined && inc !== null && inc !== "revised" && inc !== "unrevised") {
+            throw new Error(`include must be "revised" or "unrevised", got ${JSON.stringify(inc)}.`);
+        }
         const limit = optRange(opts.limit, "limit", PAGE_LIMIT_MIN, PAGE_LIMIT_MAX);
         const body = {};
-        if (opts.include !== undefined)
+        if (opts.include != null)
             body.include = opts.include;
         if (limit !== undefined)
             body.limit = limit;
@@ -1098,8 +1113,8 @@ class Client {
         }
         const attempts = this.maxRetries + 1;
         const upper = method.toUpperCase();
-        const idempotent = IDEMPOTENT_METHODS.has(upper);
         const logPath = path.split("?")[0];
+        const idempotent = IDEMPOTENT_METHODS.has(upper) || reads || (upper === "POST" && READ_POSTS.has(logPath));
         const deadlineAt = this.deadlineAt();
         const headers = extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers;
         let ambiguous = false;
@@ -1120,7 +1135,7 @@ class Client {
             };
             const cutShort = () => {
                 const why = att.why();
-                if (why === "deadline" && (idempotent || reads || (upper === "POST" && READ_POSTS.has(logPath))) && previous) {
+                if (why === "deadline" && idempotent && previous) {
                     return previous;
                 }
                 return new APIConnectionError(0, this.abortMessage(why));

package/dist/wontopos.d.ts

@@ -14,7 +14,7 @@
  * (`createStore`) or calls return 404. Every account starts with a `default` store,
  * so with no `userId` anywhere the zero-setup path just works.
  *
- * The API key picks *which memory* (your account); `model` picks *which engine*
+ * The API key picks *which memory* (your workspace); `model` picks *which engine*
  * reads it. Models on the shared pool read the same memory, so you can store with
  * one and recall with another; `listModels()` reports each model's `memory` as
  * `"shared"` or `"isolated"`, and an isolated one starts empty. Set a default in
@@ -22,14 +22,14 @@
  * `mem.withModel("tablet-1").recall(...)`.
  *
  * Recall quality does not depend on which language a memory was written in: a
- * memory stored in one language is found by a question asked in another. Storing
- * and searching call no LLM.
+ * memory stored in one language is found by a question asked in another. No language
+ * model reads your stored memories.
  *
  * 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 (idempotent calls, or a failure at connect
- * time). Tune with `maxRetries` (0 disables) and `timeoutMs`, or per call site via
+ * 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.
  *
  * Debugging: set `WONTOPOS_LOG=debug` to log method/path/status/timing/retries
@@ -89,7 +89,9 @@ export declare class BadRequestError extends WosError {
 /** 401 — the API key is missing, wrong, or revoked. */
 export declare class AuthenticationError extends WosError {
 }
-/** 402 — no card on file or the balance is depleted. Top up to continue. */
+/** 402 — no card on file, the balance is depleted, or the month's spend cap for the
+ *  account's tier is reached (`details.reason` is `tier_cap_reached`). Top up to
+ *  continue; a top-up also raises the tier. */
 export declare class PaymentRequiredError extends WosError {
 }
 /** 403 — the key/model isn't allowed to do this. */
@@ -194,8 +196,9 @@ export interface StatusResult {
 /**
  * An image attached to a memory, passed to `add`/`store` via `opts.image`.
  *
- * Both edges must be 700px or more; a smaller image is refused (400). A request
- * body is capped at 10MB.
+ * Both edges must be 700px or more and the long edge at most 2500px, and the image
+ * file at most 7MB; anything else is refused (400) with the reason. A request body is
+ * capped at 10MB.
  *
  * What the service keeps is NOT your original. An image whose long edge is over
  * 1568px is downscaled to 1568 before anything else happens, and that smaller
@@ -241,8 +244,9 @@ export interface ImageBytes {
      * The image as stored. Write it to a file, or wrap it in a Blob to show it.
      *
      * This is the service's copy, not necessarily your upload: anything over 1568px
-     * on its long edge was downscaled on the way in, and re-encoded to WebP unless it
-     * was a JPEG (see `ImageInput`). Take the file extension from `contentType`.
+     * on its long edge (2500 at most) was downscaled on the way in, and re-encoded to
+     * WebP unless it was a JPEG (see `ImageInput`). Take the file extension from
+     * `contentType`.
      */
     bytes: Uint8Array;
     /** Sniffed from the BYTES, not from whatever the upload was named — e.g. `image/jpeg`. */
@@ -317,7 +321,8 @@ export interface LineageStep {
     is_current?: boolean;
     [key: string]: unknown;
 }
-/** `lineage` → the full chain of edits behind one memory, oldest first. */
+/** `lineage` → the edits that followed one memory, from the id passed forward to the
+ *  version in force, oldest first. */
 export interface LineageResult {
     memory_id?: string;
     chain: LineageStep[];
@@ -360,8 +365,8 @@ export interface SearchResult {
     /** Image memories the answer carried (one by default on an image-capable model,
      *  up to `max_images`); `[]` when there were none. */
     images: Memory[];
-    /** Re-ask passes actually performed. Present only when `verify` was sent; lower
-     *  than you asked for means the store had nothing further to add. */
+    /** Re-ask passes that added memories. Present only when `verify` above 0 was sent;
+     *  lower than you asked for means a pass found nothing new, or could not run. */
     verify_used?: number;
     [key: string]: unknown;
 }
@@ -414,7 +419,7 @@ export interface UsageResult {
         output_tokens?: number;
         since?: string;
     };
-    /** The workspace this key belongs to, over the window. */
+    /** The workspace this key belongs to, over the window: every key in it, not only this one. */
     workspace?: {
         workspace_id?: string | null;
         requests?: number;
@@ -542,9 +547,8 @@ export interface SpeakersList {
     [key: string]: unknown;
 }
 /**
- * Narrow a search to part of a store. The filter chooses what is searched, not what
- * is kept afterwards — so a narrow filter still returns your full `limit` when that
- * many matches sit inside it.
+ * Narrow a search to part of a store. A narrow filter can return fewer than `limit`
+ * even when the store holds more inside it.
  *
  * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
@@ -565,7 +569,8 @@ export interface SearchFilters {
     time_from?: string;
     time_to?: string;
     /** WHEN THE CONTENT HAPPENED (`metadata.event_date`), not when it was written —
-     *  this is the one you usually want. */
+     *  this is the one you usually want. A memory stored without an `event_date` is
+     *  matched by when it was stored. */
     event_from?: string;
     event_to?: string;
     /** Drop matches the engine scored below this importance (0–1). */
@@ -578,9 +583,11 @@ export declare function _resetFilterWarnings(): void;
  *  could not be told from an option that worked. Put a genuinely new one under
  *  `extra`. */
 export interface SearchOptions {
-    /** Recall caching. A hit inside the TTL bills at 0.1× — but the FIRST call
-     *  writes the cache and bills the query tokens at 2× (`5m`) or 3× (`1h`), so
-     *  this only pays for a query you repeat or extend. Do not enable it globally. */
+    /** Recall caching. The same query again inside the TTL bills at 0.1×; one that
+     *  extends the cached query bills only its cached part at 0.1×, the new part at the
+     *  write rate and its results at the normal rate. The FIRST call writes the cache
+     *  and bills the query tokens at 2× (`5m`) or 3× (`1h`), so this only pays for a
+     *  query you repeat or extend. Do not enable it globally. */
     cache_control?: {
         ttl: "5m" | "1h";
     };
@@ -591,9 +598,9 @@ export interface SearchOptions {
     /**
      * Re-ask passes, 0–3. After the first retrieval the service asks the engine again up
      * to this many times, each time telling it what was already returned so it skips
-     * those and reaches further back. No LLM runs at any
+     * those and reaches further back. Raising it adds no language model call at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
-     * says how many actually ran.
+     * says how many passes added memories.
      *
      * Each pass is another engine call and can add up to `limit` more memories, so it
      * costs more — you are billed for what is delivered. Default 0. Worth it on questions
@@ -652,9 +659,10 @@ export interface SearchOptions {
 export interface WriteOptions {
     idempotencyKey?: string;
     /**
-     * An image to store alongside the text. Needs a model that lists `images` in its
-     * `listModels()` capabilities; any other refuses the write rather than store the
-     * caption and quietly drop the image.
+     * An image to store alongside the text, read by `add` (and `store`) only: `addTurn`,
+     * `addBulk` and `update` warn about it and do not send it. Needs a model that lists
+     * `images` in its `listModels()` capabilities; any other refuses the write rather than
+     * store the caption and quietly drop the image.
      *
      * A caption is required: the service refuses empty `content` (400) even with an
      * image attached.
@@ -858,15 +866,16 @@ export declare class Client {
     addBulk(content: string, userId?: string, category?: string, timestamp?: string, opts?: WriteOptions): Promise<StatusResult>;
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
     update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
-    /** Search a store's memories. Returns them most relevant first.
+    /** Search a store's memories. They come most relevant first; the assistant's own
+     *  words and image memories, when there are any, follow them in their own order.
      *
      *  `limit` is 5-20, and out of range is refused rather than clamped: asking for 50
      *  and silently receiving 20 reads as "that is all there is". The default is 10.
      *
-     *  `limit` bounds `memories`, not the returned array. The assistant's own words (on
-     *  a model that lists `self_memories` in its capabilities) and image memories (one
-     *  unless `max_images` says otherwise, on a model that lists `images`) come back in
-     *  it as well, so it can hold more than `limit`. They are billed either way. Size a
+     *  `limit` bounds `memories`, not the returned array, and each `verify` pass can add
+     *  up to `limit` more. The assistant's own words (on a model that lists
+     *  `self_memories` in its capabilities) and image memories (one unless `max_images`
+     *  says otherwise, on a model that lists `images`) come back after them in it as well, so it can hold more than `limit`. They are billed either way. Size a
      *  prompt window on the array you get back, not on `limit`. `searchFull()` hands the
      *  fields back apart.
      *
@@ -890,7 +899,7 @@ export declare class Client {
      *     const r = await mem.searchFull("the day we moved", "alice", 10,
      *                                    { max_images: 3, verify: 2 });
      *     r.images.length;   // the photos, apart from the text memories
-     *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
+     *     r.verify_used;     // re-ask passes that added memories (each billed for what it added)
      *
      * Each option needs a model that lists it in its `listModels()` capabilities
      * (`images`, `re_ask`) and is refused (403) on any other rather than accepted and
@@ -927,7 +936,8 @@ export declare class Client {
     }): Promise<EngramResult>;
     /** Recent conversation turns (short-term memory). */
     history(userId?: string): Promise<HistoryTurn[]>;
-    /** Memory counts for a store: { total_memories, short_term_turns }. */
+    /** Memory counts for a store: { total_memories, short_term_turns }. `total_memories`
+     *  can be larger than the number `listMemories` lists. */
     stats(userId?: string): Promise<StatsResult>;
     /**
      * What this key has spent, and what is left — the numbers behind "can I keep going?".
@@ -935,18 +945,17 @@ export declare class Client {
      * Free: it carries no charge and skips the balance gate, because an account at zero
      * still has to be able to find out why. Rate-limited instead.
      *
-     * Scoped to THIS key: its own lifetime spend, its workspace and stores over the
-     * window. It never returns another key's spend. `balance_cents` is account-wide,
-     * because that is what gates the next call whichever key makes it.
+     * `key` is THIS key's own lifetime spend. `workspace` and `stores` cover the window
+     * for the workspace this key belongs to, every key in it included. `balance_cents` is
+     * account-wide, because that is what gates the next call whichever key makes it.
      *
      *     const u = await mem.usage(7);
      *     if (u.balance_cents! < 100) stop();
      */
     usage(days?: number): Promise<UsageResult>;
     /** Fetch ONE memory by id — the text you stored, and its metadata.
-     * The id is what `add`/`store` or `listMemories` returned. Same visibility as
-     * `listMemories`: an id from another store, an id `listMemories` does not return,
-     * or an invalidated memory rejects with `NotFoundError`. Pass `undefined` as
+     * The id is what `add`/`store` or `listMemories` returned. An unknown id or one
+     * from another store rejects with `NotFoundError`. Pass `undefined` as
      * `userId` for the default store — it is positional here. */
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
     /** List a store's stored memories — the text you stored, plus its metadata.
@@ -992,9 +1001,10 @@ export declare class Client {
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
      *
      * Not necessarily your upload, in size OR in format: an image whose long edge was
-     * over 1568px was downscaled to 1568 on the way in and re-encoded — lossless
-     * formats as WebP, so a PNG comes back as `image/webp`; JPEG stays JPEG — and that
-     * smaller picture is what is stored and comes back here. Nothing on our side ever
+     * over 1568px (2500 at most) was downscaled to 1568 on the way in and re-encoded —
+     * lossless formats as WebP, so a PNG comes back as `image/webp`; JPEG stays JPEG;
+     * kept as sent when the re-encode came out bigger — and that smaller picture is what
+     * is stored and comes back here. Nothing on our side ever
      * uses more than 1568, so the extra pixels would be bytes nobody reads.
      * Keep your own copy for the full-resolution file.
      *
@@ -1099,11 +1109,13 @@ export declare class Client {
         skipIds?: string[];
     }): Promise<RevisionsResult>;
     /**
-     * The full chain of edits behind one memory, oldest first.
+     * The edits that followed one memory: from the id you pass forward to the version in
+     * force, oldest first.
      *
-     * `is_current` marks the version in force. Use it to answer "what did this used to
-     * say, and when did it change" — `revisions()` tells you HOW MUCH a store moved,
-     * this tells you what happened to one fact.
+     * `is_current` marks the version in force. The chain runs forward only, so to answer
+     * "what did this used to say, and when did it change" pass the first version's id;
+     * the current version's id (what `search` returns) comes back alone. `revisions()`
+     * tells you HOW MUCH a store moved, this tells you what happened to one fact.
      */
     lineage(userId: string | undefined, memoryId: string): Promise<LineageResult>;
     /**
@@ -1125,8 +1137,7 @@ export declare class Client {
      * `AuthenticationError` (bad key), `PaymentRequiredError` (valid key but no card /
      * depleted balance), or `APIConnectionError` (unreachable). Makes one metered request. */
     ping(): Promise<boolean>;
-    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`.
-     *  Needs no API key. */
+    /** Available models: `[{ id, name, available, memory, capabilities, retires_at? }, ...]`. */
     listModels(): Promise<ModelInfo[]>;
     /**
      * The engrams (and delivery forms) the selected model can actually run.
@@ -1159,7 +1170,9 @@ export declare class Client {
     addSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** The store's registered people, each with its memory count. */
     listSpeakers(userId?: string): Promise<SpeakersList>;
-    /** Unregister a person. Their memories stay; the name tag goes. Retried like
+    /** Unregister a person. Their memories stay, and the name can no longer tag a new
+     *  memory or filter a search. The tag goes from stored memories too, except on
+     *  `tablet-2`, which keeps it on memories already stored with it. Retried like
      *  `deleteStore`, with the same note on a 404 after an ambiguous failure. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
     /** Delete a single memory by id. Pass `undefined` as `userId` for the default
@@ -1209,12 +1222,12 @@ 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 idempotent methods; 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 an idempotent method or of a POST that
-     * only reads that the deadline cuts short. Any other retry cut short stays a status-0
-     * deadline error: a write may have been applied.
+     * 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
+     * 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
+     * short stays a status-0 deadline error: a write may have been applied.
      */
     private send;
     /**

package/dist/wontopos.js

@@ -1,4 +1,4 @@
-const VERSION = "2.2.44";
+const VERSION = "2.2.46";
 const RUNTIME = (() => {
     const p = globalThis?.process;
     return p?.version ? ` (node/${p.version}; ${p.platform}-${p.arch})` : "";
@@ -492,7 +492,7 @@ const KNOWN_ENGRAM_KEYS = new Set(["form", "tz"]);
 function checkSearchOpts(opts) {
     checkOpts(opts, KNOWN_SEARCH_KEYS, "search");
     const o = opts;
-    optRange(o.max_images !== undefined ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
+    optRange(o.max_images != null ? o.max_images : o.extra?.max_images, "max_images", 0, MAX_IMAGES_MAX);
 }
 function checkOpts(opts, known, what) {
     for (const k of Object.keys(opts)) {
@@ -542,6 +542,17 @@ function warnOnceUnknownKeys(obj, known, warned, message) {
         console.warn(message(k));
     }
 }
+function givenOpts(known) {
+    return Object.fromEntries(Object.entries(known).filter(([, v]) => v !== null));
+}
+const ADD_KEYS = new Set(["idempotencyKey", "image"]);
+const WRITE_KEYS = new Set(["idempotencyKey"]);
+const warnedWriteKeys = new Set();
+function writeKey(opts, takesImage = false) {
+    warnOnceUnknownKeys(opts, takesImage ? ADD_KEYS : WRITE_KEYS, warnedWriteKeys, (k) => `wontopos: write option ${JSON.stringify(k)} is not sent. ` +
+        (takesImage ? "add takes idempotencyKey and image." : "This call takes idempotencyKey only."));
+    return opts.idempotencyKey;
+}
 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. ` +
@@ -702,22 +713,22 @@ export class Client {
         if (opts.image !== undefined)
             body.image = normalizeImage(opts.image);
         warnOnUnknownMetadata(metadata);
-        return this.post("/api/v1/memory/store", body, opts.idempotencyKey);
+        return this.post("/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 }, opts.idempotencyKey);
+        return this.post("/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 };
+        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, opts.idempotencyKey);
+        return this.post("/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 }, opts.idempotencyKey);
+        return this.post("/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);
@@ -725,7 +736,7 @@ export class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return mergeResults(r);
     }
     async searchSelf(query, userId, limit = 10, opts = {}) {
@@ -734,7 +745,7 @@ export class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return { memories: asRecords(r.memories), self_memories: asRecords(r.self_memories) };
     }
     async searchFull(query, userId, limit = 10, opts = {}) {
@@ -743,7 +754,7 @@ export class Client {
         limit ??= 10;
         checkCount(limit, "limit");
         const { extra, ...known } = opts;
-        const r = await this.post("/api/v1/memory/search", { ...extra, ...known, user_id: this.uid(userId), query, max_results: limit });
+        const r = await this.post("/api/v1/memory/search", { ...extra, ...givenOpts(known), user_id: this.uid(userId), query, max_results: limit });
         return {
             ...r,
             memories: asRecords(r.memories),
@@ -878,9 +889,13 @@ export class Client {
         throw truncatedWalk(`stopped after ${MAX_PAGES} pages — the store did not end.`);
     }
     async revisions(userId, opts = {}) {
+        const inc = opts.include;
+        if (inc !== undefined && inc !== null && inc !== "revised" && inc !== "unrevised") {
+            throw new Error(`include must be "revised" or "unrevised", got ${JSON.stringify(inc)}.`);
+        }
         const limit = optRange(opts.limit, "limit", PAGE_LIMIT_MIN, PAGE_LIMIT_MAX);
         const body = {};
-        if (opts.include !== undefined)
+        if (opts.include != null)
             body.include = opts.include;
         if (limit !== undefined)
             body.limit = limit;
@@ -1082,8 +1097,8 @@ export class Client {
         }
         const attempts = this.maxRetries + 1;
         const upper = method.toUpperCase();
-        const idempotent = IDEMPOTENT_METHODS.has(upper);
         const logPath = path.split("?")[0];
+        const idempotent = IDEMPOTENT_METHODS.has(upper) || reads || (upper === "POST" && READ_POSTS.has(logPath));
         const deadlineAt = this.deadlineAt();
         const headers = extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers;
         let ambiguous = false;
@@ -1104,7 +1119,7 @@ export class Client {
             };
             const cutShort = () => {
                 const why = att.why();
-                if (why === "deadline" && (idempotent || reads || (upper === "POST" && READ_POSTS.has(logPath))) && previous) {
+                if (why === "deadline" && idempotent && previous) {
                     return previous;
                 }
                 return new APIConnectionError(0, this.abortMessage(why));

package/package.json

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