Redis with LangGraph

Persist LangGraph agent state, long-term memory, and cached model calls in Redis.

LangGraph is a Python framework for building stateful AI agents as graphs. The langgraph-checkpoint-redis package stores that state in Redis. It has three parts:

Part Use it to
Checkpointers Save graph state after every step, so a thread can resume, replay, or recover from a failure.
Stores Keep long-term memories that are shared across threads, with optional vector search.
Middleware Cache model responses by semantic similarity, cache tool results, and recall past messages for a LangChain agent.

The package runs on your own Redis database. To use a managed memory service instead, see Redis Agent Memory, which has its own LangGraph integration.

Requirements

  • Python 3.10 to 3.14
  • Redis with JSON and the Redis Query Engine. Redis 8 and later includes both. Earlier versions need Redis Stack.

Install the package:

pip install langgraph-checkpoint-redis

Save graph state with a checkpointer

Create a RedisSaver, call setup() once to create its indexes, and pass it to compile():

from typing import TypedDict

from langgraph.graph import END, START, StateGraph
from langgraph.checkpoint.redis import RedisSaver


class State(TypedDict):
    count: int


def increment(state: State):
    return {"count": state["count"] + 1}


builder = StateGraph(State)
builder.add_node("increment", increment)
builder.add_edge(START, "increment")
builder.add_edge("increment", END)

with RedisSaver.from_conn_string("redis://localhost:6379") as checkpointer:
    checkpointer.setup()
    graph = builder.compile(checkpointer=checkpointer)

    config = {"configurable": {"thread_id": "thread-1"}}
    graph.invoke({"count": 0}, config)
    print(graph.get_state(config).values)

Each thread_id has its own saved state. A new RedisSaver that connects to the same database reads it back, so a thread survives a restart of your application.

For async applications, use AsyncRedisSaver and await checkpointer.asetup():

from langgraph.checkpoint.redis.aio import AsyncRedisSaver

async with AsyncRedisSaver.from_conn_string("redis://localhost:6379") as checkpointer:
    await checkpointer.asetup()
    graph = builder.compile(checkpointer=checkpointer)
    await graph.ainvoke({"count": 0}, config)

ShallowRedisSaver and its async counterpart keep only the latest checkpoint for each thread. Use them when you don't need history or replay. They are in langgraph.checkpoint.redis.shallow and langgraph.checkpoint.redis.ashallow.

Expire old checkpoints

Pass ttl to remove checkpoints automatically:

ttl = {"default_ttl": 60, "refresh_on_read": True}

with RedisSaver.from_conn_string("redis://localhost:6379", ttl=ttl) as checkpointer:
    checkpointer.setup()

default_ttl is the time to live (TTL) in minutes, not seconds. With refresh_on_read, reading a checkpoint resets its TTL. Without ttl, checkpoints stay until you delete them.

Keep long-term memories in a store

A checkpointer is scoped to one thread. A store holds data that any thread can read, such as a user's preferences. Namespaces organize the data:

from langgraph.store.redis import RedisStore

with RedisStore.from_conn_string("redis://localhost:6379") as store:
    store.setup()
    store.put(("users", "user-1", "memories"), "m1", {"text": "likes green tea"})

    item = store.get(("users", "user-1", "memories"), "m1")
    print(item.value)

AsyncRedisStore in langgraph.store.redis.aio has the same methods with an a prefix, such as aput and aget.

To search memories by meaning, pass an index configuration with an embeddings model. This example uses OpenAI embeddings. Any LangChain Embeddings object works if dims matches the model's output size:

from langchain_openai import OpenAIEmbeddings

index = {
    "dims": 1536,
    "distance_type": "cosine",
    "fields": ["text"],
    "embed": OpenAIEmbeddings(model="text-embedding-3-small"),
}

with RedisStore.from_conn_string("redis://localhost:6379", index=index) as store:
    store.setup()
    store.put(("users", "user-1", "memories"), "m1", {"text": "likes green tea"})

    results = store.search(("users", "user-1", "memories"), query="favorite drink", limit=3)

Stores accept the same ttl setting as checkpointers.

Cache model calls with middleware

The middleware plugs into LangChain's create_agent(). It needs the langchain package, which langgraph-checkpoint-redis doesn't install for you:

pip install langchain

SemanticCacheMiddleware returns a stored response when a new prompt is close enough in meaning to an earlier one. A lower distance_threshold makes matches stricter. Pass a vectorizer that wraps your embeddings model:

from langchain.agents import create_agent
from langchain_core.messages import HumanMessage
from langchain_openai import OpenAIEmbeddings
from langgraph.middleware.redis import (
    LangChainVectorizer,
    SemanticCacheConfig,
    SemanticCacheMiddleware,
)

vectorizer = LangChainVectorizer(
    embeddings=OpenAIEmbeddings(model="text-embedding-3-small"),
    dims=1536,
)

semantic_cache = SemanticCacheMiddleware(
    SemanticCacheConfig(
        redis_url="redis://localhost:6379",
        name="llm_cache",
        distance_threshold=0.15,
        ttl_seconds=3600,
        vectorizer=vectorizer,
    )
)

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[],
    middleware=[semantic_cache],
)

result = await agent.ainvoke({"messages": [HumanMessage(content="What is Redis?")]})

The middleware is async-first, so call ainvoke(). By default it caches only final responses, not responses that request a tool call, and it skips the cache when a prompt includes results from tools you haven't listed in deterministic_tools.

The package also provides ToolResultCacheMiddleware for caching tool results, ConversationMemoryMiddleware for recalling relevant earlier messages, and SemanticRouterMiddleware. For their options, see the package README and the middleware example notebooks.

Upgrade between versions

Checkpoints written by 0.1.x can't be read by 0.2.0 and later. get_state() returns nothing for them. To move to a newer version, start fresh, run the old and new versions side by side until old threads finish, or write a migration script. See the 0.2.0 migration guide.

More info

RATE THIS PAGE
Back to top ↑