feat(memory): expose expiration controls in client docs (#5874)

Co-authored-by: Soumil Rathi <soumilrathi@gmail.com>

mem0-ts/src/client/mem0.ts

@@ -281,19 +281,22 @@ export default class MemoryClient {
       text,
       metadata,
       timestamp,
+      expirationDate,
     }: {
       text?: string;
       metadata?: Record<string, any>;
       timestamp?: number | string;
+      expirationDate?: string | null;
     },
   ): Promise<Array<Memory>> {
     if (
       text === undefined &&
       metadata === undefined &&
-      timestamp === undefined
+      timestamp === undefined &&
+      expirationDate === undefined
     ) {
       throw new Error(
-        "At least one of text, metadata, or timestamp must be provided for update.",
+        "At least one of text, metadata, timestamp, or expirationDate must be provided for update.",
       );
     }
 
@@ -302,6 +305,7 @@ export default class MemoryClient {
     if (text !== undefined) payload.text = text;
     if (metadata !== undefined) payload.metadata = metadata;
     if (timestamp !== undefined) payload.timestamp = timestamp;
+    if (expirationDate !== undefined) payload.expiration_date = expirationDate;
 
     const payloadKeys = Object.keys(payload);
     this._captureEvent("update", [payloadKeys]);

mem0-ts/src/client/mem0.types.ts

@@ -13,6 +13,7 @@ export interface AddMemoryOptions extends EntityOptions {
   customCategories?: custom_categories[];
   customInstructions?: string;
   timestamp?: number;
+  expirationDate?: string;
   structuredDataSchema?: Record<string, any>;
 }
 
@@ -25,6 +26,7 @@ export interface SearchMemoryOptions {
   latestOnly?: boolean;
   fields?: string[];
   categories?: string[];
+  showExpired?: boolean;
 }
 
 export interface GetAllMemoryOptions {
@@ -35,6 +37,7 @@ export interface GetAllMemoryOptions {
   endDate?: string;
   latestOnly?: boolean;
   categories?: string[];
+  showExpired?: boolean;
 }
 
 export interface DeleteAllMemoryOptions extends EntityOptions {}
@@ -119,6 +122,7 @@ export interface Memory {
   memoryType?: string;
   score?: number;
   metadata?: any | null;
+  expirationDate?: string | null;
   owner?: string | null;
   agentId?: string | null;
   appId?: string | null;

mem0-ts/src/client/tests/memoryClient.crud.test.ts

@@ -59,6 +59,21 @@ describe("MemoryClient - add()", () => {
     expect(getFetchBody(call!).user_id).toBe("user_1");
   });
 
+  test("serializes expirationDate as expiration_date", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/v3/memories/add/", { status: 200, body: [createMockMemory()] });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.add([{ role: "user", content: "test" }], {
+      userId: "u1",
+      expirationDate: "2030-01-31",
+    });
+
+    const call = findFetchCall(mock, "/v3/memories/add/", "POST");
+    expect(getFetchBody(call!).expiration_date).toBe("2030-01-31");
+  });
+
   test("throws an error when given an empty messages array", async () => {
     setupMockFetch();
 
@@ -176,11 +191,26 @@ describe("MemoryClient - update()", () => {
     expect(body.timestamp).toBe(1710600000);
   });
 
+  test("sends expirationDate as expiration_date, including null", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/v1/memories/mem_123/", {
+      status: 200,
+      body: createMockMemory(),
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.update("mem_123", { expirationDate: null });
+
+    const call = findFetchCall(mock, "/v1/memories/mem_123/", "PUT");
+    expect(getFetchBody(call!).expiration_date).toBeNull();
+  });
+
   test("throws when no fields provided", async () => {
     setupMockFetch();
     const client = new MemoryClient({ apiKey: TEST_API_KEY });
     await expect(client.update("mem_123", {})).rejects.toThrow(
-      "At least one of text, metadata, or timestamp must be provided",
+      "At least one of text, metadata, timestamp, or expirationDate must be provided",
     );
   });
 });

mem0-ts/src/client/tests/memoryClient.search.test.ts

@@ -81,6 +81,24 @@ describe("MemoryClient - search()", () => {
     expect(getFetchBody(call!).latest_only).toBe(true);
   });
 
+  test("serializes showExpired as show_expired", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/v3/memories/search/", {
+      status: 200,
+      body: { results: [] },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.search("test", {
+      filters: { user_id: "u1" },
+      showExpired: true,
+    });
+
+    const call = findFetchCall(mock, "/v3/memories/search/", "POST");
+    expect(getFetchBody(call!).show_expired).toBe(true);
+  });
+
   test("passes complex OR filters through to the API body", async () => {
     const extra = new Map<string, { status: number; body: unknown }>();
     extra.set("/v3/memories/search/", {
@@ -300,4 +318,22 @@ describe("MemoryClient - getAll() entity param rejection", () => {
     const call = findFetchCall(mock, "/v3/memories/", "POST");
     expect(getFetchBody(call!).latest_only).toBe(true);
   });
+
+  test("serializes showExpired as show_expired", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/v3/memories/", {
+      status: 200,
+      body: { results: [] },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.getAll({
+      filters: { user_id: "u1" },
+      showExpired: true,
+    });
+
+    const call = findFetchCall(mock, "/v3/memories/", "POST");
+    expect(getFetchBody(call!).show_expired).toBe(true);
+  });
 });