examples: MongoDB SessionStore reference adapter

[alexbevi]

A self-contained reference SessionStore implementation for MongoDB under examples/session_stores/mongodb_session_store.py, alongside the existing S3, Redis, and Postgres adapters. Imports types from the published claude_agent_sdk package and passes the full 14-contract conformance suite at src/claude_agent_sdk/testing/session_store_conformance.py.

Adapter	Backend client	Unit tests	Live tests
mongodb_session_store.py	pymongo (>=4.13)	constructor only	env-gated SESSION_STORE_MONGODB_URL

Storage model

Two collections share one database. Entries — one document per JSONL transcript entry, ordered by the server-assigned _id (ObjectId):

{ "_id": ObjectId, "project_key": str, "session_id": str,
  "subpath": str,           # "" sentinel for the main transcript
  "entry": <opaque JSON>, "mtime": int }     # epoch ms

Summaries — one document per main session, maintained incrementally inside append() via fold_session_summary:

{ "_id": {"project_key": str, "session_id": str},
  "mtime": int, "data": <opaque SDK-owned dict> }

create_schema() creates three indexes (idempotent). append() is a single insert_many plus an atomic summary upsert; load() is find().sort("_id", 1).

What's different from the other adapters

This adapter implements the optional list_session_summaries method (S3/Redis/Postgres skip it via Protocol-default detection). That gives list_sessions_from_store() its fast path — one batch read for all summaries plus a cheap list_sessions() to gap-fill — instead of the fallback's N per-session load() calls (bounded at 16 concurrent). For projects with many sessions or remote-backend latency, the README explains the tradeoff.

The summary read-fold-write inside append() is serialized with a per-session asyncio.Lock to satisfy the protocol's concurrency requirement.

Driver

Uses pymongo's stable async API (pymongo.AsyncMongoClient, introduced in pymongo 4.13). pymongo>=4.13 is added to the [examples] optional-dependency group; the test module importorskips so default CI is unaffected.

Conformance with proposed CONTRIBUTING.md (#1005)

This PR was sanity-checked against the developer workflow proposed in #1005 — the package passes every check that guide will enforce on src/ and tests/:

• ✅ ruff check src/ tests/ — clean (incl. ruff B023, which had flagged a closure-over-loop-variable bug in the concurrency test).
• ✅ ruff format --check src/ tests/ — clean (the test file is ruff format-stable).
• ✅ mypy src/ — clean (no SDK source touched).
• ✅ Conventional Commits — every commit on the branch uses one of the prefixes the guide enumerates (feat:, chore:, test:, docs:).

The adapter module under examples/ is outside the guide's required surface but is formatted to the same standard since it's reference code users copy-paste.

Running

cd claude-agent-sdk-python
pip install -e '.[dev,examples]'
pytest tests/test_example_mongodb_session_store.py            # skips without env

docker run -d -p 27017:27017 mongo:latest
SESSION_STORE_MONGODB_URL=mongodb://localhost:27017 \
    pytest tests/test_example_mongodb_session_store.py -v     # live conformance + adapter tests

CI / packaging impact: none

Nothing under examples/ is packaged or built by repo CI. The test module importorskips on pymongo and module-level skips on the env var, so default CI is unaffected if [examples] isn't installed. No workflow files added; no CHANGELOG entry (examples are reference code, not versioned, per RELEASING.md).

Verified locally against mongo:latest (mongod 8.2.5)

• 14-contract conformance harness — pass.
• _store_implements duck-type probe — pass.
• Constructor name validation (positional + dataclass) — pass.
• create_schema() idempotence — pass.
• options= constructor path equivalence — pass.
• Subpath-targeted delete() does NOT drop the summary sidecar — pass.
• Concurrent appends carrying disjoint summary fields both survive — pass (adversarially verified: 29/30 trials clobber without the lock).
• End-to-end TranscriptMirrorBatcher → MongoDB → materialize_resume_session round-trip — pass.

Total: 8 passed in 0.89s.

Test plan

• cd examples/session_stores && cat mongodb_session_store.py for review
• pip install -e '.[dev,examples]'
• ruff check src/ tests/ — clean
• ruff format --check src/ tests/ — clean
• mypy src/ — clean
• pytest tests/test_example_mongodb_session_store.py — skips cleanly without env
• docker run -d -p 27017:27017 mongo:latest then SESSION_STORE_MONGODB_URL=mongodb://localhost:27017 pytest tests/test_example_mongodb_session_store.py -v — 8 pass
• pytest tests/test_example_redis_session_store.py tests/test_example_s3_session_store.py — no regressions in sibling adapters

[alexbevi]

Note this is a follow up to anthropics/claude-agent-sdk-typescript#341