What you will be able to do
- Persist LangGraph thread state in Lakebase so follow-up questions survive restarts
- Choose between the managed checkpointer and self-managed Lakebase memory based on SQL and schema needs
- Add a Lakebase database resource to a Databricks app and know what credentials and privileges it provides
- Initialize the memory tables and diagnose the common Lakebase memory errors
1.Short-term memory for LangGraph lives in a checkpointer
LangGraph saves graph state through a checkpointer keyed by a thread ID. The thread ID is what lets an agent answer a follow-up question with the earlier turns in view, which is short-term memory. Where the checkpointer writes decides how long that state lasts. A checkpointer backed by Lakebase, Databricks' managed Postgres, stores the thread outside the agent's process, so a later request or a restarted app picks it up from the database.
Lakebase-backed agent state runs on two deployment targets. On Databricks Apps, agents use LangGraph checkpointers or the OpenAI Agents SDK, and Databricks handles authentication between the app and Lakebase. On Model Serving, agents use Lakebase-backed checkpoints and can use LangGraph time travel to resume or fork a conversation from any checkpoint.
Use the checkpointer for thread state, not the long-term memory store. A memory store holds durable facts about a subject, found by search. Writing a whole transcript into it as a single entry each turn mixes up the two jobs. Retrieval by vector similarity is a different mechanism again: it finds relevant documents rather than replaying a thread, as covered in Vector Search indexes.
Checkpoint 1 of 7· Check yourself
A LangGraph support agent deployed on Databricks Apps loses the earlier turns of a conversation whenever the app restarts. Users expect follow-up questions in the same thread to keep working. What should you configure?
Short-term memory for a LangGraph thread comes from a checkpointer keyed by a thread ID. If Lakebase backs the checkpointer, the state is stored outside the app's process and survives a restart. The memory store holds durable facts that the agent finds by search, so it is the wrong place for transcripts. Vector Search finds relevant documents and does not replay a thread.
“Captures context within a single conversation session using thread IDs and checkpointing.”Source: docs.databricks.com
Checkpoint 2 of 7· Exam question
An agent built with LangGraph needs to maintain conversation context for follow-up questions within a single chat session, using a thread ID, and the state must survive across serving replicas rather than living only in process memory. Which configuration meets this need?
Correct answer: D — Compile the graph with a Lakebase Postgres-backed LangGraph checkpointer, pass the thread ID in each request's config, and scale the serving endpoint out to several replicas.
- A. The in-memory checkpointer keeps thread state inside each replica's own process. A follow-up routed to a different replica finds no history, which fails the requirement that session state not live only in process memory.
- B. A managed memory store holds long-term facts that carry across conversations. Saving extracted facts and searching them does not keep a thread's ordered messages or scope them to its thread ID, so follow-ups can lose earlier turns and pull in facts from other sessions.
- C. Direct Vector Access indexes hold vectors that the application reads and writes itself, and similarity search returns only the nearest fragments. It does not store or restore a thread's full ordered state, so follow-ups that depend on earlier turns can lose context.
- D. A LangGraph checkpointer backed by Lakebase Postgres saves thread state in a managed Postgres database outside any replica. Whichever replica receives the next request with that thread ID can load the earlier conversation context.
2.Plugging the managed session store into LangGraph
For a new or existing agent, the shortest path is the LangGraph adapter in databricks-agentbricks (version 0.5.0 or above). checkpointer() returns a checkpointer backed by a managed session store on Lakebase, and thread_config() maps a conversation ID and its user onto a LangGraph thread. The model, tools and prompts stay as they are. If the agent already has a checkpointer, swap it for checkpointer(). If you build a StateGraph directly, pass it to compile().
from langchain.agents import create_agent
from databricks_agentkit.langgraph import checkpointer, thread_config
SESSION_STORE = "support-agent-sessions"
# Your existing model and tools, unchanged, with the managed checkpointer added.
agent = create_agent(model=model, tools=tools, checkpointer=checkpointer(store=SESSION_STORE))
async def handle_message(user_id: str, conversation_id: str, message: str) -> str:
result = await agent.ainvoke(
{"messages": [{"role": "user", "content": message}]},
config=thread_config(conversation_id, actor=user_id),
)
return result["messages"][-1].contentThe checkpointer saves the full graph state, including human-in-the-loop interrupts. A run paused for approval can therefore resume after the app restarts, not just continue a chat. What it saves is serialized graph checkpoints, and a memory pipeline does not read those. If you also want the pipeline to distill long-term memories from a LangGraph agent's conversations, record a plain transcript of user and assistant messages alongside the checkpoints.
Checkpoint 3 of 7· Fill the gap
Which keyword argument persists this agent's thread state in the managed session store?
from langchain.agents import create_agent
from databricks_agentkit.langgraph import checkpointer, thread_config
SESSION_STORE = "support-agent-sessions"
# Your existing model and tools, unchanged, with the managed checkpointer added.
agent = create_agent(model=model, tools=tools, ? =checkpointer(store=SESSION_STORE))
async def handle_message(user_id: str, conversation_id: str, message: str) -> str:
result = await agent.ainvoke(
{"messages": [{"role": "user", "content": message}]},
config=thread_config(conversation_id, actor=user_id),
)
return result["messages"][-1].contentLangGraph saves thread state through a checkpointer keyed by a thread ID. You pass the managed checkpointer() to the agent as its checkpointer. A store is the place for long-term memory, not thread state.
Source: docs.databricks.comCheckpoint 4 of 7· Check yourself
After moving a LangGraph agent to checkpointer() on a session store, the team runs a memory pipeline on that store each night. Weeks later, the memory store still has no entries for those users. What is the cause, and what is the fix?
The managed checkpointer saves serialized graph checkpoints, and a memory pipeline skips them. If you want the pipeline to build memory from a LangGraph agent's conversations, record a plain user/assistant transcript alongside the checkpoints.
“The checkpointer stores serialized graph checkpoints, which a memory pipeline doesn't read. To use a memory pipeline with a LangGraph agent, also record a transcript.”Source: docs.databricks.com
Sources2
3.Self-managed Lakebase memory: when you need the SQL
Self-managed agent memory points the agent at a Lakebase instance you own. Lakebase is a fully managed Postgres OLTP database, but the memory layout inside it is yours. The approach exists for two cases: you need direct SQL access to memories, for example to join them into existing pipelines or to use a custom schema, or you want short-term memory backed by Lakebase that you control. You pay for that control with work. You manage the database schema, the connection setup and the access controls, and nothing is governed for you. Databricks now classes this as a legacy approach and steers new agents without those needs toward the managed stores.
Self-managed agents start from a template app rather than a blank file. The agent-langgraph-advanced template builds a LangGraph agent with both short-term and long-term memory. It uses LangGraph's built-in checkpointing with Lakebase for thread-based context, and it keeps user insights across sessions. The agent-openai-advanced template does the same for short-term memory with the OpenAI Agents SDK. Both add background and streaming modes, so an agent task can keep running past the Databricks Apps HTTP connection timeout.
Checkpoint 5 of 7· Check yourself
A team moves its agent's memory to a Lakebase instance it owns so that analysts can join memories into existing SQL pipelines. Before go-live, what does the team still have to set up itself?
Self-managed memory gives you direct SQL and your own schema. In exchange, you manage the schema, the connection setup and the access controls, and nothing is governed for you. Store-level grants and actor_id partitioning belong to the managed stores, Unity Catalog lineage belongs to the legacy managed store, and actor_id is never an access control.
“This approach requires you to manage the database schema, connection setup, and access controls.”Source: docs.databricks.com
Checkpoint 6 of 7· Exam question
A team is building a custom LangGraph agent and wants to integrate its conversation memory with an existing data pipeline that requires direct SQL access and a custom database schema. Which approach for persisting agent memory best fits this requirement?
Correct answer: C — Self-managed agent memory backed by Lakebase, a managed Postgres database where the team creates its own tables and queries the memory rows over a standard Postgres connection.
- A. Managed memory stores and their entries are created and accessed through the Unity Catalog REST API, not through SQL against underlying tables. The pipeline therefore cannot read memory directly with SQL, which the team requires.
- B. Managed memory keeps entries in the structure the store defines, so the team cannot impose its own database schema on the memory data. Having Databricks handle storage and partitioning does not meet the custom schema requirement, and the pipeline would have to adapt to the store.
- C. Self-managed memory on Lakebase, a managed Postgres OLTP database, lets the team define its own tables and query them directly over a normal database connection. This matches the need to integrate with an existing SQL-based pipeline with a custom schema.
- D. Self-managed memory on Lakebase is accessed through a database client the team chooses. The OpenAI-compatible conversations API is the access pattern for managed memory. Routing memory through it would give the team neither direct SQL access nor a schema it designed.
Sources3
4.Wiring the Lakebase resource into the app
The app reaches Lakebase through a database resource, never a hard-coded connection string. Each Databricks app runs as its own service principal. When you add a Lakebase database as a resource, Databricks creates a Postgres role named after that principal's client ID and grants it CONNECT and CREATE on the database. That is enough for the agent to create its memory tables. The only permission level currently offered is Can connect and create. Adding a Lakebase Autoscaling project as a resource requires CAN MANAGE on the project. At deploy time, Databricks injects the connection details as environment variables.
| Variable | Description |
|---|---|
| PGHOST | Host name of the PostgreSQL server |
| PGPORT | Port for the PostgreSQL server |
| PGDATABASE | Name of the database |
| PGUSER | Service principal's client ID and role name |
| PGSSLMODE | SSL mode for the connection |
| PGAPPNAME | App name |
For an agent defined in databricks.yml, declare the resource next to the app. These variables describe only the first database resource. An app with several databases reads the others through valueFrom with each resource key. Anything the app creates in the database persists, because schemas and tables survive redeploying or stopping the app.
resources:
apps:
my_agent:
resources:
- name: 'memory_database'
database:
instance_name: '<lakebase-instance-name>'
database_name: 'postgres'
permission: 'CAN_CONNECT_AND_CREATE'The memory tables must exist before the first request. Run the store's setup() once from your machine before deploying. The store also takes an embedding endpoint and dimension, which it uses for long-term memory.
import asyncio
from databricks_langchain import AsyncDatabricksStore
async def setup_memory():
async with AsyncDatabricksStore(
instance_name='your-lakebase-instance',
embedding_endpoint='databricks-gte-large-en',
embedding_dims=1024,
) as store:
await store.setup()
asyncio.run(setup_memory())| Error | Cause | Solution |
|---|---|---|
| relation 'store' does not exist | Memory tables not initialized | Run await store.setup() locally before deploying |
| Unable to resolve instance | Wrong instance name or configuration | LAKEBASE_INSTANCE_NAME uses value (not valueFrom) in app.yaml and matches instance_name in databricks.yml |
| permission denied for table store | Missing Lakebase permissions | Add a database resource with permission: 'CAN_CONNECT_AND_CREATE' |
| Memory not persisting across conversations | Different user_id per request | Pass a consistent user_id in custom_inputs for each user |
Whether each request carries the same user_id in custom_inputs for a given user. Long-term memory is keyed by that ID, so a value that changes per request writes every preference under a new identity, and the agent never finds it again.
Checkpoint 7 of 7· Check yourself
During a code review, you find an agent on Databricks Apps that opens Lakebase with a connection string and password hard-coded in its source. What is the recommended way to connect the app to its Lakebase memory database?
Adding Lakebase as a database resource makes Databricks create a Postgres role for the app's service principal and inject the host, database, user and related settings as environment variables, so the code has no credentials or connection strings. Store-level grants and Unity Catalog privileges control the managed stores. They do not wire an app to a Lakebase database.
“Databricks creates a service principal for your app, grants it a matching Postgres role, and injects connection details as environment variables.”Source: docs.databricks.com
Practise it for real
Deploy a LangGraph agent on Databricks Apps whose memory persists in Lakebase
1.Clone the app templates repository and open the agent-langgraph-advanced template.
Why: It already wires LangGraph checkpointing to Lakebase for short-term and long-term memory.
You should see: A local agent project ready to point at your Lakebase instance.
2.Add a database resource for your Lakebase instance in databricks.yml with permission 'CAN_CONNECT_AND_CREATE'.
Why: The resource gives the app's service principal a Postgres role with CONNECT and CREATE, and injects the PG* connection variables.
You should see: No 'permission denied for table store' errors once the app is deployed.
3.Set LAKEBASE_INSTANCE_NAME with value (not valueFrom) in app.yaml, matching instance_name in databricks.yml.
Why: A mismatched or indirect value prevents the agent from resolving the instance.
You should see: The agent connects to the instance at startup.
4.Run the setup_memory() script locally to call await store.setup().
Why: The memory tables must exist before the deployed agent writes to them.
You should see: Tables created, so the error "relation 'store' does not exist" never appears.
5.Deploy, then send two requests with the same custom_inputs.user_id and a follow-up question.
Why: A consistent user_id is how memory is found again across conversations.
You should see: The second response reflects what the first conversation stored.
Stuck? Get a nudge
If the app answers "Memory not available", check that the request payload includes custom_inputs.user_id.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Captures context within a single conversation session using thread IDs and checkpointing.”
↩︎ Short-term memory for LangGraph lives in a checkpointer“Databricks handles authentication between the app and Lakebase automatically.”
↩︎ Short-term memory for LangGraph lives in a checkpointer - 2.
“LangGraph persists graph state through a checkpointer keyed by a thread ID.”
↩︎ Short-term memory for LangGraph lives in a checkpointer“The checkpointer stores full graph state, including human-in-the-loop interrupts, so a paused run can resume after a restart.”
↩︎ Plugging the managed session store into LangGraph“The checkpointer stores serialized graph checkpoints, which a memory pipeline doesn't read.”
↩︎ Exam trap 1“The checkpointer stores serialized graph checkpoints, which a memory pipeline doesn't read. To use a memory pipeline with a LangGraph agent, also record a transcript.”
↩︎ Checkpoint - 3.
“This approach requires you to manage the database schema, connection setup, and access controls.”
↩︎ Self-managed Lakebase memory: when you need the SQL“The template uses LangGraph's built-in checkpointing with Lakebase for durable state management”
↩︎ Self-managed Lakebase memory: when you need the SQL“This is a legacy approach.”
↩︎ Self-managed Lakebase memory: when you need the SQL“This approach requires you to manage the database schema, connection setup, and access controls.”
↩︎ Exam trap 2“when you need direct SQL access to memories (for example, to integrate memory with existing data pipelines or to use a custom schema)”
↩︎ Prediction - 4.
“Databricks creates a service principal for your app, grants it a matching Postgres role, and injects connection details as environment variables.”
↩︎ Wiring the Lakebase resource into the app - 5.
“Databricks grants the service principal CONNECT and CREATE privileges on the selected database.”
↩︎ Wiring the Lakebase resource into the app“Databases persist state. Any schemas or tables created by an app remain even after you re-deploy or stop the app.”
↩︎ Wiring the Lakebase resource into the app - 6.
“Run await store.setup() locally before deploying to create required tables”
↩︎ Wiring the Lakebase resource into the app“Ensure you pass a consistent user_id in custom_inputs for each user”
↩︎ Wiring the Lakebase resource into the app