Java SDK Guide

Pre-Development Preparation

Prepare the Development Environment

The Java SDK requires JDK 1.8 or later. Refer to the download link: Java Downloads | Oracle. If JDK is already installed locally, run the command java -version in the terminal to verify the version.

Install the Java SDK

To install the Java SDK via Maven, add the latest Maven coordinates to your project's pom.xml file:

<dependency>
    <groupId>com.memnetai</groupId>
    <artifactId>memnetai-java-sdk</artifactId>
    <version>1.0.3</version>
</dependency>

Call the Server API

This document describes how to use the MemNetAI Java SDK to construct a client, build API requests, and successfully call the server API.

Step 1: Build a Client

Before calling the MemNetAI Open Platform API with the SDK, you need to create a Client instance in your code. The Client supports configuring basic information such as application authentication credentials, service address, and request timeout.

Configuration Item	Configuration Method	Required	Description
apiKey	apiKey(String)	Yes	The application's API Key for authentication.
baseUrl	baseUrl(String)	No	The server API address. Defaults to https://api.memnetai.com.
timeout	timeout(long)	No	HTTP request timeout duration (in seconds). Defaults to 200 seconds.

Construction Example

import com.memnetai.sdk.MemNetAiClient;

// Build a MemNetAiClient instance
MemNetAiClient client = MemNetAiClient.builder()
    .apiKey("YOUR_API_KEY")                 // [Required] Set the API Key
    .baseUrl("https://api.memnetai.com")    // [Optional] Set the server address
    .timeout(60)                            // [Optional] Set timeout to 60 seconds
    .build();

Note: It is recommended to manage the MemNetAiClient instance using the singleton pattern to avoid resource consumption caused by repeated instantiation.

Step 2: Construct an API Request

The SDK uses the Builder pattern to construct request objects, which significantly improves code readability and allows developers to flexibly configure optional parameters.

1. Memories

Used to write conversation data into the AI's long-term memory. This is the foundation for building a personalized AI.

import com.memnetai.sdk.model.request.OpenApiV1MemoriesRequest;
import java.util.Arrays;

OpenApiV1MemoriesRequest memoriesRequest = OpenApiV1MemoriesRequest.builder()
    // [Required] Memory agent name (automatically created if it does not exist)
    .memoryAgentName("Doraemon C")

    // [Required] List of conversation contexts
    .messages(Arrays.asList(
        OpenApiV1MemoriesRequest.Message.builder()
            .role("user")                    // Role: "user" or "assistant"
            .character("Xiao Ming")          // [Optional] Speaker identifier in multi-person scenarios
            .content("Shall we go hiking next week?")
            .build(),
        OpenApiV1MemoriesRequest.Message.builder()
            .role("assistant")
            .content("Great idea! Do we need to prepare any equipment?")
            .build()
    ))

    // [Optional] Memory namespace (default: "default")
    .namespace("default")

    // [Optional] Business metadata, used only for storing short data related to the current memory
    .metadata("User_Session_1001")

    // [Optional] Language for memory summarization (default: "zh-CN")
    .language("zh-CN")

    // [Optional] Whether to enable third-person perspective for memory summarization (default: 0)
    // 0: Disabled (first-person "I")
    // 1: Enabled (uses the memory agent name)
    .isThirdPerson(0)

    // [Optional] Whether to enable asynchronous memory processing (default: 0)
    // 0: Synchronous (waits for processing completion)
    // 1: Asynchronous (returns task ID immediately)
    .asyncMode(0)
    .build();

2. Recall

Retrieves relevant information from long-term memory based on the user's query. Supports setting recall depth and associative thinking strategies.

import com.memnetai.sdk.model.request.OpenApiV1RecallRequest;
import java.util.Collections;

OpenApiV1RecallRequest recallRequest = OpenApiV1RecallRequest.builder()
    // [Required] Memory agent name
    .memoryAgentName("Doraemon C")

    // [Required] Query statement/conversation paragraph
    .query("Where do we plan to go?")

    // [Optional] Memory namespace (default: "default")
    .namespace("default")

    // [Optional] Current conversation character name
    .character("Xiao Ming")

    // [Optional] Recall depth (0.0-1.0, default: 1.0)
    // Higher values mean broader recall scope; lower values mean more precise results
    .recallDeep(1.0)

    // [Optional] Whether to use associative thinking (default: true)
    .isUsingAssociativeThinking(true)

    // [Optional] Whether to use the common sense database (default: true)
    .isUsingCommonSenseDatabase(true)

    // [Optional] Whether to use the global common sense database (default: true)
    .isUsingGlobalCommonSenseDatabase(true)

    // [Optional] Whether to use the memory agent-specific common sense database (default: true)
    .isUsingMemoryAgentCommonSenseDatabase(true)

    // [Optional] Specify a list of common sense database IDs
    .commonSenseDatabaseIdList(Collections.singletonList(BigInteger.valueOf(122)))

    // [Optional] Whether to include linked new memories from invalid ones (default: null/false)
    .isIncludeLinkedNewMemoriesFromInvalid(false)

    // [Optional] Whether to return detailed memory information (default: false)
    .isReturningDetailedMemoryInfo(false)
    .build();

