wontopos 2.1.1 → 2.2.1

package/dist/wontopos.d.ts

@@ -4,9 +4,15 @@
  *   npm install wontopos
  *
  *   import { Client } from "wontopos";
- *   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");
+ *   const mem = new Client({ apiKey: "wos-...", userId: "alice" }); // set the store once
+ *   await mem.createStore();                              // create it (uses the client's userId)
+ *   await mem.add("she prefers tea over coffee");         // no userId needed
+ *   const hits = await mem.search("what does alice drink?");
+ *
+ * Set `userId` once on the client and every call uses it; override any single call
+ * by passing `userId` to it. Stores are explicit: the store must exist first
+ * (`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*
  * reads it. All models share one memory, so you can store
@@ -56,6 +62,9 @@ export interface ClientOptions {
     timeoutMs?: number;
     /** Default model for every call (sent as `X-WOS-Model`). See `listModels()`. */
     model?: string;
+    /** Default store for every call. Override per call by passing `userId`. Defaults
+     * to the account's built-in `default` store. */
+    userId?: string;
 }
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export declare class Client {
@@ -63,36 +72,59 @@ export declare class Client {
     private readonly headers;
     private readonly timeoutMs;
     private readonly apiKey;
+    private readonly model;
+    /** The store every call uses unless one passes `userId`. */
+    private readonly defaultUser;
     constructor(opts: ClientOptions);
+    /** Resolve a call's store: the explicit userId, else the client default. */
+    private uid;
     /**
      * 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("tablet-1").recall(...)`).
      */
     withModel(model: string): Client;
