Managed Agent Memory Stores: Save, Search and Isolate Long-Term Memory

1.The memory data model: stores and entries

Managed agent memory gives an agent long-term memory that lasts across conversations. Databricks stores it in Lakebase and handles the storage, indexing and search, so you don't operate a database. The feature is in Beta and works with agents built on any framework. It has two levels.

A memory store is the workspace-scoped container for an agent's memories. Creating one provisions its Lakebase storage, and you refer to it by its display_name. That name must be 3 to 56 characters, start with a lowercase letter, end with a letter or number, and contain only lowercase letters, numbers and hyphens.

A memory entry is a single piece of content. It has free-form text content, a short description that is used for retrieval, and three fields that organize it:

- actor_id (required): whose memory this is, such as an end user or another agent. - session_id (optional): the session the memory was captured from, kept for provenance. Leave it unset for memory that isn't tied to a session. - path (required): a filesystem-like path inside the actor, such as /preferences/response-style.md.

Sources1

2.Saving and recalling memory

The AgentKit SDK (pip install databricks-agentbricks, authenticated with a WorkspaceClient) wraps the REST API under /api/2.0/agents/memory-stores. The example below follows a support agent. It creates a store, saves a preference once it learns something durable about a user, and recalls that preference in a later conversation.

memory_store = client.memory_stores.create("support-agent-memory")

memory_store.add( actor_id="user-123", path="/preferences/communication.md", content="Prefers email over phone. Timezone: PST. Enterprise subscription.", description="User 123 communication preferences",)

There are two ways to retrieve memory, and both are scoped to one actor. List returns an actor's entries, optionally filtered by session_id or a path prefix, which is useful for browsing or rendering an index of what the agent knows. Search takes a natural-language query and returns the most relevant entries, ranked by a full-text (BM25) relevance score.

results = memory_store. ? (actor_id=actor_id, query=query, limit=10)

Sources1

3.Letting the agent decide when to remember

Your application decides when the API gets called. To let the agent choose when to save and recall, wrap the store's operations as tools and explain in the system prompt when to use them. In the OpenAI Agents SDK, the documented pattern binds actor_id when the tools are *built*, so the model only ever supplies the query, path and content:

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

The same pattern works with the Claude Agent SDK and other frameworks: expose search and add as that framework's tool type.

Sources1

4.Partitioning with actor_id, isolating with stores

Every list and search is scoped to a single actor_id, which makes the value you choose a design decision:

If your strategy depends on an end-user identity, reject any request that arrives without one. Do not fall back to a shared actor_id.

actor_id separates memories, but it does not control access. Memory stores are workspace-scoped, so any principal that can reach a store can read and write every entry for every actor. The security boundary is the store. For strict isolation between tenants or users, create one store per boundary. To let your agent's service principal use a store, grant access with memory_store.grant_permission(principal_id).

Sources12

5.Configuring a Lakebase store for a LangGraph agent on Apps

Not every agent uses the managed memory API. An agent deployed on Databricks Apps can connect to a Lakebase instance directly through AsyncDatabricksStore from databricks_langchain. That setup needs two pieces of configuration. First, the app needs a database resource in databricks.yml with the CAN_CONNECT_AND_CREATE permission:

resources:
  apps:
    my_agent:
      resources:
        - name: 'memory_database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

Second, the store's tables have to exist before the first request. Initialize them locally before you deploy:

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())

Sources2

6.Recognizing the legacy Unity Catalog memory store

You may still see an earlier managed memory store in documentation and in existing code. It was a Unity Catalog securable, and it is being turned down, so don't build new agents on it. The things that tell it apart are its three-level name, its scope field, and its access model based on UC privileges:

Sources3

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Setting actor_id to each user's ID stops users and principals from reading each other's memories.Why is that wrong?

   actor_id only partitions entries. The store is the security boundary, and anyone who can reach it can read every actor's entries, so strict isolation needs separate stores.

   Covered in Partitioning with actor_id, isolating with stores

2. 2.The model should pass actor_id to the memory tools so it can save notes for whoever it is talking to.Why is that wrong?

   actor_id comes from trusted application code and the verified end-user identity. The model never chooses whose memory to read or write.

   Covered in Letting the agent decide when to remember

3. 3.Creating an agent memory store requires the CREATE MEMORY STORE privilege on a Unity Catalog schema.Why is that wrong?

   That privilege belongs to the legacy UC-governed store, which is being turned down. The current managed memory store is workspace-scoped and addressed by display_name.

   Covered in Recognizing the legacy Unity Catalog memory store

Practise it for real

Give a support agent per-user long-term memory backed by a managed memory store

1. 1.Run pip install databricks-agentbricks on Python 3.10 or above, then build an AgentKitClient from a WorkspaceClient.

   Why: The AgentKit SDK is the Databricks Python client for the agent memory APIs and authenticates with your workspace credentials.

   You should see: The client is created without an authentication error.

2. 2.Call client.memory_stores.create("support-agent-memory").

   Why: Creating the store provisions its Lakebase storage, and the display_name must follow the naming rules.

   You should see: A memory store named support-agent-memory exists in the workspace.

3. 3.Call memory_store.add with actor_id="user-123", path="/preferences/communication.md", plus content and a description.

   Why: actor_id partitions the entry by user, path organizes it, and description improves retrieval.

   You should see: The entry is stored for user-123.

4. 4.Call memory_store.search(actor_id="user-123", query="communication preferences", limit=10).

   Why: Search is how a later conversation recalls the preference, scoped to that actor.

   You should see: The results include the /preferences/communication.md entry.

5. 5.Call memory_store.grant_permission(principal_id) with your agent's service principal ID.

   Why: The store is the security boundary, and the agent's principal needs explicit access to it.

   You should see: The deployed agent can read and write the store.