fix(managed_agents): round 5 of memory cookbook review feedback

- Simplify status_idle handler to a single unconditional break
- Document run_turn return value in the docstring
- Restore inline 'Optional: run before cleanup' hint in the seeding cell
- Add catalog store cleanup reminder to the combine-stores snippet
- Tighten registry description and intro phrasing

Author: gaganb-ant

managed_agents/CMA_remember_user_preferences.ipynb

@@ -7,11 +7,11 @@
    "source": [
     "# Build agents that remember your users\n",
     "\n",
-    "Most agents start every conversation from scratch. A customer tells your shopping assistant their size, their budget, and which materials they avoid, and the next time they return, the agent has forgotten everything. They have to repeat themselves, and the experience feels transactional rather than personal.\n",
+    "Most agents start every conversation from scratch. A customer tells your shopping assistant their size, their budget, and which materials they avoid, and the next time they return, the agent has forgotten everything. They have to repeat themselves, and the experience feels generic rather than personal.\n",
     "\n",
-    "We just introduced **Memory** in Claude Managed Agents to solve this. A memory store is a persistent collection of text files that Claude can read and write during a session, and that survives across sessions. Anthropic hosts the storage, mounts it into the agent's environment, and prompts Claude on when and what to save \u2014 so there is no database, vector store, or retrieval pipeline for you to stand up. Attach the same store to every session for a given customer, and your agent accumulates knowledge about them over time.\n",
+    "We just introduced Memory in Claude Managed Agents to solve this. Think of it as a shared notebook your agent gets for each customer: Claude jots relevant things down during a session, and those notes are still there the next time the same customer comes back. Setup is a simple API call away.\n",
     "\n",
-    "In this guide you will build a personal shopping assistant for a retail brand. The agent will learn a customer's preferences during their first visit, save them to a memory store, and recall them automatically on the next visit without being told again.\n",
+    "In this guide you will build an example shopping assistant for a retail brand. The agent will learn a customer's preferences during their first visit, save them to a user-specific memory store, and recall them automatically on the next visit without being told again.\n",
     "\n",
     "## What you will build\n",
     "\n",
@@ -54,9 +54,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "da6a39d52f3e4b0a",
    "metadata": {},
-   "execution_count": null,
    "outputs": [],
    "source": [
     "%%capture\n",
@@ -65,9 +65,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 1,
    "id": "3f060791d5fa56fd8657f80c37f2d982",
    "metadata": {},
-   "execution_count": 1,
    "outputs": [],
    "source": [
     "import os\n",
@@ -92,13 +92,16 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 2,
    "id": "f3a4cbcc2086151619d476cc38eb19fc",
    "metadata": {},
-   "execution_count": 2,
    "outputs": [],
    "source": [
     "def run_turn(session_id: str, user_text: str) -> str:\n",
-    "    \"\"\"Send one user message and stream the agent's response until it goes idle.\"\"\"\n",
+    "    \"\"\"Send one user message and stream the agent's response until it goes idle.\n",
+    "\n",
+    "    Returns the agent's full text reply for callers who want it programmatically.\n",
+    "    \"\"\"\n",
     "    print(f\"\\n[user]  {user_text}\")\n",
     "    reply_parts: list[str] = []\n",
     "\n",
@@ -128,11 +131,8 @@
     "                    print(f\"  [memory] {event.name}: {target}\")\n",
     "\n",
     "            elif event.type == \"session.status_idle\":\n",
-    "                if event.stop_reason and event.stop_reason.type == \"end_turn\":\n",
-    "                    break\n",
-    "                # This notebook only sends user.message events, so end_turn is the\n",
-    "                # only idle reason we expect. Break on anything else as well so an\n",
-    "                # unexpected stop_reason (such as requires_action) cannot hang the loop.\n",
+    "                # Break on any idle reason so an unexpected stop_reason\n",
+    "                # (such as requires_action) cannot hang the loop.\n",
     "                break\n",
     "\n",
     "            elif event.type == \"session.status_terminated\":\n",
@@ -156,9 +156,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 3,
    "id": "e188613e44222908c586b1926f7a8426",
    "metadata": {},
-   "execution_count": 3,
    "outputs": [
     {
      "name": "stdout",
@@ -194,9 +194,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 4,
    "id": "39d254525e9703649b4e8a170d3b3d2d",
    "metadata": {},
-   "execution_count": 4,
    "outputs": [
     {
      "name": "stdout",
@@ -248,9 +248,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 5,
    "id": "ddb9a6c41adb8958ea43912ae86d775a",
    "metadata": {},
-   "execution_count": 5,
    "outputs": [
     {
      "name": "stdout",
@@ -286,9 +286,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 6,
    "id": "99218076c63d2339353963a2bfb0280b",
    "metadata": {},
-   "execution_count": 6,
    "outputs": [
     {
      "name": "stdout",
@@ -303,37 +303,37 @@
       "\n",
       "---\n",
       "\n",
-      "### \ud83c\udf3f Top Picks for You\n",
+      "### 🌿 Top Picks for You\n",
       "\n",
-      "#### 1. **Olive Moto Jacket** \u2014 ~$110\u2013$150\n",
+      "#### 1. **Olive Moto Jacket** — ~$110–$150\n",
       "A classic biker silhouette in a deep **olive green** faux leather. Look for styles with zip-detail sleeves and a fitted waist. Great for casual or edgy looks.\n",
       "- *Why you'll love it:* Earthy tone, very on-trend, versatile for layering.\n",
       "\n",
-      "#### 2. **Camel/Tan Oversized Blazer-Jacket** \u2014 ~$80\u2013$160\n",
+      "#### 2. **Camel/Tan Oversized Blazer-Jacket** — ~$80–$160\n",
       "A structured vegan leather blazer in **camel or tan** gives a polished, sophisticated vibe. Works dressed up or down.\n",
       "- *Why you'll love it:* Classic earth tone, medium sizing runs well in this style, timeless investment.\n",
       "\n",
-      "#### 3. **Rust/Cognac Bomber Jacket** \u2014 ~$90\u2013$170\n",
+      "#### 3. **Rust/Cognac Bomber Jacket** — ~$90–$170\n",
       "A **rust or cognac-toned** vegan leather bomber is a bold earth-tone statement piece with a relaxed, comfortable fit.\n",
       "- *Why you'll love it:* Rich warm color, bomber silhouettes are flattering in medium, cozy feel.\n",
       "\n",
-      "#### 4. **Terracotta Cropped Jacket** \u2014 ~$75\u2013$140\n",
+      "#### 4. **Terracotta Cropped Jacket** — ~$75–$140\n",
       "A cropped vegan leather jacket in **terracotta** pairs beautifully with high-waisted jeans or wide-leg trousers.\n",
       "- *Why you'll love it:* Trendy silhouette, stunning earthy hue, well within budget.\n",
       "\n",
       "---\n",
       "\n",
-      "### \ud83d\udecd\ufe0f Brands to Check Out\n",
+      "### 🛍️ Brands to Check Out\n",
       "Here are some brands known for quality vegan leather within your budget:\n",
-      "- **ASOS** \u2013 Wide range of faux leather styles in various earth tones\n",
-      "- **Free People** \u2013 Boho-leaning earth tone options\n",
-      "- **H&M** \u2013 Affordable vegan leather jackets in seasonal colors\n",
-      "- **Lulus** \u2013 Great selection of trendy vegan styles under $100\n",
-      "- **Noize** \u2013 A dedicated vegan outerwear brand, often has earthy tones under $200\n",
+      "- **ASOS** – Wide range of faux leather styles in various earth tones\n",
+      "- **Free People** – Boho-leaning earth tone options\n",
+      "- **H&M** – Affordable vegan leather jackets in seasonal colors\n",
+      "- **Lulus** – Great selection of trendy vegan styles under $100\n",
+      "- **Noize** – A dedicated vegan outerwear brand, often has earthy tones under $200\n",
       "\n",
       "---\n",
       "\n",
-      "Do any of these styles appeal to you? I can help narrow it down further \u2014 for example, do you prefer a **fitted or relaxed fit**, or a particular style like moto, bomber, or blazer? \ud83d\ude0a\n"
+      "Do any of these styles appeal to you? I can help narrow it down further — for example, do you prefer a **fitted or relaxed fit**, or a particular style like moto, bomber, or blazer? 😊\n"
      ]
     }
    ],
@@ -360,9 +360,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 7,
    "id": "8e9635b265c0205eb209d791613b1448",
    "metadata": {},
-   "execution_count": 7,
    "outputs": [
     {
      "name": "stdout",
@@ -382,7 +382,7 @@
       "- Usually under $200\n",
       "\n",
       "## Materials\n",
-      "- VEGAN LEATHER ONLY \u2014 absolutely no animal leather\n",
+      "- VEGAN LEATHER ONLY — absolutely no animal leather\n",
       "- (No other material restrictions noted yet)\n",
       "\n",
       "## Favorite Brands\n",
@@ -426,9 +426,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 8,
    "id": "1e1b4b4e8183a2f5fbf095f8f68caab6",
    "metadata": {},
-   "execution_count": 8,
    "outputs": [
     {
      "name": "stdout",
@@ -439,25 +439,25 @@
       "  [memory] read: /mnt/memory/shopper-preferences\n",
       "  [memory] bash: ls /mnt/memory/shopper-preferences/\n",
       "  [memory] read: /mnt/memory/shopper-preferences/preferences.md\n",
-      "[agent] Great news \u2014 I already have your preferences on file! Here's what I kept in mind for you:\n",
+      "[agent] Great news — I already have your preferences on file! Here's what I kept in mind for you:\n",
       "\n",
-      "- \ud83c\udfa8 **Style:** Earth tones (browns, tans, olive, camel, etc.)\n",
-      "- \ud83d\udcb0 **Budget:** Under $200\n",
-      "- \ud83c\udf31 **Materials:** Vegan leather only \u2014 no animal leather\n",
+      "- 🎨 **Style:** Earth tones (browns, tans, olive, camel, etc.)\n",
+      "- 💰 **Budget:** Under $200\n",
+      "- 🌱 **Materials:** Vegan leather only — no animal leather\n",
       "\n",
       "With that in mind, here are some work bag recommendations that would suit you perfectly:\n",
       "\n",
       "---\n",
       "\n",
-      "### \ud83d\udecd\ufe0f Top Picks for a Work Bag\n",
+      "### 🛍️ Top Picks for a Work Bag\n",
       "\n",
-      "1. **Structured Tote in Camel Vegan Leather** \u2014 A polished, professional look in a warm earth tone. Fits a laptop + daily essentials. Great desk-to-commute bag.\n",
+      "1. **Structured Tote in Camel Vegan Leather** — A polished, professional look in a warm earth tone. Fits a laptop + daily essentials. Great desk-to-commute bag.\n",
       "\n",
-      "2. **Olive Canvas & Vegan Leather Trim Laptop Bag** \u2014 A sleek crossbody/shoulder bag with a relaxed but put-together vibe. The canvas keeps it lightweight.\n",
+      "2. **Olive Canvas & Vegan Leather Trim Laptop Bag** — A sleek crossbody/shoulder bag with a relaxed but put-together vibe. The canvas keeps it lightweight.\n",
       "\n",
-      "3. **Tan Vegan Leather Satchel** \u2014 A classic work satchel with a top handle and shoulder strap. Timeless silhouette, stays under budget.\n",
+      "3. **Tan Vegan Leather Satchel** — A classic work satchel with a top handle and shoulder strap. Timeless silhouette, stays under budget.\n",
       "\n",
-      "4. **Terracotta Faux-Leather Tote** \u2014 A bold but grounded earth tone that adds personality to a work outfit without being over the top.\n",
+      "4. **Terracotta Faux-Leather Tote** — A bold but grounded earth tone that adds personality to a work outfit without being over the top.\n",
       "\n",
       "---\n",
       "\n",
@@ -506,19 +506,20 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 9,
    "id": "22425c8bded6cc68f57d6610c148d71f",
    "metadata": {},
-   "execution_count": 9,
    "outputs": [
     {
-     "output_type": "stream",
      "name": "stdout",
+     "output_type": "stream",
      "text": [
       "Seeded /purchase-history.md\n"
      ]
     }
    ],
    "source": [
+    "# Optional: run before the cleanup cell.\n",
     "seeded = client.beta.memory_stores.memories.create(\n",
     "    store.id,\n",
     "    path=\"/purchase-history.md\",\n",
@@ -564,6 +565,9 @@
     "        },\n",
     "    ],\n",
     ")\n",
+    "\n",
+    "# Remember to clean up the catalog store when you are done:\n",
+    "# client.beta.memory_stores.delete(catalog.id)\n",
     "```\n",
     "\n",
     "### Audit and correct\n",
@@ -583,9 +587,9 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 10,
    "id": "ee5e185e47607a3948f634faeb30dbce",
    "metadata": {},
-   "execution_count": 10,
    "outputs": [],
    "source": [
     "wait_for_idle_status(client, session_one.id)\n",
@@ -616,8 +620,8 @@
     "\n",
     "### Other notebooks in this series\n",
     "\n",
-    "- [`CMA_iterate_fix_failing_tests.ipynb`](CMA_iterate_fix_failing_tests.ipynb) \u2014 the entry-point notebook. Introduces agents, environments, sessions, file mounts, and the streaming event loop through a do-observe-fix loop on a failing test suite.\n",
-    "- [`CMA_operate_in_production.ipynb`](CMA_operate_in_production.ipynb) \u2014 production setup story: vault-backed MCP credentials, the `session.status_idled` webhook for HITL without long-lived connections, and the resource lifecycle CRUD verbs.\n",
+    "- [`CMA_iterate_fix_failing_tests.ipynb`](CMA_iterate_fix_failing_tests.ipynb) — the entry-point notebook. Introduces agents, environments, sessions, file mounts, and the streaming event loop through a do-observe-fix loop on a failing test suite.\n",
+    "- [`CMA_operate_in_production.ipynb`](CMA_operate_in_production.ipynb) — production setup story: vault-backed MCP credentials, the `session.status_idled` webhook for HITL without long-lived connections, and the resource lifecycle CRUD verbs.\n",
     "\n",
     "### Learn more\n",
     "\n",

registry.yaml

@@ -737,9 +737,8 @@
   - Multimodal
   - Tools
 - title: Build agents that remember your users
-  description: Give a Managed Agent a memory store so it learns and recalls a
-    customer's shopping preferences across separate sessions, plus patterns for
-    seeding, inspecting, and combining stores from your own application.
+  description: Give your Claude Managed Agents a Memory store so they learn and
+    remember your users' preferences across multiple interactions.
   path: managed_agents/CMA_remember_user_preferences.ipynb
   authors:
   - gaganb-ant