Memory & Context Management with Claude Sonnet 4.5

[Pines-Cheng]

Claude Sonnet 4.5 的记忆与上下文管理

学习如何使用 Claude 的记忆工具和上下文编辑功能构建能够跨对话学习和改进的 AI 智能体。

目录

1. 简介：为什么记忆很重要
2. 使用场景
3. 快速入门示例
4. 工作原理
5. 代码审查助手演示
6. 实际应用
7. 最佳实践

设置

VSCode 用户

# 1. 创建虚拟环境
python -m venv .venv

# 2. 激活虚拟环境
source .venv/bin/activate  # macOS/Linux
# 或者: .venv\Scripts\activate  # Windows

# 3. 安装依赖
pip install -r requirements.txt

# 4. 在 VSCode 中：选择 .venv 作为内核（右上角）

API 密钥

cp .env.example .env
# 编辑 .env 并添加你的 ANTHROPIC_API_KEY

从这里获取你的 API 密钥：https://console.anthropic.com/

1. 简介：为什么记忆很重要 {#introduction}

本教程演示了Effective context engineering for AI agents中描述的上下文工程模式的实际实现。该文章涵盖了为什么上下文是有限资源、注意力预算如何工作，以及构建有效智能体的策略——这些技术你将在这里看到实际应用。

问题

大型语言模型具有有限的上下文窗口（Claude 4 为 200k 个令牌）。虽然这看起来很大，但会出现几个挑战：

• 上下文限制：长对话或复杂任务可能超出可用上下文
• 计算成本：处理大型上下文很昂贵 - 注意力机制呈二次方扩展
• 重复模式：跨对话的相似任务每次都需要重新解释上下文
• 信息丢失：当上下文填满时，早期的重要信息会丢失

解决方案

Claude Sonnet 4.5 引入了两个强大的功能：

1. 记忆工具 (memory_20250818)：启用跨对话学习

   • Claude 可以记录学到的内容以供将来参考
   • 基于文件的系统，位于 /memories 目录下
   • 客户端实现让你完全控制

2. 上下文编辑 (clear_tool_uses_20250919)：自动管理上下文

   • 当上下文增长过大时清除旧的工具结果
   • 保留最近的上下文同时保存记忆
   • 可配置的触发器和保留策略

好处

构建随时间在特定任务上变得更好的 AI 智能体：

• 会话 1：Claude 解决问题，记录模式
• 会话 2：Claude 立即应用学到的模式（更快！）
• 长会话：上下文编辑保持对话可管理

可以把它想象成给 Claude 一个笔记本来记笔记并回顾——就像人类做的那样。

2. 使用场景 {#use-cases}

记忆和上下文管理启用了强大的新工作流程：

🔍 代码审查助手

• 从过去的审查中学习调试模式
• 在未来会话中立即识别相似的错误
• 构建团队特定的代码质量知识
• 生产就绪：与 claude-code-action 集成进行 GitHub PR 审查

📚 研究助手

• 在多个会话中积累主题知识
• 连接不同研究线程的见解
• 维护参考书目和来源跟踪

💬 客户支持机器人

• 学习用户偏好和沟通风格
• 记住常见问题和解决方案
• 从交互中构建产品知识库

📊 数据分析助手

• 记住数据集模式和异常
• 存储有效的分析技术
• 随时间构建领域特定见解

支持的模型：Claude Opus 4 (claude-opus-4-20250514)、Claude Opus 4.1 (claude-opus-4-1-20250805)、Claude Sonnet 4 (claude-sonnet-4-20250514) 和 Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

本教程专注于代码审查助手，因为它清楚地演示了记忆（学习模式）和上下文编辑（处理长审查）。

3. 快速入门示例 {#quick-start}

让我们通过简单的示例看看记忆和上下文管理的实际应用。

设置

首先，安装依赖并配置你的环境：

# 安装所需包
# 选项 1：从 requirements.txt
# %pip install -q -r requirements.txt

# 选项 2：直接安装
%pip install -q anthropic python-dotenv ipykernel

⚠️ 重要：在此目录中创建 .env 文件：

# 复制 .env.example 到 .env 并添加你的 API 密钥
cp .env.example .env

然后编辑 .env 添加你从 https://console.anthropic.com/ 获得的 Anthropic API 密钥

import os
from typing import Any, cast

from anthropic import Anthropic
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

API_KEY = os.getenv("ANTHROPIC_API_KEY")
MODEL = os.getenv("ANTHROPIC_MODEL")

if not API_KEY:
    raise ValueError(
        "未找到 ANTHROPIC_API_KEY。"
        "复制 .env.example 到 .env 并添加你的 API 密钥。"
    )

if not MODEL:
    raise ValueError(
        "未找到 ANTHROPIC_MODEL。"
        "复制 .env.example 到 .env 并设置模型。"
    )

MODEL = cast(str, MODEL)

client = Anthropic(api_key=API_KEY)

print("✓ API 密钥已加载")
print(f"✓ 使用模型：{MODEL}")

示例 1：基本记忆使用

让我们看看 Claude 如何使用记忆来存储信息以供将来参考。

辅助函数

这些示例使用来自 demo_helpers.py 的辅助函数：

• run_conversation_loop()：处理 API 对话循环

  • 调用启用了记忆工具的 Claude API
  • 执行工具使用（记忆操作）
  • 继续直到 Claude 停止使用工具
  • 返回最终响应

• run_conversation_turn()：单轮对话（在示例 3 中使用）

  • 与上面相同，但在一次 API 调用后返回
  • 当你需要细粒度控制时很有用

• print_context_management_info()：显示上下文清理统计

  • 显示节省的令牌、清除的工具使用
  • 帮助可视化上下文编辑何时触发

⚠️ 记忆清除说明

以下单元格清除所有记忆文件，为此演示提供干净的起点。这对于多次运行笔记本以查看一致结果很有用。

在生产应用中，你应该仔细考虑是否清除所有记忆，因为这会永久删除学到的模式。考虑使用选择性删除或将记忆组织到项目特定的目录中。

# 导入辅助函数
from memory_demo.demo_helpers import run_conversation_loop, run_conversation_turn, print_context_management_info
from memory_tool import MemoryToolHandler

# 初始化
client = Anthropic(api_key=API_KEY)
memory = MemoryToolHandler(base_path="./demo_memory")

# 清除任何现有记忆以重新开始
print("🧹 清除之前的记忆...")
memory.clear_all_memory()
print("✓ 记忆已清除\n")

# 加载带有竞态条件错误的示例代码
with open("memory_demo/sample_code/web_scraper_v1.py", "r") as f:
    code_to_review = f.read()

messages = [
    {
        "role": "user",
        "content": f"我正在审查一个多线程网络爬虫，它有时返回的结果比预期少。计数在运行间不一致。你能找到问题吗？\n\n```python\n{code_to_review}\n```"
    }
]

print("=" * 60)
print("📝 会话 1：从错误中学习")
print("=" * 60)

# 运行对话循环
response = run_conversation_loop(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="你是一个代码审查员。",
    max_tokens=2048,
    max_turns=5,
    verbose=True
)

print("\n" + "=" * 60)
print("✅ 会话 1 完成！")
print("=" * 60)

发生了什么？

1. Claude 检查了它的记忆（首次运行时为空）
2. 识别了错误：竞态条件 - 多个线程在没有同步的情况下修改共享状态（self.results 和 self.failed_urls）
3. 在记忆中存储了并发模式以供将来参考

现在让我们看看魔法 - Claude 在新对话中应用这个学到的模式：

示例 2：跨对话学习

开始一个全新的对话 - 记忆持续存在！

# 新对话（空消息）
# 加载具有类似并发问题的 API 客户端代码
with open("memory_demo/sample_code/api_client_v1.py", "r") as f:
    code_to_review = f.read()

messages = [
    {
        "role": "user",
        "content": f"审查这个 API 客户端代码：\n\n```python\n{code_to_review}\n```"
    }
]

print("=" * 60)
print("🚀 会话 2：应用学到的模式")
print("=" * 60)

# 运行对话循环
response = run_conversation_loop(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="你是一个代码审查员。",
    max_tokens=2048,
    max_turns=5,
    verbose=True
)

print("\n" + "=" * 60)
print("✅ 会话 2 完成！")
print("=" * 60)

注意区别：

• Claude 立即检查记忆并找到了线程安全/并发模式
• 立即识别了异步代码中的类似问题，无需重新学习
• 响应更快，因为它应用了关于共享可变状态的存储知识

这就是跨对话学习的实际应用！

示例 3：在保留记忆的同时清除上下文

在有许多代码文件的长审查会话中会发生什么？

• 上下文被之前审查的工具结果填满
• 但记忆（学到的模式）必须持续存在！

让我们触发上下文编辑来看看 Claude 如何自动管理这个。

配置说明： 我们使用 clear_at_least: 50 个令牌，因为记忆工具操作的结果很小（每个约 50-150 个令牌）。在生产环境中，对于更大的工具结果（如网络搜索或代码执行），你会使用更高的值，如 3000-5000 个令牌。

# 配置上下文管理以便演示时积极清除
CONTEXT_MANAGEMENT = {
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 5000},  # 更低的阈值以更快触发清除
            "keep": {"type": "tool_uses", "value": 1},  # 只保留最后一个工具使用
            "clear_at_least": {"type": "input_tokens", "value": 50}
        }
    ]
}

