wontopos 2.2.23 → 2.2.24

package/dist/wontopos.d.ts

@@ -107,7 +107,18 @@ export interface Memory {
 /** `add` / `store` → `{ id, status }` (`status: "stored" | "stored (async)" | "duplicate"`). */
 export interface StoreResult {
     id?: string;
+    /** `"stored"`, or `"duplicate"` when nothing was saved. */
     status?: string;
+    /**
+     * 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.
+     */
+    duplicate_of?: string;
     /** Present when the store was a duplicate and something (e.g. a speaker tag) was dropped. */
     note?: string;
     [key: string]: unknown;
@@ -183,6 +194,19 @@ export interface ModelInfo {
     /** "shared" — reads the common memory pool; "isolated" — its own dedicated store. */
     memory: "shared" | "isolated";
 }
+/** One entry of the engram / delivery-form catalogue (`listEngrams`). */
+export interface EngramInfo {
+    name: string;
+    description: string;
+    [key: string]: unknown;
+}
+/** `listEngrams` → what the SELECTED model can run. `forms` is empty on models
+ *  without delivery forms; `note` explains an empty `engrams`. */
+export interface EngramCatalog {
+    engrams: EngramInfo[];
+    forms: EngramInfo[];
+    note?: string;
+}
 /** `createStore` / `deleteStore` → `{ user_id, status }`. */
 export interface StoreOpResult {
     user_id?: string;
@@ -215,6 +239,27 @@ export interface SpeakersList {
     limit?: number;
     [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.
+ *
+ * Retrieval itself stays purely semantic (no keyword matching), 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.
+ */
+export interface SearchFilters {
+    /** Only these categories (the `category` you see on `listMemories` results). */
+    categories?: string[];
+    /** Ingestion-time window, as the API stores it. Plain strings, matched as given. */
+    time_from?: string;
+    time_to?: string;
+    /** WHEN THE CONTENT HAPPENED (`metadata.event_date`), not when it was written —
+     *  this is the one you usually want. RFC3339, or a plain `YYYY-MM-DD`. */
+    event_from?: string;
+    event_to?: string;
+    /** Drop matches the engine scored below this importance (0–1). */
+    min_importance?: number;
+}
 /** Known `search` options; extra fields pass through to the API untouched. */
 export interface SearchOptions {
     /** Recall caching: repeated/extended queries within the TTL bill at 0.1×. */
@@ -223,8 +268,29 @@ export interface SearchOptions {
     };
     /** Recall only this person's words ("me" or a registered name). */
     speaker?: string;
+    /** Restrict the search to part of the store — see {@link SearchFilters}. */
+    filters?: SearchFilters;
     [key: string]: unknown;
 }
+/**
+ * Per-call options for a write.
+ *
+ * `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.
+ *
+ * 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
+ * and is silently lost. Format: 1-128 chars of `[A-Za-z0-9._:-]`, checked locally.
+ *
+ * The window is in-memory on the API, so a deploy or restart clears it early. It is a
+ * guard against a retry storm, not a durable ledger.
+ */
+export interface WriteOptions {
+    idempotencyKey?: string;
+}
 export interface ClientOptions {
     apiKey: string;
     /** API base URL (defaults to the hosted service). */
@@ -284,17 +350,25 @@ export declare class Client {
     withTimeout(timeoutMs: number): Client;
     /** A client with a different retry budget (everything else kept). 0 disables retries. */
     withRetries(maxRetries: number): Client;
-    /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01T00:00:00Z" } — RFC3339).
-     * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store). */
-    add(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<StoreResult>;
+    /** 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.
+     * `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
+     * of this exact write safe to repeat. */
+    add(content: string, userId?: string, metadata?: Record<string, unknown>, opts?: WriteOptions): Promise<StoreResult>;
     /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
-    store(content: string, userId?: string, metadata?: Record<string, unknown>): Promise<StoreResult>;
+    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): Promise<StatusResult>;
-    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
-    addBulk(content: string, userId?: string, category?: string, timestamp?: string): Promise<StatusResult>;
+    addTurn(userMsg: string, assistantMsg: string, userId?: string, opts?: WriteOptions): Promise<StatusResult>;
+    /** Bulk-ingest a large blob of text (chunked + embedded server-side). 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. */
+    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): Promise<UpdateResult>;
+    update(oldMemoryId: string, newContent: string, userId?: string, opts?: WriteOptions): Promise<UpdateResult>;
     /** Semantic search over a store's memories. Returns memories, most relevant first. */
     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
@@ -357,6 +431,19 @@ export declare class Client {
     ping(): Promise<boolean>;
     /** Available models: `[{ id, name, available, memory }, ...]`. Needs no API key. */
     listModels(): Promise<ModelInfo[]>;
+    /**
+     * 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
+     * comes back depends on the model (delivery forms need Scroll 1.2+), so pass
+     * `withModel()` if you want another model's catalogue.
+     *
+     *   const { engrams, forms } = await mem.listEngrams();
+     */
+    listEngrams(): Promise<EngramCatalog>;
     /** 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.
@@ -380,6 +467,10 @@ export declare class Client {
      * this is destructive, so it never falls back to the default store. */
     deleteAll(userId: string): Promise<StatusResult>;
     private post;
+    /** Validate an idempotency key BEFORE the network. The API answers a malformed
+     *  key with a 400, which on a retry path reads as "my write failed" when in fact
+     *  it was never attempted — cheaper and clearer to reject it here. */
+    private idemHeader;
     /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
     private backoffMs;
     /** Read the body with a hard size cap, so a broken/hostile endpoint can't

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.23";
+const VERSION = "2.2.24";
 /** 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). */
@@ -71,6 +71,12 @@ const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
 const MODEL_RE = /^[A-Za-z0-9._-]+$/;
 /** Cap a server-controlled error message so a hostile body can't blow up a log. */
 const MAX_ERR_MSG = 4096;
+/** What the API accepts as an `Idempotency-Key`. Checked client-side so a bad key
+ *  fails before the request instead of coming back as a 400 mid-retry. */
+const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:\-]{1,128}$/;
+/** Statuses that legitimately carry NO body (RFC 9110). Everything else must
+ *  answer with a JSON object — see the empty-body check in `request`. */
+const NO_BODY_STATUS = new Set([204, 205, 304]);
 /** Paging backstop: bound the walk so a fresh-cursor-forever server can't loop us. */
 const MAX_PAGES = 1_000_000;
 /** Error codes that only occur while ESTABLISHING a connection — the request
@@ -341,29 +347,37 @@ export class Client {
     // ----- 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-01T00:00:00Z" } — RFC3339).
-     * `metadata.speaker`: "me" = the assistant's own words, or a person's name (up to 50 per store). */
-    add(content, userId, metadata = {}) {
-        return this.post("/api/v1/memory/store", { user_id: this.uid(userId), content, metadata });
+    /** 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.
+     * `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
+     * of this exact write safe to repeat. */
+    add(content, userId, metadata = {}, opts = {}) {
+        return this.post("/api/v1/memory/store", { user_id: this.uid(userId), content, metadata }, opts.idempotencyKey);
     }
     /** Alias of `add` — store one memory. Same surface as the Python SDK's `store`. */
-    store(content, userId, metadata = {}) {
-        return this.add(content, userId, metadata);
+    store(content, userId, metadata = {}, opts = {}) {
+        return this.add(content, userId, metadata, opts);
     }
     /** Store a conversation turn (user + assistant). Payload first, userId last — same shape as add/search. */
-    addTurn(userMsg, assistantMsg, userId) {
-        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg });
+    addTurn(userMsg, assistantMsg, userId, opts = {}) {
+        return this.post("/api/v1/memory/store-turn", { user_id: this.uid(userId), user_msg: userMsg, assistant_msg: assistantMsg }, opts.idempotencyKey);
     }
-    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
-    addBulk(content, userId, category = "general", timestamp) {
+    /** Bulk-ingest a large blob of text (chunked + embedded server-side). 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. */
+    addBulk(content, userId, category = "general", timestamp, opts = {}) {
         const body = { user_id: this.uid(userId), content, category };
         if (timestamp)
             body.timestamp = timestamp;
-        return this.post("/api/v1/memory/bulk-store", body);
+        return this.post("/api/v1/memory/bulk-store", body, opts.idempotencyKey);
     }
     /** Supersede an old memory with new content. Payload first, userId last — same shape as add/search. */
-    update(oldMemoryId, newContent, userId) {
-        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent });
+    update(oldMemoryId, newContent, userId, opts = {}) {
+        return this.post("/api/v1/memory/supersede", { user_id: this.uid(userId), old_memory_id: oldMemoryId, new_content: newContent }, opts.idempotencyKey);
     }
     // ----- read -----
     /** Semantic search over a store's memories. Returns memories, most relevant first. */
@@ -473,6 +487,29 @@ export class Client {
         const data = await this.request("GET", "/api/v1/models");
         return asRecords(data.models);
     }
+    // ----- engrams -----
+    /**
+     * 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
+     * comes back depends on the model (delivery forms need Scroll 1.2+), so pass
+     * `withModel()` if you want another model's catalogue.
+     *
+     *   const { engrams, forms } = await mem.listEngrams();
+     */
+    async listEngrams() {
+        const data = await this.request("GET", "/api/v1/engram");
+        return {
+            engrams: asRecords(data.engrams),
+            forms: asRecords(data.forms),
+            // Present when the selected model has no engram support — the service explains
+            // rather than returning a bare empty list.
+            note: typeof data.note === "string" ? data.note : undefined,
+        };
+    }
     // ----- 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
@@ -526,8 +563,19 @@ export class Client {
         return this.post("/api/v1/memory/forget", { user_id: userId });
     }
     // ----- internal -----
-    post(path, body) {
-        return this.request("POST", path, body);
+    post(path, body, idempotencyKey) {
+        return this.request("POST", path, body, idempotencyKey);
+    }
+    /** Validate an idempotency key BEFORE the network. The API answers a malformed
+     *  key with a 400, which on a retry path reads as "my write failed" when in fact
+     *  it was never attempted — cheaper and clearer to reject it here. */
+    idemHeader(key) {
+        if (key === undefined)
+            return undefined;
+        if (!IDEMPOTENCY_KEY_RE.test(key)) {
+            throw new Error(`invalid idempotencyKey: ${JSON.stringify(key)} — 1-128 chars of [A-Za-z0-9._:-]`);
+        }
+        return { "Idempotency-Key": key };
     }
     /** Seconds→ms to sleep before retry `attempt` (0-based). Honors Retry-After. */
     backoffMs(attempt, retryAfter) {
@@ -573,7 +621,8 @@ export class Client {
         }
         return new TextDecoder().decode(buf);
     }
-    async request(method, path, body) {
+    async request(method, path, body, idempotencyKey) {
+        const extraHeaders = this.idemHeader(idempotencyKey);
         const attempts = this.maxRetries + 1;
         // Debug logging shows the path WITHOUT its query string — a query can carry
         // a store id (listSpeakers), and logs must never carry data.
@@ -586,7 +635,7 @@ export class Client {
             try {
                 res = await fetch(`${this.base}${path}`, {
                     method,
-                    headers: this.headers,
+                    headers: extraHeaders ? { ...this.headers, ...extraHeaders } : this.headers,
                     body: body === undefined ? undefined : JSON.stringify(body),
                     signal: ctrl.signal,
                     // Never follow a redirect: fetch would forward the API key to
@@ -679,8 +728,15 @@ export class Client {
                     msg = msg.slice(0, MAX_ERR_MSG) + "…(truncated)";
                 throw errorFor(res.status, msg, requestId);
             }
-            if (!text)
-                return {};
+            // An empty body is only legal when the STATUS says there is no body. This
+            // used to accept any empty 2xx, so an `add()` answered by a truncating proxy
+            // returned `{}` and read as a successful write with no id — while the Python
+            // and Rust SDKs raised on the same response. Same rule in all three now.
+            if (!text) {
+                if (NO_BODY_STATUS.has(res.status))
+                    return {};
+                throw new WosError(res.status, "empty response body — expected a JSON object");
+            }
             let data;
             try {
                 data = JSON.parse(text);

package/package.json

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