{"id":5289,"library":"langgraph-checkpoint-redis","title":"LangGraph Redis Checkpoint","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://www.github.com/redis-developer/langgraph-redis","tags":["langgraph","redis","checkpoint","state management","AI","persistence","agent"],"install":[{"cmd":"pip install langgraph-checkpoint-redis langgraph redis","lang":"bash","label":"Install core packages"}],"dependencies":[{"reason":"Required for Redis client communication.","package":"redis>=5.2.1","optional":false},{"reason":"Required for vector search capabilities when using RedisStore.","package":"redisvl>=0.5.1","optional":true},{"reason":"Provides the base interface for LangGraph checkpointers.","package":"langgraph-checkpoint>=2.0.24","optional":false},{"reason":"The core LangGraph framework.","package":"langgraph>=0.3.0","optional":false}],"imports":[{"symbol":"RedisSaver","correct":"from langgraph.checkpoint.redis import RedisSaver"},{"symbol":"AsyncRedisSaver","correct":"from langgraph.checkpoint.redis.aio import AsyncRedisSaver"},{"symbol":"ShallowRedisSaver","correct":"from langgraph.checkpoint.redis.shallow import ShallowRedisSaver"},{"symbol":"AsyncShallowRedisSaver","correct":"from langgraph.checkpoint.redis.ashallow import AsyncShallowRedisSaver"},{"symbol":"RedisStore","correct":"from langgraph.store.redis import RedisStore"}],"quickstart":{"code":"import os\nfrom typing import Annotated\nfrom langgraph.graph import StateGraph, START\nfrom langgraph.checkpoint.redis import RedisSaver\nfrom langchain_core.messages import BaseMessage, HumanMessage, AIMessage\n\n# Set up Redis connection string, e.g., 'redis://localhost:6379/0'\nREDIS_URL = os.environ.get('REDIS_URL', 'redis://localhost:6379/0')\n\n# Define your graph state\nclass AgentState:\n    messages: Annotated[list[BaseMessage], lambda x, y: x + y]\n\n# Define a simple node\ndef simple_agent_node(state: AgentState) -> dict:\n    new_message = AIMessage(content=f\"Echo: {state.messages[-1].content}\")\n    return {\"messages\": [new_message]}\n\n# Create the Redis Checkpoint Saver\n# Make sure Redis is running and accessible at REDIS_URL\n# For production, ensure RedisJSON and RediSearch modules are enabled (Redis 8.0+ includes them)\nwith RedisSaver.from_conn_string(REDIS_URL) as checkpointer:\n    # Important: Call setup() to initialize required RediSearch indices\n    checkpointer.setup()\n\n    # Build the graph\n    workflow = StateGraph(AgentState)\n    workflow.add_node(\"agent\", simple_agent_node)\n    workflow.set_entry_point(START)\n    workflow.set_finish_point(\"agent\")\n\n    # Compile the graph with the checkpointer\n    app = workflow.compile(checkpointer=checkpointer)\n\n    # Example usage with a specific thread_id for persistence\n    thread_id = \"test_conversation_123\"\n    config = {\"configurable\": {\"thread_id\": thread_id}}\n\n    print(f\"\\n--- Invoking agent for thread: {thread_id} ---\")\n    inputs = {\"messages\": [HumanMessage(content=\"Hello LangGraph with Redis!\")]}\n    result = app.invoke(inputs, config)\n    print(\"Result 1:\", result)\n\n    print(f\"\\n--- Invoking agent again for the same thread: {thread_id} ---\")\n    inputs = {\"messages\": [HumanMessage(content=\"How are you doing?\")]}\n    result = app.invoke(inputs, config)\n    print(\"Result 2:\", result)\n\n    # List checkpoints (optional)\n    print(f\"\\n--- Checkpoints for thread {thread_id} ---\")\n    for checkpoint in checkpointer.list(config):\n        print(checkpoint)\n","lang":"python","description":"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`."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":"<0.1.0 to 0.1.0+"},{"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.","message":"Redis 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always call `checkpointer.setup()` (for synchronous) or `await checkpointer.asetup()` (for asynchronous) after creating your `RedisSaver` or `AsyncRedisSaver` instance.","message":"The `.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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Potential 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Incorrect 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.","severity":"gotcha","affected_versions":"All versions (especially with LangGraph v0.6.4+)"},{"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.","message":"High 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"It is strongly recommended to use a genuine Redis instance instead of Valkey for reliable operation with `langgraph-checkpoint-redis`.","message":"Compatibility issues have been reported with Valkey (a Redis fork), which may cause hanging requests and connection problems.","severity":"gotcha","affected_versions":"All versions when used with Valkey"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}