wontopos 2.2.18 → 2.2.20

package/README.md

@@ -8,6 +8,10 @@ npm install wontopos
 import { Client } from "wontopos";
 
 const mem = new Client({ apiKey: "wos-..." });
+
+// 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.)
+await mem.createStore("alice");
 await mem.add("she prefers tea over coffee", "alice");
 
 // one call → short-term + long-term + context, ready for your LLM prompt

package/dist/wontopos.d.ts

@@ -299,10 +299,19 @@ export declare class Client {
      * 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). */
     searchSelf(query: string, userId?: string, limit?: number, opts?: SearchOptions): Promise<SelfSearchResult>;
-    /** One-call LLM context: short-term turns + long-term matches + surrounding context. */
-    recall(query: string, userId?: string): Promise<RecallResult>;
-    /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result. */
-    engram(name: string, query: string, userId?: string): Promise<EngramResult>;
+    /** 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. */
+    recall(query: string, userId?: string, opts?: {
+        form?: string;
+        tz?: number;
+    }): Promise<RecallResult>;
+    /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). 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;
+        tz?: number;
+    }): Promise<EngramResult>;
     /** Recent conversation turns (short-term memory). */
     history(userId?: string): Promise<HistoryTurn[]>;
     /** Memory counts for a store: { total_memories, short_term_turns }. */

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.17";
+const VERSION = "2.2.20";
 /** 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). */
@@ -123,6 +123,21 @@ function parseRateLimit(h) {
         return null;
     return { limit, remaining, reset };
 }
+// A list/object field the API promises. `x ?? []` only replaces null/undefined — a
+// broken or hostile server sending a truthy wrong type (`"memories": "oops"`) would
+// slip through as a string and blow up the caller's `for (…of…)`. Coerce anything
+// that isn't actually an array/object to the empty value.
+const asList = (x) => (Array.isArray(x) ? x : []);
+const asObj = (x) => (x != null && typeof x === "object" && !Array.isArray(x) ? x : {});
+// Attach a delivery-form override (memoir/archive) + tz to a body, the way search
+// passes them; on Scroll 1.2+ this renders each returned memory's time in that form.
+function withForm(body, form, tz) {
+    if (form !== undefined)
+        body.form = form;
+    if (tz !== undefined)
+        body.tz = tz;
+    return body;
+}
 export class WosError extends Error {
     status;
     /** The server's id for the request when it sent one — include it when contacting support. */
@@ -328,7 +343,7 @@ export class Client {
         // Reserved fields win over ...opts: an app that forwards untrusted input as
         // opts must not be able to override the store (user_id), query, or limit.
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
-        return (r.memories ?? []);
+        return asList(r.memories);
     }
     /** 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 /
@@ -337,20 +352,23 @@ export class Client {
      * without a self lane, `self_memories` is `[]`. `userId` optional (default store). */
     async searchSelf(query, userId, limit = 10, opts = {}) {
         const r = await this.post("/api/v1/memory/search", { ...opts, user_id: this.uid(userId), query, max_results: limit });
-        return { memories: (r.memories ?? []), self_memories: (r.self_memories ?? []) };
+        return { memories: asList(r.memories), self_memories: asList(r.self_memories) };
     }
-    /** One-call LLM context: short-term turns + long-term matches + surrounding context. */
-    recall(query, userId) {
-        return this.post("/api/v1/memory/recall", { user_id: this.uid(userId), query });
+    /** 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. */
+    recall(query, userId, opts = {}) {
+        return this.post("/api/v1/memory/recall", withForm({ user_id: this.uid(userId), query }, opts.form, opts.tz));
     }
-    /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result. */
-    engram(name, query, userId) {
-        return this.post("/api/v1/engram/run", { name, user_id: this.uid(userId), query });
+    /** Run a built-in engram ("deep_recall" | "timeline" | "gather"). Returns the merged result.
+     * `form`/`tz` render memory times (memoir/archive) on Scroll 1.2+, same as search/recall. */
+    engram(name, query, userId, opts = {}) {
+        return this.post("/api/v1/engram/run", withForm({ name, user_id: this.uid(userId), query }, opts.form, opts.tz));
     }
     /** Recent conversation turns (short-term memory). */
     async history(userId) {
         const r = await this.post("/api/v1/memory/history", { user_id: this.uid(userId) });
-        return (r.turns ?? []);
+        return asList(r.turns);
     }
     /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId) {
@@ -366,7 +384,7 @@ export class Client {
         if (!memoryId || typeof memoryId !== "string") {
             throw new Error("memoryId is required — the id that add/store or listMemories returned.");
         }
-        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId }).then((r) => (r.memory ?? {}));
+        return this.post("/api/v1/memory/get", { user_id: this.uid(userId), memory_id: memoryId }).then((r) => asObj(r.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
@@ -398,7 +416,7 @@ export class Client {
         // server that mints a FRESH cursor every page forever — bound the walk.
         for (let page = 0; page < MAX_PAGES; page++) {
             const p = await this.listMemories(userId, { limit: opts.pageSize ?? 100, cursor });
-            for (const m of p.memories ?? [])
+            for (const m of asList(p.memories))
                 yield m;
             const next = p.next_cursor ?? undefined;
             if (!next || seen.has(next))
@@ -425,7 +443,7 @@ export class Client {
     /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
     async listModels() {
         const data = await this.request("GET", "/api/v1/models");
-        return (data.models ?? []);
+        return asList(data.models);
     }
     // ----- stores -----
     /** Create a store — the `userId` you read and write under. Stores are explicit:
@@ -438,7 +456,7 @@ export class Client {
     /** List your stores: `[{ user_id, created_at }, ...]` (`default` first). */
     async listStores() {
         const r = await this.request("GET", "/api/v1/memory/collections");
-        return (r.collections ?? []);
+        return asList(r.collections);
     }
     /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
     deleteStore(userId) {

package/package.json

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