3. Think

Triggers the AI to perform in-depth logical reasoning or induction on a specific topic, usually used for handling complex tasks or generating new insights.

import com.memnetai.sdk.model.request.OpenApiV1ThinkRequest;

OpenApiV1ThinkRequest thinkRequest = OpenApiV1ThinkRequest.builder()
    // [Required] Memory agent name
    .memoryAgentName("Doraemon C")

    // [Optional] Memory namespace (default: "default")
    .namespace("default")

    // [Optional] Thinking topic
    .subject("Safety Precautions for Outdoor Sports")

    // [Optional] Whether to enable asynchronous invocation (default: true)
    .asyncMode(true)

    // [Optional] Whether it is an automatic invocation (default: false)
    .isAuto(false)
    .build();

4. Dream

import com.memnetai.sdk.model.request.OpenApiV1DreamRequest;

OpenApiV1DreamRequest dreamRequest = OpenApiV1DreamRequest.builder()
    // [Required] Memory agent name
    .memoryAgentName("Doraemon C")

    // [Optional] Memory namespace (default: "default")
    .namespace("default")

    // [Optional] Dream/organization topic
    .subject("Organize Recent Memories About Travel")

    // [Optional] Whether to enable asynchronous invocation (default: true)
    .asyncMode(true)

    // [Optional] Whether it is an automatic invocation (default: false)
    .isAuto(false)
    .build();

5. Add Common Sense

import com.memnetai.sdk.model.request.OpenApiV1CommonSenseRequest;
import java.math.BigInteger;

OpenApiV1CommonSenseRequest commonSenseRequest = OpenApiV1CommonSenseRequest.builder()
    // [Required] Common sense database ID
    .commonSenseDatabaseId(BigInteger.valueOf(122))

    // [Required] Text of the common sense memory to be stored
    .commonSenseText("Hiking requires trekking poles, water, and a first-aid kit.")

    // [Optional] Whether to enable asynchronous invocation (default: true)
    .asyncMode(true)
    .build();

Step 3: Call the API and Process the Response

After building the Client and Request, you can access the V1 version of the service via the v1() method of the Client instance and call the corresponding business methods.

Memories Call Example:

import com.memnetai.sdk.model.response.OpenApiV1MemoriesResponse;

// Initiate the call
try {
    OpenApiV1MemoriesResponse response = client.v1().memories(request);
} catch (Exception e) {
    // Handle exceptions
    System.err.println("Call failed: " + e.getMessage());
    e.printStackTrace();
}

Step 4: Asynchronous Task Management (Task Service)

The MemNetAI SDK provides a dedicated task management system for time-consuming operations (such as memory writing and in-depth thinking). You need to track task results through the Task Service.

The four interfaces (Memories, Dream, Think, Add Common Sense) support the task management system.

Important Note: The retrieved task list includes all tasks of all API Keys owned by the API Key holder, not just tasks of the current API Key.

Different types of tasks support different management capabilities. Please pay special attention to the scope of application of the progress query interface:

Task Interface	Method Name	Memories / Common Sense	Think / Dream	Description
Get Task Details	getTaskInfo(taskId)	Supported	Supported	Get the final execution result or current detailed status of the task.
Get Task Progress	getTaskProgress(taskId)	Supported	Not Supported	Think and Dream tasks do not support percentage progress queries; calling this method will result in an error or no response.
Get Task List	getAllTaskList()	Supported	Supported	Get the historical task list under the current business module.
Delete Task	deleteTask(taskId)	Supported	Supported	Clean up task records that are no longer needed.

Memories Task Code Example

String taskId = client.v1().memories(memoriesRequest).getTaskId();
// Get task details
MemoryTaskInfoResponse info = client.thinkTask().getTaskInfo(taskId);
// Get task progress
TaskProgressResponse progress = client.memoriesTask().getTaskProgress(taskId);
// Get the list of all memory tasks
TaskListResponse memoriesTasks = client.memoriesTask().getAllTaskList();
// Delete the task
client.thinkTask().deleteTask(taskId);