updated based on the PR comment

Author: emre-openai

examples/agents_sdk/session_memory.ipynb

@@ -13,9 +13,11 @@
    "id": "eeab798a",
    "metadata": {},
    "source": [
-    "AI agents often operate in **long-running, multi-turn interactions**, where keeping the right balance of context is critical. If too much is carried forward, the model risks distraction, inefficiency, or outright failure. If too little is preserved, the agent loses coherence. This guide focuses on two proven context management techniques—**trimming** and **compression**—to keep agents fast, reliable, and cost-efficient.\n",
+    "AI agents often operate in **long-running, multi-turn interactions**, where keeping the right balance of **context** is critical. If too much is carried forward, the model risks distraction, inefficiency, or outright failure. If too little is preserved, the agent loses coherence. \n",
     "\n",
-    "In this cookbook, we’ll explore how to **manage context effectively using the `Session` object from the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)**.\n",
+    "Here, context refers to the total window of tokens (input + output) that the model can attend to at once. For [GPT-5](https://platform.openai.com/docs/models/gpt-5), this capacity is up to 272k input tokens and 128k output tokens but even such a large window can be overwhelmed by uncurated histories, redundant tool results, or noisy retrievals. This makes context management not just an optimization, but a necessity.\n",
+    "\n",
+    "In this cookbook, we’ll explore how to **manage context effectively using the `Session` object from the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)**, focusing on two proven context management techniques—**trimming** and **compression**—to keep agents fast, reliable, and cost-efficient.\n",
     "\n",
     "#### Why Context Management Matters\n",
     "\n",
@@ -35,6 +37,18 @@
     "![Memory Comparison in AI Agents](../../images/memory_comparison.jpg)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "4ae8fdc3",
+   "metadata": {},
+   "source": [
+    "The [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses/create#responses-create-previous_response_id) includes **basic memory support** through built-in state and message chaining with `previous_response_id`.\n",
+    "\n",
+    "You can continue a conversation by passing the prior response’s `id` as `previous_response_id`, or you can manage context manually by collecting outputs into a list and resubmitting them as the `input` for the next response.\n",
+    "\n",
+    "What you don’t get is **automatic memory management**. That’s where the **Agents SDK** comes in. It provides [session memory](https://openai.github.io/openai-agents-python/sessions/) on top of Responses, so you no longer need to manually append `response.output` or track IDs yourself. The session becomes the **memory object**: you simply call `session.run(\"...\")` repeatedly, and the SDK handles context length, history, and continuity—making it far easier to build coherent, multi-turn agents."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "7068564c",
@@ -50,15 +64,76 @@
     "\n",
     "#### Techniques Covered\n",
     "\n",
-    "To address these challenges, we introduce two concrete approaches using OpenAI Agents SDK:\n",
+    "To address these challenges, we introduce two separate concrete approaches using OpenAI Agents SDK:\n",
+    "\n",
+    "- **Context Trimming** – dropping older turns while keeping the last N turns.\n",
+    "  - **Pros**\n",
+    "\n",
+    "    * **Deterministic & simple:** No summarizer variability; easy to reason about state and to reproduce runs.\n",
+    "    * **Zero added latency:** No extra model calls to compress history.\n",
+    "    * **Fidelity for recent work:** Latest tool results, parameters, and edge cases stay verbatim—great for debugging.\n",
+    "    * **Lower risk of “summary drift”:** You never reinterpret or compress facts.\n",
+    "\n",
+    "    **Cons**\n",
     "\n",
-    "1. **Trimming Messages** – dropping older turns while keeping the last N turns.\n",
-    "2. **Summarizing Messages** – compressing prior exchanges into structured, shorter representations.\n",
+    "    * **Forgets long-range context abruptly:** Important earlier constraints, IDs, or decisions can vanish once they scroll past N.\n",
+    "    * **User experience “amnesia”:** Agent can appear to “forget” promises or prior preferences midway through long sessions.\n",
+    "    * **Wasted signal:** Older turns may contain reusable knowledge (requirements, constraints) that gets dropped.\n",
+    "    * **Token spikes still possible:** If a recent turn includes huge tool payloads, your last-N can still blow up the context.\n",
     "\n",
+    "  - **Best when**\n",
     "\n",
+    "    - Your tasks in the conversation is indepentent from each other with non-overlapping context that does not reuqire carrying previous details further.\n",
+    "    - You need predictability, easy evals, and low latency (ops automations, CRM/API actions).\n",
+    "    - The conversation’s useful context is local (recent steps matter far more than distant history).\n",
+    "\n",
+    "- **Context Summarization** – compressing prior messages(assistant, user, tools, etc.) into structured, shorter summaries injected into the conversation history.\n",
+    "\n",
+    "  - **Pros**\n",
+    "\n",
+    "    * **Retains long-range memory compactly:** Past requirements, decisions, and rationales persist beyond N.\n",
+    "    * **Smoother UX:** Agent “remembers” commitments and constraints across long sessions.\n",
+    "    * **Cost-controlled scale:** One concise summary can replace hundreds of turns.\n",
+    "    * **Searchable anchor:** A single synthetic assistant message becomes a stable “state of the world so far.”\n",
+    "\n",
+    "    **Cons**\n",
+    "\n",
+    "    * **Summarization loss & bias:** Details can be dropped or misweighted; subtle constraints may vanish.\n",
+    "    * **Latency & cost spikes:** Each refresh adds model work (and potentially tool-trim logic).\n",
+    "    * **Compounding errors:** If a bad fact enters the summary, it can **poison** future behavior (“context poisoning”).\n",
+    "    * **Observability complexity:** You must log summary prompts/outputs for auditability and evals.\n",
+    "\n",
+    "  - **Best when**\n",
+    "\n",
+    "    - You have use cases where your tasks needs context collected accross the flow such as  planning/coaching, RAG-heavy analysis, policy Q&A.\n",
+    "    - You need continuity over long horizons and carry the important details further to solve related tasks.\n",
+    "    - Sessions exceed N turns but must preserve decisions, IDs, and constraints reliably.\n",
     "<br>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "3765f2b8",
+   "metadata": {},
+   "source": [
+    "**Quick comparison**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "940e5bf7",
+   "metadata": {},
+   "source": [
+    "| Dimension         | **Trimming (last-N turns)**         | **Summarizing (older → generated summary)** |\n",
+    "| ----------------- | ------------------------------- | ------------------------------------ |\n",
+    "| Latency / Cost    | Lowest (no extra calls)     | Higher at summary refresh points |\n",
+    "| Long-range recall | Weak (hard cut-off)         | Strong (compact carry-forward)   |\n",
+    "| Risk type         | Context loss                | Context distortion/poisoning     |\n",
+    "| Observability     | Simple logs                 | Must log summary prompts/outputs |\n",
+    "| Eval stability    | High                        | Needs robust summary evals       |\n",
+    "| Best for          | Tool-heavy ops, short workflows | Analyst/concierge, long threads      |\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "fc613968",
@@ -68,7 +143,7 @@
     "\n",
     "Before running this cookbook, you must set up the following accounts and complete a few setup actions. These prerequisites are essential to interact with the APIs used in this project.\n",
     "\n",
-    "#### Step0: OpenAI Account\n",
+    "#### Step0: OpenAI Account and `OPENAI_API_KEY`\n",
     "\n",
     "- **Purpose:**  \n",
     "  You need an OpenAI account to access language models and use the Agents SDK featured in this cookbook.\n",
@@ -77,14 +152,34 @@
     "  [Sign up for an OpenAI account](https://openai.com) if you don’t already have one. Once you have an account, create an API key by visiting the [OpenAI API Keys page](https://platform.openai.com/api-keys)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "094205e7",
+   "metadata": {},
+   "source": [
+    "**Before running the workflow, set your environment variables:**\n",
+    "\n",
+    "```\n",
+    "# Your openai key\n",
+    "os.environ[\"OPENAI_API_KEY\"] = \"sk-proj-...\"\n",
+    "```\n",
+    "\n",
+    "Alternatively, you can set your OpenAI API key for use by the agents via the `set_default_openai_key` function by importing agents library .\n",
+    "\n",
+    "```\n",
+    "from agents import set_default_openai_key\n",
+    "set_default_openai_key(\"YOUR_API_KEY\")\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "3cd9a109",
    "metadata": {},
    "source": [
     "#### Step1: Install the Required Libraries\n",
     "\n",
-    "Below we install the `openai-agents` library (the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)"
+    "Below we install the `openai-agents` library ([OpenAI Agents SDK](https://github.com/openai/openai-agents-python))"
    ]
   },
   {
@@ -130,7 +225,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "fe54469a",
    "metadata": {},
    "outputs": [
@@ -201,7 +296,7 @@
    "id": "b8074e05",
    "metadata": {},
    "source": [
-    "## 1. Context Trimming "
+    "## Context Trimming"
    ]
   },
   {
@@ -577,7 +672,7 @@
    "id": "d6fa349f",
    "metadata": {},
    "source": [
-    "## 2. Context Summarization "
+    "## Context Summarization"
    ]
   },
   {
@@ -1150,12 +1245,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 248,
+   "execution_count": null,
    "id": "5448ce93",
    "metadata": {},
    "outputs": [],
    "source": [
-    "full_history = await session.get_items_with_metadata()\n"
+    "full_history = await session.get_items_with_metadata()"
    ]
   },
   {