{"id":5648,"library":"langgraph-checkpoint-mongodb","title":"LangGraph MongoDB Checkpoint Saver","description":"This library provides a MongoDB implementation of LangGraph's `CheckpointSaver` interface, enabling persistence for LangGraph agent states. It allows agents to maintain short-term memory, facilitate human-in-the-loop workflows, and provide fault tolerance by saving graph state checkpoints in a MongoDB database. The current version is 0.3.1, with releases tied to the broader LangChain/LangGraph ecosystem updates.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/langchain-ai/langchain-mongodb/tree/main/libs/langgraph-checkpoint-mongodb","tags":["langgraph","mongodb","checkpoint","persistence","state management","memory","rag"],"install":[{"cmd":"pip install langgraph-checkpoint-mongodb","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides the base interface for checkpoint saving that this library implements.","package":"langgraph-checkpoint"},{"reason":"Official MongoDB driver for Python, used for database interaction.","package":"pymongo"}],"imports":[{"symbol":"MongoDBSaver","correct":"from langgraph.checkpoint.mongodb import MongoDBSaver"}],"quickstart":{"code":"import os\nfrom langgraph.checkpoint.mongodb import MongoDBSaver\nfrom pymongo import MongoClient\n\n# NOTE: Ensure a MongoDB instance is running, e.g., locally at mongodb://localhost:27017\n# Replace with your actual MongoDB URI\nMONGODB_URI = os.environ.get('MONGODB_URI', 'mongodb://localhost:27017')\nDB_NAME = \"langgraph_checkpoints_db\"\nCOLLECTION_NAME = \"checkpoints_collection\"\n\n# Initialize the MongoDB client\nclient = MongoClient(MONGODB_URI)\n\n# Initialize the checkpointer with a client, database name, and optional collection name\ncheckpointer = MongoDBSaver(\n    client,\n    db_name=DB_NAME,\n    collection_name=COLLECTION_NAME\n)\n\n# Example usage with a dummy checkpoint and config (simplified for quickstart)\n# In a real LangGraph application, this would be managed by the graph's execution.\nconfig = {\"configurable\": {\"thread_id\": \"test_thread_1\", \"checkpoint_ns\": \"\"}}\ndummy_checkpoint = {\n    \"v\": 1,\n    \"ts\": \"2026-04-11T12:00:00.000000+00:00\",\n    \"id\": \"12345678-abcd-1234-abcd-1234567890ab\",\n    \"channel_values\": {\"my_state\": \"initial_value\"},\n    \"channel_versions\": {},\n    \"versions_seen\": {},\n    \"pending_sends\": []\n}\n\nprint(f\"Saving checkpoint for thread_id: {config['configurable']['thread_id']}\")\ncheckpointer.put(config, dummy_checkpoint, {}, {})\nprint(\"Checkpoint saved.\")\n\nprint(f\"Loading checkpoint for thread_id: {config['configurable']['thread_id']}\")\nloaded_checkpoint_tuple = checkpointer.get(config)\nif loaded_checkpoint_tuple:\n    print(f\"Loaded checkpoint state: {loaded_checkpoint_tuple.checkpoint.channel_values}\")\nelse:\n    print(\"No checkpoint found.\")\n\n# Clean up (optional, for demonstration)\ncheckpointer.delete_thread(config)\nprint(f\"Deleted checkpoints for thread_id: {config['configurable']['thread_id']}\")\n\nclient.close()","lang":"python","description":"This quickstart demonstrates how to initialize `MongoDBSaver` and interact with it directly to save and load a dummy checkpoint. In a typical LangGraph application, the `checkpointer` instance is passed to the `graph.compile()` method to automatically manage state persistence."},"warnings":[{"fix":"Refer to the official documentation and release notes of `langgraph-checkpoint-mongodb` and `langgraph` for compatible version ranges. Upgrade both `langgraph` and `langgraph-checkpoint-mongodb` to their latest compatible versions.","message":"Breaking changes in the base `langgraph-checkpoint` library (e.g., between v0.x/v1.x and v2.x/v3.x) can lead to API mismatches and dependency conflicts. Ensure your `langgraph-checkpoint-mongodb` version is compatible with your `langgraph` and `langgraph-checkpoint` versions to avoid issues like the `langgraph-checkpoint@3.0` incompatibility reported previously.","severity":"breaking","affected_versions":"<0.3.1 (possibly previous major `langgraph-checkpoint` versions)"},{"fix":"Implement a periodic cleanup job to manually prune old checkpoints based on `checkpoint_id` (which is time-sortable) or wrap the saver to add an `expiresAt`/`createdAt` top-level field for MongoDB's native TTL indexing. It is recommended to keep at least the last few checkpoints per thread.","message":"The `MongoDBSaver` currently does not offer built-in mechanisms for automatic checkpoint retention or Time-To-Live (TTL) configuration. This means that checkpoints will accumulate indefinitely, potentially leading to significant storage growth in production environments with high conversation volume.","severity":"gotcha","affected_versions":"All versions up to 0.3.1"},{"fix":"Ensure your MongoDB deployment is a replica set (or Atlas/`mongos` router). Update your MongoDB connection URI to include the database name, for example, `mongodb://<host>:<port>/<db_name>`.","message":"For use with the official LangGraph Agent Server, a MongoDB replica set is a prerequisite; standalone `mongod` instances are not supported. Additionally, the MongoDB connection URI must include the database name in its path (e.g., `mongodb://localhost:27017/mydatabase`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate from `AsyncMongoDBSaver` to `MongoDBSaver`. Review LangGraph's asynchronous execution patterns to integrate the synchronous `MongoDBSaver` appropriately, potentially by running operations in a separate thread/executor if truly non-blocking database calls are required.","message":"The `AsyncMongoDBSaver` class has been removed. Users who previously relied on this for asynchronous operations will need to refactor their code to use the main `MongoDBSaver` which handles operations synchronously or manage async interaction at a higher level.","severity":"deprecated","affected_versions":">=0.3.0 (removed around this version)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}