+    /** A client bound to `userId` as its default store (everything else kept). */
+    withUser(userId: 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>;
+    add(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<any>;
     /** Store a conversation turn (user + assistant) into short-term + long-term memory. */
-    addTurn(userId: string, userMsg: string, assistantMsg: string): Promise<any>;
+    addTurn(userId: string | undefined, userMsg: string, assistantMsg: string): Promise<any>;
     /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
-    addBulk(content: string, userId: string, category?: string, timestamp?: string): Promise<any>;
+    addBulk(content: string, userId?: string, category?: string, timestamp?: string): Promise<any>;
     /** Supersede an old memory with new content (a fact that changed). */
-    update(userId: string, oldMemoryId: string, newContent: string): Promise<any>;
-    /** Semantic search over a user's memories. Returns memories, most relevant first. */
-    search(query: string, userId: string, limit?: number, opts?: Record<string, unknown>): Promise<Memory[]>;
+    update(userId: string | undefined, oldMemoryId: string, newContent: string): Promise<any>;
+    /** Semantic search over a store's memories. Returns memories, most relevant first. */
+    search(query: string, userId?: string, limit?: number, opts?: Record<string, unknown>): Promise<Memory[]>;
     /** One-call LLM context: short-term turns + long-term matches + surrounding context. */
-    recall(query: string, userId: string): Promise<RecallResult>;
+    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<any>;
     /** Recent conversation turns (short-term memory). */
-    history(userId: string): Promise<unknown[]>;
-    /** Memory counts for a user: { total_memories, short_term_turns }. */
-    stats(userId: string): Promise<any>;
+    history(userId?: string): Promise<unknown[]>;
+    /** Memory counts for a store: { 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). */
+    /** Create a store — the `userId` you read and write under. Stores are explicit:
+     * a store must exist before you `add` to or `search` it, otherwise those calls
+     * return 404. Idempotent. Every account starts with a `default` store.
+     * Returns `{ user_id, status }` (`status` is `"created"` or `"exists"`). */
+    createStore(userId?: string): Promise<any>;
+    /** List your stores: `[{ user_id, created_at }, ...]` (`default` first). */
+    listStores(): Promise<Array<{
+        user_id: string;
+        created_at: string;
+    }>>;
+    /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
+    deleteStore(userId: string): Promise<any>;
+    /** Delete a single memory by id. `userId` optional (uses the default store). */
+    delete(userId: string | undefined, memoryId: string): Promise<any>;
+    /** 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. */
     deleteAll(userId: string): Promise<any>;
     private post;
+    private request;
 }
 /** Back-compat alias: older code used `WME`. */
 export declare const WME: typeof Client;

package/dist/wontopos.js

@@ -4,9 +4,15 @@
  *   npm install wontopos
  *
  *   import { Client } from "wontopos";
- *   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");
+ *   const mem = new Client({ apiKey: "wos-...", userId: "alice" }); // set the store once
+ *   await mem.createStore();                              // create it (uses the client's userId)
+ *   await mem.add("she prefers tea over coffee");         // no userId needed
+ *   const hits = await mem.search("what does alice drink?");
+ *
+ * Set `userId` once on the client and every call uses it; override any single call
+ * by passing `userId` to it. Stores are explicit: the store must exist first
+ * (`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*
  * reads it. All models share one memory, so you can store
@@ -26,22 +32,31 @@ export class WosError extends Error {
         this.status = status;
     }
 }
+const DEFAULT_USER = "default";
 /** Wontopos memory client. Store and recall memories, isolated per `userId`. */
 export class Client {
     base;
     headers;
     timeoutMs;
     apiKey;
+    model;
+    /** The store every call uses unless one passes `userId`. */
+    defaultUser;
     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.model = opts.model ?? DEFAULT_MODEL;
+        this.defaultUser = opts.userId || DEFAULT_USER;
         this.headers = { "X-API-Key": opts.apiKey, "Content-Type": "application/json" };
-        if (model)
-            this.headers["X-WOS-Model"] = model;
+        if (this.model)
+            this.headers["X-WOS-Model"] = this.model;
+    }
+    /** Resolve a call's store: the explicit userId, else the client default. */
+    uid(userId) {
+        return userId || this.defaultUser;
     }
     /**
      * A client that uses `model` (sent as `X-WOS-Model`). Use it to set the default
@@ -49,46 +64,56 @@ export class Client {
      * (`client.withModel("tablet-1").recall(...)`).
      */
     withModel(model) {
-        return new Client({ apiKey: this.apiKey, baseUrl: this.base, timeoutMs: this.timeoutMs, model });
+        return new Client({ apiKey: this.apiKey, baseUrl: this.base, timeoutMs: this.timeoutMs, model, userId: this.defaultUser });
+    }
+    /** A client bound to `userId` as its default store (everything else kept). */
+    withUser(userId) {
+        return new Client({ apiKey: this.apiKey, baseUrl: this.base, timeoutMs: this.timeoutMs, model: this.model, userId });
     }
     // ----- write -----
+    // `userId` is optional in every call below - omit it to use the client's default
+    // store (set via `new Client({ apiKey, userId })` or `withUser`).
     /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01" }). */
     add(content, userId, metadata = {}) {
-        return this.post("/api/v1/memory/store", { user_id: userId, content, metadata });
+        return this.post("/api/v1/memory/store", { user_id: this.uid(userId), content, metadata });
     }
     /** Store a conversation turn (user + assistant) into short-term + long-term memory. */
     addTurn(userId, userMsg, assistantMsg) {
-        return this.post("/api/v1/memory/store-turn", { user_id: userId, user_msg: userMsg, assistant_msg: assistantMsg });
+        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg });
     }
     /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
     addBulk(content, userId, category = "general", timestamp) {
-        const body = { user_id: userId, content, category };
+        const body = { user_id: this.uid(userId), content, category };
         if (timestamp)
             body.timestamp = timestamp;
         return this.post("/api/v1/memory/bulk-store", body);
     }
     /** Supersede an old memory with new content (a fact that changed). */
     update(userId, oldMemoryId, newContent) {
-        return this.post("/api/v1/memory/supersede", { user_id: userId, old_memory_id: oldMemoryId, new_content: newContent });
+        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent });
     }
     // ----- read -----
-    /** Semantic search over a user's memories. Returns memories, most relevant first. */
+    /** Semantic search over a store's memories. Returns memories, most relevant first. */
     async search(query, userId, limit = 10, opts = {}) {
-        const r = await this.post("/api/v1/memory/search", { user_id: userId, query, max_results: limit, ...opts });
+        const r = await this.post("/api/v1/memory/search", { user_id: this.uid(userId), query, max_results: limit, ...opts });
         return (r.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: userId, query });
+        return this.post("/api/v1/memory/recall", { user_id: this.uid(userId), query });
+    }
+    /** 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 });
     }
     /** Recent conversation turns (short-term memory). */
     async history(userId) {
-        const r = await this.post("/api/v1/memory/history", { user_id: userId });
+        const r = await this.post("/api/v1/memory/history", { user_id: this.uid(userId) });
         return (r.turns ?? []);
     }
-    /** Memory counts for a user: { total_memories, short_term_turns }. */
+    /** Memory counts for a store: { total_memories, short_term_turns }. */
     stats(userId) {
-        return this.post("/api/v1/memory/stats", { user_id: userId });
+        return this.post("/api/v1/memory/stats", { user_id: this.uid(userId) });
     }
     // ----- models -----
     /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
@@ -99,25 +124,46 @@ export class Client {
         const data = await res.json();
         return (data.models ?? []);
     }
+    // ----- stores -----
+    /** Create a store — the `userId` you read and write under. Stores are explicit:
+     * a store must exist before you `add` to or `search` it, otherwise those calls
+     * return 404. Idempotent. Every account starts with a `default` store.
+     * Returns `{ user_id, status }` (`status` is `"created"` or `"exists"`). */
+    createStore(userId) {
+        return this.post("/api/v1/memory/collection", { user_id: this.uid(userId) });
+    }
+    /** List your stores: `[{ user_id, created_at }, ...]` (`default` first). */
+    async listStores() {
+        const r = await this.request("GET", "/api/v1/memory/collections");
+        return (r.collections ?? []);
+    }
+    /** Delete a store and ALL its memories. Returns `{ user_id, status }`. */
+    deleteStore(userId) {
+        return this.request("DELETE", "/api/v1/memory/collection", { user_id: userId });
+    }
     // ----- delete -----
-    /** Delete a single memory by id. */
+    /** Delete a single memory by id. `userId` optional (uses the default store). */
     delete(userId, memoryId) {
-        return this.post("/api/v1/memory/forget", { user_id: userId, memory_id: memoryId });
+        return this.post("/api/v1/memory/forget", { user_id: this.uid(userId), memory_id: memoryId });
     }
-    /** Delete ALL memories for a user (GDPR erase). */
+    /** 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. */
     deleteAll(userId) {
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
     // ----- internal -----
-    async post(path, body) {
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async request(method, path, body) {
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
         let res;
         try {
             res = await fetch(`${this.base}${path}`, {
-                method: "POST",
+                method,
                 headers: this.headers,
-                body: JSON.stringify(body),
+                body: body === undefined ? undefined : JSON.stringify(body),
                 signal: ctrl.signal,
             });
         }

package/package.json

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