Synchronous Neo4j checkpoint saver for LangGraph.
This class implements the BaseCheckpointSaver interface using Neo4j as the persistence backend with a proper graph model. It supports storing checkpoints, channel states, and pending writes using relationships for efficient traversal.
Neo4jSaver(
self,
driver: Driver,
database: str | None = None,
)Graph Model:
(:Thread)-[:HAS_CHECKPOINT]->(:Checkpoint)-[:PREVIOUS]->(:Checkpoint) (:Checkpoint)-[:HAS_CHANNEL]->(:ChannelState) (:Checkpoint)-[:HAS_WRITE]->(:PendingWrite)
Example:
Using from_conn_string (recommended)
with Neo4jSaver.from_conn_string( ... uri="bolt://localhost:7687", ... user="neo4j", ... password="password" ... ) as checkpointer: ... checkpointer.setup() # Create indexes (run once) ... graph = builder.compile(checkpointer=checkpointer) ... result = graph.invoke({"messages": [...]}, config)
Using existing driver
driver = GraphDatabase.driver(uri, auth=(user, password)) checkpointer = Neo4jSaver(driver) checkpointer.setup()
| Name | Type | Description |
|---|---|---|
driver* | Driver | A Neo4j Driver instance. |
database | str | None | Default: NoneOptional database name (defaults to Neo4j default). |
| Name | Type |
|---|---|
| driver | Driver |
| database | str | None |
Create a Neo4jSaver from connection parameters.
This is the recommended way to create a Neo4jSaver as it properly manages the driver lifecycle.
Close the driver connection if owned by this instance.
Create indexes and constraints in Neo4j.
This method should be called once before using the checkpointer. It creates the necessary indexes and constraints for the graph model, including branch-related constraints for time-travel functionality.
Store a checkpoint with its configuration and metadata.
Creates Thread and Checkpoint nodes with HAS_CHECKPOINT relationship, links to parent via PREVIOUS relationship, and stores channel states with HAS_CHANNEL relationships. Also manages branch tracking for time-travel functionality.
Store pending writes for fault tolerance.
Creates PendingWrite nodes and links them to the Checkpoint via HAS_WRITE relationships.
Retrieve a checkpoint tuple by configuration.
Traverses the graph model from Thread -> Checkpoint -> ChannelStates to retrieve all data. When no checkpoint_id is specified, retrieves the HEAD of the active branch (instead of lexicographic latest).
List checkpoints matching the given criteria.
Traverses from Thread to Checkpoints via HAS_CHECKPOINT relationships.
Delete all checkpoints, channel states, and writes for a thread.
Uses DETACH DELETE to cascade through relationships.