feat(sdk, docs): expose agent_custom_instructions for agent-scoped extraction (#6809)

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

@@ -12,6 +12,7 @@ export interface AddMemoryOptions extends EntityOptions {
   infer?: boolean;
   customCategories?: custom_categories[];
   customInstructions?: string;
+  agentCustomInstructions?: string;
   timestamp?: number;
   expirationDate?: string;
   structuredDataSchema?: Record<string, any>;
@@ -60,6 +61,7 @@ export interface ProjectOptions {
 
 export interface PromptUpdatePayload {
   customInstructions?: string;
+  agentCustomInstructions?: string;
   customCategories?: custom_categories[];
   version?: string;
   memoryDepth?: string | null;
@@ -174,6 +176,7 @@ export interface PaginatedMemories {
 
 export interface ProjectResponse {
   customInstructions?: string;
+  agentCustomInstructions?: string;
   // The API returns category objects (`[{ "<name>": "<description>" }]`),
   // not bare strings (see issue #5738).
   customCategories?: custom_categories[];

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

@@ -74,6 +74,35 @@ describe("MemoryClient - add()", () => {
     expect(getFetchBody(call!).expiration_date).toBe("2030-01-31");
   });
 
+  test("serializes agentCustomInstructions as agent_custom_instructions", 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" }], {
+      agentId: "a1",
+      agentCustomInstructions: "Remember tool failures",
+    });
+
+    const call = findFetchCall(mock, "/v3/memories/add/", "POST");
+    expect(getFetchBody(call!).agent_custom_instructions).toBe(
+      "Remember tool failures",
+    );
+  });
+
+  test("omits agent_custom_instructions when it is not passed", 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" });
+
+    const call = findFetchCall(mock, "/v3/memories/add/", "POST");
+    expect(getFetchBody(call!)).not.toHaveProperty("agent_custom_instructions");
+  });
+
   test("throws an error when given an empty messages array", async () => {
     setupMockFetch();
 

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

@@ -96,6 +96,84 @@ describe("MemoryClient - updateProject()", () => {
       "Updated instructions",
     );
   });
+
+  test("camelCases agentCustomInstructions into agent_custom_instructions", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/api/v1/orgs/organizations/", {
+      status: 200,
+      body: { message: "Updated" },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.ping();
+    await client.updateProject({
+      agentCustomInstructions: "Remember tool failures",
+    });
+
+    const call = findFetchCall(mock, "/api/v1/orgs/organizations/", "PATCH");
+    expect(getFetchBody(call!).agent_custom_instructions).toBe(
+      "Remember tool failures",
+    );
+  });
+
+  test("sends both instruction sets in one PATCH", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/api/v1/orgs/organizations/", {
+      status: 200,
+      body: { message: "Updated" },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.ping();
+    await client.updateProject({
+      customInstructions: "Remember user preferences",
+      agentCustomInstructions: "Remember tool failures",
+    });
+
+    const body = getFetchBody(
+      findFetchCall(mock, "/api/v1/orgs/organizations/", "PATCH")!,
+    );
+    expect(body.custom_instructions).toBe("Remember user preferences");
+    expect(body.agent_custom_instructions).toBe("Remember tool failures");
+  });
+
+  test("an empty string round-trips, so the field can be cleared", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/api/v1/orgs/organizations/", {
+      status: 200,
+      body: { message: "Updated" },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.ping();
+    await client.updateProject({ agentCustomInstructions: "" });
+
+    const body = getFetchBody(
+      findFetchCall(mock, "/api/v1/orgs/organizations/", "PATCH")!,
+    );
+    expect(body).toHaveProperty("agent_custom_instructions", "");
+  });
+
+  test("omits agent_custom_instructions when it is not passed", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/api/v1/orgs/organizations/", {
+      status: 200,
+      body: { message: "Updated" },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.ping();
+    await client.updateProject({ customInstructions: "Be helpful" });
+
+    const body = getFetchBody(
+      findFetchCall(mock, "/api/v1/orgs/organizations/", "PATCH")!,
+    );
+    expect(body).not.toHaveProperty("agent_custom_instructions");
+  });
 });
 
 // ─── feedback() ─────────────────────────────────────────