> ## 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.

# Bailian Memory

`agentscope-extensions-memory-bailian` integrates with Alibaba Cloud Bailian's long-term memory service. It is fully managed and supports advanced retrieval features such as rerank, judge, and rewrite.

## When to use

* You are already on Alibaba Cloud Bailian and want to reuse memory libraries from the platform.
* You care about retrieval quality and want to use Bailian's rerank / judge / rewrite pipeline.
* You need three-level isolation via `userId` + `memoryLibraryId` + `projectId`.

## Add the dependency

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

## Quickstart

```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("Remind me to drink water at 9am every day")).block();
}
```

`BailianLongTermMemory` implements `AutoCloseable` — try-with-resources is recommended so the underlying HTTP connections get released.

## Retrieval feature switches

On top of basic recall, Bailian supports three pipeline switches:

```java theme={null}
BailianLongTermMemory memory = BailianLongTermMemory.builder()
    .apiKey(apiKey)
    .userId("user_001")
    .memoryLibraryId("lib_xxxxx")
    .topK(20)
    .minScore(0.4)
    .enableRerank(true)   // Re-rank results, more accurate but slower
    .enableJudge(true)    // Let an LLM judge whether results are actually relevant
    .enableRewrite(true)  // Rewrite/merge memories on write
    .build();
```

Leave them off by default unless you need them — they add latency and cost.

## Message filtering

Bailian memory only stores natural user/assistant exchanges:

* Only `MsgRole.USER` and `MsgRole.ASSISTANT` messages are written.
* Assistant messages containing `ToolUseBlock` (tool-call requests) are skipped.
* Messages with the `<compressed_history>` marker are skipped to avoid storing duplicated compressed history.

If you need tool results to enter memory, write them yourself via higher-level logic before calling `record(...)`.

## Builder reference

| Method | Required | Default | Notes |
| - | - | - | - |
| `apiKey(String)` | ✅ | - | Bailian DashScope API key |
| `userId(String)` | ✅ | - | User-level ID |
| `memoryLibraryId(String)` | ❌ | - | Memory library ID |
| `projectId(String)` | ❌ | - | Project ID |
| `profileSchema(String)` | ❌ | - | User profile schema ID |
| `apiBaseUrl(String)` | ❌ | `https://dashscope.aliyuncs.com` | Override for custom gateways |
| `topK(Integer)` | ❌ | `10` | Maximum number of retrieved items |
| `minScore(Double)` | ❌ | `0.3` | Minimum similarity threshold (0–1) |
| `enableRerank(Boolean)` | ❌ | `false` | Enable rerank |
| `enableJudge(Boolean)` | ❌ | `false` | Enable LLM judge |
| `enableRewrite(Boolean)` | ❌ | `false` | Enable rewrite on write |
| `metadata(Map)` | ❌ | - | Custom metadata stored with each memory |
| `httpTransport(HttpTransport)` | ❌ | default | Replace the HTTP client |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.