@redis-iris/agent-memory 0.4.0-beta.3 → 1.0.0-beta.2

package/src/sdk/sdk.ts

@@ -8,6 +8,7 @@ import { bulkCreateLongTermMemories } from "../funcs/bulk-create-long-term-memor
 import { bulkDeleteLongTermMemories } from "../funcs/bulk-delete-long-term-memories.js";
 import { createDocumentIngestion } from "../funcs/create-document-ingestion.js";
 import { createNamespace } from "../funcs/create-namespace.js";
+import { createSession } from "../funcs/create-session.js";
 import { createSummaryView } from "../funcs/create-summary-view.js";
 import { deleteNamespace } from "../funcs/delete-namespace.js";
 import { deleteSessionEvent } from "../funcs/delete-session-event.js";
@@ -18,17 +19,17 @@ import { getIngestionHookStatus } from "../funcs/get-ingestion-hook-status.js";
 import { getLongTermMemory } from "../funcs/get-long-term-memory.js";
 import { getNamespaceRouting } from "../funcs/get-namespace-routing.js";
 import { getNamespace } from "../funcs/get-namespace.js";
+import { getServiceLiveness } from "../funcs/get-service-liveness.js";
+import { getServiceReadiness } from "../funcs/get-service-readiness.js";
 import { getSessionEvent } from "../funcs/get-session-event.js";
 import { getSessionMemory } from "../funcs/get-session-memory.js";
 import { getSummaryViewResult } from "../funcs/get-summary-view-result.js";
 import { getSummaryView } from "../funcs/get-summary-view.js";
-import { health } from "../funcs/health.js";
 import { listDocumentIngestionOutputs } from "../funcs/list-document-ingestion-outputs.js";
 import { listIngestionHookStatuses } from "../funcs/list-ingestion-hook-statuses.js";
 import { listMemorySourceEvidence } from "../funcs/list-memory-source-evidence.js";
 import { listMemorySourceLinks } from "../funcs/list-memory-source-links.js";
 import { listNamespaces } from "../funcs/list-namespaces.js";
-import { listSessionSummaries } from "../funcs/list-session-summaries.js";
 import { listSessions } from "../funcs/list-sessions.js";
 import { listSourceMemories } from "../funcs/list-source-memories.js";
 import { listSummaryViews } from "../funcs/list-summary-views.js";
@@ -41,6 +42,7 @@ import { updateLongTermMemoryFields } from "../funcs/update-long-term-memory-fie
 import { updateLongTermMemory } from "../funcs/update-long-term-memory.js";
 import { updateNamespace } from "../funcs/update-namespace.js";
 import { updateSummaryView } from "../funcs/update-summary-view.js";
+import { upsertLongTermMemory } from "../funcs/upsert-long-term-memory.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
 import * as models from "../models/index.js";
 import * as operations from "../models/operations/index.js";
