Skip to main content
Agent Server persists graph state using a checkpointer backend. By default, LangSmith stores checkpoints in PostgreSQL alongside other server data. You can switch to MongoDB or provide a custom implementation.
Regardless of the checkpointer backend, LangSmith always requires PostgreSQL for threads, runs, assistants, crons, and the memory store. The checkpointer backend only controls where checkpoint data is stored.

​
Available backends

BackendStorageConfigurationUse case
defaultPostgreSQLNone (built-in)Standard deployments
mongoMongoDBlanggraph.json or LS_DEFAULT_CHECKPOINTER_BACKEND env varTeams with existing MongoDB infrastructure
customUser-providedlanggraph.jsonCustom storage backends (see custom checkpointer)

​
Set up MongoDB checkpointing

Requires Agent Server v0.7.64 or later.

​
Prerequisites

  • A MongoDB replica set (standalone mongod is not supported). This can be a self-managed replica set, a mongos router, or a managed service like MongoDB Atlas.
  • A connection URI that includes the database name in the path (e.g., /langgraph).

​
Select the backend

Set the backend to "mongo" using one of these methods: In langgraph.json (app-level—bundled with your application code): 
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "checkpointer": {
    "backend": "mongo",
    "ttl": {
      "strategy": "delete",
      "default_ttl": 43200,
      "sweep_interval_minutes": 10
    }
  }
}
Via environment variable (platform-level—for operators managing standalone deployments): 
LS_DEFAULT_CHECKPOINTER_BACKEND=mongo
The environment variable sets the default backend for agent servers that don’t specify one in langgraph.json. If langgraph.json includes a backend value, it takes precedence.

​
Provide the MongoDB URI

Set the LS_MONGODB_URI environment variable at deploy time: 
LS_MONGODB_URI="mongodb://user:password@host:27017/langgraph?replicaSet=rs0"

​
Connection URI requirements

The URI must:
  • Point to a replica set member or mongos router
  • Include the target database name in the path
Valid examples: 
mongodb://user:password@host:27017/langgraph?replicaSet=rs0
mongodb://host1:27017,host2:27017,host3:27017/mydb?replicaSet=prod-rs
mongodb+srv://user:password@cluster.example.net/langgraph

​
Deploy by environment

The langgraph-cloud Helm chart (v0.2.6+) has built-in MongoDB support. Enable it in your values file:Bundled MongoDB (development and testing):
mongo:
  enabled: true
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
  persistence:
    size: 8Gi
The chart deploys a single-node MongoDB replica set and automatically configures the server to use it.External MongoDB (production):
mongo:
  enabled: true
  external:
    enabled: true
    connectionUrl: "mongodb://user:password@mongo.example.net:27017/langgraph?replicaSet=rs0"
Or reference an existing Kubernetes secret:
mongo:
  enabled: true
  external:
    enabled: true
    existingSecretName: "my-mongo-secret"
The secret must contain a mongodb_connection_url key.

​
Default (PostgreSQL)

PostgreSQL is the default checkpointer backend. No configuration is needed. To use a custom PostgreSQL instance, set the POSTGRES_URI_CUSTOM environment variable.

​
Custom checkpointer

To use a storage backend other than PostgreSQL or MongoDB, implement a custom BaseCheckpointSaver. See Add custom checkpointer for details.
Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.