MongoAgentStateStore

MongoDB-backed implementation of AgentStateStore.

Each session is stored as a single MongoDB document with a compound _id of {user, session} to prevent cross-tenant key collisions. State keys are stored inside a states sub-document (via dot notation, e.g. states.foo), keeping them isolated from reserved top-level fields such as _id, user_id, session_id, and _updated_at. Per-key versions live in a versions sub-document and list-content hashes in a hashes sub-document.

Supports optimistic concurrency via the versions.<key> field. List state uses ListHashUtil for change detection to avoid unnecessary full rewrites. The list element count is obtained server-side via $size aggregation to avoid transferring the full array just to call .size().

Usage:

`MongoAgentStateStore store = MongoAgentStateStore.builder()
.connectionString("mongodb://localhost:27017")
.databaseName("agentscope")
.collectionName("sessions")
.build();
`

Key constraints

• State key character set: keys passed to #save / #get must match ^[a-zA-Z_][a-zA-Z0-9_]*$ — no dots, dollar signs, or Unicode. Values inside Map<String, Object> fields are automatically escaped by MongoKeyEscaper and have no character restrictions.

• Snapshots use GridFS: sandbox workspace snapshots are stored in GridFS (up to 16 GB per file), not as single BSON documents. The legacy 16 MB BSON limit no longer applies.

• Session TTL is off by default: sessions are retained indefinitely, aligned with Postgres/JDBC/Redis. To enable automatic expiry, pass MongoAgentStateStore.builder().ttlDays(n) with a positive integer. The TTL index is sparse — only documents with a non-null _updated_at field expire.