Merge branch 'main' into fix/ts-oss-camelcase-filters

Both methods reject top-level entity params with "Use filters: { userId:
"..." } instead", and docs/open-source/node-quickstart.mdx teaches that same
shape. But search() and getAll() only read filters.user_id / .agent_id /
.run_id, so following either one throws a second, contradictory error:
"filters must contain at least one of: user_id, agent_id, run_id".

Normalize the three camelCase aliases to snake_case before validation in both
methods, so the shape the SDK tells callers to use actually works. An explicit
snake_case value wins if both are supplied, and the camelCase key is dropped
rather than passed through to the vector store as a stray metadata field.

mem0-ts/jest.integration.config.js

@@ -2,6 +2,8 @@
 module.exports = {
   ...require("./jest.config"),
   testMatch: ["**/integration/**/*.test.ts"],
+  globalSetup: "<rootDir>/src/client/tests/integration/global-setup.ts",
+  globalTeardown: "<rootDir>/src/client/tests/integration/global-teardown.ts",
   // Run integration tests serially to avoid rate limiting and race conditions
   maxWorkers: 1,
 };

mem0-ts/src/client/tests/integration/global-setup.ts

@@ -0,0 +1,40 @@
+/**
+ * Jest global setup for integration tests.
+ *
+ * Runs a full project cleanup before any integration test starts,
+ * then waits 10 seconds for the async cleanup to propagate.
+ */
+import { MemoryClient } from "../../mem0";
+
+export default async function globalSetup() {
+  const apiKey = process.env.MEM0_API_KEY;
+  if (!apiKey) return; // skip if no key — tests will be skipped too
+
+  const client = new MemoryClient({ apiKey });
+  await client.ping();
+
+  console.log("[integration] Running pre-test cleanup...");
+
+  // Full project wipe — all four filters set explicitly
+  try {
+    await client.deleteAll({
+      userId: "*",
+      agentId: "*",
+      appId: "*",
+      runId: "*",
+    });
+  } catch {
+    // ignore — may 404 if no data exists
+  }
+
+  try {
+    await client.deleteUsers();
+  } catch {
+    // ignore — may throw "No entities to delete"
+  }
+
+  // Wait 10 seconds for async cleanup to propagate
+  console.log("[integration] Waiting 10s for cleanup to propagate...");
+  await new Promise((r) => setTimeout(r, 10_000));
+  console.log("[integration] Pre-test cleanup done.");
+}

mem0-ts/src/client/tests/integration/global-teardown.ts

@@ -0,0 +1,36 @@
+/**
+ * Jest global teardown for integration tests.
+ *
+ * Runs a full project cleanup after all integration tests complete
+ * so no test data is left behind.
+ */
+import { MemoryClient } from "../../mem0";
+
+export default async function globalTeardown() {
+  const apiKey = process.env.MEM0_API_KEY;
+  if (!apiKey) return;
+
+  const client = new MemoryClient({ apiKey });
+  await client.ping();
+
+  console.log("[integration] Running post-test cleanup...");
+
+  try {
+    await client.deleteAll({
+      userId: "*",
+      agentId: "*",
+      appId: "*",
+      runId: "*",
+    });
+  } catch {
+    // ignore
+  }
+
+  try {
+    await client.deleteUsers();
+  } catch {
+    // ignore
+  }
+
+  console.log("[integration] Post-test cleanup done.");
+}

mem0-ts/src/client/tests/integration/helpers.ts

