wontopos 2.2.31 → 2.2.33

package/dist/wontopos.d.ts

@@ -148,9 +148,24 @@ export interface StatusResult {
 /**
  * An image attached to a memory, passed to `add`/`store` via `opts.image`.
  *
- * The bytes are used ONCE, to embed the image, and are not kept. If you want the
- * original back later, either let the service keep it (then `getImage` returns it) or
- * put your own URL in `reference` — we store that string and never open it.
+ * 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
+ * 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
+ * we write lossless formats as WebP — send a PNG or a GIF over 1568px and `getImage`
+ * hands back `image/webp`; JPEG stays JPEG. So do not name the file from the
+ * extension you uploaded: read `contentType`. Nothing is re-encoded when the image
+ * already fits within 1568px, and a re-encode that would make the file BIGGER is
+ * thrown away and your bytes kept as they were.
+ *
+ * Keep your own copy if you need the full-resolution file. Either archive it
+ * yourself, or put its URL in `reference` — we store that string and never open it.
+ *
+ * You are billed for the picture we keep, so downscaling never costs you more.
  */
 export interface ImageInput {
     /** base64 of the image. A `data:image/...;base64,` prefix is accepted and stripped. */
@@ -166,9 +181,15 @@ export interface ImageInput {
      */
     taken_at?: string;
 }
-/** `getImage` → the original bytes plus what they actually are. */
+/** `getImage` → the picture the service holds, plus what it actually is. */
 export interface ImageBytes {
-    /** The raw image. Write it to a file, or wrap it in a Blob to show it. */
+    /**
+     * 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`.
+     */
     bytes: Uint8Array;
     /** Sniffed from the BYTES, not from whatever the upload was named — e.g. `image/jpeg`. */
     contentType: string;
@@ -650,16 +671,26 @@ export declare class Client {
     /** Collect ALL of a store's memories into an array (original text + metadata, no vectors). */
     exportMemories(userId?: string): Promise<Memory[]>;
     /**
-     * Fetch the ORIGINAL bytes of an image memory.
-     *
-     * Returns what was uploaded, with the type sniffed from the bytes themselves rather
-     * than from whatever the file was called. Rejects with `NotFoundError` when this
-     * memory has no image, or when the service was not configured to keep originals —
-     * it says "no" instead of handing back something empty, so "a memory with no image"
-     * never looks the same as "an image we lost".
+     * 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 was embedded, stored and comes back here. Nothing in the
+     * retrieval path looks above 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
+     * was called, so name the file from `contentType` rather than from what you sent.
+     * When the format changed, the response also carries `x-wos-image-converted-from`
+     * naming what you uploaded. Rejects with `NotFoundError` when this memory has no
+     * image, or when the service keeps no image bytes at all — it says "no" instead of
+     * handing back something empty, so "a memory with no image" never looks the same as
+     * "an image we lost".
      *
      *     const { bytes, contentType } = await mem.getImage(undefined, id);
-     *     await fs.writeFile("image.jpg", bytes);
+     *     const ext = contentType.split("/")[1];   // "webp" for a downscaled PNG
+     *     await fs.writeFile(`image.${ext}`, bytes);
      */
     getImage(userId: string | undefined, memoryId: string): Promise<ImageBytes>;
     /**

package/dist/wontopos.js

@@ -37,7 +37,7 @@
  * runtime's (never disabled by this SDK; Node 18+ floors TLS at 1.2). Prefer
  * `Client.fromEnv()` over keys in source code.
  */
-const VERSION = "2.2.31";
+const VERSION = "2.2.33";
 /** Runtime info helps support debug a report ("node 18 on Windows...") —
  * platform only, never anything identifying. Browsers have no `process` (and
  * silently drop the UA header anyway). */
@@ -689,16 +689,26 @@ export class Client {
     }
     // ----- images (Tablet 2 and newer) -----
     /**
-     * Fetch the ORIGINAL bytes of an image memory.
+     * Fetch the bytes of an image memory — the picture the SERVICE holds.
      *
-     * Returns what was uploaded, with the type sniffed from the bytes themselves rather
-     * than from whatever the file was called. Rejects with `NotFoundError` when this
-     * memory has no image, or when the service was not configured to keep originals —
-     * it says "no" instead of handing back something empty, so "a memory with no image"
-     * never looks the same as "an image we lost".
+     * 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.
+     * Keep your own copy for the full-resolution file.
+     *
+     * The type is sniffed from the bytes themselves rather than from whatever the file
+     * was called, so name the file from `contentType` rather than from what you sent.
+     * When the format changed, the response also carries `x-wos-image-converted-from`
+     * naming what you uploaded. Rejects with `NotFoundError` when this memory has no
+     * image, or when the service keeps no image bytes at all — it says "no" instead of
+     * handing back something empty, so "a memory with no image" never looks the same as
+     * "an image we lost".
      *
      *     const { bytes, contentType } = await mem.getImage(undefined, id);
-     *     await fs.writeFile("image.jpg", bytes);
+     *     const ext = contentType.split("/")[1];   // "webp" for a downscaled PNG
+     *     await fs.writeFile(`image.${ext}`, bytes);
      */
     getImage(userId, memoryId) {
         if (!memoryId || typeof memoryId !== "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wontopos",
-  "version": "2.2.31",
+  "version": "2.2.33",
   "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
   "keywords": [
     "memory",