Principle:Langchain ai Langgraph Store Configuration
| Attribute | Value |
|---|---|
| Page Type | Principle |
| Library | langgraph (checkpoint, checkpoint-postgres) |
| Workflow | Persistence_and_Memory_Setup |
| Principle | Store_Configuration |
| Implementation | Langchain_ai_Langgraph_BaseStore_And_InMemoryStore |
| Source | libs/checkpoint/langgraph/store/base/__init__.py:L700-745, libs/checkpoint/langgraph/store/memory/__init__.py
|
Overview
Stores in LangGraph provide cross-thread, long-term memory that persists independently of graph execution state. While checkpointers capture thread-scoped snapshots of graph state at each step, stores offer a general-purpose key-value persistence layer with hierarchical namespaces, optional semantic search via embeddings, and configurable time-to-live (TTL) for automatic expiration.
Description
The store system addresses a fundamentally different persistence need than checkpointers. Checkpointers are tied to execution threads and capture the complete graph state at each step. Stores, by contrast, are shared across all threads and allow nodes to read and write arbitrary key-value data that persists beyond any single execution.
Key Concepts
Namespaced Storage
Every item in a store is organized under a namespace, represented as a tuple of strings that forms a hierarchical path. For example, ("users", "user-123", "preferences") creates a three-level namespace. Namespaces enable logical organization and scoped queries. The store enforces that namespace labels cannot contain periods, cannot be empty strings, and the root label cannot be "langgraph" (reserved for internal use).
Items
Each stored item (Item) consists of:
- namespace: The hierarchical path where the item resides.
- key: A unique identifier within the namespace.
- value: A dictionary with string keys and JSON-serializable values.
- created_at: Timestamp of creation.
- updated_at: Timestamp of last modification.
Semantic Search (Optional)
Stores can optionally be configured with an index configuration (IndexConfig) that enables vector similarity search:
- dims: The dimensionality of the embedding vectors.
- embed: An embedding function or LangChain
Embeddingsinstance that converts text to vectors. - fields: Which fields of stored items to embed. Defaults to
["$"](the entire serialized value).
When indexing is enabled, items are automatically embedded when stored, and the search() method supports natural language queries that return results ranked by cosine similarity.
TTL (Time-to-Live)
Stores that support TTL (supports_ttl = True) allow items to expire automatically. TTL is configured per-item or via a default TTLConfig:
- default_ttl: Default expiration time in minutes for new items.
- refresh_on_read: Whether reading an item refreshes its TTL (default:
True). - sweep_interval_minutes: How often to sweep for expired items.
Currently, PostgresStore supports TTL while InMemoryStore does not.
Available Backends
- InMemoryStore: Dictionary-backed store for development and testing. Supports optional vector search. Data is lost when the process exits.
- PostgresStore: PostgreSQL-backed store for production. Supports vector search via pgvector, TTL, connection pooling, and durable persistence.
Usage
To configure a store:
- Choose a backend based on persistence and search requirements.
- Optionally configure indexing by providing an
indexdictionary withdims,embed, and optionallyfields. - Optionally configure TTL (PostgresStore only).
- Pass the store to
StateGraph.compile(store=...). - Access the store from within nodes using the
InjectedStoreannotation or through the graph'sconfig.
Theoretical Basis
The store abstraction implements a hierarchical key-value store pattern, similar to a file system with directories (namespaces) and files (items). This model is widely used in distributed systems for its simplicity and flexibility.
The optional semantic search capability transforms the store into a vector database overlay, enabling retrieval-augmented generation (RAG) patterns directly within the graph execution context. The use of cosine similarity for ranking follows standard practice in information retrieval.
The separation between stores (cross-thread) and checkpointers (thread-scoped) mirrors the distinction between long-term memory and working memory in cognitive science. Long-term memory (the store) holds facts, preferences, and knowledge that accumulate over time. Working memory (the checkpointer) holds the current execution context and is scoped to a specific task or conversation.
The batch operation model (batch/abatch) follows the Command pattern, where operations are expressed as data objects (GetOp, PutOp, SearchOp, ListNamespacesOp) that can be batched, serialized, and executed efficiently.