examples: MongoDB SessionStore reference adapter

[alexbevi]

A self-contained reference SessionStore implementation for MongoDB under examples/session-stores/mongodb/, alongside the existing S3/Redis/Postgres adapters. Imports SessionStore, SessionKey, and SessionStoreEntry types from the published @anthropic-ai/claude-agent-sdk package and passes the 13-contract conformance suite at examples/session-stores/shared/conformance.ts.

Adapter	Backend client	Unit tests	Live tests
mongodb/	mongodb	constructor only	env-gated SESSION_STORE_MONGODB_URL

Storage model

One document per JSONL entry, ordering via the server-generated _id (ObjectId) — same property the Postgres adapter exploits with BIGSERIAL.

{ _id, projectKey, sessionId, subpath: string|null, entry, createdAt }

ensureSchema() is idempotent and creates two compound indexes covering load()/delete()/listSubkeys() and listSessions() respectively. The adapter follows the Postgres pattern of live-only conformance: there is no in-process Mongo mock that faithfully exercises the aggregation pipeline and distinct.

Running

cd examples/session-stores/mongodb
npm install
npm test                                                              # constructor-only, no DB

docker run -d -p 27017:27017 mongo:latest
SESSION_STORE_MONGODB_URL=mongodb://localhost:27017 npm run test:live # live conformance
SESSION_STORE_MONGODB_URL=mongodb://localhost:27017 npm run demo      # query() + resume

CI / packaging impact: none

Nothing under examples/ is packaged, published, or built by repo CI; examples/.gitignore already excludes node_modules and lockfiles. No workflow files added. The umbrella examples/session-stores/README.md is updated to advertise the new adapter (table row, layout glob, MongoDB section, production checklist).

Verified locally

• bun run typecheck clean.
• No-DB unit tests: bun test test/MongoDBSessionStore.test.ts — 2/2 pass; live suite skips cleanly when env unset.
• Live conformance against docker run -d -p 27017:27017 mongo:latest: 15/15 pass (13 contract tests + ensureSchema is idempotent + listSessions mtime is epoch ms).
• End-to-end demo round-trip: first call replied pineapple, second call resumed from Mongo and replied pineapple again. mongosh confirmed 18 entries persisted under claude_test.claude_session_entries.

Test plan

• cd examples/session-stores/mongodb && bun install && bun run typecheck
• bun test test/MongoDBSessionStore.test.ts — 2/2 pass with no infra
• docker run -d -p 27017:27017 mongo:latest then SESSION_STORE_MONGODB_URL=mongodb://localhost:27017 bun run test:live — 15/15 pass
• With ANTHROPIC_API_KEY set, SESSION_STORE_MONGODB_URL=mongodb://localhost:27017 bun run demo.ts prints two pineapple results

[alexbevi]

Can't update https://code.claude.com/docs/en/agent-sdk/session-storage#reference-implementations, but was hoping to get it added there. I can do the Python example as well if this approach is acceptable.

[alexbevi]

Ended up opening this as anthropics/claude-agent-sdk-python#1014 for the Python side