feat(memory):support self-host mem0 (#403)

This pull request improves support for both platform and self-hosted
Mem0 deployments in the long-term memory extension, making the API more
flexible and robust. The main changes include allowing users to specify
the Mem0 API type, updating endpoint handling in the client, and
enhancing search request capabilities.

**Mem0 API deployment flexibility and configuration:**

* The `Mem0LongTermMemory` builder and `Mem0Client` now accept an
`apiType` parameter, allowing users to specify `"platform"` (default) or
`"self-hosted"` deployments. Endpoints are selected accordingly, and
example code and documentation have been updated to reflect this.
[[1]](diffhunk://#diff-9cba458daeb3e8cf4c31784a4959c2943eea0a8a6a93a4de1fbe4f5eb140d7dbR68-R75)
[[2]](diffhunk://#diff-9cba458daeb3e8cf4c31784a4959c2943eea0a8a6a93a4de1fbe4f5eb140d7dbL100-R113)
[[3]](diffhunk://#diff-9cba458daeb3e8cf4c31784a4959c2943eea0a8a6a93a4de1fbe4f5eb140d7dbR260)
[[4]](diffhunk://#diff-9cba458daeb3e8cf4c31784a4959c2943eea0a8a6a93a4de1fbe4f5eb140d7dbR330-R341)
[[5]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aR33-R64)
[[6]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aL57-R95)
[[7]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aR110-R122)
[[8]](diffhunk://#diff-6b9103fbf3a240744117a2bf207e08f728ae356b07f26db47787eb2283beac2dL61-R64)
[[9]](diffhunk://#diff-4952aadfeff4e923a4f33c8f2e1f54fea0e151561103f782103707a676572d7eR34-R48)
[[10]](diffhunk://#diff-4952aadfeff4e923a4f33c8f2e1f54fea0e151561103f782103707a676572d7eR85-R93)

* The `Mem0Client` class now chooses the correct API endpoints for
memory add/search operations based on the `apiType`, supporting both
platform and self-hosted Mem0.
[[1]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aR33-R64)
[[2]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aL57-R95)
[[3]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aR110-R122)
[[4]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aL180-R230)
[[5]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aL203-R265)

**Robustness and compatibility improvements:**

* The `Mem0Client` search method now handles differences in response
format between platform and self-hosted Mem0. It parses results
accordingly to ensure compatibility.
[[1]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aL203-R265)
[[2]](diffhunk://#diff-8332bcfd89ba54150c52b48221dbd3f8f7c80198636a0a7ceeb5eb3e22e19e1aL221-R280)

* The `Mem0AddResponse` and `Mem0SearchResponse` classes now ignore
unknown JSON properties, increasing forward compatibility with future
API changes.
[[1]](diffhunk://#diff-e16424679ccb9aebbb4a66a2e19f617646a43edccabb49c31792aedd27f03e9cR18)
[[2]](diffhunk://#diff-e16424679ccb9aebbb4a66a2e19f617646a43edccabb49c31792aedd27f03e9cR35)
[[3]](diffhunk://#diff-3f16da56a4e77b05005e143f0c9319a486682653e632ae8e4522074d73666545R18)
[[4]](diffhunk://#diff-3f16da56a4e77b05005e143f0c9319a486682653e632ae8e4522074d73666545R32)

**Search request enhancements:**

* The `Mem0SearchRequest` class and its builder now support a `userId`
field, which is automatically added to filters for compatibility with
the v2 API.
[[1]](diffhunk://#diff-569eccfea80f2361d61a7b14915a655674edc419751dbb2cc6826baa575e93e1R81-R84)
[[2]](diffhunk://#diff-569eccfea80f2361d61a7b14915a655674edc419751dbb2cc6826baa575e93e1R182-R193)
[[3]](diffhunk://#diff-569eccfea80f2361d61a7b14915a655674edc419751dbb2cc6826baa575e93e1R216)
[[4]](diffhunk://#diff-569eccfea80f2361d61a7b14915a655674edc419751dbb2cc6826baa575e93e1L230-R255)
[[5]](diffhunk://#diff-569eccfea80f2361d61a7b14915a655674edc419751dbb2cc6826baa575e93e1R354-R357)

These changes make the Mem0 extension more flexible, easier to configure
for different deployment scenarios, and more robust to API
changes.Change-Id: If8c877e63f8d225d9e88e3830380ec855e7c9fd2
Co-developed-by: Aone Copilot <noreply@alibaba-inc.com>

## AgentScope-Java Version

[The version of AgentScope-Java you are working on, e.g. 1.0.4, check
your pom.xml dependency version or run `mvn dependency:tree | grep
agentscope-parent:pom`(only mac/linux)]

## Description

[Please describe the background, purpose, changes made, and how to test
this PR]

## Checklist

Please check the following items before code is ready to be reviewed.

- [ ]  Code has been formatted with `mvn spotless:apply`
- [ ]  All tests are passing (`mvn test`)
- [ ]  Javadoc comments are complete and follow project conventions
- [ ] Related documentation has been updated (e.g. links, examples,
etc.)
- [ ]  Code is ready for review

---------

Co-authored-by: Albumen Kevin <jhq0812@gmail.com>

Author: shiyiyue1102

agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/AutoMemoryExample.java

@@ -18,6 +18,7 @@
 
 import io.agentscope.core.ReActAgent;
 import io.agentscope.core.formatter.dashscope.DashScopeChatFormatter;
+import io.agentscope.core.memory.LongTermMemoryMode;
 import io.agentscope.core.memory.autocontext.AutoContextConfig;
 import io.agentscope.core.memory.autocontext.AutoContextHook;
 import io.agentscope.core.memory.autocontext.AutoContextMemory;
@@ -78,11 +79,12 @@ public static void main(String[] args) {
                         .memory(memory)
                         .maxIters(50)
                         .longTermMemory(longTermMemory)
+                        .longTermMemoryMode(LongTermMemoryMode.STATIC_CONTROL)
                         .enablePlan()
                         .toolkit(toolkit)
                         .hook(new AutoContextHook()) // Register the hook for automatic setup
                         .build();
-        String sessionId = "session111111111111";
+        String sessionId = "123453344";
         // Set up session path
         Path sessionPath =
                 Paths.get(System.getProperty("user.home"), ".agentscope", "examples", "sessions");

agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/Mem0Example.java

@@ -18,6 +18,7 @@
 import io.agentscope.core.ReActAgent;
 import io.agentscope.core.agent.user.UserAgent;
 import io.agentscope.core.memory.LongTermMemoryMode;
+import io.agentscope.core.memory.mem0.Mem0ApiType;
 import io.agentscope.core.memory.mem0.Mem0LongTermMemory;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.model.DashScopeChatModel;
@@ -31,14 +32,17 @@ public static void main(String[] args) throws Exception {
         // Get API keys
         String dashscopeApiKey = ExampleUtils.getDashScopeApiKey();
         String mem0BaseUrl = getMem0BaseUrl();
+        Mem0ApiType mem0ApiType = getMem0ApiType();
 
-        Mem0LongTermMemory longTermMemory =
+        Mem0LongTermMemory.Builder memoryBuilder =
                 Mem0LongTermMemory.builder()
                         .agentName("SmartAssistant")
                         .userId("static-control01126")
                         .apiBaseUrl(mem0BaseUrl)
                         .apiKey(System.getenv("MEM0_API_KEY"))
-                        .build();
+                        .apiType(mem0ApiType);
+
+        Mem0LongTermMemory longTermMemory = memoryBuilder.build();
 
         // Create agent with AGENT_CONTROL mode
         ReActAgent agent =
@@ -75,4 +79,17 @@ private static String getMem0BaseUrl() {
         }
         return baseUrl;
     }
+
+    /**
+     * Gets Mem0 API type from environment variable.
+     *
+     * @return API type enum: PLATFORM (default) or SELF_HOSTED
+     */
+    private static Mem0ApiType getMem0ApiType() {
+        String apiTypeStr = System.getenv("MEM0_API_TYPE");
+        if (apiTypeStr == null || apiTypeStr.isEmpty()) {
+            return Mem0ApiType.PLATFORM;
+        }
+        return Mem0ApiType.fromString(apiTypeStr);
+    }
 }

agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0AddResponse.java

@@ -15,6 +15,7 @@
  */
 package io.agentscope.core.memory.mem0;
 
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import java.util.List;
 import java.util.Map;
@@ -31,6 +32,7 @@
  * in the input messages.
  */
 @JsonInclude(JsonInclude.Include.NON_NULL)
+@JsonIgnoreProperties(ignoreUnknown = true)
 public class Mem0AddResponse {
 
     /**

agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0ApiType.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2024-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.agentscope.core.memory.mem0;
+
+/**
+ * Enumeration of Mem0 API deployment types.
+ *
+ * <p>Mem0 provides two deployment options with different API endpoints:
+ * <ul>
+ *   <li><b>PLATFORM</b>: Official cloud service with endpoints /v1/memories/ and /v2/memories/search/</li>
+ *   <li><b>SELF_HOSTED</b>: Self-deployed service with endpoints /memories and /search</li>
+ * </ul>
+ */
+public enum Mem0ApiType {
+    /** Platform Mem0 (default) - official cloud service. */
+    PLATFORM,
+
+    /** Self-hosted Mem0 - user-deployed service. */
+    SELF_HOSTED;
+
+    /**
+     * Parses a string to Mem0ApiType (case-insensitive).
+     *
+     * @param value String value to parse
+     * @return Corresponding Mem0ApiType, or PLATFORM if value is null/empty/invalid
+     */
+    public static Mem0ApiType fromString(String value) {
+        if (value == null || value.isEmpty()) {
+            return PLATFORM;
+        }
+        String normalized = value.toLowerCase().replace("_", "-");
+        if ("self-hosted".equals(normalized) || "selfhosted".equals(normalized)) {
+            return SELF_HOSTED;
+        }
+        return PLATFORM; // Default to PLATFORM
+    }
+}

agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0Client.java

@@ -30,20 +30,37 @@
 
 /**
  * HTTP client for interacting with the Mem0 API.
+ *
+ * <p>Supports both Platform Mem0 and self-hosted Mem0 deployments:
+ * <ul>
+ *   <li><b>Platform Mem0:</b> Uses endpoints /v1/memories/ and /v2/memories/search/</li>
+ *   <li><b>Self-hosted Mem0:</b> Uses endpoints /memories and /memories/search</li>
+ * </ul>
+ *
+ * <p>By default, the client uses Platform Mem0 endpoints. To use self-hosted Mem0,
+ * specify "self-hosted" as the apiType parameter.
  */
 public class Mem0Client {
 
     private static final MediaType JSON = MediaType.parse("application/json; charset=utf-8");
-    private static final String MEMORIES_ENDPOINT = "/v1/memories/";
-    private static final String SEARCH_ENDPOINT = "/v2/memories/search/";
+
+    // Platform Mem0 endpoints
+    private static final String PLATFORM_MEMORIES_ENDPOINT = "/v1/memories/";
+    private static final String PLATFORM_SEARCH_ENDPOINT = "/v2/memories/search/";
+
+    // Self-hosted Mem0 endpoints
+    private static final String SELF_HOSTED_MEMORIES_ENDPOINT = "/memories";
+    private static final String SELF_HOSTED_SEARCH_ENDPOINT = "/search";
 
     private final OkHttpClient httpClient;
     private final String apiBaseUrl;
     private final String apiKey;
     private final ObjectMapper objectMapper;
+    private final String addEndpoint;
+    private final String searchEndpoint;
 
     /**
-     * Creates a new Mem0Client with specified configuration.
+     * Creates a new Mem0Client with specified configuration (defaults to Platform Mem0).
      *
      * @param apiBaseUrl The base URL of the Mem0 API (e.g., "http://localhost:8000")
      * @param apiKey The API key for authentication (can be null for local deployments without
@@ -54,14 +71,27 @@ public Mem0Client(String apiBaseUrl, String apiKey) {
     }
 
     /**
-     * Creates a new Mem0Client with custom timeout.
+     * Creates a new Mem0Client with custom timeout (defaults to Platform Mem0).
      *
      * @param apiBaseUrl The base URL of the Mem0 API
      * @param apiKey The API key for authentication (can be null for local deployments without
      *     authentication)
      * @param timeout HTTP request timeout duration
      */
     public Mem0Client(String apiBaseUrl, String apiKey, Duration timeout) {
+        this(apiBaseUrl, apiKey, Mem0ApiType.PLATFORM, timeout);
+    }
+
+    /**
+     * Creates a new Mem0Client with API type specification.
+     *
+     * @param apiBaseUrl The base URL of the Mem0 API
+     * @param apiKey The API key for authentication (can be null for local deployments without
+     *     authentication)
+     * @param apiType API type enum
+     * @param timeout HTTP request timeout duration
+     */
+    public Mem0Client(String apiBaseUrl, String apiKey, Mem0ApiType apiType, Duration timeout) {
         this.apiBaseUrl =
                 apiBaseUrl.endsWith("/")
                         ? apiBaseUrl.substring(0, apiBaseUrl.length() - 1)
@@ -76,6 +106,19 @@ public Mem0Client(String apiBaseUrl, String apiKey, Duration timeout) {
                         .readTimeout(timeout)
                         .writeTimeout(Duration.ofSeconds(30))
                         .build();
+
+        // Determine API type (default to PLATFORM if null)
+        Mem0ApiType resolvedApiType = apiType != null ? apiType : Mem0ApiType.PLATFORM;
+
+        // Select endpoints based on API type
+        if (resolvedApiType == Mem0ApiType.SELF_HOSTED) {
+            this.addEndpoint = SELF_HOSTED_MEMORIES_ENDPOINT;
+            this.searchEndpoint = SELF_HOSTED_SEARCH_ENDPOINT;
+        } else {
+            // Default to platform endpoints
+            this.addEndpoint = PLATFORM_MEMORIES_ENDPOINT;
+            this.searchEndpoint = PLATFORM_SEARCH_ENDPOINT;
+        }
     }
 
     /**
@@ -129,6 +172,12 @@ private <T> Mono<String> executePostRaw(String endpoint, T request, String opera
 
                                 // Return raw response body
                                 return response.body().string();
+                            } catch (IOException e) {
+                                // Re-throw IOException as-is (it already contains status code info)
+                                throw e;
+                            } catch (Exception e) {
+                                // Wrap other exceptions
+                                throw new IOException("Mem0 API " + operationName + " failed", e);
                             }
                         })
                 .subscribeOn(Schedulers.boundedElastic());
@@ -177,7 +226,7 @@ private <T, R> Mono<R> executePost(
      * @return A Mono emitting the response with extracted memories
      */
     public Mono<Mem0AddResponse> add(Mem0AddRequest request) {
-        return executePost(MEMORIES_ENDPOINT, request, Mem0AddResponse.class, "add request");
+        return executePost(addEndpoint, request, Mem0AddResponse.class, "add request");
     }
 
     /**
@@ -200,25 +249,37 @@ public Mono<Mem0AddResponse> add(Mem0AddRequest request) {
      * @return A Mono emitting the search response with relevant memories
      */
     public Mono<Mem0SearchResponse> search(Mem0SearchRequest request) {
-        return executePostRaw(SEARCH_ENDPOINT, request, "search request")
+        return executePostRaw(searchEndpoint, request, "search request")
                 .map(
                         responseBody -> {
                             try {
-                                // Parse response as array
-                                List<Mem0SearchResult> results =
-                                        objectMapper.readValue(
-                                                responseBody,
-                                                objectMapper
-                                                        .getTypeFactory()
-                                                        .constructCollectionType(
-                                                                List.class,
-                                                                Mem0SearchResult.class));
-
-                                // Wrap in Mem0SearchResponse for consistency
-                                Mem0SearchResponse searchResponse = new Mem0SearchResponse();
-                                searchResponse.setResults(results);
-                                return searchResponse;
-                            } catch (IOException e) {
+                                // Platform Mem0 uses /v2/memories/search/ endpoint and returns
+                                // direct array
+                                // Self-hosted Mem0 uses /search endpoint and returns wrapped format
+                                if (searchEndpoint.contains("/v2/")) {
+                                    // Platform Mem0 returns direct array
+                                    List<Mem0SearchResult> results =
+                                            objectMapper.readValue(
+                                                    responseBody,
+                                                    objectMapper
+                                                            .getTypeFactory()
+                                                            .constructCollectionType(
+                                                                    List.class,
+                                                                    Mem0SearchResult.class));
+
+                                    // Wrap in Mem0SearchResponse for consistency
+                                    Mem0SearchResponse searchResponse = new Mem0SearchResponse();
+                                    searchResponse.setResults(results);
+                                    return searchResponse;
+                                } else {
+                                    // Self-hosted Mem0 returns response wrapped in {"results":
+                                    // [...]}
+                                    Mem0SearchResponse searchResponse =
+                                            objectMapper.readValue(
+                                                    responseBody, Mem0SearchResponse.class);
+                                    return searchResponse;
+                                }
+                            } catch (Exception e) {
                                 throw new RuntimeException("Failed to parse search response", e);
                             }
                         });

agentscope-extensions/agentscope-extensions-mem0/src/main/java/io/agentscope/core/memory/mem0/Mem0LongTermMemory.java

@@ -65,6 +65,14 @@
  *     .apiBaseUrl("http://localhost:8000")
  *     .build();
  *
+ * // For self-hosted Mem0
+ * Mem0LongTermMemory selfHostedMemory = Mem0LongTermMemory.builder()
+ *     .agentName("Assistant")
+ *     .userName("user_123")
+ *     .apiBaseUrl("http://localhost:8000")
+ *     .apiType(Mem0ApiType.SELF_HOSTED)  // Specify self-hosted API type
+ *     .build();
+ *
  * // Record a message
  * Msg msg = Msg.builder()
  *     .role(MsgRole.USER)
@@ -97,7 +105,8 @@ public class Mem0LongTermMemory implements LongTermMemory {
      * Private constructor - use Builder instead.
      */
     private Mem0LongTermMemory(Builder builder) {
-        this.client = new Mem0Client(builder.apiBaseUrl, builder.apiKey, builder.timeout);
+        Mem0ApiType apiType = builder.apiType != null ? builder.apiType : Mem0ApiType.PLATFORM;
+        this.client = new Mem0Client(builder.apiBaseUrl, builder.apiKey, apiType, builder.timeout);
         this.agentId = builder.agentName;
         this.userId = builder.userId;
         this.runId = builder.runName;
@@ -244,6 +253,7 @@ public static class Builder {
         private String runName;
         private String apiBaseUrl;
         private String apiKey;
+        private Mem0ApiType apiType;
         private java.time.Duration timeout = java.time.Duration.ofSeconds(60);
 
         /**
@@ -313,6 +323,17 @@ public Builder timeout(java.time.Duration timeout) {
             return this;
         }
 
+        /**
+         * Sets the Mem0 API type.
+         *
+         * @param apiType API type enum
+         * @return This builder
+         */
+        public Builder apiType(Mem0ApiType apiType) {
+            this.apiType = apiType;
+            return this;
+        }
+
         /**
          * Builds the Mem0LongTermMemory instance.
          *