@@ -52,17 +52,13 @@ export async function withRetry<T>(
 }
 
 /**
- * Poll getAll until a user's memories reach minCount and the ID set
- * stops changing between polls.
- *
- * The Mem0 API processes memories asynchronously, and consolidating a
- * new fact replaces a memory (delete + add) instead of editing it in
- * place. Returning on the first non-empty read hands callers IDs the
- * pipeline then invalidates, so compare IDs rather than length: a
- * replacement leaves the count unchanged.
+ * Poll getAll until memories appear for a user.
+ * The Mem0 API processes memories asynchronously — after add()
+ * we need to wait for them to be available.
  *
  * Polls every 15 seconds with a maximum of 4 retries to avoid
- * hitting rate limits. Throws if minCount is never reached.
+ * hitting rate limits. Throws if results aren't available after
+ * all retries.
  */
 export async function waitForMemories(
   client: MemoryClient,
@@ -70,32 +66,18 @@ export async function waitForMemories(
   minCount: number,
   maxRetries = 4,
 ): Promise<Memory[]> {
-  let memories: Memory[] = [];
-  let previousIds = "";
-
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     const response = await withRetry(() =>
       client.getAll({ filters: { user_id: userId } }),
     );
-    memories = response.results ?? [];
-
-    const ids = memories
-      .map((m) => m.id)
-      .sort()
-      .join(",");
-    if (memories.length >= minCount && ids === previousIds) {
+    const memories = response.results ?? [];
+    if (memories.length >= minCount) {
       return memories;
     }
-    previousIds = ids;
-
     if (attempt < maxRetries) {
       await new Promise((r) => setTimeout(r, 15_000));
     }
   }
-
-  if (memories.length >= minCount) {
-    return memories;
-  }
   throw new Error(
     `waitForMemories: expected at least ${minCount} memories for user "${userId}" but did not get them after ${maxRetries} attempts`,
   );
@@ -220,3 +202,32 @@ export async function cleanupTestUser(
     // ignore
   }
 }
+
+/**
+ * Full project wipe — deletes all memories and all entities.
+ * Equivalent to Python SDK's:
+ *   client.delete_all(user_id="*", agent_id="*", app_id="*", run_id="*")
+ *
+ * Used as cleanup before and after integration test runs so tests
+ * start from a clean slate and don't leave data behind.
+ */
+export async function fullProjectCleanup(client: MemoryClient): Promise<void> {
+  // Delete all memories — all four filters set explicitly
+  try {
+    await client.deleteAll({
+      userId: "*",
+      agentId: "*",
+      appId: "*",
+      runId: "*",
+    });
+  } catch {
+    // ignore — may 404 if no data exists
+  }
+
+  // Delete all entities (users, agents, apps, runs)
+  try {
+    await client.deleteUsers();
+  } catch {
+    // ignore — may throw "No entities to delete"
+  }
+}

mem0-ts/src/client/tests/integration/management.test.ts

@@ -100,7 +100,6 @@ describeIntegration("MemoryClient Integration — Users & Project", () => {
     const hookName = `test-hook-${randomUUID().slice(0, 8)}`;
     const hookUrl = `https://example.com/webhook/${randomUUID().slice(0, 8)}`;
     const updatedName = `updated-hook-${randomUUID().slice(0, 8)}`;
-    const updatedUrl = `https://example.com/updated/${randomUUID().slice(0, 8)}`;
 
     afterAll(async () => {
       if (createdWebhookId) {
@@ -169,7 +168,7 @@ describeIntegration("MemoryClient Integration — Users & Project", () => {
         client.updateWebhook({
           webhookId: createdWebhookId,
           name: updatedName,
-          url: updatedUrl,
+          url: "https://example.com/updated",
           eventTypes: [WebhookEvent.MEMORY_DELETED],
         }),
       );

mem0-ts/src/client/tests/waitForMemories.test.ts

@@ -1,69 +0,0 @@
-import { waitForMemories } from "./integration/helpers";
-
-const clientReturning = (polls: Array<Array<{ id: string }>>) => {
-  let call = 0;
-  return {
-    getAll: jest.fn(async () => ({
-      results: polls[Math.min(call++, polls.length - 1)],
-    })),
-  } as any;
-};
-
-const settle = async <T>(pending: Promise<T>): Promise<T> => {
-  pending.catch(() => {});
-  for (let i = 0; i < 4; i++) {
-    await jest.advanceTimersByTimeAsync(15_000);
-  }
-  return pending;
-};
-
-describe("waitForMemories", () => {
-  beforeEach(() => jest.useFakeTimers());
-  afterEach(() => jest.useRealTimers());
-
-  test("waits for the id set to stop changing", async () => {
-    const client = clientReturning([
-      [{ id: "a" }],
-      [{ id: "a" }, { id: "b" }],
-      [{ id: "a" }, { id: "b" }],
-    ]);
-
-    const memories = await settle(waitForMemories(client, "user", 1));
-
-    expect(memories.map((m) => m.id)).toEqual(["a", "b"]);
-    expect(client.getAll).toHaveBeenCalledTimes(3);
-  });
-
-  test("keeps polling when consolidation replaces a memory at a constant count", async () => {
-    const client = clientReturning([
-      [{ id: "a" }, { id: "b" }],
-      [{ id: "a" }, { id: "c" }],
-      [{ id: "a" }, { id: "c" }],
-    ]);
-
-    const memories = await settle(waitForMemories(client, "user", 1));
-
-    expect(memories.map((m) => m.id)).toEqual(["a", "c"]);
-  });
-
-  test("returns the last read when the set never settles but minCount is met", async () => {
-    const client = clientReturning([
-      [{ id: "a" }],
-      [{ id: "b" }],
-      [{ id: "c" }],
-      [{ id: "d" }],
-    ]);
-
-    const memories = await settle(waitForMemories(client, "user", 1));
-
-    expect(memories.map((m) => m.id)).toEqual(["d"]);
-  });
-
-  test("throws when minCount is never reached", async () => {
-    const client = clientReturning([[]]);
-
-    await expect(settle(waitForMemories(client, "user", 1))).rejects.toThrow(
-      /expected at least 1 memories/,
-    );
-  });
-});

mem0-ts/src/oss/src/memory/index.ts

@@ -149,6 +149,27 @@ function rejectTopLevelEntityParams(
   }
 }
 
+const ENTITY_ID_ALIASES: Record<string, string> = {
+  userId: "user_id",
+  agentId: "agent_id",
+  runId: "run_id",
+};
+
+/** Rewrites camelCase entity ids inside filters to the snake_case keys vector stores index on. */
+function normalizeEntityFilterKeys(
+  filters: Record<string, any>,
+): Record<string, any> {
+  const normalized = { ...filters };
+  for (const [camelKey, snakeKey] of Object.entries(ENTITY_ID_ALIASES)) {
+    if (!(camelKey in normalized)) continue;
+    if (normalized[snakeKey] === undefined) {
+      normalized[snakeKey] = normalized[camelKey];
+    }
+    delete normalized[camelKey];
+  }
+  return normalized;
+}
+
 /**
  * Validates and normalizes an entity ID.
  * - Coerces non-string ids (e.g. numeric database keys) to string
@@ -1357,16 +1378,20 @@ export class Memory {
     // receive `agent_id: undefined` / `run_id: undefined` and fail
     // (Qdrant rejects the malformed match, pgvector binds NULL, Redis
     // emits a literal "undefined" string in TAG filters).
+    const requestedFilters = normalizeEntityFilterKeys(config.filters ?? {});
     const normalizedFilters: Record<string, any> = config.filters
       ? Object.fromEntries(
           Object.entries({
-            ...config.filters,
-            user_id: validateAndTrimEntityId(config.filters.user_id, "user_id"),
+            ...requestedFilters,
+            user_id: validateAndTrimEntityId(
+              requestedFilters.user_id,
+              "user_id",
+            ),
             agent_id: validateAndTrimEntityId(
-              config.filters.agent_id,
+              requestedFilters.agent_id,
               "agent_id",
             ),
-            run_id: validateAndTrimEntityId(config.filters.run_id, "run_id"),
+            run_id: validateAndTrimEntityId(requestedFilters.run_id, "run_id"),
           }).filter(([, v]) => v !== undefined),
         )
       : {};
@@ -1853,12 +1878,16 @@ export class Memory {
     // Validate and trim entity IDs in filters. Drop keys that resolve to
     // undefined so downstream vector stores don't receive
     // `agent_id: undefined` / `run_id: undefined` and fail.
+    const requestedFilters = normalizeEntityFilterKeys(config.filters || {});
     const filters: Record<string, any> = Object.fromEntries(
       Object.entries({
-        ...(config.filters || {}),
-        user_id: validateAndTrimEntityId(config.filters?.user_id, "user_id"),
-        agent_id: validateAndTrimEntityId(config.filters?.agent_id, "agent_id"),
-        run_id: validateAndTrimEntityId(config.filters?.run_id, "run_id"),
+        ...requestedFilters,
+        user_id: validateAndTrimEntityId(requestedFilters.user_id, "user_id"),
+        agent_id: validateAndTrimEntityId(
+          requestedFilters.agent_id,
+          "agent_id",
+        ),
+        run_id: validateAndTrimEntityId(requestedFilters.run_id, "run_id"),
       }).filter(([, v]) => v !== undefined),
     );
 

mem0-ts/src/oss/tests/memory.validation.test.ts

@@ -281,6 +281,66 @@ describe("Memory Input Validation", () => {
     });
   });
 
+  describe("camelCase entity IDs in filters", () => {
+    it("maps camelCase filter keys to snake_case in search", async () => {
+      const searchSpy = jest
+        .spyOn((memory as any).vectorStore, "search")
+        .mockResolvedValue([]);
+
+      await memory.search("q", {
+        filters: { userId: "alice", agentId: "bot", runId: "run-1" },
+      });
+
+      const passedFilters = searchSpy.mock.calls[0][2] as Record<string, any>;
+      expect(passedFilters).toMatchObject({
+        user_id: "alice",
+        agent_id: "bot",
+        run_id: "run-1",
+      });
+      expect(passedFilters.userId).toBeUndefined();
+      expect(passedFilters.agentId).toBeUndefined();
+      expect(passedFilters.runId).toBeUndefined();
+
+      searchSpy.mockRestore();
+    });
+
+    it("maps camelCase filter keys to snake_case in getAll", async () => {
+      const listSpy = jest
+        .spyOn((memory as any).vectorStore, "list")
+        .mockResolvedValue([[], 0]);
+
+      await memory.getAll({ filters: { userId: "alice" } });
+
+      const passedFilters = listSpy.mock.calls[0][0] as Record<string, any>;
+      expect(passedFilters.user_id).toBe("alice");
+      expect(passedFilters.userId).toBeUndefined();
+
+      listSpy.mockRestore();
+    });
+
+    it("prefers an explicit snake_case value over its camelCase alias", async () => {
+      const listSpy = jest
+        .spyOn((memory as any).vectorStore, "list")
+        .mockResolvedValue([[], 0]);
+
+      await memory.getAll({
+        filters: { user_id: "snake", userId: "camel" },
+      });
+
+      const passedFilters = listSpy.mock.calls[0][0] as Record<string, any>;
+      expect(passedFilters.user_id).toBe("snake");
+      expect(passedFilters.userId).toBeUndefined();
+
+      listSpy.mockRestore();
+    });
+
+    it("validates camelCase filter values like their snake_case counterparts", async () => {
+      await expect(
+        memory.search("q", { filters: { userId: "user 123" } }),
+      ).rejects.toThrow("Invalid user_id: cannot contain whitespace");
+    });
+  });
+
   describe("search() filter entity ID validation", () => {
     it("should throw error when user_id in filters is whitespace-only", async () => {
       await expect(