@@ -48,12 +50,24 @@ import { unwrapAsync } from "../types/fp.js";
 
 export class AgentMemory extends ClientSDK {
   /**
-   * Return information about the operational status of the service.
+   * Reports that this API process can answer requests, independently of downstream dependencies.
    */
-  async health(
+  async getServiceLiveness(
     options?: RequestOptions,
-  ): Promise<models.HealthResponseContent> {
-    return unwrapAsync(health(
+  ): Promise<models.GetServiceLivenessResponseContent> {
+    return unwrapAsync(getServiceLiveness(
+      this,
+      options,
+    ));
+  }
+
+  /**
+   * Evaluates the same serving dependencies as the operational readiness probe. Returns 503 without dependency details when the service cannot serve requests.
+   */
+  async getServiceReadiness(
+    options?: RequestOptions,
+  ): Promise<models.GetServiceReadinessResponseContent> {
+    return unwrapAsync(getServiceReadiness(
       this,
       options,
     ));
@@ -87,20 +101,20 @@ export class AgentMemory extends ClientSDK {
   async listDocumentIngestionOutputs(
     ingestionId: string,
     limit?: number | undefined,
-    offset?: number | undefined,
+    cursor?: string | undefined,
     options?: RequestOptions,
   ): Promise<models.ListDocumentIngestionOutputsResponseContent> {
     return unwrapAsync(listDocumentIngestionOutputs(
       this,
       ingestionId,
       limit,
-      offset,
+      cursor,
       options,
     ));
   }
 
   /**
-   * Returns read-only health for applicable store-scoped RAM features.
+   * Returns read-only health for applicable store-scoped Agent Memory features.
    */
   async storeHealth(
     request?: operations.StoreHealthRequest | undefined,
@@ -114,7 +128,7 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * List hook decisions in stable newest-first order. Pages can be empty after owner filtering; continue while nextCursor is present. Internal run reservations are omitted.
+   * List hook decisions in stable newest-first order. Pages can be empty after owner filtering; continue while nextCursor is present.
    */
   async listIngestionHookStatuses(
     limit?: number | undefined,
@@ -144,13 +158,13 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * Deletes long-term memories in bulk by their IDs.
+   * Creates long-term memories in bulk. A memoryId that already exists is rejected for that record (reported in errors) and the stored memory is left unchanged; change a memory with UpdateLongTermMemory. Records without namespaceId stay un-namespaced. Automatic routing does not place them in a shared namespace. An explicit namespaceId must pass destination admission and is never rerouted. Admission failures are reported per record in errors.
    */
-  async bulkDeleteLongTermMemories(
-    request: models.BulkDeleteLongTermMemoriesRequestContent,
+  async bulkCreateLongTermMemories(
+    request: models.BulkCreateLongTermMemoriesRequestContent,
     options?: RequestOptions,
-  ): Promise<models.BulkDeleteLongTermMemoriesResponseContent> {
-    return unwrapAsync(bulkDeleteLongTermMemories(
+  ): Promise<models.BulkCreateLongTermMemoriesResponseContent> {
+    return unwrapAsync(bulkCreateLongTermMemories(
       this,
       request,
       options,
@@ -158,13 +172,13 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * Creates long-term memories in bulk. Records without namespace or namespaceRef stay un-namespaced. Automatic routing does not place them in a shared namespace. An explicit namespaceRef must pass destination admission and is never rerouted. Admission failures are reported per record in errors.
+   * Deletes long-term memories in bulk by their IDs.
    */
-  async bulkCreateLongTermMemories(
-    request: models.BulkCreateLongTermMemoriesRequestContent,
+  async bulkDeleteLongTermMemories(
+    request: models.BulkDeleteLongTermMemoriesRequestContent,
     options?: RequestOptions,
-  ): Promise<models.BulkCreateLongTermMemoriesResponseContent> {
-    return unwrapAsync(bulkCreateLongTermMemories(
+  ): Promise<models.BulkDeleteLongTermMemoriesResponseContent> {
+    return unwrapAsync(bulkDeleteLongTermMemories(
       this,
       request,
       options,
@@ -172,7 +186,7 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * Moves long-term memories to an explicit namespaceRef, or automatically routes a memory that is already in a shared namespace when namespaceRef is omitted. Personal and un-namespaced memories are not automatic-routing candidates and keep their current placement with a per-item error. If routing is disabled or no shared destination qualifies, the memory also keeps its current placement and receives a per-item error. An explicit destination must pass admission and is never rerouted. Returns 409 when the explicit destination is archived; automatic routing and admission failures are reported per item in errors.
+   * Moves long-term memories to an explicit namespaceId, or automatically routes a memory that is already in a shared namespace when namespaceId is omitted. Personal and un-namespaced memories are not automatic-routing candidates and keep their current placement with a per-item error. If routing is disabled or no shared destination qualifies, the memory also keeps its current placement and receives a per-item error. An explicit destination must pass admission and is never rerouted. Returns 409 when the explicit destination is archived; automatic routing and admission failures are reported per item in errors.
    */
   async moveLongTermMemories(
     request: models.MoveLongTermMemoriesRequestContent,
@@ -214,7 +228,7 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * Partially updates a long-term memory by its ID. The merged record must pass admission at its destination. Updates never select a different destination automatically.
+   * Partially updates a long-term memory by its ID. The merged record must pass admission at its destination. Updates never select a different destination automatically. Namespace-only updates preserve the current expiration and are allowed for document-managed memories; their extracted content remains protected.
    */
   async updateLongTermMemory(
     memoryId: string,
@@ -230,7 +244,23 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * Atomically updates a custom-typed long-term memory's text and/or attributes, scoped to the caller's bound memory type. Used by the custom-extraction worker. New text must pass destination admission before the update is applied.
+   * Creates or fully replaces one manually managed memory, including custom attributes. Omitted optional fields are cleared; memoryType defaults to semantic. Replacement preserves creation time and restarts the store TTL. Destination admission and ownership checks apply. A concurrent write can return a conflict or not-found error; retry after reading the current record. An idempotencyKey replays the saved result during the retry window (at most 24 hours, capped by the store memory TTL); expectedRevision guards replacement against concurrent changes.
+   */
+  async upsertLongTermMemory(
+    memoryId: string,
+    body: models.UpsertLongTermMemoryRequestContent,
+    options?: RequestOptions,
+  ): Promise<models.UpsertLongTermMemoryResponseContent> {
+    return unwrapAsync(upsertLongTermMemory(
+      this,
+      memoryId,
+      body,
+      options,
+    ));
+  }
+
+  /**
+   * Atomically updates a custom-typed long-term memory's text and/or attributes, scoped to the caller's bound memory type. New text must pass destination admission before the update is applied.
    */
   async updateLongTermMemoryFields(
     memoryId: string,
@@ -251,14 +281,14 @@ export class AgentMemory extends ClientSDK {
   async listMemorySourceLinks(
     memoryId: string,
     limit?: number | undefined,
-    pageToken?: string | undefined,
+    cursor?: string | undefined,
     options?: RequestOptions,
   ): Promise<models.ListMemorySourceLinksResponseContent> {
     return unwrapAsync(listMemorySourceLinks(
       this,
       memoryId,
       limit,
-      pageToken,
+      cursor,
       options,
     ));
   }
@@ -270,7 +300,7 @@ export class AgentMemory extends ClientSDK {
     memoryId: string,
     sourceId: string,
     limit?: number | undefined,
-    pageToken?: string | undefined,
+    cursor?: string | undefined,
     options?: RequestOptions,
   ): Promise<models.ListMemorySourceEvidenceResponseContent> {
     return unwrapAsync(listMemorySourceEvidence(
@@ -278,7 +308,7 @@ export class AgentMemory extends ClientSDK {
       memoryId,
       sourceId,
       limit,
-      pageToken,
+      cursor,
       options,
     ));
   }
@@ -298,7 +328,7 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * Replaces the store's namespace routing policy. Namespaces remain hierarchy records; routing is an ordered store-level document of plug-in strategies.
+   * Replaces the store's namespace routing policy.
    */
   async putNamespaceRouting(
     request: models.PutNamespaceRoutingRequestContent,
@@ -319,7 +349,7 @@ export class AgentMemory extends ClientSDK {
     scope?: models.NamespaceScope | undefined,
     ownerId?: string | undefined,
     limit?: number | undefined,
-    pageToken?: string | undefined,
+    cursor?: string | undefined,
     options?: RequestOptions,
     sortBy?: models.NamespaceSortBy | undefined,
     sortOrder?: models.NamespaceSortOrder | undefined,
@@ -330,7 +360,7 @@ export class AgentMemory extends ClientSDK {
       scope,
       ownerId,
       limit,
-      pageToken,
+      cursor,
       options,
       sortBy,
       sortOrder,
@@ -396,35 +426,39 @@ export class AgentMemory extends ClientSDK {
   }
 
   /**
-   * Returns a paginated list of session IDs for a store.
+   * Returns paginated session rows with metadata and caller-selected order.
    */
   async listSessions(
     limit?: number | undefined,
-    pageToken?: string | undefined,
-    filterOwnerId?: string | undefined,
+    cursor?: string | undefined,
+    ownerId?: string | undefined,
     includeAll?: boolean | undefined,
     options?: RequestOptions,
-    namespaceRef?: string | undefined,
+    namespaceId?: string | undefined,
+    sortBy?: models.SessionListSortBy | undefined,
+    sortOrder?: models.SessionListSortOrder | undefined,
   ): Promise<models.ListSessionsResponseContent> {
     return unwrapAsync(listSessions(
       this,
       limit,
-      pageToken,
-      filterOwnerId,
+      cursor,
+      ownerId,
       includeAll,
       options,
-      namespaceRef,
+      namespaceId,
+      sortBy,
+      sortOrder,
     ));
   }
 
   /**
-   * Appends a single event to a session. Creates the session if it does not exist. If sessionId is omitted, the server generates one.
+   * Creates a session with its first event. If sessionId is omitted, the server generates one. A sessionId that already exists is refused with 409 and the session is left unchanged; use AddSessionEvent to append to an existing session.
    */
-  async addSessionEvent(
-    request: models.AddSessionEventRequestContent,
+  async createSession(
+    request: models.CreateSessionRequestContent,
     options?: RequestOptions,
-  ): Promise<models.AddSessionEventResponseContent> {
-    return unwrapAsync(addSessionEvent(
+  ): Promise<models.CreateSessionResponseContent> {
+    return unwrapAsync(createSession(
       this,
       request,
       options,
@@ -461,6 +495,22 @@ export class AgentMemory extends ClientSDK {
     ));
   }
 
+  /**
+   * Appends a single event to a session. Creates the session if it does not exist.
+   */
+  async addSessionEvent(
+    sessionId: string,
+    body: models.AddSessionEventRequestContent,
+    options?: RequestOptions,
+  ): Promise<models.AddSessionEventResponseContent> {
+    return unwrapAsync(addSessionEvent(
+      this,
+      sessionId,
+      body,
+      options,
+    ));
+  }
+
   /**
    * Deletes a single event from a session by event ID.
    */
@@ -493,32 +543,6 @@ export class AgentMemory extends ClientSDK {
     ));
   }
 
-  /**
-   * Returns paginated session rows with metadata and caller-selected order. The ID-only ListSessions operation remains unchanged.
-   */
-  async listSessionSummaries(
-    limit?: number | undefined,
-    pageToken?: string | undefined,
-    filterOwnerId?: string | undefined,
-    namespaceRef?: string | undefined,
-    includeAll?: boolean | undefined,
-    sortBy?: models.SessionListSortBy | undefined,
-    sortOrder?: models.SessionListSortOrder | undefined,
-    options?: RequestOptions,
-  ): Promise<models.ListSessionSummariesResponseContent> {
-    return unwrapAsync(listSessionSummaries(
-      this,
-      limit,
-      pageToken,
-      filterOwnerId,
-      namespaceRef,
-      includeAll,
-      sortBy,
-      sortOrder,
-      options,
-    ));
-  }
-
   /**
    * Pages memories linked to one source. A source link does not grant access to a memory in another owner or namespace.
    */
@@ -526,7 +550,7 @@ export class AgentMemory extends ClientSDK {
     sourceId: string,
     ownerId: string,
     limit?: number | undefined,
-    pageToken?: string | undefined,
+    cursor?: string | undefined,
     options?: RequestOptions,
   ): Promise<models.ListSourceMemoriesResponseContent> {
     return unwrapAsync(listSourceMemories(
@@ -534,7 +558,7 @@ export class AgentMemory extends ClientSDK {
       sourceId,
       ownerId,
       limit,
-      pageToken,
+      cursor,
       options,
     ));
   }
@@ -544,13 +568,13 @@ export class AgentMemory extends ClientSDK {
    */
   async listSummaryViews(
     limit?: number | undefined,
-    pageToken?: string | undefined,
+    cursor?: string | undefined,
     options?: RequestOptions,
   ): Promise<models.ListSummaryViewsResponseContent> {
     return unwrapAsync(listSummaryViews(
       this,
       limit,
-      pageToken,
+      cursor,
       options,
     ));
   }
@@ -636,7 +660,7 @@ export class AgentMemory extends ClientSDK {
     viewId: string,
     ownerId?: string | undefined,
     sessionId?: string | undefined,
-    namespaceRef?: string | undefined,
+    namespaceId?: string | undefined,
     memoryType?: string | undefined,
     includeSourceMemoryIds?: boolean | undefined,
     options?: RequestOptions,
@@ -646,7 +670,7 @@ export class AgentMemory extends ClientSDK {
       viewId,
       ownerId,
       sessionId,
-      namespaceRef,
+      namespaceId,
       memoryType,
       includeSourceMemoryIds,
       options,

package/tests/current-contracts.test.mjs

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const STORE = "st_" + "a".repeat(32);
+const BASE = `/iris/data/v1/agent-memory/stores/${STORE}`;
+
+for (const mode of ["esm", "commonjs"]) {
+  const sdkModule = mode === "esm" ? await import("../dist/esm/index.js") : require("../dist/commonjs/index.js");
+  const errors = mode === "esm" ? await import("../dist/esm/models/errors/index.js") : require("../dist/commonjs/models/errors/index.js");
+  const { AgentMemory, AgentMemoryService, HTTPClient } = sdkModule;
+
+  test(`${mode}: every published operation is available`, () => {
+    for (const [file, client] of [["openapi-agent-memory.json", AgentMemory],
+      ["openapi-agent-memory-controlplane.json", AgentMemoryService]]) {
+      const contract = JSON.parse(readFileSync(new URL(`../../${file}`, import.meta.url), "utf8"));
+      for (const item of Object.values(contract.paths)) {
+        for (const [method, operation] of Object.entries(item)) {
+          if (!["get", "post", "put", "patch", "delete"].includes(method)) continue;
+          const name = operation.operationId[0].toLowerCase() + operation.operationId.slice(1);
+          assert.equal(typeof client.prototype[name], "function", operation.operationId);
+        }
+      }
+    }
+  });
+
+  test(`${mode}: upsert, PATCH and typed field updates preserve revision and retry keys`, async () => {
+    const bodies = [
+      { text: "Prefers email", ownerId: "alice@example.com", attributes: { enabled: false }, expectedRevision: "r1", idempotencyKey: "upsert-1" },
+      { namespaceId: "ns_" + "b".repeat(32), expectedRevision: "r2", idempotencyKey: "patch-1" },
+      { memoryType: "preference", attributes: { count: 0 }, expectedRevision: "r3", idempotencyKey: "fields-1" },
+    ];
+    let calls = 0;
+    const sdk = new AgentMemory({ serverURL: "https://example.test", storeId: STORE, apiKey: "dp-token",
+      httpClient: new HTTPClient({ fetcher: async (request) => {
+        const i = calls++;
+        assert.equal(request.method, i === 0 ? "PUT" : "PATCH");
+        assert.equal(new URL(request.url).pathname, BASE + "/memories/memory-1" + (i === 2 ? "/fields" : ""));
+        assert.equal(request.headers.get("authorization"), "Bearer dp-token");
+        assert.deepEqual(await request.json(), bodies[i]);
+        return Response.json(i === 0 ? { memoryId: "memory-1", created: false } : i === 1
+          ? { memoryId: "memory-1", text: "Unchanged", revision: "r3", createdAt: "2026-10-30T12:00:00Z", updatedAt: "2026-10-30T13:00:00Z" } : {});
+      } }),
+    });
+    assert.deepEqual(await sdk.upsertLongTermMemory("memory-1", bodies[0]), { memoryId: "memory-1", created: false });
+    assert.equal((await sdk.updateLongTermMemory("memory-1", bodies[1])).revision, "r3");
+    await sdk.updateLongTermMemoryFields("memory-1", bodies[2]);
+    assert.equal(calls, 3);
+  });
+
+  test(`${mode}: memory-type deletion keeps CP credentials and revision query`, async () => {
+    const sdk = new AgentMemoryService({ serverURL: "https://example.test", token: "cp-token",
+      httpClient: new HTTPClient({ fetcher: async (request) => {
+        assert.equal(request.method, "DELETE");
+        const url = new URL(request.url);
+        assert.equal(url.pathname, `/iris/v1/agent-memory/stores/${STORE}/memory-types/preference`);
+        assert.deepEqual(Object.fromEntries(url.searchParams), { expectedRevision: "r1", projectId: "project-1" });
+        assert.equal(request.headers.get("authorization"), "Bearer cp-token");
+        return new Response(null, { status: 204 });
+      } }),
+    });
+    await sdk.removeMemoryType(STORE, "preference", "project-1", "r1");
+  });
+
+  for (const [status, errorName] of [[409, "ConflictErrorResponseContent"],
+    [412, "PreconditionFailedErrorResponseContent"], [413, "PayloadTooLargeErrorResponseContent"]]) {
+    test(`${mode}: HTTP ${status} keeps its typed error and unknown server reason`, async () => {
+      const sdk = new AgentMemory({ serverURL: "https://example.test", storeId: STORE,
+        httpClient: new HTTPClient({ fetcher: async () => Response.json({ title: "Rejected", type: "/errors/future-server-reason",
+          status, currentRevision: "r2" }, { status }) }),
+      });
+      await assert.rejects(sdk.upsertLongTermMemory("memory-1", { text: "test", ownerId: "alice@example.com", expectedRevision: "r1" }),
+        (error) => error instanceof errors[errorName] && error.type === "/errors/future-server-reason"
+          && (status !== 412 || error.currentRevision === "r2"));
+    });
+  }
+
+  for (const [Client, prefix] of [[AgentMemory, "/iris/data/v1"], [AgentMemoryService, "/iris/v1"]]) {
+    test(`${mode}: ${Client.name} health preserves future enum values`, async () => {
+      const sdk = new Client({ serverURL: "https://example.test", storeId: STORE,
+        httpClient: new HTTPClient({ fetcher: async (request) => {
+          assert.equal(new URL(request.url).pathname, prefix + "/agent-memory/health/live");
+          return Response.json({ status: "FUTURE_HEALTH_STATE" });
+        } }),
+      });
+      assert.equal((await sdk.getServiceLiveness()).status, "FUTURE_HEALTH_STATE");
+    });
+  }
+}

package/tests/list-sessions-compatibility.ts

@@ -1,4 +1,5 @@
-// Keep these pre-0.4 call shapes unchanged when regenerating the SDK.
+// Keep these pre-0.4 call shapes unchanged when regenerating the SDK. Parameters the
+// contract adds after them (namespaceId, sortBy, sortOrder) go after `options`.
 import { AgentMemory } from "../dist/esm/index.js";
 import { AgentMemoryCore } from "../dist/esm/core.js";
 import { listSessions } from "../dist/esm/funcs/list-sessions.js";
@@ -20,6 +21,8 @@ listSessions(core, 10, undefined, undefined, true);
 listSessions(core, 10, undefined, "owner-1", false, options);
 listSessions(core, undefined, undefined, "owner-1", undefined, options);
 
-// New namespace filtering leaves every existing argument in place.
-sdk.listSessions(10, undefined, undefined, false, options, "namespace-1");
-listSessions(core, 10, undefined, undefined, false, options, "namespace-1");
+// New namespace filtering and ordering leave every existing argument in place.
+sdk.listSessions(10, undefined, undefined, false, options, "ns_" + "e".repeat(32));
+listSessions(core, 10, undefined, undefined, false, options, "ns_" + "e".repeat(32));
+sdk.listSessions(10, undefined, undefined, true, options, undefined, "createdAt", "DESC");
+listSessions(core, 10, undefined, undefined, true, options, undefined, "createdAt", "DESC");