wontopos 2.0.0 → 2.1.0

package/dist/wontopos.d.ts

@@ -4,10 +4,15 @@
  *   npm install wontopos
  *
  *   import { Client } from "wontopos";
- *   const mem = new Client({ apiKey: "wos-..." });
+ *   const mem = new Client({ apiKey: "wos-...", model: "tablet-1" });
  *   await mem.add("she prefers tea over coffee", "alice");
  *   const hits = await mem.search("what does alice drink?", "alice");
  *
+ * The API key picks *which memory* (your account); `model` picks *which engine*
+ * reads it — like Claude's `model`. 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("scroll").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.
  */
@@ -36,19 +41,35 @@ export interface RecallResult {
     };
     [key: string]: unknown;
 }
+export interface ModelInfo {
+    id: string;
+    name: string;
+    available: boolean;
+    /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
+    memory: "shared" | "isolated";
+}
 export interface ClientOptions {
     apiKey: string;
     /** API base URL (defaults to the hosted service). */
     baseUrl?: string;
     /** Per-request timeout in ms (default 30000). */
     timeoutMs?: number;
+    /** Default model for every call (sent as `X-WOS-Model`). See `listModels()`. */
+    model?: string;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
     private readonly base;
     private readonly headers;
     private readonly timeoutMs;
+    private readonly apiKey;
     constructor(opts: ClientOptions);
+    /**
+     * A client that uses `model` (sent as `X-WOS-Model`). Use it to set the default
+     * (`new Client({ apiKey, model })`) or to override one call
+     * (`client.withModel("scroll").recall(...)`).
+     */
+    withModel(model: string): Client;
     /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01" }). */
     add(content: string, userId: string, metadata?: Record<string, unknown>): Promise<any>;
     /** Store a conversation turn (user + assistant) into short-term + long-term memory. */
@@ -65,6 +86,8 @@ export declare class Client {
     history(userId: string): Promise<unknown[]>;
     /** Memory counts for a user: { total_memories, short_term_turns }. */
     stats(userId: string): Promise<any>;
+    /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
+    listModels(): Promise<ModelInfo[]>;
     /** Delete a single memory by id. */
     delete(userId: string, memoryId: string): Promise<any>;
     /** Delete ALL memories for a user (GDPR erase). */

package/dist/wontopos.js

@@ -4,14 +4,20 @@
  *   npm install wontopos
  *
  *   import { Client } from "wontopos";
- *   const mem = new Client({ apiKey: "wos-..." });
+ *   const mem = new Client({ apiKey: "wos-...", model: "tablet-1" });
  *   await mem.add("she prefers tea over coffee", "alice");
  *   const hits = await mem.search("what does alice drink?", "alice");
  *
+ * The API key picks *which memory* (your account); `model` picks *which engine*
+ * reads it — like Claude's `model`. 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("scroll").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.
  */
 const DEFAULT_BASE_URL = "https://api.wontopos.com";
+const DEFAULT_MODEL = "tablet-1";
 export class WosError extends Error {
     status;
     constructor(status, message) {
@@ -25,12 +31,25 @@ export class Client {
     base;
     headers;
     timeoutMs;
+    apiKey;
     constructor(opts) {
         if (!opts?.apiKey)
             throw new Error("apiKey is required");
+        this.apiKey = opts.apiKey;
         this.base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.timeoutMs = opts.timeoutMs ?? 30_000;
+        const model = opts.model ?? DEFAULT_MODEL;
         this.headers = { "X-API-Key": opts.apiKey, "Content-Type": "application/json" };
+        if (model)
+            this.headers["X-WOS-Model"] = model;
+    }
+    /**
+     * A client that uses `model` (sent as `X-WOS-Model`). Use it to set the default
+     * (`new Client({ apiKey, model })`) or to override one call
+     * (`client.withModel("scroll").recall(...)`).
+     */
+    withModel(model) {
+        return new Client({ apiKey: this.apiKey, baseUrl: this.base, timeoutMs: this.timeoutMs, model });
     }
     // ----- write -----
     /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01" }). */
@@ -71,6 +90,15 @@ export class Client {
     stats(userId) {
         return this.post("/api/v1/memory/stats", { user_id: userId });
     }
+    // ----- models -----
+    /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
+    async listModels() {
+        const res = await fetch(`${this.base}/api/v1/models`);
+        if (!res.ok)
+            throw new WosError(res.status, await res.text());
+        const data = await res.json();
+        return (data.models ?? []);
+    }
     // ----- delete -----
     /** Delete a single memory by id. */
     delete(userId, memoryId) {
@@ -94,7 +122,7 @@ export class Client {
             });
         }
         catch (e) {
-            throw new WosError(0, `network error: ${e.message}`);
+            throw new WosError(0, `network error: ${e?.message ?? e}`);
         }
         finally {
             clearTimeout(timer);
@@ -116,7 +144,9 @@ export class Client {
                         msg = data.message;
                 }
             }
-            catch { /* keep raw text */ }
+            catch {
+                /* keep raw text */
+            }
             throw new WosError(res.status, msg);
         }
         return res.json();

package/package.json

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