wontopos 2.2.33 → 2.2.35

package/README.md

@@ -4,10 +4,13 @@
 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.
+
 ```ts
 import { Client } from "wontopos";
 
-const mem = new Client({ apiKey: "wos-..." });
+const mem = new Client({ apiKey: "wos-live-..." });
 
 // Each end-user / agent / topic gets its own store — create it once.
 // (A `default` store already exists, so you can skip this and omit the id.)
@@ -20,15 +23,23 @@ const ctx = await mem.recall("what does alice drink?", "alice");
 
 ## Why
 
-- **Pure semantic retrieval** — no keyword/BM25. Identical recall in every language (한국어 · 日本語 · 中文 · English).
-- **No LLM in the loop** — `store` / `search` / `recall` never call a language model. You pay embeddings, not generation.
+- **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 (~1,200 tokens) regardless of how much you've stored.
 
 ## Methods
 
-`add` · `addTurn` · `addBulk` · `update` · `search` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
+`add` · `addTurn` · `addBulk` · `update` · `search` · `searchFull` · `recall` · `history` · `stats` · `get` · `listMemories` · `delete` · `deleteAll`
 
-All methods take `{ userId }` — it names the **store**: one isolated memory space per end-user, agent, or topic, then per account. WHO said each memory inside a store is the `speaker` tag below — storing the assistant's own words never needs a separate id.
+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")`,
+`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.
+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)
 
@@ -69,7 +80,12 @@ const hits = await mem.search("...the conversation so far...", "alice", 10,
 
 Built in, no configuration needed:
 
-- **Automatic retries** — 429 / 502 / 503 and connection errors retry twice with
+- **Automatic retries** — 429 always, and 502 / 503 or a connection error only when a
+  retry cannot double-process a write. The writes and the searches are POSTs, and a
+  502 on one of those may have been returned *after* the service already stored and
+  billed it, so those get 429 and connect-level failures only. The reads and the
+  deletes that address a whole store — `listStores`, `listSpeakers`, `deleteStore`,
+  `removeSpeaker`, `forgetImage` — are GET or DELETE and do retry a 502. Twice, with
   exponential backoff + jitter, honoring the server's `Retry-After`. Tune with
   `new Client({ maxRetries })`; `0` disables.
 - **Redirects refused** — the API key never follows a 3xx to another host.
@@ -87,6 +103,9 @@ egress proxy this SDK could not connect at all — while the Python and Rust SDK
 through, because `requests` and `reqwest` both read those variables. Pass a
 proxy-aware `fetch` and the three behave the same:
 
+This one needs `npm i undici` — Node's global `fetch` is built on undici, but the
+package itself is not installed for you.
+
 ```ts
 import { ProxyAgent } from "undici";
 
