Agent memory

What it is

Managed agent memory gives an agent something to remember between conversations. You create a memory store — a workspace-scoped container, addressed by its display_name — and Databricks provisions the Lakebase storage behind it for you.

An entry in that store carries the text itself (content), a short description used when retrieving it, and three fields that place it:

The three together identify an entry uniquely. Names are constrained: three to fifty-six characters, lowercase letters, digits and hyphens, starting with a letter — and display_name cannot be changed afterwards, so choose it as carefully as you would a table name.

This is Beta as of September 2026. There is no toggle to turn it on.

Why it exists

An agent without memory re-meets its user every morning. It re-learns that they work in euros, that “the report” means the weekly one, that they never want the raw table. Every conversation starts from nothing, and the user does the remembering on the agent’s behalf.

The usual answer is to bolt a database onto the agent: a table of preferences, a retrieval query, a migration to maintain, an instance to size. That works, and it is one more piece of infrastructure to run for what is often a few kilobytes per person.

What managed memory removes is that operational burden — the storage, the indexing and the retrieval are somebody else’s problem, and you address the whole thing through one API.

It is worth being plain about what it does not yet remove, because an earlier reading of this page said otherwise. Memory is the most personal data an agent holds, and the questions that come with personal data are still yours to answer: the documentation describes no per-actor access control, no deletion operation for an entry or a store, and no retention or expiry. Treat the convenience as an operational one, not a governance one.

How it works

Short-term and long-term are different problems

Short-term memory is the conversation you are in. Databricks has a separate feature for it, managed sessions, which appends items to a session under the same store-and-actor shape; a framework’s own message history or a LangGraph checkpointer does the same job. Deleting a session does not touch anything the agent wrote into a memory store — the two are deliberately independent.

Long-term memory is what survives the conversation ending. That is what this page is about. Entries reach a store in two ways: your agent or application writes them directly, or a memory pipeline distills them from the conversations in a session store. A pipeline is the one case where something other than your code edits what the agent saved, so do not assume an entry you wrote is still there unchanged on a store that has one.

Where actor_id comes from

Set it in your own code, from an identity you have already verified, and never from anything the model produced. The moment the model can choose whose memory it reads, a well-phrased question becomes a way to read somebody else’s.

Common shapes: one actor per end user; one shared actor for a group that genuinely shares context; or a composite such as {tenant}:{user} when one agent serves several customers — with a separate store per tenant, since the store is the boundary.

Getting an entry back out

Two ways, both scoped to a single actor. List returns an actor’s entries, optionally narrowed by session_id or by a path prefix. Search takes a natural-language query and ranks by BM25 full-text relevance — up to a hundred entries, without pagination.

Reaching it

A REST API under /api/2.0/agents/memory-stores creates stores, adds entries and searches them, so any language works. For Python there is the AgentKit SDK, the client for the agent APIs (pip install databricks-agentbricks, Python 3.10 or above), which wraps the same calls and is what the examples use. It was documented under the name Mason earlier, which is why that name still turns up in older write-ups.

Granting another principal — typically the service principal your deployed agent runs as — access to a store is a single grant-permission operation on the store itself. There are no finer privileges to reach for.

Example: the decision to make first

Before any of the API, decide what the agent is allowed to remember, because that decision is a product one with a legal edge and no API will make it for you.

A workable starting policy for an internal analytics agent: remember stated preferences — currency, default date range, the tables this person works with — and never the content of results; one actor per person; one store per group that is allowed to share, and a separate store for anything belonging to a different customer.

Then write down how you would delete a person’s memory if they asked tomorrow. Today that answer is code you write against the list operation, not a feature you can point at, and it is much cheaper to discover that now than after the store has a year of entries in it.

Common mistakes

• Reading actor_id as a permission. It separates, it does not protect. Isolation is one store per boundary.
• Taking actor_id from the model or from a request body. It belongs to the trusted part of your code, derived from an identity you checked.
• Expecting semantic search. Retrieval is BM25 today, so an entry phrased in different words than the query may never come back. The description is where you put the words that will be searched for.
• Remembering everything. Memory that accumulates without a policy becomes both a liability and noise, and noisy memory makes answers worse, not better.
• Confusing memory with retrieval. What the user said last week is memory. What the company knows is the ontology and the indexes behind it. Putting company facts in per-user memory duplicates them badly.
• Building on Beta. It can change, and this page is the proof: the storage model changed entirely within a month. Prototype on it, and keep the authoritative copy of anything you must not lose somewhere generally available.