MemNetAI

中文

English

中文

English

Appearance

MemNet AI Java SDK ​

开发前准备 ​

准备开发环境 ​

Java SDK 运行环境需 JDK 1.8 及以上。下载地址参见Java Downloads | Oracle。如果本地环境已安装 JDK，可以在终端内执行 java -version 命令确认版本信息。

安装Java SDK ​

基于 Maven 安装 Java SDK，需要在项目的 pom.xml 文件中添加最新版本Maven坐标

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

调用服务端 API ​

本文介绍如何使用 MemNetAI Java SDK 构建客户端、构造 API 请求并成功调用服务端 API。

步骤一：构建客户端 (Client) ​

在使用 SDK 调用 MemNetAI 开放平台 API 之前，你需要在代码中创建一个 Client。Client 支持对应用鉴权凭证、服务地址、请求超时时间等基本信息进行配置。 配置选项说明

配置项配置方法是否必填描述
apiKeyapiKey(String)是应用的 API Key，用于鉴权。
baseUrlbaseUrl(String)否服务端 API 地址。默认为 https://api.memnetai.com。
timeouttimeout(long)否HTTP 请求超时时间（秒），默认为 200 秒。

构造示例

java
import com.memnetai.sdk.MemNetAiClient;

// 构建 MemNetAiClient 实例
MemNetAiClient client = MemNetAiClient.builder()
    .apiKey("YOUR_API_KEY")                 // [必填] 设置 API Key
    .baseUrl("https://api.memnetai.com")    // [可选] 设置服务端地址
    .timeout(60)                            // [可选] 设置超时时间为 60 秒
    .build();

注意：推荐使用单例模式管理 MemNetAiClient 实例，避免重复创建带来的资源消耗。

步骤二：构造 API 请求 (Request) ​

SDK 采用 Builder 模式 来构建请求对象，这种方式能显著提升代码的可读性，方便开发者灵活配置可选参数。

1. 记忆 (Memories) ​

用于将对话数据写入 AI 的长期记忆。这是构建个性化 AI 的基础。

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

OpenApiV1MemoriesRequest memoriesRequest = OpenApiV1MemoriesRequest.builder()
    // [必填] 记忆体名称 (不存在会自动创建)
    .memoryAgentName("多啦C梦")

    // [必填] 对话上下文列表
    .messages(Arrays.asList(
        OpenApiV1MemoriesRequest.Message.builder()
            .role("user")                    // 角色: "user" 或 "assistant"
            .character("小明")               // [可选] 多人场景下的说话人标识
            .content("我们下周去爬山怎么样？")
            .build(),
        OpenApiV1MemoriesRequest.Message.builder()
            .role("assistant")
            .content("好主意！需要准备什么装备吗？")
            .build()
    ))

    // [可选] 记忆体命名空间 (默认值: "default")
    .namespace("default")

    // [可选] 业务元数据，仅用于存储与当前记忆相关的简短数据
    .metadata("User_Session_1001")

    // [可选] 记忆摘要语言 (默认值: "zh-CN")
    .language("zh-CN")

    // [可选] 记忆摘要是否启用第三人称 (默认值: 0)
    // 0: 不启用 (第一人称 "我")
    // 1: 启用 (使用记忆体名称)
    .isThirdPerson(0)

    // [可选] 是否启用异步记忆 (默认值: 0)
    // 0: 同步 (等待处理完成)
    // 1: 异步 (立即返回任务ID)
    .asyncMode(0) 
    .build();

2. 回忆 (Recall) ​

根据用户的查询语句，从长期记忆中检索相关信息。支持设置回忆深度和关联思考策略。

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

OpenApiV1RecallRequest recallRequest = OpenApiV1RecallRequest.builder()
    // [必填] 记忆体名称
    .memoryAgentName("多啦C梦")

    // [必填] 查询语句/对话段落
    .query("我们计划去哪里？")

    // [可选] 记忆体命名空间 (默认值: "default")
    .namespace("default")

    // [可选] 当前对话角色名
    .character("小明")

    // [可选] 回忆深度 0.0-1.0 (默认值: 1.0)
    // 值越大召回范围越宽泛，值越小越精准
    .recallDeep(1.0)

    // [可选] 是否使用联想性思考 (默认值: true)
    .isUsingAssociativeThinking(true)

    // [可选] 是否使用常识库 (默认值: true)
    .isUsingCommonSenseDatabase(true)

    // [可选] 是否使用全局常识库 (默认值: true)
    .isUsingGlobalCommonSenseDatabase(true)

    // [可选] 是否使用记忆体常识库 (默认值: true)
    .isUsingMemoryAgentCommonSenseDatabase(true)

    // [可选] 指定常识记忆库 ID 列表
    .commonSenseDatabaseIdList(Collections.singletonList(BigInteger.valueOf(122)))

    // [可选] 是否使用非有效性记忆关联的新记忆 (默认为 null/false)
    .isIncludeLinkedNewMemoriesFromInvalid(false)

    // [可选] 是否返回记忆详细信息 (默认值: false)
    .isReturningDetailedMemoryInfo(false)
    .build();

