persistence
Choose and wire LangGraph persistence: checkpoint savers, stores, thread config, SQLite/Postgres backends, and safe serde settings.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- persistence
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Choose and wire LangGraph persistence: checkpoint savers, stores, thread config, SQLite/Postgres backends, and safe serde settings.
- disable-model-invocation
- true
02 资源文件 3
- 参考文档references/checkpointing.md8.0 KB
- 参考文档references/store-memory.md5.0 KB
- 参考文档references/troubleshooting.md6.5 KB
03 SKILL.md 正文
Persistence
Use this sub-skill when a task asks an agent to persist LangGraph state, resume a graph thread, choose a checkpoint backend, add long-term memory, debug checkpoint configuration, or harden checkpoint serialization.
Route Here When
- A graph needs memory across
invoke,stream,batch,ainvoke, orastreamcalls. - A stateless graph must become a persistent threaded graph with
thread_idconfig. - The task mentions checkpointers, checkpoints, checkpoint savers,
checkpoint_id,checkpoint_ns, pending writes, or time travel. - A local app needs SQLite checkpoints or a production app needs Postgres checkpoints.
- A graph needs a key-value store such as
InMemoryStoreor semantic memory search. - The error involves
PostgresSaver,SqliteSaver, async saver imports, psycopg row factories, missing setup, or msgpack deserialization warnings.
For graph compilation and runtime invocation patterns, pair this with graph-runtime. For agent templates and tool-calling agents that need memory, pair with prebuilt-agents. For deployment-managed checkpointers, pair with the cli-deployment sibling sub-skill when present. For hosted thread APIs, pair with the sdk-clients sibling sub-skill when present.
Core Decision Flow
- Decide whether the app needs checkpoints, a store, or both:
- Checkpoints persist graph execution state by thread and are passed to
builder.compile(checkpointer=...). - Stores persist long-term key-value memory across threads and are passed to
builder.compile(store=...)when graph nodes access a store.
- Checkpoints persist graph execution state by thread and are passed to
- Pick the checkpoint saver:
InMemorySaverfromlanggraph.checkpoint.memoryfor debugging and tests only.SqliteSaverfromlanggraph.checkpoint.sqlitefor lightweight local sync persistence.AsyncSqliteSaverfromlanggraph.checkpoint.sqlite.aiofor async SQLite graph execution.PostgresSaverfromlanggraph.checkpoint.postgresfor durable sync production persistence.AsyncPostgresSaverfromlanggraph.checkpoint.postgres.aiofor async production persistence.
- Require thread configuration whenever a compiled graph uses a checkpointer:
- Minimum config:
{"configurable": {"thread_id": "user-or-session-id"}}. - Optional resume point: add
"checkpoint_id": "...". - Optional namespace: add
"checkpoint_ns": "..."when isolating checkpoint streams inside one thread.
- Minimum config:
- Harden deserialization before reading untrusted or long-lived checkpoint databases:
- Prefer setting
LANGGRAPH_STRICT_MSGPACK=truein the runtime environment. - Or pass
JsonPlusSerializer(allowed_msgpack_modules=[("package.module", "ClassName")])to the saver.
- Prefer setting
- Validate with a tiny graph and a repeated
thread_idbefore changing application logic.
Common Patterns
Debug or Test Checkpoints
from langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "debug-thread"}}
result = graph.invoke(input_state, config)
InMemorySaver(*, serde=None, factory=defaultdict) stores checkpoints in process memory. Do not recommend it for production because data is lost when the process exits.
Local SQLite Checkpoints
from langgraph.checkpoint.sqlite import SqliteSaver
with SqliteSaver.from_conn_string("checkpoints.sqlite") as checkpointer:
graph = builder.compile(checkpointer=checkpointer)
graph.invoke(input_state, {"configurable": {"thread_id": "local-user-1"}})
Use sync SqliteSaver only with sync graph methods. For ainvoke, astream, or async apps, import AsyncSqliteSaver from langgraph.checkpoint.sqlite.aio; it requires aiosqlite.
Durable Postgres Checkpoints
from langgraph.checkpoint.postgres import PostgresSaver
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
checkpointer.setup()
graph = builder.compile(checkpointer=checkpointer)
graph.invoke(input_state, {"configurable": {"thread_id": "customer-123"}})
Call setup() the first time a Postgres checkpoint database is used so migrations and checkpoint tables exist. For manual psycopg connections, use autocommit=True and row_factory=dict_row.
Long-Term Store Memory
from langgraph.store.memory import InMemoryStore
store = InMemoryStore()
store.put(("users", "123"), "prefs", {"theme": "dark"})
item = store.get(("users", "123"), "prefs")
InMemoryStore(*, index=None) supports namespaced key-value storage and optional semantic search. It is in-memory and process-local; use it for tests, demos, and memory logic development before selecting a durable store backend.
References
- Checkpointing: saver selection, thread config, SQLite/Postgres wiring, metadata queries, and serde security.
- In-Memory Store:
InMemoryStorenamespaces, filters, optional vector search, and async methods. - Troubleshooting: dependency, config, sync/async, Postgres row factory, setup, and security failures.
- Memory checkpoint smoke script: self-contained check for package imports,
InMemorySaver, thread config, and checkpoint listing.
Validation Checklist
- Run
python skills/langgraph/sub-skills/persistence/scripts/smoke_memory_checkpoint.py --helpto confirm the bundled script is discoverable. - Run
python skills/langgraph/sub-skills/persistence/scripts/smoke_memory_checkpoint.pyin an environment withlanggraphinstalled. - Confirm repeated graph calls reuse the same
thread_idwhen continuity is expected. - Confirm sync apps use sync savers and async apps use async savers.
- Confirm SQLite apps have
langgraph-checkpoint-sqliteinstalled and async SQLite apps also haveaiosqlite. - Confirm Postgres apps have
langgraph-checkpoint-postgres, psycopg connectivity,setup(), and correct row factory settings. - Confirm checkpoint data from shared or persistent databases is read with strict msgpack or an explicit allowlist.
Do Not
- Do not tell future agents to read source repository files or tests at runtime.
- Do not use
InMemorySaverorInMemoryStoreas durable production persistence. - Do not call sync saver methods from async graph execution; use the matching async saver.
- Do not omit
thread_idwhen compiling with a checkpointer. - Do not create manual Postgres connections without
autocommit=Trueandrow_factory=dict_row. - Do not suppress serde warnings without either strict mode or an intentional allowlist.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.