@@ -126,10 +145,17 @@ update. `search` options are typed too (`SearchOptions`: `cache_control`,
 `speaker`, plus pass-through).
 
 ```ts
+import { type Memory } from "wontopos";
+
 const hits: Memory[] = await mem.search("what did Bob say?", "alice", 10, { speaker: "Bob" });
 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
+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.
+
 ## Errors
 
 Any non-2xx response throws `WosError` with `status`, `message`, and — when the
@@ -162,8 +188,7 @@ const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });
 
 ## Reporting a bug
 
-Found something wrong, or something that looks unsafe? Tell us — one person reads
-every report.
+Found something wrong, or something that looks unsafe? Tell us — every report gets read.
 
 - Bugs: <https://wontopos.com/contact?topic=bug>
 - Security: <https://wontopos.com/contact?topic=security> (also published at
@@ -177,7 +202,60 @@ data to fix it.
 
 The three clients release in lockstep — same version, same surface, same day.
 Patch releases are additive: nothing is removed or reordered within a minor line.
-
+Two have bent that, deliberately and named at the top of their entry — 2.2.34 moved the
+default engine, and 2.2.35 gives `search` the count range `recall` has always had. A
+rule you can bend without saying so is not a rule, so both are stated rather than left
+for a reader to hit.
+
+- **2.2.35** — fixes, and **two behaviour changes**, both listed first because a patch
+  release is not the place to find one by surprise.
+
+  ⚠️ **`search`'s count is now 5–20, and out of range is refused rather than
+  adjusted.** `recall` has carried that range from the start; search had no contract
+  anywhere, so the clients sent whatever they were given and the service capped at 50
+  with no floor. `search(q, limit=50)` and `search(q, limit=3)` both worked on 2.2.34
+  and now raise. The default is still 10, so a call that passes no count is unaffected.
+  Asking for 20 and silently getting 10 reads as "that is all there is", which is why
+  this refuses instead of clamping.
+
+  ⚠️ **A Rust `limit` of 0 is no longer rewritten to 10.** It was, and the caller whose
+  prompt budget computed zero was handed ten memories and the bill for them. It is now
+  refused under the range above rather than quietly changed to something nobody asked
+  for.
+
+  The fixes: a `null` idempotency key no longer becomes the literal key `"null"`, which
+  had made every write on that path share one key so the second onward stored nothing
+  (TypeScript). The async client no longer reads an explicit `retries=2` as "the caller
+  said nothing" (Python). The image read is actually streamed, so the 64MB cap bounds a
+  compressed body instead of measuring bytes already in memory (Python async), and that
+  route's ERROR body is capped too (Rust). `iter_images` stops on a repeated cursor the
+  way `iter_memories` always did (Python). `iterImages` no longer throws on the ordinary
+  end of a walk (TypeScript). `get_image` retries a 429 and a connect-level failure like
+  every other call — it had none at all — in the **sync Python client and TypeScript**;
+  the async Python client and the Rust crate still make a single attempt there, and say
+  so at the method. An empty or control-character API key is refused at the call site
+  rather than at the network in **Python and Rust**; TypeScript still refuses only empty
+  and whitespace. And a page walk that reaches its ceiling now raises instead of
+  returning a truncated list that looks complete.
+- **2.2.34** — the default engine is `tablet-2`: same token price as `tablet-1`, and
+  the one that serves images and re-ask. Pin the old one with
+  `model="tablet-1"` for the previous behaviour exactly. (The engine's own default
+  count differs between the two, but these SDKs always send one, so a call through
+  them is unaffected.) New `search_full` /
+  `searchFull` keeps every field the answer came with — `search` was merging away
+  the photos and `verify_used`, both of which you were billed for. Also: results arrive
+  best-first — take the order as given. `similarity` is a raw closeness score, and
+  sorting by it makes results worse.
+- **2.2.33** — `get_image` can return a different FORMAT than you uploaded: the
+  service re-encodes on downscale, so a large PNG comes back as WebP. Take the file
+  extension from the response Content-Type, not from what you sent.
+- **2.2.32** — `get_image` returns the picture the SERVICE holds, not your original.
+  An image whose long edge is over 1568px is downscaled on the way in, and that
+  smaller picture is what is stored and handed back. Keep your own copy if you need
+  the full file.
+- **2.2.31** — images, by-speaker, lineage and revisions are SDK methods in all three
+  clients; `search` and `recall` take `verify`, `max_images` and recall's `limit` /
+  `context_limit`.
 - **2.2.30** — documentation only: this changelog, which had not been updated
   in the shipped package since 2.2.10.
 - **2.2.29** — a store id that was PASSED but unusable no longer becomes the

package/dist/wontopos.d.ts

@@ -15,12 +15,15 @@
  * so with no `userId` anywhere the zero-setup path just works.
  *
  * The API key picks *which memory* (your account); `model` picks *which engine*
- * reads it. All models share one memory, so you can store
- * with one and recall with another. Set a default in the constructor, or override
- * a single call with `mem.withModel("tablet-1").recall(...)`.
+ * 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
+ * the constructor, or override a single call with
+ * `mem.withModel("tablet-1").recall(...)`.
  *
- * Pure semantic retrieval — no keyword/BM25 matching, so it works the SAME in every
- * language. Storing and searching call no LLM; you only pay for embeddings.
+ * 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.
  *
  * Reliability: every call retries transient failures with exponential backoff +
  * jitter, honoring `Retry-After` — 429 always; 502/503 and connection errors only
@@ -39,6 +42,8 @@
  */
 /** Test hook — the warn-once set is process-global by design. */
 export declare function _resetStoreIdWarnings(): void;
+export declare const SEARCH_LIMIT_MIN = 5;
+export declare const SEARCH_LIMIT_MAX = 20;
 /** Quota from a response's `X-RateLimit-*` headers, or `null` if absent. */
 export interface RateLimit {
     limit: number | null;
@@ -84,8 +89,8 @@ export declare class RateLimitError extends WosError {
  * `501` is NOT transient. It means the engine behind the model you selected does
  * not implement that endpoint at all (the error carries `model` and `endpoint`).
  * Retrying can never succeed — pick a model that supports it (`listModels`) or
- * drop the call. This class used to say "safe to retry" for the whole 5xx range,
- * which sent callers into a loop that could not end.
+ * drop the call. Treating the whole 5xx range as retryable sends a caller into a
+ * loop that cannot end.
  */
 export declare class ServerError extends WosError {
 }
@@ -99,9 +104,12 @@ export interface Memory {
     content?: string;
     /** Cognitive category, e.g. "general". */
     category?: string;
-    /** Semantic relevance to the query — higher is closer. This IS the relevance score; there is no `score` field. */
+    /** Raw closeness to the query — higher is closer. NOT the ranking key: results already
+     *  arrive best-first, and what produces that order is internal and not returned, so
+     *  re-sorting by `similarity` overrides the ranking and makes results worse. Take the
+     *  list in the order given. There is no `score` field. */
     similarity?: number;
-    /** Learned importance weight of the memory. */
+    /** Importance weight the service assigns to the memory. */
     importance?: number;
     /** Month bucket the memory belongs to (e.g. "2026-07"). Omitted when temporal fields are stripped. */
     time_bucket?: string;
@@ -125,11 +133,11 @@ export interface StoreResult {
     /**
      * Present when `status` is `"duplicate"`: the id of the memory this write collided with.
      *
-     * The match is by MEANING, not by exact text — a genuinely new fact that only varies a
-     * detail of one already stored ("allergic to shellfish" next to "allergic to peanuts")
-     * lands here too. So a duplicate is not always a harmless no-op: read this id, and
-     * either merge the two into one sentence or `update()` the existing memory. Without it
-     * a dropped write gave the caller nothing to act on.
+     * A genuinely new fact that only varies a detail of one already stored ("no meetings
+     * before 10am" next to "no meetings on Fridays") can land here too, so a duplicate is
+     * not always a harmless no-op: read this id, and either store one sentence that states
+     * both or `update()` the existing memory with the combined statement. Without it a
+     * dropped write gave the caller nothing to act on.
      */
     duplicate_of?: string;
     /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
@@ -150,9 +158,9 @@ export interface StatusResult {
  *
  * 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
- * picture is what gets embedded, stored, and handed back by `getImage`. Nothing in
- * the retrieval path ever looks above 1568 — the embedder and the reader both
- * shrink to it — so the extra pixels would be bytes nobody reads. This is a memory
+ * picture is what gets stored, and handed back by `getImage`. Nothing on our side
+ * ever uses more than 1568, so the extra pixels would be bytes nobody reads. This
+ * is a memory
  * service, not a photo host: the picture it holds has the resolution of a memory.
  *
  * It can also come back in a different FORMAT. Downscaling means re-encoding, and
@@ -231,7 +239,7 @@ export interface RevisionsResult {
     revised?: number;
     /** Memories nothing has touched since they were written. Always `total - revised`. */
     unrevised?: number;
-    /** Every memory in the store. Atoms — the fragments search uses internally — are not counted. */
+    /** Every memory in the store. Internal records nobody stored directly are not counted. */
     total?: number;
     /** What `revised` counts, spelled out by the service. */
     counts?: string;
@@ -280,7 +288,7 @@ export interface LineageResult {
 export interface SpeakerPage {
     speaker?: string;
     memories: Memory[];
-    /** Sentence-level fragments behind these memories — what a delete would actually remove. */
+    /** How many underlying records a delete would actually remove, beyond what was returned. */
     chunks?: number;
     points_to_delete?: number;
     returned?: number;
@@ -296,6 +304,26 @@ export interface UpdateResult {
     status?: string;
     [key: string]: unknown;
 }
+/** `searchFull` → everything one search answered with, not just the merged memories.
+ *
+ *  `search` returns the memories and nothing else, which is the right answer for
+ *  almost every call. Two options make it the wrong one: `max_images` asks for
+ *  photos, which arrive in their own field, and `verify` is reported on by
+ *  `verify_used`. Merging away both means paying for a
+ *  search you shaped and never seeing what came of it. */
+export interface SearchResult {
+    /** What others said, and general memories. */
+    memories: Memory[];
+    /** The assistant's own words (speaker "me"); `[]` on a model that does not keep
+     *  them apart. */
+    self_memories: Memory[];
+    /** Image memories, when `max_images` asked for any; `[]` otherwise. */
+    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. */
+    verify_used?: number;
+    [key: string]: unknown;
+}
 export interface RecallResult {
     short_term: {
         turns: unknown[];
@@ -333,7 +361,7 @@ export interface StatsResult {
     short_term_turns?: number;
     [key: string]: unknown;
 }
-/** `listMemories` → one page of a store's raw memories (original text + metadata, no vector). */
+/** `listMemories` → one page of a store's raw memories (the text you stored, and its metadata). */
 export interface MemoryPage {
     memories: Memory[];
     count: number;
@@ -341,9 +369,9 @@ export interface MemoryPage {
     next_cursor: string | null;
     [key: string]: unknown;
 }
-/** `searchSelf` result: the main lane plus the assistant's own words, split. */
+/** `searchSelf` result: general memories and the assistant's own, kept apart. */
 export interface SelfSearchResult {
-    /** Main lane — what others said / general memories. */
+    /** What others said, and general memories. */
     memories: Memory[];
     /** The assistant's own words (stored with speaker "me"); `[]` on non-self models. */
     self_memories: Memory[];
@@ -406,10 +434,11 @@ export interface SpeakersList {
     [key: string]: unknown;
 }
 /**
- * Narrow a search to part of a store — applied BEFORE ranking, so the results are
- * the best matches *within* the filter, not a filtered top-N.
+ * 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.
  *
- * Retrieval itself stays purely semantic (no keyword matching), so these behave
+ * Retrieval behaves the same in every language, so these behave
  * identically in every language. Unlisted keys are dropped by the API rather than
  * rejected, so a typo silently widens the search — spell them exactly.
  */
@@ -443,7 +472,7 @@ 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. Retrieval stays purely semantic — no LLM at any
+     * those and reaches further back. No LLM runs at any
      * value. Stops early when a pass finds nothing new; `verify_used` in the response
      * says how many actually ran.
      *
@@ -452,7 +481,7 @@ export interface SearchOptions {
      * that need several distinct memories from far apart in the history; it does little
      * on a single-fact lookup.
      *
-     * ⚠️Requires a re-ask-capable model. Older ones REFUSE the call (403) rather than
+     * Requires a re-ask-capable model. Older ones REFUSE the call (403) rather than
      * quietly charging you for passes that never happened.
      */
     verify?: number;
@@ -461,7 +490,7 @@ export interface SearchOptions {
      * Out of range is refused, not clamped — silently cutting 5 to 1 would leave you
      * believing you got five.
      *
-     * ⚠️Requires an image-capable model, and is refused (403) on one without it rather
+     * Requires an image-capable model, and is refused (403) on one without it rather
      * than answering with no images.
      */
     max_images?: number;
@@ -473,8 +502,11 @@ export interface SearchOptions {
  * `idempotencyKey` makes repeating THIS EXACT write safe: the API replays the first
  * response instead of storing again, for 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 never retries writes by itself,
- * because without a key it cannot know whether the first attempt landed.
+ * was re-run, a queue that redelivers). The SDK retries a write on exactly one
+ * status: 429, which the service answers before it processes anything, so nothing
+ * was stored. It never retries a write on 502 / 503 or a dropped body, where the
+ * request may already have been stored and billed — without a key it cannot know
+ * whether that first attempt landed.
  *
  * 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
@@ -578,8 +610,7 @@ export declare class Client {
     withRetries(maxRetries: number): Client;
     /** Store one memory. `metadata` optional — e.g. `{ event_date: "2026-03-01" }` for when the
      * content actually happened. A plain date works (read as UTC midnight); a full RFC3339
-     * timestamp also works. The API used to demand the full form and answered a bare date with
-     * an opaque 400, which is why older examples here show the long one.
+     * timestamp also works; older examples here show the long form.
      * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store).
      *
      * `opts.idempotencyKey`: see {@link WriteOptions} — pass one to make YOUR retry
@@ -589,27 +620,42 @@ export declare class Client {
     store(content: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
     /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
     addTurn(userMsg: string, assistantMsg: string, userId?: string, opts?: WriteOptions): Promise<StatusResult>;
-    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling.
+    /** Bulk-ingest a large blob of text in one call. For backfilling.
      *  The call most worth an `opts.idempotencyKey`: a backfill that dies halfway and is
-     *  re-run would otherwise re-chunk and re-bill the whole blob. */
+     *  re-run would otherwise re-ingest and re-bill the whole blob. */
     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>;
-    /** Semantic search over a store's memories. Returns memories, most relevant first.
-     *
-     *  `limit` bounds the MAIN lane, not the returned array. On a self-lane model
-     *  (Scroll 1.2+) the service answers in two disjoint lanes — the assistant's own
-     *  words come back separately — and both are returned here, so the array can hold
-     *  more than `limit`. They were retrieved and billed either way; dropping them would
-     *  only hide what you already paid for. Size a prompt window on the array you get
-     *  back, not on `limit`. `searchSelf()` hands the lanes back apart. */
+    /** Search a store's memories. Returns them most relevant first.
+     *
+     *  `limit` bounds `memories`, not the returned array. On a model that keeps the
+     *  assistant's own words separate (Scroll 1.2+) those come back as well, so the
+     *  array can hold more than `limit`. They were retrieved and billed either way;
+     *  dropping them would only hide what you already paid for. Size a prompt window
+     *  on the array you get back, not on `limit`. `searchSelf()` hands the two back
+     *  apart. */
     search(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<Memory[]>;
-    /** Search a self-memory model (Scroll 1.2+): both lanes from ONE call. Returns
-     * `{ memories, self_memories }` — `memories` is the main lane (what others said /
-     * general memories), `self_memories` is the assistant's OWN words (stored with
-     * speaker "me"), kept separate so the reader never confuses who said what. On a model
-     * without a self lane, `self_memories` is `[]`. `userId` optional (default store). */
+    /** Search a self-memory model (Scroll 1.2+): both fields from ONE call. Returns
+     * `{ memories, self_memories }` — `memories` is what others said and general
+     * memories, `self_memories` is the assistant's OWN words (stored with speaker
+     * "me"), kept apart so whoever reads them never confuses who said what. On a model
+     * that does not keep them apart, `self_memories` is `[]`. `userId` may be omitted. */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
+    /**
+     * Search, and keep every field the answer came with.
+     *
+     * Same request as {@link Client.search} — reach for this one when the options make
+     * the merged array an incomplete answer:
+     *
+     *     const r = await mem.searchFull("the day we moved", "alice", 10,
+     *                                    { max_images: 3, verify: 2 });
+     *     r.images.length;   // the photos, which `search` drops
+     *     r.verify_used;     // how many re-ask passes actually ran (you are billed per pass)
+     *
+     * Both options need Tablet 2 or newer and are refused (403) on an older engine
+     * rather than accepted and ignored.
+     */
+    searchFull(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SearchResult>;
     /** One-call LLM context: short-term turns + long-term matches + surrounding context.
      * `form` ("memoir"/"archive", Scroll 1.2+) renders each long-term memory's time in
      * that form; `tz` is your UTC-offset hours for that rendering. */
@@ -620,16 +666,18 @@ export declare class Client {
          * Long-term memories to recall, 5–20. Default 10. Out of range is refused, not
          * clamped — asking for 20 and silently getting 10 reads as "that is all there is".
          *
-         * ⚠️Needs a limit-aware model. An older one recalls a fixed ten no matter what you
+         * Needs a limit-aware model. An older one recalls a fixed ten no matter what you
          * send, so the API refuses the call (403) rather than answering with a number you
          * did not ask for.
          */
         limit?: number;
-        /** Chunks of surrounding context attached around the best match, 0–20. Default 10;
+        /** How much surrounding context is attached around the best match, 0–20. Default 10;
          *  0 attaches none. Same model floor as `limit`. */
         context_limit?: number;
     }): Promise<RecallResult>;
-    /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result.
+    /** Run a built-in engram ("deep_recall" | "timeline" | "gather" | "equilibrium" |
+     * "tone_stabilizer"; the service is the authority — an unknown name comes back with
+     * the list it accepts). Returns the merged result.
      * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
     engram(name: string, query: string, userId?: string, opts?: {
         form?: string;
@@ -639,13 +687,14 @@ export declare class Client {
     history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId?: string): Promise<StatsResult>;
-    /** Fetch ONE memory by id — the original text + metadata, never the vector.
+    /** 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, a decomposed atom sentence, or an
-     * invalidated memory rejects with `NotFoundError`. `userId` optional (default store). */
+     * `listMemories`: an id from another store, an internal record id, or an
+     * invalidated memory rejects with `NotFoundError`. Pass `undefined` as `userId` for
+     * the default store — it is positional here, not omittable as it is in Python. */
     get(userId: string | undefined, memoryId: string): Promise<Memory>;
-    /** List a store's stored memories — the original text plus metadata, never the
-     * vector. Paginated: pass the returned `next_cursor` back as `cursor` for the next
+    /** List a store's stored memories — the text you stored, plus its metadata.
+     * Paginated: pass the returned `next_cursor` back as `cursor` for the next
      * page; a `null` cursor means the last page. Use it to browse or export a store.
      *
      *     let cursor: string | null = null;
@@ -661,14 +710,14 @@ export declare class Client {
         cursor?: string;
     }): Promise<MemoryPage>;
     /** Async-iterate every stored memory in a store, paging under the hood — no cursor
-     * bookkeeping. Original text + metadata only, never vectors.
+     * bookkeeping. The text you stored and its metadata only.
      *
      *     for await (const m of mem.iterMemories()) console.log(m.id, m.content);
      */
     iterMemories(userId?: string, opts?: {
         pageSize?: number;
     }): AsyncGenerator<Memory>;
-    /** Collect ALL of a store's memories into an array (original text + metadata, no vectors). */
+    /** Collect ALL of a store's memories into an array (the text you stored, and its metadata). */
     exportMemories(userId?: string): Promise<Memory[]>;
     /**
      * Fetch the bytes of an image memory — the picture the SERVICE holds.
@@ -676,8 +725,8 @@ export declare class Client {
      * 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 was embedded, stored and comes back here. Nothing in the
-     * retrieval path looks above 1568, so the extra pixels would be bytes nobody reads.
+     * 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.
      *
      * The type is sniffed from the bytes themselves rather than from whatever the file
@@ -735,10 +784,10 @@ export declare class Client {
      *
      * Counts memories a transform touched (supersede, update, retract, image removed).
      * Deletions are NOT counted: a deleted memory leaves nothing to count. Neither are
-     * atoms, the sentence fragments search uses internally — nobody stored one, so they
-     * do not belong in a ratio that answers "how much of MY memory changed".
+     * the internal records derived from what you stored — nobody stored those directly,
+     * so they do not belong in a ratio that answers "how much of MY memory changed".
      *
-     * ★By default this returns COUNTS ONLY, and the answer is the same size for a store
+     * By default this returns COUNTS ONLY, and the answer is the same size for a store
      * of a hundred memories and a store of a hundred million. That is deliberate: a model
      * asks this mid-conversation, and an answer that grew with the store would be
      * unusable for exactly the customers who most need to ask.
@@ -759,10 +808,10 @@ export declare class Client {
      * }
      * ```
      *