3. 自主思考 (Think) ​

触发 AI 对特定主题进行深度的逻辑推理或归纳，通常用于处理复杂的任务或生成新的见解。

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

OpenApiV1ThinkRequest thinkRequest = OpenApiV1ThinkRequest.builder()
    // [必填] 记忆体名称
    .memoryAgentName("多啦C梦")

    // [可选] 记忆体命名空间 (默认值: "default")
    .namespace("default")

    // [可选] 思考主题
    .subject("关于户外运动的安全注意事项")

    // [可选] 是否启用异步调用 (默认值: true)
    .asyncMode(true)

    // [可选] 是否为自动调用 (默认值: false)
    .isAuto(false)
    .build();

4. 自动做梦 (Dream) ​

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

OpenApiV1DreamRequest dreamRequest = OpenApiV1DreamRequest.builder()
    // [必填] 记忆体名称
    .memoryAgentName("多啦C梦")

    // [可选] 记忆体命名空间 (默认值: "default")
    .namespace("default")

    // [可选] 梦境/整理主题
    .subject("整理最近关于旅行的记忆")

    // [可选] 是否启用异步调用 (默认值: true)
    .asyncMode(true)

    // [可选] 是否为自动调用 (默认值: false)
    .isAuto(false)
    .build();

5. 添加常识 (Common Sense) ​

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

OpenApiV1CommonSenseRequest commonSenseRequest = OpenApiV1CommonSenseRequest.builder()
    // [必填] 常识库 ID 
    .commonSenseDatabaseId(BigInteger.valueOf(122))

    // [必填] 待存储的常识记忆文本 
    .commonSenseText("爬山需要准备登山杖、水和急救包。")

    // [可选] 是否启用异步调用 (默认值: true)
    .asyncMode(true)
    .build();

步骤三：调用 API 与处理响应 ​

构建好 Client 和 Request 后，可以通过 Client 实例下的 v1() 方法访问 V1 版本服务，并调用对应的业务方法。

记忆调用示例：

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

// 发起调用
try {
    OpenApiV1MemoriesResponse response = client.v1().memories(request);
} catch (Exception e) {
    // 处理异常
    System.err.println("调用失败: " + e.getMessage());
    e.printStackTrace();
}

步骤四：异步任务管理 (Task Service) ​

MemNetAI SDK 针对耗时较长的业务（如记忆写入、深度思考）提供了专门的任务管理系统，您需要通过 Task Service 追踪任务结果。 记忆，做梦，思考，添加常识这四个接口有任务管理系统 特别注意：获取的任务列表不是当前apikey的所有任务，而是apikey持有者的所有apikey的所有任务 不同类型的任务支持的管理能力不同，请特别注意进度查询接口的适用范围：

任务接口方法名Memories / Common SenseThink / Dream说明
获取人物详情getTaskInfo(taskId)支持支持获取任务的最终执行结果或当前详细状态。
获取任务进度getTaskProgress(taskId)支持不支持Think 和 Dream 任务不支持百分比进度查询，调用会报错或无响应。
获取任务列表getAllTaskList()支持支持获取当前业务模块下的历史任务列表。
删除任务deleteTask(taskId)支持支持清理不再需要的任务记录。

记忆任务代码示例

java
String taskId = client.v1().memories(memoriesRequest).getTaskId();
// 获取任务详情
MemoryTaskInfoResponse info = client.thinkTask().getTaskInfo(taskId);
// 获取任务进度
TaskProgressResponse progress = client.memoriesTask().getTaskProgress(taskId);
// 获取所有记忆任务的列表
TaskListResponse memoriesTasks = client.memoriesTask().getAllTaskList();
// 删除任务
client.thinkTask().deleteTask(taskId);