View source for Principle:Langchain ai Langgraph Store Configuration

{{PageInfo|type=Principle|title=Langchain_ai_Langgraph_Store_Configuration}}
{| class="wikitable" style="width: 100%;"
|-
! 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''' || <code>libs/checkpoint/langgraph/store/base/__init__.py:L700-745</code>, <code>libs/checkpoint/langgraph/store/memory/__init__.py</code>
|}

== 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, <code>("users", "user-123", "preferences")</code> 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 <code>"langgraph"</code> (reserved for internal use).

==== Items ====

Each stored item (<code>Item</code>) 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''' (<code>IndexConfig</code>) that enables vector similarity search:

* '''dims''': The dimensionality of the embedding vectors.
* '''embed''': An embedding function or LangChain <code>Embeddings</code> instance that converts text to vectors.
* '''fields''': Which fields of stored items to embed. Defaults to <code>["$"]</code> (the entire serialized value).

When indexing is enabled, items are automatically embedded when stored, and the <code>search()</code> method supports natural language queries that return results ranked by cosine similarity.

==== TTL (Time-to-Live) ====

Stores that support TTL (<code>supports_ttl = True</code>) allow items to expire automatically. TTL is configured per-item or via a default <code>TTLConfig</code>:

* '''default_ttl''': Default expiration time in minutes for new items.
* '''refresh_on_read''': Whether reading an item refreshes its TTL (default: <code>True</code>).
* '''sweep_interval_minutes''': How often to sweep for expired items.

Currently, <code>PostgresStore</code> supports TTL while <code>InMemoryStore</code> 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 <code>index</code> dictionary with <code>dims</code>, <code>embed</code>, and optionally <code>fields</code>.
# Optionally configure TTL (PostgresStore only).
# Pass the store to <code>StateGraph.compile(store=...)</code>.
# Access the store from within nodes using the <code>InjectedStore</code> annotation or through the graph's <code>config</code>.

== 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 (<code>batch</code>/<code>abatch</code>) follows the '''Command pattern''', where operations are expressed as data objects (<code>GetOp</code>, <code>PutOp</code>, <code>SearchOp</code>, <code>ListNamespacesOp</code>) that can be batched, serialized, and executed efficiently.

== Related Pages ==

* [[implemented_by::Implementation:Langchain_ai_Langgraph_BaseStore_And_InMemoryStore]]
* [[Langchain_ai_Langgraph_Store_Access_In_Nodes]]
* [[Langchain_ai_Langgraph_Graph_Persistence_Compilation]]

[[Category:Principles]]