> ## Documentation Index
> Fetch the complete documentation index at: https://java.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 百炼记忆

`agentscope-extensions-memory-bailian` 接入阿里云百炼的长期记忆服务，提供云端托管、企业级的语义记忆能力，支持 rerank、judge、rewrite 等检索增强特性。

## 何时使用

* 已经在使用阿里云百炼平台，希望直接复用平台上的记忆库。
* 关注检索质量，想启用百炼提供的 rerank / judge / rewrite 流水线。
* 需要按 `userId` + `memoryLibraryId` + `projectId` 三个维度做记忆隔离。

## 添加依赖

```xml theme={null}
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-memory-bailian</artifactId>
    <version>${agentscope.version}</version>
</dependency>
```

## 快速上手

```java theme={null}
import io.agentscope.core.memory.bailian.BailianLongTermMemory;

try (BailianLongTermMemory memory = BailianLongTermMemory.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .userId("user_001")
        .memoryLibraryId("lib_xxxxx")
        .projectId("proj_xxxxx")
        .build()) {

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

    agent.call(new UserMessage("帮我每天 9 点提醒喝水")).block();
}
```

`BailianLongTermMemory` 实现了 `AutoCloseable`，建议用 try-with-resources，确保底层 HTTP 连接被释放。

## 检索增强开关

百炼记忆服务在召回基础上还支持三个流水线开关：

```java theme={null}
BailianLongTermMemory memory = BailianLongTermMemory.builder()
    .apiKey(apiKey)
    .userId("user_001")
    .memoryLibraryId("lib_xxxxx")
    .topK(20)
    .minScore(0.4)
    .enableRerank(true)   // 二次重排，更准但更慢
    .enableJudge(true)    // 让 LLM 判断结果是否真的相关
    .enableRewrite(true)  // 在写入时做改写、合并
    .build();
```

不需要的特性建议保持默认（关闭），可以减少调用延迟和费用。

## 消息过滤行为

百炼记忆只会写入用户和助手之间的"自然"对话：

* 仅写入 `MsgRole.USER` 与 `MsgRole.ASSISTANT` 消息。
* 含 `ToolUseBlock` 的助手消息（即工具调用请求）会被跳过。
* 含 `<compressed_history>` 标记的压缩历史消息也会被跳过，避免重复存储。

如果你希望让工具调用结果进入记忆，需要自己用更上层的逻辑写入，再调用 `record(...)`。

## Builder 配置参数

| 方法                             | 是否必填 | 默认                               | 说明                   |
| ------------------------------ | ---- | -------------------------------- | -------------------- |
| `apiKey(String)`               | ✅    | -                                | 百炼 DashScope API Key |
| `userId(String)`               | ✅    | -                                | 用户维度 ID              |
| `memoryLibraryId(String)`      | ❌    | -                                | 记忆库 ID               |
| `projectId(String)`            | ❌    | -                                | 项目 ID                |
| `profileSchema(String)`        | ❌    | -                                | 用户画像 schema ID       |
| `apiBaseUrl(String)`           | ❌    | `https://dashscope.aliyuncs.com` | 自定义网关时使用             |
| `topK(Integer)`                | ❌    | `10`                             | 检索返回条数上限             |
| `minScore(Double)`             | ❌    | `0.3`                            | 最低相似度阈值（0\~1）        |
| `enableRerank(Boolean)`        | ❌    | `false`                          | 是否启用 rerank          |
| `enableJudge(Boolean)`         | ❌    | `false`                          | 是否启用 LLM judge       |
| `enableRewrite(Boolean)`       | ❌    | `false`                          | 写入时是否启用 rewrite      |
| `metadata(Map)`                | ❌    | -                                | 写入时附带的自定义 metadata   |
| `httpTransport(HttpTransport)` | ❌    | 默认实现                             | 替换 HTTP 客户端          |