Addendum — 2026-09-16:
This ticket's original scope was to provide an implementation example in one of Anthropic's repository (addressed already by this PR). That scope is now expanded to cover:

• Self-publishing. The MongoDB adapter ships as a standalone package on PyPI. See scope doc. The work by alexbevi can be reviewed and ported to a the new package.
• Client metadata attribution. As a published package, it identifies itself in the driver handshake via append_metadata/appendMetadata.

• Security threat model. The findings from  the Threat Model have been included in the acceptance criteria section.

TL;DR

Add a MongoDB-backed SessionStore reference adapter to the Claude Agent SDK for Python. The adapter should let developers copy a tested example into their application to mirror and resume Claude agent sessions through MongoDB.

This must follow the existing S3, Redis, and Postgres reference-example model. It is not a request for a packaged, importable, or production-supported MongoDB SDK integration. This was originally scoped as a copy-and-adapt reference example, matching S3, Redis, and Postgres. Per the addendum above, scope now includes publishing it as a packaged, importable MongoDB-owned integration.

Context

The Claude Agent SDK for Python lets developers run Claude Code programmatically from Python applications. An agent session contains the conversation and action history needed for an agent to continue work later.

A SessionStore is the SDK extension point for saving that session transcript outside the host where the agent ran. When an application passes a store to the SDK, the SDK mirrors transcript entries to it. The application can later use the same store to resume a session, including from another host.

The SDK already includes copyable SessionStore reference examples for S3, Redis, and Postgres. These are not part of the installed claude-agent-sdk package. Instead, they demonstrate the interface, expected behavior, and testing approach so developers can copy and adapt an adapter for their own environment.

MongoDB is not currently represented among those examples. Developers who use MongoDB therefore need to design, implement, and validate their own adapter, even though MongoDB is a suitable backend for storing session-transcript entries. Add MongoDB as a fourth reference adapter so those developers have a tested starting point consistent with the existing examples.

Desired User Experience

Before: A developer must create and validate their own MongoDB implementation of the SDK's SessionStore interface before they can persist and resume agent sessions.

# Before: application-owned implementation is required.
store = MyMongoSessionStore(...)
options = ClaudeAgentOptions(session_store=store)

After: A developer installs the MongoDB Python driver, copies the SDK's MongoDB reference adapter into their application, creates an asynchronous MongoDB client, and passes the configured store to ClaudeAgentOptions.

from pymongo import AsyncMongoClient
from claude_agent_sdk import ClaudeAgentOptions, query

# Package name is a proposed example
from claude_agent_sdk_mongodb import MongoDBSessionStore 

client = AsyncMongoClient("mongodb://localhost:27017")
store = MongoDBSessionStore(client=client, db_name="claude_sessions")
await store.create_schema()  # one-time, idempotent

async for message in query("Hello!", options=ClaudeAgentOptions(session_store=store)):
    ...

Install: pip install claude-agent-sdk-mongodb (proposed name) / npm install @mongodb/claude-agent-sdk-mongodb (proposed name).

Task

Goals

• Provide a tested MongoDB example for persisting and resuming Claude Agent SDK session transcripts.
• Make the example discoverable alongside the existing S3, Redis, and Postgres adapters.
• Preserve the existing reference-adapter model: copyable example code, not a packaged SDK integration. Publish a versioned, packaged MongoDBSessionStore to PyPI with a documented public API and a declared SDK/driver compatibility range.

Where

• SessionStore protocol
• Existing reference-adapter directory
• Existing Postgres reference adapter
• Current session-storage documentation

(Product) Acceptance Criteria

• [ ] A MongoDB reference adapter passes the SDK's SessionStore conformance coverage against a configured MongoDB instance.
• [ ] Developers can copy the adapter, configure it with PyMongo's asynchronous AsyncMongoClient, and use it to mirror and resume session transcripts.
• [ ] The adapter is stored with the existing examples/session_stores/ adapters and is clearly described as reference code rather than an importable SDK feature.
• [ ] The repository's reference-adapter README includes MongoDB installation, basic usage, resume behavior, and retention guidance.
• [ ] A follow-up ticket is created to add MongoDB to the live Persist sessions to external storage documentation after the example is available on the upstream default branch.
• UPDATED / ADDED:
  • [ ] The package is published to PyPI as a versioned artifact with a documented public API.
  • [ ] The package's DriverInfo/metadata appears in the handshake metadata of a caller-supplied client, without disturbing any metadata the caller already set.
  • [ ] All findings in the Thread Model doc are addressed in the code and commented in the document.