LangGraph LMDB Checkpointer

A high-performance, local checkpoint saver for LangGraph using LMDB (Lightning Memory-Mapped Database).

🚀 Why LMDB?

LMDB is a transactional, memory-mapped key-value store. It is incredibly fast because it uses the operating system's memory-map (mmap) to provide zero-copy reads and highly efficient writes. For LangGraph, where state persistence can become a bottleneck during complex agentic loops, LMDB offers a near-memory speed with full persistence.

🏢 When to Use?

• High-Performance Local Agents: When running agents on a single machine or edge device where network latency to a database (like Postgres) is unacceptable.
• Embedded Applications: Desktop or mobile apps that need a self-contained, lightweight, and zero-configuration database.
• Development & Prototyping: Fast startup and easy portability of checkpoints during the R&D phase.

🏆 Where it Excels

• Read Latency: Since it maps the database file directly into memory, reading a checkpoint is essentially a memory access.
• Reliability (ACID): Fully ACID compliant with a crash-proof design. If the power fails, your checkpoints stay consistent.
• Multi-Process/Multi-Thread: Highly concurrent reads without blocking, making it perfect for multi-agent workflows.

Features

• Blazing Fast Local Storage: Optimized for high-frequency writes and low-latency state retrieval.
• Binary Key Strategy: Uses a compact binary key layout (thread_id\x00checkpoint_ns\x00checkpoint_id) for efficient multi-index prefix scanning.
• Flexible Serialization: Supports both msgpack (default) and orjson for high-speed state encoding.
• Async & Sync Support: Provides both thread-safe synchronous (LMDBSaver) and non-blocking asynchronous (AsyncLMDBSaver) implementations.

Installation

pip install langgraph-checkpoint-lmdb

Quick Start

import lmdb
from langgraph_checkpoint_lmdb import LMDBSaver
from langgraph.graph import StateGraph

# Initialize LMDB environment
env = lmdb.open("./checkpoints", max_dbs=10)
saver = LMDBSaver(env)

# Use in your LangGraph as a checkpointer
graph = builder.compile(checkpointer=saver)

Real-World Examples

• Customer Support Bot: See examples/customer_support.py for a complete implementation of a multi-turn support agent with state persistence.
• Interactive Chatbot: See examples/chatbot.py for a simple interactive CLI chatbot that remembers your name across sessions.

Performance

Benchmarks conducted on local hardware comparing LMDBSaver with the default MemorySaver.

Development

Run Tests

pytest

Run Benchmarks

python benchmark.py

License

MIT License. See LICENSE for details.