# 从之前的会话继续 - 记忆持续存在！
# 添加多个代码审查以建立上下文

print("=" * 60)
print("📚 会话 3：带上下文清除的长审查会话")
print("=" * 60)
print()

# 审查 1：数据处理器（更大的文件）
with open("memory_demo/sample_code/data_processor_v1.py", "r") as f:
    data_processor_code = f.read()

messages.extend([
    {
        "role": "user",
        "content": f"审查这个数据处理器：\n\n```python\n{data_processor_code}\n```"
    }
])

print("📝 审查 1：数据处理器")
response = run_conversation_turn(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="你是一个代码审查员。",
    context_management=CONTEXT_MANAGEMENT,
    max_tokens=2048,
    verbose=True
)

# 将响应添加到消息中
messages.append({"role": "assistant", "content": response[1]})
if response[2]:
    messages.append({"role": "user", "content": response[2]})

print(f"  📊 输入令牌：{response[0].usage.input_tokens:,}")
context_cleared, saved = print_context_management_info(response[0])
print()

# 审查 2：添加 SQL 代码
with open("memory_demo/sample_code/sql_query_builder.py", "r") as f:
    sql_code = f.read()

messages.extend([
    {
        "role": "user",
        "content": f"审查这个 SQL 查询构建器：\n\n```python\n{sql_code}\n```"
    }
])

