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

# Overview

> [!NOTE]
>
> **Recommended: use [DistributedStore](https://java.agentscope.io/dev/en/integration/distributed/index.md) for one-line setup** — it covers AgentStateStore, BaseStore, SandboxSnapshotSpec, and SandboxExecutionGuard together. Read on if you only need to configure AgentStateStore individually.

`io.agentscope.core.state.AgentStateStore` is the interface AgentScope uses to persist agent state — Memory, Workspace, Plan, and other components are serialized as `State` objects and stored via `AgentStateStore`, enabling restart recovery and cross-node sharing.

State is addressed by `(userId, sessionId)`:

* `sessionId` — required, non-blank, identifies a session.
* `userId` — optional. `null` means anonymous / single-tenant (CLI, tests, etc.).

## AgentStateStore and the Thread journal

This page covers `AgentStateStore`. With journaling enabled, `HarnessAgent` recovers from its
`ThreadJournalStore`; changing only `stateStore` does not move or share journal history. The main
Thread also reads state written by AgentScope 2.0 and mirrors each committed checkpoint back to the
2.0 `agent_state` slot for rollback compatibility. Named Threads use independent state entries.
A file-capable BaseStore does not necessarily provide the journal CAS and fencing contract. See
[Thread journals and recovery](https://java.agentscope.io/dev/en/docs/harness/session-log.md).

## Available Implementations

| Implementation | Module | When to use |
| - | - | - |
| `InMemoryAgentStateStore` | `agentscope-core` | Unit tests |
| `JsonFileAgentStateStore` | `agentscope-core` | Single-node dev (**HarnessAgent default**) |
| `RedisAgentStateStore` | `agentscope-extensions-redis` | [Multi-replica production default](https://java.agentscope.io/dev/en/integration/distributed/redis.md) |
| `JdbcAgentStateStore` | `agentscope-extensions-jdbc` | [Existing database infrastructure](https://java.agentscope.io/dev/en/integration/distributed/jdbc.md) |
| `OssAgentStateStore` | `agentscope-extensions-oss` | [Alibaba Cloud ecosystem](https://java.agentscope.io/dev/en/integration/distributed/oss.md) |

## Standalone Configuration

```java theme={null}
ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .model(model)
    .stateStore(stateStore)   // any AgentStateStore implementation
    .build();
```

For detailed usage and code examples, see each store's documentation:

* [Redis](https://java.agentscope.io/dev/en/integration/distributed/redis.md#1-redisagentstatestore)
* [JDBC](https://java.agentscope.io/dev/en/integration/distributed/jdbc.md#1-jdbcagentstatestore)
* [OSS](https://java.agentscope.io/dev/en/integration/distributed/oss.md#1-ossagentstatestore)


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