Skip to main content
Last updated on

Managed agent memory

Beta

This feature is in Beta.

Managed agent memory gives your agents durable, long-term memory that persists across conversations. Databricks stores the memory in Lakebase and manages the storage, indexing, and semantic search for you, so your agents can remember user preferences, past decisions, and accumulated context without you operating a database.

note

During the preview, you are billed for the underlying Lakebase instance that stores your memory entries. No additional charges apply for managed agent memory itself. Pricing is subject to change as the preview progresses.

Use managed memory when you want your agents to:

  • Remember user preferences, facts, and decisions across separate conversations.
  • Personalize responses based on what an agent learned in earlier sessions.
  • Share accumulated knowledge across agents and projects.
  • Improve in accuracy and efficiency over time.

Managed memory works with agents built on any framework. For short-term conversation history within a single interaction, use managed agent sessions.

How managed memory works​

Managed agent memory resource hierarchy: a memory store contains many memory entries, each identified by actor_id, optional session_id, and path, and holding content and a description.

Managed memory has two levels:

  • A memory store is the workspace-scoped container for an agent's memories. Creating a store provisions the backing Lakebase storage automatically. You address a store by its display_name.
  • A memory entry is an individual piece of content in a store. Each entry has a free-form text content, a short description used for retrieval, and a set of fields that organize and partition it:
    • actor_id (required): who the memory belongs to, such as an end user or another agent.
    • session_id (optional): records which session the memory was captured from, for tracing and provenance. Leave it unset for memory that isn't tied to a specific session.
    • path (required): a filesystem-like path that organizes entries within an actor, such as /preferences/response-style.md.

An entry is uniquely identified by the combination of actor_id, session_id, and path.

Retrieval​

Retrieve memory two ways:

  • List entries for an actor, optionally filtered by session_id or a path prefix. Use this to browse or render an index of what an agent knows.
  • Search entries for an actor with a natural-language query. Search returns the most relevant entries ranked by a full-text (BM25) relevance score.

Requirements​

  • Python 3.10 or above, to use Mason (Databricks' Python client and CLI for agent APIs), which the examples below use. You can also call the REST API directly from any language, with no Python requirement.

Get started​

These examples set up managed memory for a support agent: they create a memory store, save a user's preference, and recall it in a later conversation. Choose the client that fits your project. A memory store's display_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.

Mason is Databricks' Python client and CLI for agent APIs. It authenticates with the Databricks SDK's WorkspaceClient.

  1. Install Mason:

    Bash
    pip install databricks-mason

  2. Create a memory store for your agent. MasonClient authenticates with your WorkspaceClient credentials:

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_mason import MasonClient

    mason = MasonClient(WorkspaceClient())
    memory_store = mason.memory_stores.create("support-agent-memory")

  3. Save a memory after the agent learns something durable about a user. actor_id is whose memory this is, path organizes it within that actor, and description improves retrieval:

    Python
    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",
    )

  4. Recall the user's memories in a later conversation with a natural-language search:

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

Give your agent memory tools​

To let an agent decide when to save and recall memory, wrap the client operations as tools and instruct the agent on when to use them in its system prompt. Set the actor_id in trusted application code from the verified end-user identity. Never let the model choose whose memory to read or write.

The following example wraps the Mason memory_store from Get started as tools for the OpenAI Agents SDK.

Python
from agents import Agent, function_tool

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]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences and recall them when relevant.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

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

Partition and secure memory​

Within a store, actor_id is how you separate whose memories are whose. Every list and search is scoped to a single actor_id, so pick the strategy that matches what your agent needs to remember:

  • Private memory for each user: Set actor_id to the verified end-user identity. Each user gets their own partition, and the agent only recalls that user's entries.
    • Example: A support agent remembers one user's communication preferences and past tickets.
  • Shared memory for a group: Set actor_id to a fixed key you choose, such as a team, project, or organization ID. Everyone reads and writes the same memories.
    • Example: A team agent remembers a shared glossary of company terms and internal conventions.
  • Memory split by something else: Build actor_id from your own values, such as a tenant ID or a user:project composite.
    • Example: A multi-tenant app sets actor_id to {tenant}:{user} so each customer's users stay isolated from one another.

Set actor_id in your application code from trusted caller context: the verified end-user identity for per-user memory, or a trusted team or project key for shared memory. Never let the model choose it. If your strategy depends on an end-user identity, reject requests that don't carry one rather than falling back to a shared actor_id.

warning

actor_id separates memories, but it is not an access control. Managed memory stores are workspace-scoped, so any principal that can reach a store can read and write every entry across all actors. The store, not the actor, is the security boundary. For strict isolation between tenants or users, create a separate memory store per boundary.

To let another principal, such as your agent's service principal, use a store, grant it access with the store's grant-permission operation (memory_store.grant_permission(principal_id) in Mason).

Limitations​

  • Managed memory provides long-term memory only. For short-term conversation history, see managed agent sessions.
  • Search is a relevance-ranked, full-text (BM25) operation that returns a top-N result set of up to 100 entries. It does not support pagination or vector similarity search.
  • Access control is enforced at the store level. Per-entry and per-actor access control are not available.
  • The store display_name is immutable after creation. Only description can be updated.

Next steps​

On this page