Skip to main content

langgraph-checkpoint-gridgain

GridGain persistence for LangGraph: a checkpointer for short-term (thread) state, a store for long-term, cross-thread memory, and a node cache for compile(cache=...).

Version 3.1.0 requires Python 3.11 or later and pygridgain >= 1.7.0, < 2.0. The imports and stored data format remain compatible with 3.0.0.

pip install langgraph-checkpoint-gridgain
from pygridgain import Client
from langgraph.cache.gridgain import GridGainNodeCache
from langgraph.checkpoint.gridgain import GridGainCheckpointSaver
from langgraph.store.gridgain import GridGainMemoryStore

client = Client()
client.connect("127.0.0.1", 10800)

graph = builder.compile(
    checkpointer=GridGainCheckpointSaver(client),
    store=GridGainMemoryStore(client),
)

Import paths

The classes are defined in langgraph.checkpoint.gridgain, langgraph.store.gridgain and langgraph.cache.gridgain — the namespace every LangGraph persistence backend publishes under, and the only one this package installs into:

from langgraph.checkpoint.gridgain import GridGainCheckpointSaver
from langgraph.store.gridgain import GridGainMemoryStore
from langgraph.cache.gridgain import GridGainNodeCache

There is no flat langgraph_checkpoint_gridgain module, for the same reason postgres, sqlite, redis and mongodb ship none: one object should have one import path.

Relationship to langchain-gridgain

This package depends on langchain-gridgain and borrows its client guard and TTL helper, so a checkpoint write cannot interleave with a vector search on the one socket a synchronous pygridgain client has. Installing this package installs that one too, which is how you get GridGain's LangChain components — a vector store, LLM caches, a byte store, a document loader and a chat message history — beside the LangGraph persistence.

Moving from langchain-gridgain 2.x? These two classes used to ship there. The 3.0.0 release moved them here:

-from langchain_gridgain import GridGainCheckpointSaver, GridGainMemoryStore
+from langgraph.checkpoint.gridgain import GridGainCheckpointSaver
+from langgraph.store.gridgain import GridGainMemoryStore

Behavior and stored data are unchanged.

Async

Both classes implement the async surface natively against pygridgain's AioClient, rather than running the sync path on a worker thread:

from pygridgain import AioClient

aio_client = AioClient()
await aio_client.connect("127.0.0.1", 10800)

checkpointer = GridGainCheckpointSaver(client, aio_client=aio_client)

Requirements

  • Python 3.11+
  • A GridGain 8 cluster reachable over the thin client protocol

GridGainCheckpointSaver

GridGainCheckpointSaver is a LangGraph checkpointer (BaseCheckpointSaver) that persists agent state in GridGain, enabling resume, human-in-the-loop, and time-travel. It stores each checkpoint, its payload and its intermediate writes in three SQL-backed caches — lg_checkpoints, lg_checkpoint_blobs and lg_checkpoint_writes — created automatically on first use. The payload is deliberately kept out of lg_checkpoints, which is the table every "latest checkpoint" query orders by; see Upgrading. Unlike the vector components, it uses only SQL, so it runs on any GridGain/Apache Ignite node (no vector license required).

Usage example:

from pygridgain import Client
from langgraph.checkpoint.gridgain import GridGainCheckpointSaver

client = Client()
client.connect("127.0.0.1", 10800)

checkpointer = GridGainCheckpointSaver(client)

graph = builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "conversation-1"}}
result = graph.invoke(inputs, config)

# Resume later on the same thread; inspect the latest state.
snapshot = graph.get_state(config)

For native async graphs (ainvoke / astream), pass a connected AioClient so the checkpointer uses non-blocking I/O:

from pygridgain import AioClient

aio_client = AioClient()
await aio_client.connect("127.0.0.1", 10800)

checkpointer = GridGainCheckpointSaver(aio_client=aio_client)

Pass both client and aio_client to serve sync and async graphs from one instance. A sync-only saver still works with ainvoke — it runs the sync path on a worker thread.

GridGainMemoryStore

GridGainMemoryStore is a LangGraph store (BaseStore) for memory that outlives a single thread — user preferences, extracted facts, anything an agent should recall across conversations. Items live in namespaces and support structured search, so this is the counterpart to the checkpointer's per-thread state.

It stores items in one cache (lg_store, created when the store is constructed) and, like the checkpointer, needs no vector license — it uses the key-value and SQL APIs only.

Usage example:

from pygridgain import Client
from langgraph.store.gridgain import GridGainMemoryStore

client = Client()
client.connect("127.0.0.1", 10800)

store = GridGainMemoryStore(client)

# Namespaced items
store.put(("users", "u1"), "prefs", {"theme": "dark", "score": 5})
store.get(("users", "u1"), "prefs").value  # {"theme": "dark", "score": 5}

# Search a namespace and everything nested under it
store.search(("users",), filter={"theme": "dark"})
store.search(("users",), filter={"score": {"$gte": 5}}, limit=10, offset=0)

# Explore the namespace hierarchy
store.list_namespaces(prefix=("users",))
store.list_namespaces(max_depth=1)

store.delete(("users", "u1"), "prefs")

graph = builder.compile(store=store)  # cross-thread memory for an agent

Filters support exact matches plus $eq, $ne, $gt, $gte, $lt, $lte, and are applied to the item's JSON value.

TTL is native. Unlike the Postgres/SQLite stores, expiry is enforced by the server rather than an expires_at column. Pass a per-item ttl (in minutes) and/or store-wide defaults, and by default reads refresh the expiry:

store = GridGainMemoryStore(
    client,
    ttl_config={"default_ttl": 60, "refresh_on_read": True},  # minutes
)

