What you will be able to do
- Tell apart the two kinds of agent state, session state and long-term memory, and pick the right managed store for each
- Explain what Lakebase provides as the persistent backend for agent state, and where it can be deployed
- Create a session store, start a session, append items and read the history back in chronological order
- Map framework history operations onto session store calls, and explain how access to a session store is controlled
Key concept
Session state vs. long-term memory — An agent keeps two separate kinds of persistent state. Session state is the working transcript of a single interaction, and it gives the agent continuity within one conversation. Memory holds durable facts about a subject, and it gives the agent continuity across conversations. Databricks provides a separate Lakebase-backed managed store for each.
1.Two kinds of state an agent must persist
A model serving request has no state of its own. If an agent needs to answer a follow-up question, or remember next week that a user prefers email, something outside the model has to hold that context. Databricks splits this into two problems. Managed agent sessions store session state. That is the ordered transcript of messages, tool calls and results for one interaction, or any other state a framework persists, such as a LangGraph graph. Managed agent memory stores durable facts, preferences and decisions that the agent recalls in later, unrelated conversations.
What separates them is scope. A session belongs to one interaction and is complete on its own. A memory belongs to a *subject*, such as a user, a team or a project, and is recalled whenever it becomes relevant.
| Aspect | Managed agent sessions | Managed agent memory |
|---|---|---|
| Scoped to | One interaction | A subject, not an interaction |
| Typical contents | Conversation history: messages, tool calls, results; or a LangGraph graph | A user's stable preferences, a past decision, an ongoing project |
| How the agent uses it | Reads it at the start of a turn and appends to it as the interaction runs | Recalls it in later, separate conversations |
| Container | Session store | Memory store |
The two stores meet at one point: something said in a conversation turns out to be worth keeping. While a session grows, the agent (or your application) pulls the durable facts out of it and writes them to memory. Eventually the session is cleared or ages out, but the memory stays. For most agents, use both stores. Use sessions alone when you only need in-interaction state. Use memory alone when your framework already manages session state.
Checkpoint 1 of 6· Put it in order
Put the lifecycle of a durable fact in the order the documentation describes
- 1.Those facts are written to the memory store
- 2.A session accumulates turns during one interaction
- 3.The agent or application distills durable facts out of the session
- 4.The session is cleared or ages out, while the memory persists
Facts are extracted from a growing session and written to memory. Because the memory store is independent, the facts outlive the session.
“As a session accumulates, an agent (or your application) distills the durable facts out of it and writes them to memory.”Source: docs.databricks.com
Checkpoint 2 of 6· 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, since it is a fully managed Postgres OLTP database that lets the team define its own schema and query memory directly with SQL.
- A. Managed memory stores and entries are created and managed only through the Unity Catalog REST API, not through direct SQL queries against underlying tables, so this does not meet the team's need for direct SQL access.
- B. Automatic storage and partitioning management is a real benefit of the managed approach, but it removes the ability to define a custom schema, which is exactly what the team needs for their existing pipeline.
- C. Self-managed agent memory on Lakebase, a fully managed Postgres OLTP database, gives the team direct SQL access and full control over the schema, connection setup, and access controls, matching a requirement to integrate with an existing SQL-based pipeline.
- D. The self-managed approach does not require using the OpenAI-compatible conversations API; that API pattern applies to managed memory, while self-managed memory is accessed through whatever database client the team chooses.
Sources1
2.Lakebase: the Postgres datastore underneath
Both managed stores run on Lakebase, the fully managed Postgres database built into Databricks. Lakebase works with Databricks authentication and scales automatically. Among its documented uses is acting as a state store for agents. It also offers scale to zero, branches for isolated development and testing, and instant restore.
The Lakebase agent-state documentation uses the terms short-term and long-term memory. Short-term memory holds context within a single conversation, keyed by thread IDs and checkpointing. Long-term memory extracts key insights across conversations. One agent can use either or both. Lakebase-backed memory is supported on two deployment targets. On Databricks Apps, you can 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, which support LangGraph time travel to resume or fork a conversation from any checkpoint.
With the managed stores you never provision the database yourself. Creating a session store or a memory store provisions its Lakebase storage automatically. Both features are in Beta. During the preview you pay for the underlying Lakebase instance, with no extra charge for the session or memory feature itself.
Checkpoint 3 of 6· Check yourself
A team creates a managed session store during the preview. What do they need to do, and what are they billed for?
Creating the store provisions its Lakebase storage. During the preview, the only charge is for the Lakebase instance that stores the sessions.
“you are billed for the underlying Lakebase instance that stores your sessions”Source: docs.databricks.com
3.The session data model: store, session, item
Managed sessions have three levels.
- A session store is a workspace-scoped container. You give it a workspace-unique session_store_name.
- A session is one durable interaction inside a store, usually a conversation thread. It is identified by actor_id, which is required and names who the session belongs to so you can list and filter one subject's sessions together. It also takes session_id, which is optional and chosen by the caller (the service generates one if you omit it), and parent_session_id, which is optional and links a forked conversation to the session it came from.
- A session item is one entry in the ordered history. It holds an opaque, JSON-compatible value such as a message, tool call, tool result or reasoning block. Databricks assigns each item an item_id and a create_time, does not inspect the contents, and treats items as immutable once appended.
Checkpoint 4 of 6· Match them up
Match each session field to its role
Tap a term, then the definition that fits it.
actor_id groups sessions by subject, and session_id names the interaction. parent_session_id records branching. Databricks assigns item_id and create_time to every item.
“parent_session_id (optional): links a session to the one it was forked from, to represent branched conversations.”Source: docs.databricks.com
Sources4
4.Writing and reading a session
The AgentKit SDK is the Databricks Python client for agent APIs. It ships in the databricks-agentbricks package, needs Python 3.10 or above, and authenticates through the Databricks SDK's WorkspaceClient. Other languages can call the REST API under /api/2.0/agents/session-stores. After creating a store with client.session_stores.create("support-agent-sessions"), start a session for one conversation:
session = session_store.add(actor_id="customer-123", session_id="case-456")session.append_items( [ {"type": "message", "role": "user", "content": "I need help with my cluster."}, {"type": "message", "role": "assistant", "content": "Let's take a look."}, ])When a follow-up request arrives, reload the session with session_store.get("case-456") and read its items to rebuild the context. There is a catch: list_items returns the newest items first by default. To replay a transcript, you have to ask for chronological order explicitly.
Checkpoint 5 of 6· Fill the gap
Which ordering rebuilds the conversation in the order it happened?
history = [item.data for item in session.list_items(order_by=" ? ")]list_items defaults to newest-first. Passing create_time asc returns the transcript oldest-first, which is the order a framework replays it in.
Source: docs.databricks.comFrameworks such as the OpenAI Agents SDK and the Claude Agent SDK read the history when a run starts and append new items when it ends. Each of those operations has a direct session store equivalent:
| Framework operation | Session store call |
|---|---|
| Read history | list_items in chronological order (order_by="create_time asc") |
| Add turn items | append the new items |
| Undo last item | pop the most recent item |
| Clear the thread | clear the session's items |
Undo does not edit an item. It pops the most recent item off the session's history. Clearing a thread removes the items altogether. Neither operation changes the contents of an existing item.
Sources4
5.Branching, deletion and who can read a session
The clients can also fork a conversation into an independent copy, optionally only up to a specific item. The fork is linked back through parent_session_id. If you delete a session that has child sessions, you must pass a force option, for example session.delete(force=True), to cascade the deletion to the children.
The service stores items without interpreting them. It has no first-class concept of runs, checkpoints or approvals, although a framework that serializes that kind of state can save it as ordinary items.
Access works at the store level. Session stores are workspace-scoped, and every operation is authorized against the store. actor_id and metadata exist only for grouping and filtering, and they grant or restrict nothing. To let another principal, such as your agent's service principal, use the store, call session_store.grant_permission(principal_id). Set actor_id from trusted application context, never from a value supplied by the model or the user.
Checkpoint 6 of 6· Check yourself
A developer sets actor_id to each user's verified ID and assumes users therefore cannot read each other's sessions. What is actually true?
actor_id and metadata are grouping and filtering fields. Whether a principal can read a session depends on its access to the session store.
“The actor_id and metadata fields support grouping and filtering only; they do not grant or restrict access.”Source: docs.databricks.com
Sources4
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Deleting a session store also removes the long-term memories that were distilled from its conversations.Why is that wrong?
Session and memory stores are independent. Deleting sessions, or a whole session store, leaves memory entries in place.
Covered in Two kinds of state an agent must persist
2.Calling list_items with no arguments returns the conversation in chronological order, ready to replay.Why is that wrong?
list_items defaults to newest-first. To replay the history oldest-first, pass order_by="create_time asc".
Covered in Writing and reading a session
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Use sessions alone when you only need in-interaction state, or memory alone when your framework already manages session state.”
↩︎ Two kinds of state an agent must persist“Memories are scoped to a subject, not an interaction”
↩︎ Two kinds of state an agent must persist“sessions give the agent continuity within a conversation, and memory gives it continuity across conversations”
↩︎ Key concept“deleting a session, or an entire session store, does not delete memory retained in a memory store.”
↩︎ Exam trap 1“deleting a session, or an entire session store, does not delete memory retained in a memory store.”
↩︎ Prediction“As a session accumulates, an agent (or your application) distills the durable facts out of it and writes them to memory.”
↩︎ Checkpoint - 2.
“Lakebase provides a fully managed Postgres backend for storing agent state and memory”
↩︎ Lakebase: the Postgres datastore underneath“Deploy agents to Model Serving endpoints with Lakebase-backed checkpoints.”
↩︎ Lakebase: the Postgres datastore underneath - 3.https://docs.databricks.com/aws/en/oltp/projectsOfficial docs
“Use Lakebase as an online feature store for ML models, or as a state store for agents.”
↩︎ Lakebase: the Postgres datastore underneath - 4.
“Creating a store provisions the backing Lakebase storage automatically.”
↩︎ Lakebase: the Postgres datastore underneath“Databricks assigns each item an item_id and a create_time and does not inspect or validate its contents.”
↩︎ The session data model: store, session, item“Items are immutable after they are appended.”
↩︎ The session data model: store, session, item“list_items defaults to newest-first and auto-pages.”
↩︎ Writing and reading a session“Deleting a session that has child sessions requires a force option to cascade the deletion to them”
↩︎ Branching, deletion and who can read a session“Session stores are workspace-scoped, and access is authorized at the store level.”
↩︎ Branching, deletion and who can read a session“It doesn't add execution-control resources such as runs, checkpoints, or approvals as first-class concepts”
↩︎ Branching, deletion and who can read a session“list_items defaults to newest-first and auto-pages.”
↩︎ Exam trap 2“you are billed for the underlying Lakebase instance that stores your sessions”
↩︎ Checkpoint“parent_session_id (optional): links a session to the one it was forked from, to represent branched conversations.”
↩︎ Checkpoint“The actor_id and metadata fields support grouping and filtering only; they do not grant or restrict access.”
↩︎ Checkpoint