feat: support metadata recording and filtering for Mem0 (#563)

## AgentScope-Java Version

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

$ mvn dependency:tree | grep agentscope-parent:pom
[INFO] io.agentscope:agentscope-parent:pom:1.0.8-SNAPSHOT

## Description

[Please describe the background, purpose, changes made, and how to test
this PR]
Feat [#561
](#561)


## Checklist

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

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

Author: xuanmiss

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

@@ -22,6 +22,8 @@
 import io.agentscope.core.memory.mem0.Mem0LongTermMemory;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.model.DashScopeChatModel;
+import java.util.HashMap;
+import java.util.Map;
 
 /**
  * Mem0Example - Demonstrates long-term memory using Mem0 backend.
@@ -33,14 +35,16 @@ public static void main(String[] args) throws Exception {
         String dashscopeApiKey = ExampleUtils.getDashScopeApiKey();
         String mem0BaseUrl = getMem0BaseUrl();
         Mem0ApiType mem0ApiType = getMem0ApiType();
-
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put("agentName", "SmartAssistant");
         Mem0LongTermMemory.Builder memoryBuilder =
                 Mem0LongTermMemory.builder()
                         .agentName("SmartAssistant")
                         .userId("static-control01126")
                         .apiBaseUrl(mem0BaseUrl)
                         .apiKey(System.getenv("MEM0_API_KEY"))
-                        .apiType(mem0ApiType);
+                        .apiType(mem0ApiType)
+                        .metadata(metadata);
 
         Mem0LongTermMemory longTermMemory = memoryBuilder.build();
 

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

@@ -18,6 +18,7 @@
 import io.agentscope.core.memory.LongTermMemory;
 import io.agentscope.core.message.Msg;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.stream.Collectors;
 import reactor.core.publisher.Mono;
@@ -34,6 +35,7 @@
  *   <li>Semantic memory search using vector embeddings
  *   <li>LLM-powered memory extraction and inference
  *   <li>Multi-tenant memory isolation (agent, user, run)
+ *   <li>Custom metadata support for tagging and filtering memories
  *   <li>Automatic fallback mechanisms to ensure reliable memory storage
  *   <li>Reactive, non-blocking operations
  * </ul>
@@ -44,6 +46,7 @@
  *   <li><b>agentId:</b> Identifies the agent (optional)</li>
  *   <li><b>userId:</b> Identifies the user/workspace (optional)</li>
  *   <li><b>runId:</b> Identifies the session/run (optional)</li>
+ *   <li><b>metadata:</b> Custom key-value pairs for additional filtering (optional)</li>
  * </ul>
  * At least one identifier is required. During retrieval, only memories with matching
  * metadata are returned.
@@ -53,35 +56,47 @@
  * // Create memory instance with authentication
  * Mem0LongTermMemory memory = Mem0LongTermMemory.builder()
  *     .agentName("Assistant")
- *     .userName("user_123")
+ *     .userId("user_123")
  *     .apiBaseUrl("http://localhost:8000")
  *     .apiKey(System.getenv("MEM0_API_KEY"))
  *     .build();
  *
  * // For local deployments without authentication
  * Mem0LongTermMemory localMemory = Mem0LongTermMemory.builder()
  *     .agentName("Assistant")
- *     .userName("user_123")
+ *     .userId("user_123")
  *     .apiBaseUrl("http://localhost:8000")
  *     .build();
  *
  * // For self-hosted Mem0
  * Mem0LongTermMemory selfHostedMemory = Mem0LongTermMemory.builder()
  *     .agentName("Assistant")
- *     .userName("user_123")
+ *     .userId("user_123")
  *     .apiBaseUrl("http://localhost:8000")
  *     .apiType(Mem0ApiType.SELF_HOSTED)  // Specify self-hosted API type
  *     .build();
  *
- * // Record a message
+ * // With custom metadata for filtering
+ * Map<String, Object> metadata = new HashMap<>();
+ * metadata.put("category", "travel");
+ * metadata.put("project_id", "proj_001");
+ *
+ * Mem0LongTermMemory memoryWithMetadata = Mem0LongTermMemory.builder()
+ *     .agentName("Assistant")
+ *     .userId("user_123")
+ *     .apiBaseUrl("http://localhost:8000")
+ *     .metadata(metadata)  // Custom metadata for storage and filtering
+ *     .build();
+ *
+ * // Record a message (metadata will be stored with the memory)
  * Msg msg = Msg.builder()
  *     .role(MsgRole.USER)
  *     .content("I prefer homestays when traveling")
  *     .build();
  *
  * memory.record(List.of(msg)).block();
  *
- * // Retrieve relevant memories
+ * // Retrieve relevant memories (metadata will be used as filter)
  * Msg query = Msg.builder()
  *     .role(MsgRole.USER)
  *     .content("What are my travel preferences?")
@@ -101,6 +116,24 @@ public class Mem0LongTermMemory implements LongTermMemory {
     private final String userId;
     private final String runId;
 
+    /**
+     * Custom metadata to be stored with memories and used for filtering during retrieval.
+     *
+     * <p>This metadata is:
+     * <ul>
+     *   <li>Included in the {@code metadata} field when recording memories via {@link #record(List)}</li>
+     *   <li>Added to the {@code filters} field when retrieving memories via {@link #retrieve(Msg)}</li>
+     * </ul>
+     *
+     * <p>Use cases include:
+     * <ul>
+     *   <li>Tagging memories with custom labels (e.g., "category": "travel")</li>
+     *   <li>Filtering memories by project, tenant, or other business attributes</li>
+     *   <li>Storing additional context that should be associated with all memories</li>
+     * </ul>
+     */
+    private final Map<String, Object> metadata;
+
     /**
      * Private constructor - use Builder instead.
      */
@@ -110,6 +143,7 @@ private Mem0LongTermMemory(Builder builder) {
         this.agentId = builder.agentName;
         this.userId = builder.userId;
         this.runId = builder.runName;
+        this.metadata = builder.metadata;
 
         // Validate that at least one identifier is provided
         if (agentId == null && userId == null && runId == null) {
@@ -161,6 +195,7 @@ public Mono<Void> record(List<Msg> msgs) {
                         .agentId(agentId)
                         .userId(userId)
                         .runId(runId)
+                        .metadata(metadata)
                         .infer(true)
                         .build();
 
@@ -191,17 +226,30 @@ private Mem0Message convertToMem0Message(Msg msg) {
     /**
      * Builds a search request with the given query.
      *
+     * <p>The search request includes:
+     * <ul>
+     *   <li>Standard filters: userId, agentId, runId (added by builder convenience methods)</li>
+     *   <li>Custom metadata filters: merged into filters via builder.getFilters()</li>
+     * </ul>
+     *
      * @param query The search query string
      * @return A configured Mem0SearchRequest for v2 API
      */
     private Mem0SearchRequest buildSearchRequest(String query) {
-        return Mem0SearchRequest.builder()
-                .query(query)
-                .userId(userId)
-                .agentId(agentId)
-                .runId(runId)
-                .topK(5)
-                .build();
+        Mem0SearchRequest.Builder builder =
+                Mem0SearchRequest.builder()
+                        .query(query)
+                        .userId(userId)
+                        .agentId(agentId)
+                        .runId(runId)
+                        .topK(5);
+
+        // Merge custom metadata into filters if present
+        if (metadata != null && !metadata.isEmpty()) {
+            builder.getFilters().putAll(metadata);
+        }
+
+        return builder.build();
     }
 
     /**
@@ -262,6 +310,7 @@ public static class Builder {
         private String apiKey;
         private Mem0ApiType apiType;
         private java.time.Duration timeout = java.time.Duration.ofSeconds(60);
+        private Map<String, Object> metadata;
 
         /**
          * Sets the agent name identifier.
@@ -341,6 +390,37 @@ public Builder apiType(Mem0ApiType apiType) {
             return this;
         }
 
+        /**
+         * Sets custom metadata to be stored with memories and used for filtering.
+         *
+         * <p>This metadata will be:
+         * <ul>
+         *   <li>Included in the request body when recording memories</li>
+         *   <li>Added to the filters when searching/retrieving memories</li>
+         * </ul>
+         *
+         * <p>Example usage:
+         * <pre>{@code
+         * Map<String, Object> metadata = new HashMap<>();
+         * metadata.put("category", "travel");
+         * metadata.put("priority", "high");
+         *
+         * Mem0LongTermMemory memory = Mem0LongTermMemory.builder()
+         *     .agentName("Assistant")
+         *     .userId("user_123")
+         *     .apiBaseUrl("http://localhost:8000")
+         *     .metadata(metadata)
+         *     .build();
+         * }</pre>
+         *
+         * @param metadata Custom metadata map (can be null)
+         * @return This builder
+         */
+        public Builder metadata(Map<String, Object> metadata) {
+            this.metadata = metadata;
+            return this;
+        }
+
         /**
          * Builds the Mem0LongTermMemory instance.
          *

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

@@ -230,6 +230,10 @@ public Builder filters(Map<String, Object> filters) {
             return this;
         }
 
+        public Map<String, Object> getFilters() {
+            return this.filters;
+        }
+
         /**
          * Convenience method to add agent_id to filters.
          *