store.put(("users", "u1"), "session", {"step": 3}, ttl=10)  # expires in 10 minutes
store.get(("users", "u1"), "session")  # ...and that resets the clock
store.get(("users", "u1"), "session", refresh_ttl=False)  # read without refreshing

For native async graphs, pass a connected AioClient (optionally alongside the sync client, to serve both):

from pygridgain import AioClient

aio_client = AioClient()
await aio_client.connect("127.0.0.1", 10800)

store = GridGainMemoryStore(aio_client=aio_client)
await store.aput(("users", "u1"), "prefs", {"theme": "dark"})

Semantic search is not implemented yet. search(..., query="...") is accepted but the query is ignored (with a warning) and the structured-filter path runs; vector-backed search depends on the GridGain vector engine and lands separately.

GridGainNodeCache

GridGainNodeCache is a LangGraph node cache (langgraph.cache.base.BaseCache). When a node has a CachePolicy, the engine stores the node's output keyed by its input, and a later run with the same input skips the node. Attach it at compile(cache=...). Despite the shared interface name it is unrelated to the LangChain LLM cache above: GridGainCache (langchain_core.caches.BaseCache) caches model generations by prompt, GridGainNodeCache caches graph node runs.

It stores entries in one cache (lg_node_cache, created when the node cache is constructed with a sync client, or on first use with an aio_client only) and needs no vector license — it uses the key-value and SQL APIs only.

Usage example:

from pygridgain import Client
from langgraph.graph import END, START, StateGraph
from langgraph.types import CachePolicy
from langgraph.cache.gridgain import GridGainNodeCache

client = Client()
client.connect("127.0.0.1", 10800)

builder = StateGraph(State)
builder.add_node("expensive", expensive, cache_policy=CachePolicy(ttl=300))  # seconds
builder.add_edge(START, "expensive")
builder.add_edge("expensive", END)
graph = builder.compile(cache=GridGainNodeCache(client))

graph.invoke({"x": 3})  # runs `expensive`
graph.invoke({"x": 3})  # same input: the node's output comes from GridGain
graph.clear_cache(["expensive"])  # deletes those nodes' entries, one SQL DELETE

graph.clear_cache() with no arguments clears every node namespace of that graph (still one SQL DELETE). Only a direct node_cache.clear() empties the whole GridGain cache, other graphs' entries included.

What two graphs share. LangGraph's namespace for a node is the node's name plus its function's module.qualname; it carries no graph or application id. Two graphs share entries, hits and clears exactly when they have a node of the same name whose function has the same module.qualname: the same function, or two closures or functools.partials from one factory. That is what makes a hit survive a restart, and it is also how a factory-built node in one graph can serve another graph's cached output. The default lg_node_cache is shared across the cluster on purpose; give each application its own cache_name= (a plain identifier, [A-Za-z_][A-Za-z0-9_]*, not a SQL reserved word) when its node functions are built by a factory, or whenever two deployments must not see each other's entries.

Chat states need an explicit key_func. LangGraph's default cache key pickles the node's input. A message that came back from any cache, InMemoryCache included, carries a larger model_fields_set than a freshly built one and pickles differently, so in a model-plus-tools loop over an add_messages state only the first model step of a repeat run hits. Key on what the model sees instead:

def messages_key(state):
    return "|".join(f"{m.type}:{m.content}" for m in state["messages"])


builder.add_node(
    "call_model", call_model, cache_policy=CachePolicy(key_func=messages_key)
)

Key shapes. Namespace labels and cache keys must be built-in str. LangGraph produces those itself, except for the node name, which is whatever you passed to add_node: a StrEnum or (str, Enum) member is rejected with a TypeError, so spell it add_node(str(N.SUMMARIZE), ...).

TTL is native and in seconds. CachePolicy(ttl=...) is enforced by the server; an entry with no TTL never expires, and reads do not extend an entry's life. Entries live in GridGain, not in the process, so a second process — or a restart — sees the same hits.

For native async graphs, pass a connected AioClient (optionally alongside the sync client, to serve both):

graph = builder.compile(cache=GridGainNodeCache(aio_client=aio_client))
await graph.ainvoke({"x": 3})

Metadata

Release files for langgraph-checkpoint-gridgain 3.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for langgraph-checkpoint-gridgain 3.1.0
File Size Uploaded Provenance Actions
langgraph_checkpoint_gridgain-3.1.0.tar.gz 103.4 kB Without provenance Details for langgraph_checkpoint_gridgain-3.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for langgraph-checkpoint-gridgain 3.1.0
File Interpreter ABI Platform Actions
langgraph_checkpoint_gridgain-3.1.0-py3-none-any.whl Python 3 none any Details for langgraph_checkpoint_gridgain-3.1.0-py3-none-any.whl

Total release size: 147.6 kB

Release files / langgraph_checkpoint_gridgain-3.1.0.tar.gz

Download URL langgraph_checkpoint_gridgain-3.1.0.tar.gz
Size 103.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a0e8941d69d30d0253b1d50e2b8ffbb6c25492a74bac307edc779f0ae752c572
BLAKE2b-256 checksum
How to use checksums
fa7e13ec99818807cd04eb56caaaa2b660382f048b84244b74bc085ba57331fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / langgraph_checkpoint_gridgain-3.1.0-py3-none-any.whl

Download URL langgraph_checkpoint_gridgain-3.1.0-py3-none-any.whl
Size 44.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08323a25da5d163f3881274e5fcd9e309f8790fdca095455c994e49a57e9cfe5
BLAKE2b-256 checksum
How to use checksums
e0bda4ada5462d530169fe1dc2dbf28b7a16b23778f9d12ad9e7bfc78c3c6f4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for langgraph-checkpoint-gridgain 3.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page