langchain-ai/langgraphjs
1
0
Fork 0
mirror of https://github.com/langchain-ai/langgraphjs.git synced 2026-07-25 21:26:05 -04:00
Code Issues 108 Packages Projects Releases 20 Wiki Activity

[PR #1189] [CLOSED] feat(checkpoint-redis): add Redis checkpoint saver #1288

New Issue
Closed
opened 2026-02-15 20:15:07 -05:00 by yindo · 0 comments
yindo commented 2026-02-15 20:15:07 -05:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/langchain-ai/langgraphjs/pull/1189
Author: @yahav-levy
Created: 5/17/2025
Status: ❌ Closed

Base: main ← Head: checkpoint-redis-feat

📝 Commits (1)

  • 9f57ac9 Added checkpoint-redis project with tests and code

📊 Changes

21 files changed (+1639 additions, -0 deletions)

View changed files

➕ libs/checkpoint-redis/.env.example (+6 -0)
➕ libs/checkpoint-redis/.eslintrc.cjs (+69 -0)
➕ libs/checkpoint-redis/.gitignore (+7 -0)
➕ libs/checkpoint-redis/.prettierrc (+19 -0)
➕ libs/checkpoint-redis/.release-it.json (+13 -0)
➕ libs/checkpoint-redis/LICENSE (+21 -0)
➕ libs/checkpoint-redis/README.md (+24 -0)
➕ libs/checkpoint-redis/docker-compose.yml (+8 -0)
➕ libs/checkpoint-redis/jest.config.cjs (+20 -0)
➕ libs/checkpoint-redis/jest.env.cjs (+12 -0)
➕ libs/checkpoint-redis/langchain.config.js (+21 -0)
➕ libs/checkpoint-redis/package.json (+91 -0)
➕ libs/checkpoint-redis/src/checkpoint-redis-repository.ts (+381 -0)
➕ libs/checkpoint-redis/src/index.ts (+1 -0)
➕ libs/checkpoint-redis/src/redis-saver.ts (+247 -0)
➕ libs/checkpoint-redis/src/tests/redis-saver.test.ts (+234 -0)
➕ libs/checkpoint-redis/src/utils.ts (+310 -0)
➕ libs/checkpoint-redis/tsconfig.cjs.json (+8 -0)
➕ libs/checkpoint-redis/tsconfig.json (+24 -0)
➕ libs/checkpoint-redis/turbo.json (+11 -0)

...and 1 more files

📄 Description

Feat: Introduce Redis Checkpoint Saver

Type: New Feature

Summary

This pull request introduces a new checkpoint saver implementation using Redis, named RedisSaver. This saver provides a robust and efficient way to persist LangGraph checkpoints, leveraging several Redis best practices to ensure data integrity, performance, and scalability.

Attribution

This implementation incorporates and adapts code from the levivoelz/checkpoint-redis project, which is licensed under the MIT License. The original code has been modified to align with LangGraph's architecture and to integrate additional features such as TTL support and enhanced indexing.

Motivation

For LangGraph applications requiring robust and scalable checkpoint management, a persistent and high-performance backend is essential. The RedisSaver is designed to meet these demands by leveraging Redis as its storage layer.

This RedisSaver provides a dedicated solution for users seeking to integrate LangGraph's powerful checkpointing features with the proven capabilities of Redis.

Detailed Description

The RedisSaver implementation adheres to common Redis best practices and offers the following key features:

  • Atomic Operations: Utilizes Redis MULTI / EXEC transactions for critical operations like setting checkpoints and their associated index entries. This ensures that checkpoint data and its corresponding index are written atomically, preventing partial writes and maintaining data consistency.
  • Indexed Queries:
    • Checkpoints are indexed in a sorted set (ZSET) by their timestamp (ts). This allows for efficient chronological listing and retrieval of checkpoints, including pagination capabilities (e.g., fetching checkpoints before a certain ID, and limiting the number of results).
    • Writes associated with a checkpoint are also indexed in a sorted set, ordered by their insertion sequence. This allows for reliable retrieval of all writes for a given checkpoint.
  • TTL Support: All keys stored in Redis (checkpoints, indexes, writes) support Time-To-Live (TTL). This allows for automatic expiration of old checkpoint data, helping to manage storage and prevent Redis from filling up with stale data. The TTL is configurable.
  • Efficient Data Storage:
    • Checkpoint data and metadata are serialized and stored efficiently.
    • Associated pending writes are stored separately and linked to their parent checkpoint, allowing for granular management.
  • Clear Key Schema: A well-defined and namespaced key schema (checkpoint:<threadId>:<checkpointNs>:<checkpointId>, writes:<threadId>:<checkpointNs>:<checkpointId>:<taskId>:<idx>, checkpoint_index:<threadId>:<checkpointNs>, writes_index:<threadId>:<checkpointNs>:<checkpointId>) is used for easy debugging and management of data within Redis.
  • Comprehensive Unit Tests: The RedisSaver is accompanied by a suite of unit tests (redis-saver.test.ts) covering various scenarios, including:
    • Saving and retrieving checkpoints.
    • Saving and retrieving checkpoints with pending writes.
    • Listing checkpoints with and without filters (limit, before).
    • Handling edge cases like missing thread_id or non-existent checkpoints.

The implementation is organized into:

  • redis-saver.ts: Contains the main RedisSaver class, implementing the BaseCheckpointSaver interface.
  • checkpoint-redis-repository.ts: Encapsulates the direct Redis interactions, providing an abstraction layer for CRUD operations on checkpoints and writes. This promotes separation of concerns and makes the main saver logic cleaner.
  • utils.ts: Includes helper functions for Redis key generation, parsing, and data serialization/deserialization.

How to Test

  1. Ensure you have a Redis instance running (e.g., using the provided docker-compose.yml in the libs/checkpoint-redis directory, which can be started with docker-compose up).
  2. The existing unit tests in libs/checkpoint-redis/src/tests/redis-saver.test.ts can be run using the standard testing command for the workspace (e.g., yarn test or yarn test:single libs/checkpoint-redis/src/tests/redis-saver.test.ts from within the libs/checkpoint-redis directory).
  3. Manual testing can be performed by instantiating RedisSaver in a LangGraph application and configuring it as the checkpointer.

Example Usage:

import { Redis } from "ioredis";
import { RedisSaver } from "@langchain/langgraph-checkpoint-redis"; // Adjust import path as per final package structure

// ... assuming a LangGraph setup ...

const redisConnection = new Redis({ port: 6379 }); // Or your Redis connection details
const checkpointSaver = new RedisSaver({ connection: redisConnection, ttlSeconds: 86400 }); // Optional: 1 day TTL

const graph = new StateGraph({
  channels: {}, // your channels
  schema: YourStateType, // your state type
})
  // ... add nodes and edges ...
  .compile({ checkpointer: checkpointSaver });

// ... then use the graph with thread_id for checkpointing ...
// await graph.invoke({ ... }, { configurable: { thread_id: "my-thread-1" } });

This contribution aims to provide a high-quality, production-grade checkpointing solution for LangGraph users who prefer or require Redis. I'm open to feedback and further improvements!

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/langchain-ai/langgraphjs/pull/1189 **Author:** [@yahav-levy](https://github.com/yahav-levy) **Created:** 5/17/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `checkpoint-redis-feat` --- ### 📝 Commits (1) - [`9f57ac9`](https://github.com/langchain-ai/langgraphjs/commit/9f57ac9837b1817e212ef2822c8a3b9ef5107843) Added checkpoint-redis project with tests and code ### 📊 Changes **21 files changed** (+1639 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `libs/checkpoint-redis/.env.example` (+6 -0) ➕ `libs/checkpoint-redis/.eslintrc.cjs` (+69 -0) ➕ `libs/checkpoint-redis/.gitignore` (+7 -0) ➕ `libs/checkpoint-redis/.prettierrc` (+19 -0) ➕ `libs/checkpoint-redis/.release-it.json` (+13 -0) ➕ `libs/checkpoint-redis/LICENSE` (+21 -0) ➕ `libs/checkpoint-redis/README.md` (+24 -0) ➕ `libs/checkpoint-redis/docker-compose.yml` (+8 -0) ➕ `libs/checkpoint-redis/jest.config.cjs` (+20 -0) ➕ `libs/checkpoint-redis/jest.env.cjs` (+12 -0) ➕ `libs/checkpoint-redis/langchain.config.js` (+21 -0) ➕ `libs/checkpoint-redis/package.json` (+91 -0) ➕ `libs/checkpoint-redis/src/checkpoint-redis-repository.ts` (+381 -0) ➕ `libs/checkpoint-redis/src/index.ts` (+1 -0) ➕ `libs/checkpoint-redis/src/redis-saver.ts` (+247 -0) ➕ `libs/checkpoint-redis/src/tests/redis-saver.test.ts` (+234 -0) ➕ `libs/checkpoint-redis/src/utils.ts` (+310 -0) ➕ `libs/checkpoint-redis/tsconfig.cjs.json` (+8 -0) ➕ `libs/checkpoint-redis/tsconfig.json` (+24 -0) ➕ `libs/checkpoint-redis/turbo.json` (+11 -0) _...and 1 more files_ </details> ### 📄 Description ## Feat: Introduce Redis Checkpoint Saver **Type:** New Feature ### Summary This pull request introduces a new checkpoint saver implementation using Redis, named `RedisSaver`. This saver provides a robust and efficient way to persist LangGraph checkpoints, leveraging several Redis best practices to ensure data integrity, performance, and scalability. ### Attribution This implementation incorporates and adapts code from the [levivoelz/checkpoint-redis](https://github.com/levivoelz/checkpoint-redis) project, which is licensed under the MIT License. The original code has been modified to align with LangGraph's architecture and to integrate additional features such as TTL support and enhanced indexing. ### Motivation For LangGraph applications requiring robust and scalable checkpoint management, a persistent and high-performance backend is essential. The `RedisSaver` is designed to meet these demands by leveraging Redis as its storage layer. This `RedisSaver` provides a dedicated solution for users seeking to integrate LangGraph's powerful checkpointing features with the proven capabilities of Redis. ### Detailed Description The `RedisSaver` implementation adheres to common Redis best practices and offers the following key features: * **Atomic Operations:** Utilizes Redis `MULTI` / `EXEC` transactions for critical operations like setting checkpoints and their associated index entries. This ensures that checkpoint data and its corresponding index are written atomically, preventing partial writes and maintaining data consistency. * **Indexed Queries:** * Checkpoints are indexed in a sorted set (`ZSET`) by their timestamp (`ts`). This allows for efficient chronological listing and retrieval of checkpoints, including pagination capabilities (e.g., fetching checkpoints `before` a certain ID, and `limit`ing the number of results). * Writes associated with a checkpoint are also indexed in a sorted set, ordered by their insertion sequence. This allows for reliable retrieval of all writes for a given checkpoint. * **TTL Support:** All keys stored in Redis (checkpoints, indexes, writes) support Time-To-Live (TTL). This allows for automatic expiration of old checkpoint data, helping to manage storage and prevent Redis from filling up with stale data. The TTL is configurable. * **Efficient Data Storage:** * Checkpoint data and metadata are serialized and stored efficiently. * Associated pending writes are stored separately and linked to their parent checkpoint, allowing for granular management. * **Clear Key Schema:** A well-defined and namespaced key schema (`checkpoint:<threadId>:<checkpointNs>:<checkpointId>`, `writes:<threadId>:<checkpointNs>:<checkpointId>:<taskId>:<idx>`, `checkpoint_index:<threadId>:<checkpointNs>`, `writes_index:<threadId>:<checkpointNs>:<checkpointId>`) is used for easy debugging and management of data within Redis. * **Comprehensive Unit Tests:** The `RedisSaver` is accompanied by a suite of unit tests (`redis-saver.test.ts`) covering various scenarios, including: * Saving and retrieving checkpoints. * Saving and retrieving checkpoints with pending writes. * Listing checkpoints with and without filters (limit, before). * Handling edge cases like missing `thread_id` or non-existent checkpoints. The implementation is organized into: * `redis-saver.ts`: Contains the main `RedisSaver` class, implementing the `BaseCheckpointSaver` interface. * `checkpoint-redis-repository.ts`: Encapsulates the direct Redis interactions, providing an abstraction layer for CRUD operations on checkpoints and writes. This promotes separation of concerns and makes the main saver logic cleaner. * `utils.ts`: Includes helper functions for Redis key generation, parsing, and data serialization/deserialization. ### How to Test 1. Ensure you have a Redis instance running (e.g., using the provided `docker-compose.yml` in the `libs/checkpoint-redis` directory, which can be started with `docker-compose up`). 2. The existing unit tests in `libs/checkpoint-redis/src/tests/redis-saver.test.ts` can be run using the standard testing command for the workspace (e.g., `yarn test` or `yarn test:single libs/checkpoint-redis/src/tests/redis-saver.test.ts` from within the `libs/checkpoint-redis` directory). 3. Manual testing can be performed by instantiating `RedisSaver` in a LangGraph application and configuring it as the checkpointer. **Example Usage:** ```typescript import { Redis } from "ioredis"; import { RedisSaver } from "@langchain/langgraph-checkpoint-redis"; // Adjust import path as per final package structure // ... assuming a LangGraph setup ... const redisConnection = new Redis({ port: 6379 }); // Or your Redis connection details const checkpointSaver = new RedisSaver({ connection: redisConnection, ttlSeconds: 86400 }); // Optional: 1 day TTL const graph = new StateGraph({ channels: {}, // your channels schema: YourStateType, // your state type }) // ... add nodes and edges ... .compile({ checkpointer: checkpointSaver }); // ... then use the graph with thread_id for checkpointing ... // await graph.invoke({ ... }, { configurable: { thread_id: "my-thread-1" } }); ``` This contribution aims to provide a high-quality, production-grade checkpointing solution for LangGraph users who prefer or require Redis. I'm open to feedback and further improvements! --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
yindo added the pull-request label 2026-02-15 20:15:07 -05:00
yindo closed this issue 2026-02-15 20:15:07 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
checkpointer
docs-needed
documentation
enhancement
good first issue
good writeup
help wanted
invalid
langgraph-supervisor
open-swe-auto
platform
prebuilt
pull-request
Mirrored from GitHub Pull Request
 question
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/langgraphjs#1288
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?