print("📝 审查 2：SQL 查询构建器")
response = run_conversation_turn(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="你是一个代码审查员。",
    context_management=CONTEXT_MANAGEMENT,
    max_tokens=2048,
    verbose=True
)

messages.append({"role": "assistant", "content": response[1]})
if response[2]:
    messages.append({"role": "user", "content": response[2]})

print(f"  📊 输入令牌：{response[0].usage.input_tokens:,}")
context_cleared, saved = print_context_management_info(response[0])
print()

print("=" * 60)
print("✅ 会话 3 完成！")
print("=" * 60)

刚才发生了什么？

随着多次审查期间上下文的增长：

1. 上下文清除自动触发，当输入令牌超过 5,000 时
2. 旧的工具结果被移除 - 清除了 2 个工具使用，每次节省约 66 个令牌
3. 记忆文件保持完整 - Claude 仍然可以查询学到的模式
4. 令牌使用继续增长，但由于清除而增长速度较慢

这演示了关键好处：

• 短期记忆（带工具结果的对话上下文）→ 清除以节省空间
• 长期记忆（/memories 中存储的模式）→ 跨会话持续存在

为什么令牌节省这么少？ 记忆工具操作返回紧凑的结果（文件路径、成功消息）。str_replace 操作只返回"文件编辑成功"加上元数据。在具有更大工具结果（返回完整文章的网络搜索、具有长输出的代码执行）的生产用例中，上下文清除将节省数千个令牌。

让我们验证记忆在清除后仍然存在：

# 验证记忆在上下文清除后持续存在
import os

print("📂 demo_memory/ 中的记忆文件：")
print()

for root, dirs, files in os.walk("./demo_memory"):
    # 计算显示的相对路径
    level = root.replace("./demo_memory", "").count(os.sep)
    indent = "  " * level
    folder_name = os.path.basename(root) or "demo_memory"
    print(f"{indent}{folder_name}/")
    
    sub_indent = "  " * (level + 1)
    for file in files:
        file_path = os.path.join(root, file)
        size = os.path.getsize(file_path)
        print(f"{sub_indent}├── {file} ({size} 字节)")

print()
print("✅ 尽管上下文清除，所有学到的模式都得到保留！")

