记忆管理

概述

记忆负责管理 AgentScope 中智能体的对话历史和上下文。AgentScope 提供两种类型的记忆：

短期记忆 (Short-term Memory)：存储当前会话的对话历史，需要结合 Session 进行持久化和恢复
长期记忆 (Long-term Memory)：存储跨会话的用户偏好和知识，依赖外部记忆组件（如 Mem0、ReMe）自动持久化

记忆架构

在 ReActAgent 中，短期记忆与长期记忆协同工作：

┌──────────────┐    ┌──────────────┐    ┌──────────┐    ┌──────────────┐    ┌──────────────┐
│   用户输入    │───▶│   短期记忆     │───▶│   LLM    │───▶│   短期记忆    │───▶│   回复用户     │
└──────────────┘    │   (Memory)   │    │  (推理)  │     │   (Memory)   │    └──────────────┘
                    └───────┬──────┘    └──────────┘    └───────┬──────┘
                            │                                   │
                            │ 召回记忆                          │ 异步存入
                            ▼                                   ▼
                    ┌───────────────────────────────────────────────────┐
                    │              长期记忆 (独立组件)                     │
                    └───────────────────────────────────────────────────┘

分工说明：

短期记忆：存储当前会话消息，提供给 LLM 作为上下文，支持推理循环
长期记忆（独立组件）：
- 内部集成 LLM（记忆提取/总结）和向量数据库（存储/检索）
- 召回：对话开始时，召回相关记忆注入短期记忆
- 存储：回复用户后，异步存入长期记忆进行提取和持久化

Memory 接口

所有短期记忆实现都扩展 Memory 接口：

public interface Memory extends StateModule {
    void addMessage(Msg message);
    List<Msg> getMessages();
    void deleteMessage(int index);
    void clear();
}

Memory 继承自 StateModule，支持状态序列化和反序列化，可结合 SessionManager 实现持久化。

短期记忆 (Short-term Memory)

InMemoryMemory

默认的短期记忆实现，在内存中存储消息。特点：

简单的内存存储
没有上下文管理能力，消息会无限增长
适用于简单短对话场景

使用示例：

import io.agentscope.core.ReActAgent;
import io.agentscope.core.memory.InMemoryMemory;

ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .memory(new InMemoryMemory())
        .build();

// 消息自动存储
agent.call(msg1).block();
agent.call(msg2).block();

// 访问历史
List<Msg> history = agent.getMemory().getMessages();
System.out.println("消息总数: " + history.size());

短期记忆持久化

短期记忆需要结合 SessionManager 实现持久化，以支持重启恢复会话。

import io.agentscope.core.session.JsonSession;
import io.agentscope.core.session.SessionManager;

// 创建 Agent 和 Memory
InMemoryMemory memory = new InMemoryMemory();
ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .memory(memory)
        .build();

// 创建 SessionManager，注册需要持久化的组件
SessionManager sessionManager = SessionManager.forSessionId(sessionId)
        .withSession(new JsonSession(sessionPath))
        .addComponent(agent)
        .addComponent(memory);

// 加载已有会话（如果存在）
sessionManager.loadIfExists();

// ... 对话交互 ...

// 保存会话
sessionManager.saveSession();

完整示例：agentscope-examples/documentation/quickstart/src/main/java/io/agentscope/examples/quickstart/SessionExample.java

长期记忆 (Long-term Memory)

LongTermMemory 接口

长期记忆用于存储和召回跨会话的用户偏好和知识：

public interface LongTermMemory {
    // 记录消息到长期记忆（框架在 Agent 回复后自动调用）
    Mono<Void> record(List<Msg> msgs);
    
    // 根据输入消息检索相关记忆（框架在推理前自动调用）
    Mono<String> retrieve(Msg msg);
}

持久化说明：长期记忆依赖外部记忆组件（如 Mem0、ReMe 服务），数据自动持久化到外部存储，无需手动管理。 LongTermMemoryMode：在 ReActAgent 中配置长期记忆的工作模式：

STATIC_CONTROL：静态控制模式，框架自动在推理前召回记忆、回复后记录记忆
AGENT_CONTROL：Agent 控制模式，通过工具让 Agent 自主决定何时记录和召回
BOTH：同时启用两种模式

Mem0LongTermMemory

基于 Mem0 的长期记忆实现。

背景说明

Mem0 的自建部署和 Platform 提供的 OpenAPI 接口不一致（端点路径和响应格式不同）。Mem0LongTermMemory 内部提供了兼容适配机制，通过 apiType 参数指定 Mem0 部署类型，自动选择正确的 API 端点和响应解析方式。

使用示例

Platform Mem0（默认）：

import io.agentscope.core.ReActAgent;
import io.agentscope.core.memory.LongTermMemoryMode;
import io.agentscope.core.memory.mem0.Mem0LongTermMemory;

// 使用 Platform Mem0（默认，无需指定 apiType）
Mem0LongTermMemory longTermMemory = Mem0LongTermMemory.builder()
        .agentName("SmartAssistant")
        .userId("user-001")
        .apiBaseUrl("https://api.mem0.ai")
        .apiKey(System.getenv("MEM0_API_KEY"))
        .build();

ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .longTermMemory(longTermMemory)
        .longTermMemoryMode(LongTermMemoryMode.STATIC_CONTROL)
        .build();

自建 Mem0：

import io.agentscope.core.ReActAgent;
import io.agentscope.core.memory.LongTermMemoryMode;
import io.agentscope.core.memory.mem0.Mem0ApiType;
import io.agentscope.core.memory.mem0.Mem0LongTermMemory;

