AgentStateStore

Persistent storage interface for AgentScope agent state.

An AgentStateStore provides save / load / delete / list operations for State objects keyed by a (userId, sessionId) pair, allowing agents, memories, toolkits, and other stateful components to be persisted and restored across application runs or user interactions.

Slot addressing is intentionally simple:

• sessionId — non-null, non-blank; identifies a conversation / session.

• userId — nullable. null represents an anonymous / single-tenant caller (CLI usage, tests). Implementations group all anonymous sessions under a single namespace.

Implementations decide how to combine the pair into a storage key (filesystem path, Redis key prefix, SQL column). Callers MUST NOT concatenate them manually before calling.

Example usage:

`AgentStateStore store = new JsonFileAgentStateStore(Path.of("state"));

// Save state for an anonymous session
store.save(null, "session-1", "agent_state", state);

// Save state scoped to a user
store.save("alice", "session-1", "agent_state", state);

// Load state
Optional<AgentState> loaded =
store.get("alice", "session-1", "agent_state", AgentState.class);

// List all sessions owned by a user (null lists anonymous sessions)
Set<String> mySessions = store.listSessionIds("alice");
`