tutorialintermediate

Build agents that remember your users Apr 2026 • Agent Patterns Tools Give your Claude Managed Agents a Memory store so they learn and remember your users' preferences across multiple interactions.

April 28, 2026cookbook

This guide demonstrates how to build Claude Managed Agents with persistent memory capabilities that learn and retain user preferences across multiple sessions. Users create a memory store, configure a shopping agent with file access tools, and show how the agent automatically reads and updates customer preferences on repeat visits. The memory system uses a simple file-based approach mounted at /mnt/memory/ that both the agent and application can access via API.

Key Points

•Memory stores are named containers scoped to your workspace, typically one per end user with mappings stored in your database
•Memory stores appear as directories (/mnt/memory/{store-name}) inside the agent's environment accessible via standard file tools
•Attach memory stores to sessions through the resources array with read_write access and per-session instructions
•The agent automatically checks memory at conversation start and updates it whenever learning new user preferences
•Both the agent and your application have full read/write access to memory files through the REST API for seeding, auditing, and exporting
•Use the agent_toolset_20260401 type to give agents built-in file tools for reading and writing memory without manual tool definition
•Memory store descriptions are rendered into the agent's system prompt to guide how Claude uses the store
•The event-driven API streams events until the session goes idle, allowing you to track memory operations via agent.tool_use events
•Create agents and environments once and reuse them across many customers and sessions for efficiency
•This is a beta feature; the API may change before general availability

Found this useful? Add it to a playbook for a step-by-step implementation guide.

Workflow Diagram

Start Process

Step A

Step B

Step C

Complete

Quality★★★★★

Concepts

Memory Systems Use Cases Skills & Tools Setup & Infrastructure Agent Teams Tool Use Memory & Identity Installation

Artifacts (4)

Memory Store Creationpythonscript

store = client.beta.memory_stores.create(
    name="Shopper Preferences",
    description=(
        "Personal shopping preferences for a single customer: "
        "sizes, style, budget, favorite brands, and materials to avoid."
    ),
)
print(store.id)  # memstore_01...

Shopping Agent Configurationpythonconfig

agent = client.beta.agents.create(
    name="Personal Shopper",
    model=MODEL,
    system=(
        "You are a personal shopping assistant for a retail brand. "
        "Help the customer find products that match their taste and budget, "
        "and remember what you learn about them for future visits."
    ),
    tools=[
        {
            "type": "agent_toolset_20260401",
            "default_config": {
                "enabled": True,
                "permission_policy": {
                    "type": "always_allow"
                },
            },
        }
    ],
)

Session with Memory Resourcepythonscript

memory_resource = {
    "type": "memory_store",
    "memory_store_id": store.id,
    "access": "read_write",
    "instructions": (
        "This customer's personal preferences: sizes, style, budget, and "
        "materials to avoid. Check it at the start of every conversation "
        "and update it whenever you learn something new."
    ),
}

session_one = client.beta.sessions.create(
    agent={
        "type": "agent",
        "id": agent.id,
        "version": agent.version
    },
    environment_id=environment.id,
    resources=[memory_resource],
)

Conversational Turn Helperpythonscript

def run_turn(session_id: str, user_text: str) -> str:
    """Send one user message and stream the agent's response until it goes idle."""
    print(f"\n[user] {user_text}")
    reply_parts: list[str] = []
    
    with client.beta.sessions.events.stream(session_id) as stream:
        client.beta.sessions.events.send(
            session_id,
            events=[
                {
                    "type": "user.message",
                    "content": [{"type": "text", "text": user_text}],
                }
            ],
        )
        
        for event in stream:
            if event.type == "agent.message":
                for block in event.content:
                    if block.type == "text":
                        reply_parts.append(block.text)
                        print(f"[agent] {block.text}")
            elif event.type == "agent.tool_use":
                inp = event.input or {}
                target = inp.get("file_path") or inp.get("command", "")
                if "/mnt/memory/" in str(target):
                    print(f"[memory] {event.name}: {target}")
            elif event.type == "session.status_idle":
                break
            elif event.type == "session.status_terminated":
                break
        
        wait_for_idle_status(client, session_id)
    
    return "".join(reply_parts)