// 使用自建 Mem0，需要指定 apiType 为 Mem0ApiType.SELF_HOSTED
Mem0LongTermMemory selfHostedMemory = Mem0LongTermMemory.builder()
        .agentName("SmartAssistant")
        .userId("user-001")
        .apiBaseUrl("http://localhost:8000")  // 自建 Mem0 服务地址
        .apiKey(System.getenv("MEM0_API_KEY"))  // 可选，取决于自建服务配置
        .apiType(Mem0ApiType.SELF_HOSTED)  // 指定为自建 Mem0
        .build();

ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .longTermMemory(selfHostedMemory)
        .longTermMemoryMode(LongTermMemoryMode.STATIC_CONTROL)
        .build();

配置说明：

apiType：可选参数，指定 Mem0 部署类型
- Mem0ApiType.PLATFORM（默认）：使用 Platform Mem0 的 API 端点
- Mem0ApiType.SELF_HOSTED：使用自建 Mem0 的 API 端点
apiBaseUrl：Mem0 服务的基地址
- Platform Mem0：通常为 https://api.mem0.ai
- 自建 Mem0：通常为 http://localhost:8000 或您的服务器地址
apiKey：API 密钥（可选）
- Platform Mem0：必需
- 自建 Mem0：取决于您的服务配置，可能不需要

完整示例：agentscope-examples/documentation/advanced/src/main/java/io/agentscope/examples/advanced/Mem0Example.java 运行示例：

# Platform Mem0（默认）
export MEM0_API_KEY=your_api_key
export MEM0_API_BASE_URL=https://api.mem0.ai  # 可选，默认为此值
cd agentscope-examples/documentation/advanced
mvn exec:java -Dexec.mainClass="io.agentscope.examples.advanced.Mem0Example"

# 自建 Mem0
export MEM0_API_KEY=your_api_key  # 可选，取决于服务配置
export MEM0_API_BASE_URL=http://localhost:8000
export MEM0_API_TYPE=self-hosted
cd agentscope-examples/documentation/advanced
mvn exec:java -Dexec.mainClass="io.agentscope.examples.advanced.Mem0Example"

ReMeLongTermMemory

基于 ReMe 的长期记忆实现。 使用示例：

import io.agentscope.core.ReActAgent;
import io.agentscope.core.memory.LongTermMemoryMode;
import io.agentscope.core.memory.reme.ReMeLongTermMemory;

ReMeLongTermMemory longTermMemory = ReMeLongTermMemory.builder()
        .userId("example_user")
        .apiBaseUrl("http://localhost:8002")
        .build();

ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .longTermMemory(longTermMemory)
        .longTermMemoryMode(LongTermMemoryMode.STATIC_CONTROL)
        .build();

完整示例：agentscope-examples/documentation/advanced/src/main/java/io/agentscope/examples/advanced/ReMeExample.java 运行示例：

# 需要配置 REME_API_BASE_URL 环境变量（可选，默认为 http://localhost:8002）
cd examples/advanced
mvn exec:java -Dexec.mainClass="io.agentscope.examples.advanced.ReMeExample"

BailianLongTermMemory

基于百炼记忆库的长期记忆实现。 使用示例：

import io.agentscope.core.ReActAgent;
import io.agentscope.core.memory.LongTermMemoryMode;
import io.agentscope.core.memory.bailian.BailianLongTermMemory;

BailianLongTermMemory longTermMemory = BailianLongTermMemory.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .userId("your_user_id")
        .memoryLibraryId("your_memory_library_id")
        .projectId("your_project_id")
        .profileSchema("your_profile_schema")
        .metadata(Map.of("location_name", "Beijing"))
        .build();

ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .longTermMemory(longTermMemory)
        .longTermMemoryMode(LongTermMemoryMode.STATIC_CONTROL)
        .build();

配置说明：

apiKey：阿里云 DashScope API 密钥（必需）
userId：用户 ID（必需）
memoryLibraryId：百炼记忆库 ID（可选）
projectId：百炼记忆片段规则 ID（可选）
profileSchema：百炼用户画像规则 ID（可选）

完整示例：agentscope-examples/documentation/advanced/src/main/java/io/agentscope/examples/advanced/BailianMemoryExample.java 运行示例：

export DASHSCOPE_API_KEY=sk-xxxx
export BAILIAN_USER_ID=your_user_id
export BAILIAN_MEMORY_LIBRARY_ID=your_library_id
export BAILIAN_PROJECT_ID=your_project_id
export BAILIAN_PROFILE_SCHEMA=your_profile_schema

cd agentscope-examples/documentation/advanced
mvn exec:java -Dexec.mainClass="io.agentscope.examples.advanced.BailianMemoryExample"

快速开始

功能指南

多智能体

Harness

概述

记忆架构

Memory 接口

短期记忆 (Short-term Memory)

InMemoryMemory

短期记忆持久化

长期记忆 (Long-term Memory)

LongTermMemory 接口

Mem0LongTermMemory

背景说明

使用示例

ReMeLongTermMemory

BailianLongTermMemory

相关文档

​概述

​记忆架构

​Memory 接口

​短期记忆 (Short-term Memory)

​InMemoryMemory

​短期记忆持久化

​长期记忆 (Long-term Memory)

​LongTermMemory 接口

​Mem0LongTermMemory

​背景说明

​使用示例

​ReMeLongTermMemory

​BailianLongTermMemory

​相关文档

概述

记忆架构

Memory 接口

短期记忆 (Short-term Memory)

InMemoryMemory

短期记忆持久化

长期记忆 (Long-term Memory)

LongTermMemory 接口

Mem0LongTermMemory

背景说明

使用示例

ReMeLongTermMemory

BailianLongTermMemory

相关文档