4. 工作原理 {#how-it-works}

记忆工具架构

记忆工具是客户端的 - 你控制存储。Claude 进行工具调用，你的应用程序执行它们。

记忆工具命令

命令	描述	示例
view	显示目录或文件内容	{"command": "view", "path": "/memories"}
create	创建或覆盖文件	{"command": "create", "path": "/memories/notes.md", "file_text": "..."}
str_replace	替换文件中的文本	{"command": "str_replace", "path": "...", "old_str": "...", "new_str": "..."}
insert	在行号处插入文本	{"command": "insert", "path": "...", "insert_line": 2, "insert_text": "..."}
delete	删除文件或目录	{"command": "delete", "path": "/memories/old.txt"}
rename	重命名或移动文件	{"command": "rename", "old_path": "...", "new_path": "..."}

查看 memory_tool.py 了解包含路径验证和安全措施的完整实现。

理解演示代码

来自 code_review_demo.py 的关键实现细节：

class CodeReviewAssistant:
    def __init__(self, memory_storage_path="./memory_storage"):
        self.client = Anthropic(api_key=API_KEY)
        self.memory_handler = MemoryToolHandler(base_path=memory_storage_path)
        self.messages = []
    
    def review_code(self, code, filename, description=""):
        # 1. 添加用户消息
        self.messages.append({...})
        
        # 2. 带工具执行的对话循环
        while True:
            response = self.client.beta.messages.create(
                model=MODEL,
                system=self._create_system_prompt(),
                messages=self.messages,
                tools=[{"type": "memory_20250818", "name": "memory"}],
                betas=["context-management-2025-06-27"],
                context_management=CONTEXT_MANAGEMENT
            )
            
            # 3. 执行工具使用
            tool_results = []
            for content in response.content:
                if content.type == "tool_use":
                    result = self._execute_tool_use(content)
                    tool_results.append({...})
            
            # 4. 如果有工具使用则继续，否则完成
            if tool_results:
                self.messages.append({"role": "user", "content": tool_results})
            else:
                break

关键模式：在有工具使用时持续调用 API，执行它们并将结果反馈回去。

Claude 实际学到了什么

这就是记忆强大的原因 - 语义模式识别，而不仅仅是语法：

会话 1：基于线程的网络爬虫

# 错误：竞态条件
class WebScraper:
    def __init__(self):
        self.results = []  # 共享状态！
    
    def scrape_urls(self, urls):
        with ThreadPoolExecutor() as executor:
            for future in as_completed(futures):
                self.results.append(future.result())  # 竞态！

Claude 在记忆中存储的内容（示例文件：/memories/concurrency_patterns/thread_safety.md）：

当 Claude 遇到这种模式时，它将以下见解存储到其记忆文件中：

• 症状：并发操作中的不一致结果
• 原因：多个线程修改的共享可变状态（列表/字典）
• 解决方案：使用锁、线程安全数据结构或返回结果
• 红旗：线程回调中的实例变量、未使用的锁、计数器增量

---

会话 2：异步 API 客户端（新对话！）

Claude 首先检查记忆，找到线程安全模式，然后：

1. 识别异步代码中的类似模式（协程也可以交错）
2. 立即应用解决方案（无需重新学习）
3. 解释并参考存储的知识

# Claude 立即发现这个：
async def fetch_all(self, endpoints):
    for coro in asyncio.as_completed(tasks):
        self.responses.append(await coro)  # 相同模式！

---

为什么这很重要：

• ❌ 语法检查器完全错过竞态条件
• ✅ Claude 学习架构模式并跨上下文应用它们
• ✅ 跨语言：模式也适用于 Go、Java、Rust 并发
• ✅ 变得更好：每次审查都会添加到知识库中

示例代码文件

演示使用这些示例文件（都有并发/线程安全错误）：

• memory_demo/sample_code/web_scraper_v1.py - 竞态条件：线程修改共享状态
• memory_demo/sample_code/api_client_v1.py - 异步上下文中的类似并发错误
• memory_demo/sample_code/data_processor_v1.py - 长会话演示的多个并发问题

让我们看看其中一个：

memory_demo/sample_code/web_scraper_v1.py

"""
具有竞态条件错误的并发网络爬虫。
多个线程在没有同步的情况下修改共享状态。
"""

import time
from concurrent.futures import ThreadPoolExecutor, as_completed
from typing import List, Dict

import requests


class WebScraper:
    """并发获取多个 URL 的网络爬虫。"""

    def __init__(self, max_workers: int = 10):
        self.max_workers = max_workers
        self.results = []  # 错误：多个线程访问的共享可变状态！
        self.failed_urls = []  # 错误：另一个竞态条件！

    def fetch_url(self, url: str) -> Dict[str, any]:
        """获取单个 URL 并返回结果。"""
        try:
            response = requests.get(url, timeout=5)
            response.raise_for_status()
            return {
                "url": url,
                "status": response.status_code,
                "content_length": len(response.content),
            }
        except requests.exceptions.RequestException as e:
            return {"url": url, "error": str(e)}

    def scrape_urls(self, urls: List[str]) -> List[Dict[str, any]]:
        """
        并发爬取多个 URL。

        错误：self.results 被多个线程访问而没有锁定！
        这会导致结果丢失或损坏的竞态条件。
        """
        with ThreadPoolExecutor(max_workers=self.max_workers) as executor:
            futures = [executor.submit(self.fetch_url, url) for url in urls]

            for future in as_completed(futures):
                result = future.result()

                # 竞态条件：多个线程同时向 self.results 追加
                if "error" in result:
                    self.failed_urls.append(result["url"])  # 竞态条件
                else:
                    self.results.append(result)  # 竞态条件

        return self.results

错误：多个线程在没有锁定的情况下修改 self.results 和 self.failed_urls！

Claude 将：

1. 识别竞态条件
2. 在 /memories/concurrency_patterns/thread_safety.md 中存储模式
3. 在会话 2 中将此并发模式应用于异步代码

演示概述

我们构建了一个完整的代码审查助手。实现在 memory_demo/code_review_demo.py 中。

运行交互式演示：

python memory_demo/code_review_demo.py

演示展示了：

1. 会话 1：审查带有错误的 Python 代码 → Claude 学习模式
2. 会话 2：审查类似代码（新对话）→ Claude 应用模式
3. 会话 3：长审查会话 → 上下文编辑保持可管理性

7. 最佳实践与安全 {#best-practices}

记忆管理

应该做的：

• ✅ 存储任务相关模式，而不是对话历史
• ✅ 使用清晰的目录结构组织
• ✅ 使用描述性文件名
• ✅ 定期审查和清理记忆

不应该做的：

• ❌ 存储敏感信息（密码、API 密钥、PII）
• ❌ 让记忆无限增长
• ❌ 不加选择地存储所有内容

安全：路径遍历保护

关键：始终验证路径以防止目录遍历攻击。查看 memory_tool.py 了解实现。

安全：记忆中毒

⚠️ 关键风险：记忆文件被读回到 Claude 的上下文中，使它们成为提示注入的潜在载体。

缓解策略：

1. 内容清理：在存储前过滤危险模式
2. 记忆范围隔离：按用户/按项目隔离
3. 记忆审计：记录和扫描所有记忆操作
4. 提示工程：指示 Claude 忽略记忆中的指令

查看 memory_tool.py 了解完整的安全实现，以及 tests/ 中的测试。

下一步

资源

• API 文档：Claude API 参考
• 使用文档：记忆工具
• GitHub Action：claude-code-action
• AWS/Bedrock 实现：AWS 上的 Anthropic 记忆功能 - Bedrock 特定实现
• 支持：support.claude.com

反馈

记忆和上下文管理目前处于测试阶段。分享你的反馈以帮助我们改进！

[Pines-Cheng]

Memory & Context Management with Claude Sonnet 4.5

Learn how to build AI agents that learn and improve across conversations using Claude's memory tool and context editing capabilities.

Table of Contents

1. Introduction: Why Memory Matters
2. Use Cases
3. Quick Start Examples
4. How It Works
5. Code Review Assistant Demo
6. Real-World Applications
7. Best Practices

Setup

For VSCode Users

# 1. Create virtual environment
python -m venv .venv

# 2. Activate it
source .venv/bin/activate  # macOS/Linux
# or: .venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. In VSCode: Select .venv as kernel (top right)

API Key

cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

Get your API key from: https://console.anthropic.com/

1. Introduction: Why Memory Matters {#introduction}

This cookbook demonstrates practical implementations of the context engineering patterns described in Effective context engineering for AI agents. That post covers why context is a finite resource, how attention budgets work, and strategies for building effective agents—the techniques you'll see in action here.

The Problem

Large language models have finite context windows (200k tokens for Claude 4). While this seems large, several challenges emerge:

• Context limits: Long conversations or complex tasks can exceed available context
• Computational cost: Processing large contexts is expensive - attention mechanisms scale quadratically
• Repeated patterns: Similar tasks across conversations require re-explaining context every time
• Information loss: When context fills up, earlier important information gets lost

The Solution

Claude Sonnet 4.5 introduces two powerful capabilities:

1. Memory Tool (memory_20250818): Enables cross-conversation learning

   • Claude can write down what it learns for future reference
   • File-based system under /memories directory
   • Client-side implementation gives you full control

2. Context Editing (clear_tool_uses_20250919): Automatically manages context

   • Clears old tool results when context grows large
   • Keeps recent context while preserving memory
   • Configurable triggers and retention policies

The Benefit

Build AI agents that get better at your specific tasks over time:

• Session 1: Claude solves a problem, writes down the pattern
• Session 2: Claude applies the learned pattern immediately (faster!)
• Long sessions: Context editing keeps conversations manageable

Think of it as giving Claude a notebook to take notes and refer back to - just like humans do.

2. Use Cases {#use-cases}

Memory and context management enable powerful new workflows:

🔍 Code Review Assistant

• Learns debugging patterns from past reviews
• Recognizes similar bugs instantly in future sessions
• Builds team-specific code quality knowledge
• Production ready: Integrate with claude-code-action for GitHub PR reviews

📚 Research Assistant

• Accumulates knowledge on topics over multiple sessions
• Connects insights across different research threads
• Maintains bibliography and source tracking

💬 Customer Support Bot

• Learns user preferences and communication style
• Remembers common issues and solutions
• Builds product knowledge base from interactions

📊 Data Analysis Helper

• Remembers dataset patterns and anomalies
• Stores analysis techniques that work well
• Builds domain-specific insights over time

Supported Models: Claude Opus 4 (claude-opus-4-20250514), Claude Opus 4.1 (claude-opus-4-1-20250805), Claude Sonnet 4 (claude-sonnet-4-20250514), and Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)

This cookbook focuses on the Code Review Assistant as it clearly demonstrates both memory (learning patterns) and context editing (handling long reviews).

3. Quick Start Examples {#quick-start}

Let's see memory and context management in action with simple examples.

Setup

First, install dependencies and configure your environment:

# Install required packages
# Option 1: From requirements.txt
# %pip install -q -r requirements.txt

# Option 2: Direct install
%pip install -q anthropic python-dotenv ipykernel

⚠️ Important: Create a .env file in this directory:

# Copy .env.example to .env and add your API key
cp .env.example .env

Then edit .env to add your Anthropic API key from https://console.anthropic.com/

import os
from typing import Any, cast

from anthropic import Anthropic
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

API_KEY = os.getenv("ANTHROPIC_API_KEY")
MODEL = os.getenv("ANTHROPIC_MODEL")

if not API_KEY:
    raise ValueError(
        "ANTHROPIC_API_KEY not found. "
        "Copy .env.example to .env and add your API key."
    )

if not MODEL:
    raise ValueError(
        "ANTHROPIC_MODEL not found. "
        "Copy .env.example to .env and set the model."
    )

MODEL = cast(str, MODEL)

client = Anthropic(api_key=API_KEY)

print("✓ API key loaded")
print(f"✓ Using model: {MODEL}")

Example 1: Basic Memory Usage

Let's see Claude use memory to store information for future reference.

Helper Functions

These examples use helper functions from demo_helpers.py:

• run_conversation_loop(): Handles the API conversation loop

  • Calls Claude's API with memory tool enabled
  • Executes tool uses (memory operations)
  • Continues until Claude stops using tools
  • Returns the final response

• run_conversation_turn(): Single turn (used in Example 3)

  • Same as above but returns after one API call
  • Useful when you need fine-grained control

• print_context_management_info(): Displays context clearing stats

  • Shows tokens saved, tool uses cleared
  • Helps visualize when context editing triggers

⚠️ Note on Memory Clearing

The following cell clears all memory files to provide a clean slate for this demonstration. This is useful for running the notebook multiple times to see consistent results.

In production applications, you should carefully consider whether to clear all memory, as it permanently removes learned patterns. Consider using selective deletion or organizing memory into project-specific directories instead.

# Import helper functions
from memory_demo.demo_helpers import run_conversation_loop, run_conversation_turn, print_context_management_info
from memory_tool import MemoryToolHandler

# Initialize
client = Anthropic(api_key=API_KEY)
memory = MemoryToolHandler(base_path="./demo_memory")

# Clear any existing memories to start fresh
print("🧹 Clearing previous memories...")
memory.clear_all_memory()
print("✓ Memory cleared\n")

# Load example code with a race condition bug
with open("memory_demo/sample_code/web_scraper_v1.py", "r") as f:
    code_to_review = f.read()

messages = [
    {
        "role": "user",
        "content": f"I'm reviewing a multi-threaded web scraper that sometimes returns fewer results than expected. The count is inconsistent across runs. Can you find the issue?\n\n```python\n{code_to_review}\n```"
    }
]

print("=" * 60)
print("📝 SESSION 1: Learning from a bug")
print("=" * 60)

# Run conversation loop
response = run_conversation_loop(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="You are a code reviewer.",
    max_tokens=2048,
    max_turns=5,
    verbose=True
)

print("\n" + "=" * 60)
print("✅ Session 1 complete!")
print("=" * 60)

What happened?

1. Claude checked its memory (empty on first run)
2. Identified the bug: race condition - multiple threads modifying shared state (self.results and self.failed_urls) without synchronization
3. Stored the concurrency pattern in memory for future reference

Now let's see the magic - Claude applying this learned pattern in a new conversation:

Example 2: Cross-Conversation Learning

Start a completely new conversation - memory persists!

# NEW conversation (empty messages)
# Load API client code with similar concurrency issue
with open("memory_demo/sample_code/api_client_v1.py", "r") as f:
    code_to_review = f.read()

messages = [
    {
        "role": "user",
        "content": f"Review this API client code:\n\n```python\n{code_to_review}\n```"
    }
]

print("=" * 60)
print("🚀 SESSION 2: Applying learned pattern")
print("=" * 60)

# Run conversation loop
response = run_conversation_loop(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="You are a code reviewer.",
    max_tokens=2048,
    max_turns=5,
    verbose=True
)

print("\n" + "=" * 60)
print("✅ Session 2 complete!")
print("=" * 60)

Notice the difference:

• Claude immediately checked memory and found the thread-safety/concurrency pattern
• Recognized the similar issue in async code instantly without re-learning
• Response was faster because it applied stored knowledge about shared mutable state

This is cross-conversation learning in action!

Example 3: Context Clearing While Preserving Memory

What happens during a long review session with many code files?

• Context fills up with tool results from previous reviews
• But memory (learned patterns) must persist!

Let's trigger context editing to see how Claude manages this automatically.

Note on configuration: We use clear_at_least: 50 tokens because memory tool operations have small results (~50-150 tokens each). In production with larger tool results (like web search or code execution), you'd use higher values like 3000-5000 tokens.

# Configure context management to clear aggressively for demo
CONTEXT_MANAGEMENT = {
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 5000},  # Lower threshold to trigger clearing sooner
            "keep": {"type": "tool_uses", "value": 1},  # Keep only the last tool use
            "clear_at_least": {"type": "input_tokens", "value": 50}
        }
    ]
}

# Continue from previous session - memory persists!
# Add multiple code reviews to build up context

print("=" * 60)
print("📚 SESSION 3: Long review session with context clearing")
print("=" * 60)
print()

# Review 1: Data processor (larger file)
with open("memory_demo/sample_code/data_processor_v1.py", "r") as f:
    data_processor_code = f.read()

messages.extend([
    {
        "role": "user",
        "content": f"Review this data processor:\n\n```python\n{data_processor_code}\n```"
    }
])

print("📝 Review 1: Data processor")
response = run_conversation_turn(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="You are a code reviewer.",
    context_management=CONTEXT_MANAGEMENT,
    max_tokens=2048,
    verbose=True
)

# Add response to messages
messages.append({"role": "assistant", "content": response[1]})
if response[2]:
    messages.append({"role": "user", "content": response[2]})

print(f"  📊 Input tokens: {response[0].usage.input_tokens:,}")
context_cleared, saved = print_context_management_info(response[0])
print()

# Review 2: Add SQL code
with open("memory_demo/sample_code/sql_query_builder.py", "r") as f:
    sql_code = f.read()

messages.extend([
    {
        "role": "user",
        "content": f"Review this SQL query builder:\n\n```python\n{sql_code}\n```"
    }
])

print("📝 Review 2: SQL query builder")
response = run_conversation_turn(
    client=client,
    model=MODEL,
    messages=messages,
    memory_handler=memory,
    system="You are a code reviewer.",
    context_management=CONTEXT_MANAGEMENT,
    max_tokens=2048,
    verbose=True
)

messages.append({"role": "assistant", "content": response[1]})
if response[2]:
    messages.append({"role": "user", "content": response[2]})

print(f"  📊 Input tokens: {response[0].usage.input_tokens:,}")
context_cleared, saved = print_context_management_info(response[0])
print()

print("=" * 60)
print("✅ Session 3 complete!")
print("=" * 60)

What just happened?

As context grew during multiple reviews:

1. Context clearing triggered automatically when input tokens exceeded 5,000
2. Old tool results were removed - cleared 2 tool uses, saving ~66 tokens each time
3. Memory files remained intact - Claude can still query learned patterns
4. Token usage continued to grow but at a slower rate due to clearing

This demonstrates the key benefit:

• Short-term memory (conversation context with tool results) → Cleared to save space
• Long-term memory (stored patterns in /memories) → Persists across sessions

Why such small token savings? Memory tool operations return compact results (file paths, success messages). The str_replace operations only return "File edited successfully" plus metadata. In production use cases with larger tool results (web searches returning full articles, code execution with long outputs), context clearing would save thousands of tokens.

Let's verify memory survived the clearing:

# Verify memory persists after context clearing
import os

print("📂 Memory files in demo_memory/:")
print()

for root, dirs, files in os.walk("./demo_memory"):
    # Calculate relative path for display
    level = root.replace("./demo_memory", "").count(os.sep)
    indent = "  " * level
    folder_name = os.path.basename(root) or "demo_memory"
    print(f"{indent}{folder_name}/")
    
    sub_indent = "  " * (level + 1)
    for file in files:
        file_path = os.path.join(root, file)
        size = os.path.getsize(file_path)
        print(f"{sub_indent}├── {file} ({size} bytes)")

print()
print("✅ All learned patterns preserved despite context clearing!")

4. How It Works {#how-it-works}

Memory Tool Architecture

The memory tool is client-side - you control the storage. Claude makes tool calls, your application executes them.

Memory Tool Commands

Command	Description	Example
view	Show directory or file contents	{"command": "view", "path": "/memories"}
create	Create or overwrite a file	{"command": "create", "path": "/memories/notes.md", "file_text": "..."}
str_replace	Replace text in a file	{"command": "str_replace", "path": "...", "old_str": "...", "new_str": "..."}
insert	Insert text at line number	{"command": "insert", "path": "...", "insert_line": 2, "insert_text": "..."}
delete	Delete a file or directory	{"command": "delete", "path": "/memories/old.txt"}
rename	Rename or move a file	{"command": "rename", "old_path": "...", "new_path": "..."}

See memory_tool.py for the complete implementation with path validation and security measures.

Understanding the Demo Code

Key implementation details from code_review_demo.py:

class CodeReviewAssistant:
    def __init__(self, memory_storage_path="./memory_storage"):
        self.client = Anthropic(api_key=API_KEY)
        self.memory_handler = MemoryToolHandler(base_path=memory_storage_path)
        self.messages = []
    
    def review_code(self, code, filename, description=""):
        # 1. Add user message
        self.messages.append({...})
        
        # 2. Conversation loop with tool execution
        while True:
            response = self.client.beta.messages.create(
                model=MODEL,
                system=self._create_system_prompt(),
                messages=self.messages,
                tools=[{"type": "memory_20250818", "name": "memory"}],
                betas=["context-management-2025-06-27"],
                context_management=CONTEXT_MANAGEMENT
            )
            
            # 3. Execute tool uses
            tool_results = []
            for content in response.content:
                if content.type == "tool_use":
                    result = self._execute_tool_use(content)
                    tool_results.append({...})
            
            # 4. Continue if there are tool uses, otherwise done
            if tool_results:
                self.messages.append({"role": "user", "content": tool_results})
            else:
                break

The key pattern: Keep calling the API while there are tool uses, executing them and feeding results back.

What Claude Actually Learns

This is what makes memory powerful - semantic pattern recognition, not just syntax:

Session 1: Thread-Based Web Scraper

# Bug: Race condition
class WebScraper:
    def __init__(self):
        self.results = []  # Shared state!
    
    def scrape_urls(self, urls):
        with ThreadPoolExecutor() as executor:
            for future in as_completed(futures):
                self.results.append(future.result())  # RACE!

What Claude Stores in Memory (example file: /memories/concurrency_patterns/thread_safety.md):

When Claude encounters this pattern, it stores the following insights to its memory files:

• Symptom: Inconsistent results in concurrent operations
• Cause: Shared mutable state (lists/dicts) modified from multiple threads
• Solution: Use locks, thread-safe data structures, or return results instead
• Red flags: Instance variables in thread callbacks, unused locks, counter increments

---

Session 2: Async API Client (New conversation!)

Claude checks memory FIRST, finds the thread-safety pattern, then:

1. Recognizes similar pattern in async code (coroutines can interleave too)
2. Applies the solution immediately (no re-learning needed)
3. Explains with reference to stored knowledge

# Claude spots this immediately:
async def fetch_all(self, endpoints):
    for coro in asyncio.as_completed(tasks):
        self.responses.append(await coro)  # Same pattern!

---

Why This Matters:

• ❌ Syntax checkers miss race conditions entirely
• ✅ Claude learns architectural patterns and applies them across contexts
• ✅ Cross-language: Pattern applies to Go, Java, Rust concurrency too
• ✅ Gets better: Each review adds to the knowledge base

Sample Code Files

The demo uses these sample files (all have concurrency/thread-safety bugs):

• memory_demo/sample_code/web_scraper_v1.py - Race condition: threads modifying shared state
• memory_demo/sample_code/api_client_v1.py - Similar concurrency bug in async context
• memory_demo/sample_code/data_processor_v1.py - Multiple concurrency issues for long session demo

Let's look at one:

memory_demo/sample_code/web_scraper_v1.py

"""
Concurrent web scraper with a race condition bug.
Multiple threads modify shared state without synchronization.
"""

import time
from concurrent.futures import ThreadPoolExecutor, as_completed
from typing import List, Dict

import requests


class WebScraper:
    """Web scraper that fetches multiple URLs concurrently."""

    def __init__(self, max_workers: int = 10):
        self.max_workers = max_workers
        self.results = []  # BUG: Shared mutable state accessed by multiple threads!
        self.failed_urls = []  # BUG: Another race condition!

    def fetch_url(self, url: str) -> Dict[str, any]:
        """Fetch a single URL and return the result."""
        try:
            response = requests.get(url, timeout=5)
            response.raise_for_status()
            return {
                "url": url,
                "status": response.status_code,
                "content_length": len(response.content),
            }
        except requests.exceptions.RequestException as e:
            return {"url": url, "error": str(e)}

    def scrape_urls(self, urls: List[str]) -> List[Dict[str, any]]:
        """
        Scrape multiple URLs concurrently.

        BUG: self.results is accessed from multiple threads without locking!
        This causes race conditions where results can be lost or corrupted.
        """
        with ThreadPoolExecutor(max_workers=self.max_workers) as executor:
            futures = [executor.submit(self.fetch_url, url) for url in urls]

            for future in as_completed(futures):
                result = future.result()

                # RACE CONDITION: Multiple threads append to self.results simultaneously
                if "error" in result:
                    self.failed_urls.append(result["url"])  # RACE CONDITION
                else:
                    self.results.append(result)  # RACE CONDITION

        return self.results

Bug: Multiple threads modify self.results and self.failed_urls without locking!

Claude will:

1. Identify the race conditions
2. Store the pattern in /memories/concurrency_patterns/thread_safety.md
3. Apply this concurrency pattern to async code in Session 2

Demo Overview

We've built a complete Code Review Assistant. The implementation is in memory_demo/code_review_demo.py.

To run the interactive demo:

python memory_demo/code_review_demo.py

The demo demonstrates:

1. Session 1: Review Python code with a bug → Claude learns the pattern
2. Session 2: Review similar code (new conversation) → Claude applies the pattern
3. Session 3: Long review session → Context editing keeps it manageable

7. Best Practices & Security {#best-practices}

Memory Management

Do:

• ✅ Store task-relevant patterns, not conversation history
• ✅ Organize with clear directory structure
• ✅ Use descriptive file names
• ✅ Periodically review and clean up memory

Don't:

• ❌ Store sensitive information (passwords, API keys, PII)
• ❌ Let memory grow unbounded
• ❌ Store everything indiscriminately

Security: Path Traversal Protection

Critical: Always validate paths to prevent directory traversal attacks. See memory_tool.py for implementation.

Security: Memory Poisoning

⚠️ Critical Risk: Memory files are read back into Claude's context, making them a potential vector for prompt injection.

Mitigation strategies:

1. Content Sanitization: Filter dangerous patterns before storing
2. Memory Scope Isolation: Per-user/per-project isolation
3. Memory Auditing: Log and scan all memory operations
4. Prompt Engineering: Instruct Claude to ignore instructions in memory

See memory_tool.py for complete security implementation and tests in tests/.

Next Steps

Resources

• API docs: Claude API reference
• Usage docs: Memory tool
• GitHub Action: claude-code-action
• AWS/Bedrock Implementation: Anthropic on AWS Memory Features - Bedrock-specific implementation
• Support: support.claude.com

Feedback

Memory and context management are in beta. Share your feedback to help us improve!