Registry / llm-agents / langgraph-checkpoint-redis

langgraph-checkpoint-redis

JSON →
library0.5.2pypypi✓ verified 22d ago

langgraph-checkpoint-redis is a Python library providing Redis implementations for LangGraph's checkpoint savers and stores, enabling persistence for AI agent workflows. It supports both full history (`RedisSaver`) and memory-optimized shallow (`ShallowRedisSaver`) saving, as well as optional vector search capabilities via `RedisStore`. The current version is 0.4.0, with frequent patch releases addressing bug fixes and minor features.

pip install langgraph-checkpoint-redis langgraph redis
INSTALL
IMPORT
SIG · LANGGRAPH-CHECKPOI
L
langgraph-checkpoint-redis
llm-agentspythonv0.5.2
Install
11.3s avg
Import
1574ms
Disk
167MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
build_error
glibc
py 3.103.95 runs
installs and imports cleanly · install 11.3s · import 1.574s · 160MB
167MB installed
● package 167MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

RedisSaver
from langgraph.checkpoint.redis import RedisSaver
AsyncRedisSaver
from langgraph.checkpoint.redis.aio import AsyncRedisSaver
ShallowRedisSaver
from langgraph.checkpoint.redis.shallow import ShallowRedisSaver
AsyncShallowRedisSaver
from langgraph.checkpoint.redis.ashallow import AsyncShallowRedisSaver
RedisStore
from langgraph.store.redis import RedisStore

This quickstart demonstrates how to integrate `RedisSaver` with a basic LangGraph `StateGraph`. It sets up a Redis connection, initializes the `RedisSaver` (including calling `.setup()` for index creation), and then compiles a simple graph to persist its state across invocations using a `thread_id`.

import os from typing import Annotated from langgraph.graph import StateGraph, START from langgraph.checkpoint.redis import RedisSaver from langchain_core.messages import BaseMessage, HumanMessage, AIMessage # Set up Redis connection string, e.g., 'redis://localhost:6379/0' REDIS_URL = os.environ.get('REDIS_URL', 'redis://localhost:6379/0') # Define your graph state class AgentState: messages: Annotated[list[BaseMessage], lambda x, y: x + y] # Define a simple node def simple_agent_node(state: AgentState) -> dict: new_message = AIMessage(content=f"Echo: {state.messages[-1].content}") return {"messages": [new_message]} # Create the Redis Checkpoint Saver # Make sure Redis is running and accessible at REDIS_URL # For production, ensure RedisJSON and RediSearch modules are enabled (Redis 8.0+ includes them) with RedisSaver.from_conn_string(REDIS_URL) as checkpointer: # Important: Call setup() to initialize required RediSearch indices checkpointer.setup() # Build the graph workflow = StateGraph(AgentState) workflow.add_node("agent", simple_agent_node) workflow.set_entry_point(START) workflow.set_finish_point("agent") # Compile the graph with the checkpointer app = workflow.compile(checkpointer=checkpointer) # Example usage with a specific thread_id for persistence thread_id = "test_conversation_123" config = {"configurable": {"thread_id": thread_id}} print(f"\n--- Invoking agent for thread: {thread_id} ---") inputs = {"messages": [HumanMessage(content="Hello LangGraph with Redis!")]} result = app.invoke(inputs, config) print("Result 1:", result) print(f"\n--- Invoking agent again for the same thread: {thread_id} ---") inputs = {"messages": [HumanMessage(content="How are you doing?")]} result = app.invoke(inputs, config) print("Result 2:", result) # List checkpoints (optional) print(f"\n--- Checkpoints for thread {thread_id} ---") for checkpoint in checkpointer.list(config): print(checkpoint)
Debug
Known issues
breakingVersion 0.1.0 introduced breaking changes to the internal storage format. Checkpoints created with pre-0.1.0 versions are not readable by 0.1.0+ without manual migration.
fix
For new deployments, start with version 0.1.0 or newer. For existing data, migration is not automatically supported; consider clearing old checkpoints or using new thread IDs.
affects: <0.1.0 to 0.1.0+
gotchaRedis requires the 'RedisJSON' and 'RediSearch' modules to be enabled for `langgraph-checkpoint-redis` functionality, especially for index creation and efficient data access. Redis 8.0+ includes these by default.
fix
Ensure your Redis instance (local, Redis Stack, or managed service) has RedisJSON and RediSearch modules enabled. For Redis < 8.0, use Redis Stack or install modules separately. Failure to do so will result in errors during `.setup()` or checkpoint operations.
affects: All versions
gotchaThe `.setup()` method must be called on RedisSaver/AsyncRedisSaver instances upon initial setup or application start to create necessary RediSearch indices. Failure to do so will lead to runtime errors.
fix
Always call `checkpointer.setup()` (for synchronous) or `await checkpointer.asetup()` (for asynchronous) after creating your `RedisSaver` or `AsyncRedisSaver` instance.
affects: All versions
gotchaPotential data loss due to Redis persistence settings. Default Redis configurations might not guarantee durability if Redis crashes unexpectedly before RDB snapshot or AOF write operations complete.
fix
Tune Redis persistence settings: use `save` directives (e.g., `save 60 100`), enable AOF (`appendonly yes`) with `appendfsync everysec`, and consider using both RDB and AOF with `aof-use-rdb-preamble yes`. For high availability, consider Redis Sentinel or Redis Cluster.
affects: All versions
gotchaIncorrect message serialization can lead to `MESSAGE_COERCION_FAILURE` errors when using LangGraph's checkpointers. This often happens when `message.to_dict()` is stored instead of `BaseMessage` objects or simple `{role, content}` dicts.
fix
Ensure that `BaseMessage` objects or `{role, content}` dictionaries are passed directly to the state or event streams, and avoid explicit calls to `message.to_dict()` for persistence.
affects: All versions (especially with LangGraph v0.6.4+)
gotchaHigh memory usage in Redis deployments can lead to latency, failed runs, or Out of Memory (OOM) errors, especially in high-load or limited-resource environments.
fix
Monitor Redis memory usage. Implement TTL (Time To Live) settings for checkpoints (e.g., `defaultTTL` when creating saver) to manage data retention. Use `ShallowRedisSaver` for memory-optimized scenarios. Consider increasing Redis memory limits or using production-grade Redis deployments.
affects: All versions
gotchaCompatibility issues have been reported with Valkey (a Redis fork), which may cause hanging requests and connection problems.
fix
It is strongly recommended to use a genuine Redis instance instead of Valkey for reliable operation with `langgraph-checkpoint-redis`.
affects: All versions when used with Valkey
Upgrade
Version history
0.5.2latest on PyPI · released Aug 20, 2026
Audit
Dependencies
redis>=5.2.1requiredRequired for Redis client communication.
redisvl>=0.5.1optionalRequired for vector search capabilities when using RedisStore.
langgraph-checkpoint>=2.0.24requiredProvides the base interface for LangGraph checkpointers.
langgraph>=0.3.0requiredThe core LangGraph framework.
Agent activity
69 hits · last 30 days
node
62
Resources
langgraph-checkpoint-redis — pip install langgraph-checkpoint-redis · libregistry