-     * ⚠️Pages are ordered by when each memory was STORED, not by when it was edited.
+     * Pages are ordered by when each memory was STORED, not by when it was edited.
      * The response says so in `ordered_by`.
      *
-     * ★Served from `/api/v1/won/*`, not `/api/v1/memory/*`. Won is the surface for calls
+     * Served from `/api/v1/won/*`, not `/api/v1/memory/*`. Won is the surface for calls
      * a model makes ABOUT its memory rather than calls an application makes WITH it, and
      * the address says so. The old path still answers, for clients published before
      * 2026-08-18, and both share one rate-limit budget.
@@ -795,9 +844,9 @@ export declare class Client {
      * assistant's own words, otherwise a person's name. Same cursor paging as
      * `listImages`.
      *
-     * `chunks` / `points_to_delete` report the sentence-level fragments behind these
-     * memories, which is what a delete would actually remove — usually larger than
-     * `returned`, and worth showing before anyone confirms one.
+     * `chunks` / `points_to_delete` report how many internal records a delete would
+     * actually remove — usually more than `returned`, and worth showing to whoever is
+     * about to confirm one.
      */
     bySpeaker(speaker: string, userId?: string, opts?: {
         limit?: number;
@@ -813,10 +862,9 @@ export declare class Client {
     /**
      * The engrams (and delivery forms) the selected model can actually run.
      *
-     * `engram()` could always RUN one, but there was no way to ASK what exists — so a
-     * caller had to hard-code names from the docs, and every engram we shipped after
-     * their code was written stayed invisible to them. The MCP server hit exactly this
-     * and stopped hard-coding for the same reason. The service is the authority: what
+     * Ask rather than hard-code: a name copied from the docs freezes a caller to the
+     * catalogue as it was that day, and anything added later stays invisible. The
+     * service is the authority. What
      * comes back depends on the model (delivery forms need Scroll 1.2+), so pass
      * `withModel()` if you want another model's catalogue.
      *
@@ -840,7 +888,8 @@ export declare class Client {
     listSpeakers(userId?: string): Promise<SpeakersList>;
     /** Unregister a person. Their memories stay; the name tag goes. */
     removeSpeaker(speaker: string, userId?: string): Promise<SpeakerOpResult>;
-    /** Delete a single memory by id. `userId` optional (uses the default store). */
+    /** Delete a single memory by id. Pass `undefined` as `userId` for the default
+     *  store — it is positional here, not omittable as it is in Python. */
     delete(userId: string | undefined, memoryId: string): Promise<StatusResult>;
     /** Delete ALL memories for a store (GDPR erase). `userId` is required on purpose -
      * this is destructive, so it never falls back to the default store. */
@@ -870,10 +919,9 @@ export declare class Client {
     private readCapped;
     /** The same cap, for a body that is not text.
      *
-     * `getImage` used to call `arrayBuffer()` here, which buffers whatever arrives. The
-     * cap exists for a hostile or broken `baseUrl`, and a photo endpoint is exactly where
-     * that shows up — the JSON paths were guarded while the one path that returns
-     * megabytes was not. One implementation, two callers, so they cannot drift. */
+     * `arrayBuffer()` would buffer whatever arrives. The cap exists for a hostile or
+     * broken `baseUrl`, and an endpoint that returns megabytes is where that costs the
+     * most. One implementation, two callers, so they cannot drift. */
     private readCappedBytes;
     private request;
 }