Building AI agents, atomically
docs: add comprehensive memory and context management guide
KennyVaneetvelde4fda5b199bb3
diff --git a/docs/api/context.md b/docs/api/context.mdindex 81551d0..ae50f8e 100644--- a/docs/api/context.md+++ b/docs/api/context.md@@ -1,5 +1,9 @@# Context+```{seealso}+For a comprehensive guide on memory management, multi-agent patterns, and best practices, see the **[Memory and Context Guide](/guides/memory)**.+```+## Agent HistoryThe `ChatHistory` class manages conversation history and state for AI agents:diff --git a/docs/conf.py b/docs/conf.pyindex 55c4374..9a19ac0 100644--- a/docs/conf.py+++ b/docs/conf.py@@ -4,7 +4,7 @@ import syssys.path.insert(0, os.path.abspath(".."))project = "Atomic Agents"-copyright = "2024, Kenny Vaneetvelde"+copyright = "2026, Kenny Vaneetvelde"author = "Kenny Vaneetvelde"version = "2.0.4"release = "2.0.4"@@ -17,6 +17,7 @@ extensions = ["myst_parser","sphinx_copybutton","sphinx_design",+ "sphinxcontrib.mermaid",]templates_path = ["_templates"]diff --git a/docs/guides/index.md b/docs/guides/index.mdindex 599fc72..b740c70 100644--- a/docs/guides/index.md+++ b/docs/guides/index.md@@ -7,6 +7,7 @@ This section contains detailed guides for working with Atomic Agents.:caption: Guidesquickstart+memorytoolshooksorchestrationdiff --git a/docs/guides/memory.md b/docs/guides/memory.mdnew file mode 100644index 0000000..37e927a--- /dev/null+++ b/docs/guides/memory.md@@ -0,0 +1,1215 @@+# Memory and Context Management++This guide covers everything you need to know about managing conversation memory and dynamic context in Atomic Agents. Whether you're building a simple chatbot or orchestrating complex multi-agent systems, understanding memory management is essential.++```{contents}+:local:+:depth: 2+```++## Introduction++### What You'll Learn++- How conversation history works in Atomic Agents+- What "turns" are and how they're tracked+- How messages are automatically managed during agent execution+- How to persist and restore conversation state+- How to use context providers for dynamic information injection+- Advanced multi-agent memory patterns++### Prerequisites++- Basic familiarity with Atomic Agents ([Quickstart Guide](quickstart.md))+- Understanding of Python classes and async/await++### The Problem This Solves++A common question from developers (see [GitHub Issue #58](https://github.com/BrainBlend-AI/atomic-agents/issues/58)):++> "In most of the examples only the initial message is added, not any subsequent runs. Is this automatic?"++**Yes, it is automatic!** When you call `agent.run(user_input)`, the framework automatically:+1. Adds your input to the conversation history+2. Sends the full history to the LLM+3. Adds the LLM's response to history++This guide explains exactly how this works and how to leverage it for complex use cases.++---++## Understanding Memory in Atomic Agents++### The Conversation Model++Atomic Agents uses a **turn-based conversation model** where each interaction between user and assistant forms a "turn". The `ChatHistory` class manages this conversation state.++```{mermaid}+flowchart LR+ subgraph Turn1["Turn 1 (turn_id: abc-123)"]+ U1[User Message]+ A1[Assistant Response]+ end++ subgraph Turn2["Turn 2 (turn_id: def-456)"]+ U2[User Message]+ A2[Assistant Response]+ end++ subgraph Turn3["Turn 3 (turn_id: ghi-789)"]+ U3[User Message]+ A3[Assistant Response]+ end++ U1 --> A1+ A1 -.-> U2+ U2 --> A2+ A2 -.-> U3+ U3 --> A3+```++**Key Concepts:**+- **Message**: A single piece of content with a role (user, assistant, system)+- **Turn**: A logical grouping of related messages (typically user input + assistant response)+- **Turn ID**: A UUID that links messages belonging to the same turn+- **History**: The complete sequence of messages in a conversation++### Messages and Turns++Each message in the history has three components:++```python+from atomic_agents.context import Message++# Message structure+message = Message(+ role="user", # "user", "assistant", or "system"+ content=some_schema, # Must be a BaseIOSchema instance+ turn_id="abc-123" # UUID linking related messages+)+```++**Why Turn IDs Matter:**+- Group related messages together+- Enable deletion of complete turns (user message + response)+- Track conversation flow for debugging+- Support conversation branching patterns++---++## ChatHistory Fundamentals++### Creating and Configuring History++```python+from atomic_agents.context import ChatHistory++# Basic history (unlimited messages)+history = ChatHistory()++# History with message limit (oldest messages removed when exceeded)+history = ChatHistory(max_messages=50)+```++### Using History with an Agent++```python+import instructor+import openai+from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema+from atomic_agents.context import ChatHistory+from pydantic import Field++# Define schemas+class ChatInput(BaseIOSchema):+ """User chat message"""+ message: str = Field(..., description="The user's message")++class ChatOutput(BaseIOSchema):+ """Assistant response"""+ response: str = Field(..., description="The assistant's response")++# Create history and agent+history = ChatHistory(max_messages=100)+client = instructor.from_openai(openai.OpenAI())++agent = AtomicAgent[ChatInput, ChatOutput](+ config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=history,+ )+)++# Each run automatically manages history+response1 = agent.run(ChatInput(message="Hello!"))+response2 = agent.run(ChatInput(message="What did I just say?"))+# The agent remembers the previous message!+```++### The Turn Lifecycle++```{mermaid}+stateDiagram-v2+ [*] --> NoTurn: ChatHistory created+ NoTurn --> ActiveTurn: initialize_turn() called+ NoTurn --> ActiveTurn: add_message() called+ ActiveTurn --> ActiveTurn: add_message() same turn+ ActiveTurn --> NewTurn: initialize_turn() called+ NewTurn --> ActiveTurn: Generates new UUID+ ActiveTurn --> NoTurn: All turns deleted++ note right of ActiveTurn: current_turn_id = UUID+ note right of NoTurn: current_turn_id = None+```++**Turn Lifecycle Methods:**++```python+# Initialize a new turn (generates new UUID)+history.initialize_turn()++# Get the current turn ID+turn_id = history.get_current_turn_id()+print(f"Current turn: {turn_id}") # e.g., "abc-123-def-456"++# Add a message to the current turn+history.add_message("user", ChatInput(message="Hello"))++# Messages added without initialize_turn() use the existing turn+# or auto-initialize if no turn exists+```++---++## Automatic Memory Management++This section addresses the core question from GitHub Issue #58: **How does automatic message management work?**++### How .run() Manages Memory++When you call `agent.run(user_input)`, here's exactly what happens:++```{mermaid}+flowchart TD+ A["agent.run(user_input)"] --> B{user_input<br/>provided?}+ B -->|Yes| C["history.initialize_turn()<br/>Creates new UUID"]+ C --> D["history.add_message('user', user_input)<br/>Stores user message"]+ B -->|No| E["Skip turn initialization<br/>Use existing history"]+ D --> F["_prepare_messages()<br/>Build message list"]+ E --> F+ F --> G["System prompt + history"]+ G --> H["LLM API call"]+ H --> I["Receive response"]+ I --> J["history.add_message('assistant', response)<br/>Stores response"]+ J --> K["_manage_overflow()<br/>Trim if needed"]+ K --> L["Return response"]++ style C fill:#e1f5fe+ style D fill:#e1f5fe+ style J fill:#e1f5fe+```++### Step-by-Step Trace++Let's trace through a complete conversation:++```python+from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema+from atomic_agents.context import ChatHistory+from pydantic import Field++class Input(BaseIOSchema):+ """Input"""+ text: str = Field(...)++class Output(BaseIOSchema):+ """Output"""+ reply: str = Field(...)++# Create agent with history+history = ChatHistory()+agent = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=history+))++# --- TURN 1 ---+print(f"Before run: {history.get_message_count()} messages") # 0 messages++response1 = agent.run(Input(text="Hi, my name is Alice"))+# Internally:+# 1. history.initialize_turn() -> turn_id = "abc-123"+# 2. history.add_message("user", Input(text="Hi..."))+# 3. LLM called with history+# 4. history.add_message("assistant", Output(reply="Hello Alice!"))++print(f"After run 1: {history.get_message_count()} messages") # 2 messages+print(f"Turn ID: {history.get_current_turn_id()}") # "abc-123"++# --- TURN 2 ---+response2 = agent.run(Input(text="What's my name?"))+# Internally:+# 1. history.initialize_turn() -> turn_id = "def-456" (NEW turn)+# 2. history.add_message("user", Input(text="What's..."))+# 3. LLM called with FULL history (all 4 messages)+# 4. history.add_message("assistant", Output(reply="Your name is Alice!"))++print(f"After run 2: {history.get_message_count()} messages") # 4 messages+print(f"Turn ID: {history.get_current_turn_id()}") # "def-456"+```++### Running Without Input++You can call `.run()` without input to continue within the same turn:++```python+# First call with input - starts new turn+response = agent.run(Input(text="Start a story"))++# Subsequent call without input - same turn continues+# Useful for: tool follow-ups, multi-step reasoning+continuation = agent.run() # No new turn created, uses existing history+```++### Streaming and Async Behavior++All execution methods handle memory the same way:++| Method | Memory Behavior |+|--------|-----------------|+| `agent.run(input)` | Automatic turn init + message add |+| `agent.run_stream(input)` | Same as run(), streams response |+| `agent.run_async(input)` | Same as run(), async execution |+| `agent.run_async_stream(input)` | Same as run(), async + streaming |++```python+# Streaming example - memory works identically+async for chunk in agent.run_async_stream(Input(text="Hello")):+ print(chunk.reply, end="", flush=True)+# History is updated with complete response after stream finishes+```++---++## History Persistence and Management++### Serialization: Saving Conversations++Save conversation history to disk or database:++```python+from atomic_agents.context import ChatHistory++# ... after some conversation ...++# Serialize to JSON string+serialized = history.dump()++# Save to file+with open("conversation.json", "w") as f:+ f.write(serialized)++# Save to database+db.save_conversation(user_id=123, data=serialized)+```++### Deserialization: Restoring Conversations++```python+# Load from file+with open("conversation.json", "r") as f:+ serialized = f.read()++# Create new history and load+history = ChatHistory()+history.load(serialized)++# Use with agent+agent = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=history, # Restored history!+))++# Continue the conversation where it left off+response = agent.run(Input(text="Where were we?"))+```++```{warning}+Only load serialized data from trusted sources. The `load()` method reconstructs Python classes from the serialized data.+```++### Overflow Management++Control memory usage with `max_messages`:++```python+# Keep only last 20 messages+history = ChatHistory(max_messages=20)++# When 21st message is added, oldest message is removed+# This is FIFO (First In, First Out) - oldest messages go first+```++**Strategy for Long Conversations:**++```python+# Option 1: Simple limit+history = ChatHistory(max_messages=50)++# Option 2: Monitor and handle manually+if history.get_message_count() > 40:+ # Maybe summarize old messages before they're lost+ old_messages = history.get_history()[:10]+ summary = summarize_messages(old_messages)+ # Store summary in context provider instead+```++### History Manipulation++**Copying History:**++```python+# Create independent copy (deep copy)+history_copy = history.copy()++# Modifications don't affect original+history_copy.add_message("user", Input(text="This only goes in copy"))+```++**Deleting Turns:**++```python+# Get the turn ID you want to delete+turn_id = history.get_current_turn_id()++# Delete all messages with that turn ID+history.delete_turn_id(turn_id)++# Useful for: removing failed attempts, undo functionality+```++**Resetting History:**++```python+# Clear all messages, start fresh+agent.reset_history()+# or+history = ChatHistory() # Create new instance+```++---++## Multimodal Content in History++ChatHistory supports images, PDFs, and audio through Instructor's multimodal types.++### Adding Multimodal Messages++```python+from instructor import Image, PDF, Audio+from atomic_agents import BaseIOSchema+from pydantic import Field+from typing import List++class ImageAnalysisInput(BaseIOSchema):+ """Input with images for analysis"""+ question: str = Field(..., description="Question about the images")+ images: List[Image] = Field(..., description="Images to analyze")++# Create input with images+input_with_images = ImageAnalysisInput(+ question="What's in these images?",+ images=[+ Image.from_path("photo1.jpg"),+ Image.from_path("photo2.png"),+ ]+)++# Run agent - images are stored in history+response = agent.run(input_with_images)+```++### Multimodal Message Structure++When history contains multimodal content, `get_history()` returns a special structure:++```python+history_data = history.get_history()++for message in history_data:+ if isinstance(message["content"], list):+ # Multimodal message+ json_content = message["content"][0] # Text/JSON data+ multimodal_objects = message["content"][1:] # Images, PDFs, etc.+ else:+ # Text-only message+ json_content = message["content"]+```++### Serialization with Multimodal++```{note}+Multimodal content with file paths is serialized by path. Ensure files exist at the same paths when loading.+```++```python+# Serialize (file paths are preserved)+serialized = history.dump()++# When loading, files must be accessible at original paths+history.load(serialized)+```++---++## Dynamic Context with Providers++Context providers inject dynamic information into agent system prompts at runtime, complementing the static conversation history.++### Understanding the Difference++| Aspect | ChatHistory (Memory) | Context Providers |+|--------|---------------------|-------------------|+| **Purpose** | Store conversation turns | Inject dynamic context |+| **Location** | Message history | System prompt |+| **Persistence** | Saved with history | Regenerated each call |+| **Use Case** | Conversation continuity | Real-time data (RAG, user info, time) |++```{mermaid}+flowchart TB+ subgraph SystemPrompt["System Prompt (sent to LLM)"]+ BG[Background Instructions]+ ST[Steps]++ subgraph DC["Dynamic Context"]+ CP1[Context Provider 1]+ CP2[Context Provider 2]+ CP3[Context Provider 3]+ end++ OI[Output Instructions]+ end++ subgraph Messages["Conversation Messages"]+ H[ChatHistory Messages]+ end++ SystemPrompt --> LLM+ Messages --> LLM+ LLM --> Response+```++### Creating Custom Context Providers++```python+from atomic_agents.context import BaseDynamicContextProvider++class UserContextProvider(BaseDynamicContextProvider):+ """Provides current user information to the agent."""++ def __init__(self):+ super().__init__(title="Current User")+ self.user_name: str = ""+ self.user_role: str = ""+ self.preferences: dict = {}++ def get_info(self) -> str:+ """Called every time the agent runs."""+ if not self.user_name:+ return "No user logged in."++ info = f"User: {self.user_name} (Role: {self.user_role})"+ if self.preferences:+ prefs = ", ".join(f"{k}: {v}" for k, v in self.preferences.items())+ info += f"\nPreferences: {prefs}"+ return info+```++### Registering Context Providers++```python+from atomic_agents import AtomicAgent, AgentConfig+from atomic_agents.context import SystemPromptGenerator++# Create provider+user_provider = UserContextProvider()++# Option 1: Register with SystemPromptGenerator+system_prompt = SystemPromptGenerator(+ background=["You are a helpful assistant."],+ context_providers={"user": user_provider}+)++agent = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ system_prompt_generator=system_prompt,+))++# Option 2: Register after agent creation+agent.register_context_provider("user", user_provider)++# Update provider state before running+user_provider.user_name = "Alice"+user_provider.user_role = "Admin"++# Now the agent knows about Alice!+response = agent.run(Input(text="What can I do?"))+```++### Common Context Provider Patterns++**RAG (Retrieval-Augmented Generation):**++```python+class RAGContextProvider(BaseDynamicContextProvider):+ """Injects retrieved documents into the prompt."""++ def __init__(self, vector_db):+ super().__init__(title="Relevant Documents")+ self.vector_db = vector_db+ self.current_query: str = ""+ self._cached_results: list = []++ def search(self, query: str, top_k: int = 3):+ """Call before agent.run() to update context."""+ self.current_query = query+ self._cached_results = self.vector_db.search(query, top_k=top_k)++ def get_info(self) -> str:+ if not self._cached_results:+ return "No relevant documents found."++ docs = []+ for i, doc in enumerate(self._cached_results, 1):+ docs.append(f"Document {i}:\n{doc['content']}\nSource: {doc['source']}")+ return "\n\n".join(docs)++# Usage+rag_provider = RAGContextProvider(vector_db)+agent.register_context_provider("documents", rag_provider)++# Before each query+user_query = "How do I reset my password?"+rag_provider.search(user_query) # Update context+response = agent.run(Input(text=user_query))+```++**Time-Aware Context:**++```python+from datetime import datetime++class TimeContextProvider(BaseDynamicContextProvider):+ """Provides current time information."""++ def __init__(self):+ super().__init__(title="Current Time")++ def get_info(self) -> str:+ now = datetime.now()+ return f"Current date/time: {now.strftime('%Y-%m-%d %H:%M:%S %Z')}"+```++**Session Context:**++```python+class SessionContextProvider(BaseDynamicContextProvider):+ """Tracks session-specific state."""++ def __init__(self):+ super().__init__(title="Session State")+ self.data: dict = {}++ def set(self, key: str, value: str):+ self.data[key] = value++ def get_info(self) -> str:+ if not self.data:+ return "No session data."+ return "\n".join(f"- {k}: {v}" for k, v in self.data.items())+```++---++## Multi-Agent Memory Patterns++This section addresses the question from GitHub Issue #58:++> "How do I handle a scenario where one agent performs an action, a second agent evaluates it, and then passes results back to the first agent's memory?"++Here are five patterns for managing memory across multiple agents.++### Pattern 1: Shared History++Multiple agents share the same `ChatHistory` instance, seeing each other's messages.++```{mermaid}+flowchart LR+ subgraph SharedHistory["Shared ChatHistory"]+ M1[Message 1]+ M2[Message 2]+ M3[Message 3]+ M4[Message 4]+ end++ A1[Agent A] --> SharedHistory+ A2[Agent B] --> SharedHistory+ A3[Agent C] --> SharedHistory+```++**Use Case:** Agents that need full conversation context (e.g., specialist + generalist).++```python+from atomic_agents import AtomicAgent, AgentConfig+from atomic_agents.context import ChatHistory++# One history shared by all+shared_history = ChatHistory()++# Agent A - Technical Expert+technical_agent = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=shared_history, # Same history+ system_prompt_generator=SystemPromptGenerator(+ background=["You are a technical expert."]+ ),+))++# Agent B - Communication Expert+communication_agent = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=shared_history, # Same history!+ system_prompt_generator=SystemPromptGenerator(+ background=["You simplify technical explanations."]+ ),+))++# Conversation flow+user_input = Input(text="Explain quantum computing")++# Technical agent adds to shared history+technical_response = technical_agent.run(user_input)++# Communication agent sees technical response in history+simple_response = communication_agent.run(+ Input(text="Simplify the above explanation for a child")+)+```++### Pattern 2: Independent Histories++Each agent maintains its own isolated history.++```{mermaid}+flowchart TB+ subgraph Agent_A["Agent A"]+ HA[History A]+ end++ subgraph Agent_B["Agent B"]+ HB[History B]+ end++ subgraph Agent_C["Agent C"]+ HC[History C]+ end++ User --> Agent_A+ User --> Agent_B+ User --> Agent_C+```++**Use Case:** Parallel processing, independent tasks, privacy isolation.++```python+# Each agent has its own history+agent_a = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=ChatHistory(), # Independent+))++agent_b = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=ChatHistory(), # Independent+))++# They don't see each other's conversations+response_a = agent_a.run(Input(text="Research topic A"))+response_b = agent_b.run(Input(text="Research topic B"))+```++(pattern-3-agent-to-agent-messaging)=+### Pattern 3: Agent-to-Agent Messaging++Manually transfer outputs between agent memories. **This directly addresses Issue #58.**++```{mermaid}+sequenceDiagram+ participant U as User+ participant O as Orchestrator+ participant A as Agent A+ participant B as Agent B++ U->>O: Initial request+ O->>A: run(user_input)+ Note over A: Turn 1: User + Response<br/>added to A.history+ A-->>O: Result A++ O->>O: Manual transfer+ Note over O: B.history.add_message(<br/>"user", Result A)++ O->>B: run(None)+ Note over B: Uses existing history<br/>Turn 2: Response added+ B-->>O: Result B++ O->>O: Manual transfer+ Note over O: A.history.add_message(<br/>"user", Result B)++ O->>A: run(None)+ Note over A: Continues with<br/>B's feedback in context+ A-->>O: Final Result+```++**Use Case:** Agent loops, evaluation cycles, iterative refinement.++```python+from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema+from atomic_agents.context import ChatHistory+from pydantic import Field++class WriterInput(BaseIOSchema):+ """Writer input"""+ task: str = Field(...)++class WriterOutput(BaseIOSchema):+ """Writer output"""+ content: str = Field(...)++class ReviewerInput(BaseIOSchema):+ """Reviewer input"""+ content_to_review: str = Field(...)++class ReviewerOutput(BaseIOSchema):+ """Reviewer output"""+ feedback: str = Field(...)+ approved: bool = Field(...)++# Create agents with independent histories+writer = AtomicAgent[WriterInput, WriterOutput](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=ChatHistory(),+))++reviewer = AtomicAgent[ReviewerInput, ReviewerOutput](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=ChatHistory(),+))++def iterative_writing(task: str, max_iterations: int = 3) -> str:+ """Writer-Reviewer loop with memory transfer."""++ # Initial writing+ writer_response = writer.run(WriterInput(task=task))++ for i in range(max_iterations):+ # Review the content+ review = reviewer.run(ReviewerInput(+ content_to_review=writer_response.content+ ))++ if review.approved:+ return writer_response.content++ # Transfer feedback to writer's memory+ # This is the key pattern from Issue #58!+ writer.history.add_message(+ "user",+ WriterInput(task=f"Revise based on feedback: {review.feedback}")+ )++ # Writer continues with feedback in context+ writer_response = writer.run() # No input = use existing history++ return writer_response.content++# Usage+final_content = iterative_writing("Write a product description for headphones")+```++### Pattern 4: Supervisor-Worker with Context Providers++Use context providers to share state between supervisor and worker agents.++```{mermaid}+flowchart TB+ subgraph SharedContext["Shared Context Provider"]+ SC[Task State & Results]+ end++ SUP[Supervisor Agent] --> SharedContext+ W1[Worker 1] --> SharedContext+ W2[Worker 2] --> SharedContext+ W3[Worker 3] --> SharedContext++ SUP -->|Delegates| W1+ SUP -->|Delegates| W2+ SUP -->|Delegates| W3++ W1 -->|Updates| SharedContext+ W2 -->|Updates| SharedContext+ W3 -->|Updates| SharedContext+```++```python+class TaskContextProvider(BaseDynamicContextProvider):+ """Shared context for supervisor-worker pattern."""++ def __init__(self):+ super().__init__(title="Task Progress")+ self.current_task: str = ""+ self.subtask_results: dict = {}+ self.overall_status: str = "pending"++ def set_task(self, task: str):+ self.current_task = task+ self.subtask_results = {}+ self.overall_status = "in_progress"++ def add_result(self, subtask: str, result: str):+ self.subtask_results[subtask] = result++ def get_info(self) -> str:+ info = [f"Current Task: {self.current_task}"]+ info.append(f"Status: {self.overall_status}")++ if self.subtask_results:+ info.append("\nCompleted Subtasks:")+ for task, result in self.subtask_results.items():+ info.append(f" - {task}: {result[:100]}...")++ return "\n".join(info)++# Shared context+task_context = TaskContextProvider()++# All agents see the same context+supervisor = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=ChatHistory(),+))+supervisor.register_context_provider("task", task_context)++worker1 = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=ChatHistory(),+))+worker1.register_context_provider("task", task_context)++# Orchestration+task_context.set_task("Research and summarize AI trends")++# Worker does subtask+result1 = worker1.run(Input(text="Research NLP trends"))+task_context.add_result("NLP Research", result1.response)++# Supervisor sees worker's result via context provider+summary = supervisor.run(Input(text="Synthesize the research findings"))+```++### Pattern 5: Memory-Augmented Loops++Combine conversation history with external memory for long-running processes.++```python+class LongTermMemory:+ """External memory store for facts and decisions."""++ def __init__(self):+ self.facts: list = []+ self.decisions: list = []++ def add_fact(self, fact: str):+ self.facts.append(fact)++ def add_decision(self, decision: str):+ self.decisions.append(decision)++ def get_summary(self) -> str:+ summary = []+ if self.facts:+ summary.append("Known Facts:\n" + "\n".join(f"- {f}" for f in self.facts))+ if self.decisions:+ summary.append("Decisions Made:\n" + "\n".join(f"- {d}" for d in self.decisions))+ return "\n\n".join(summary) if summary else "No long-term memory yet."++class MemoryContextProvider(BaseDynamicContextProvider):+ def __init__(self, memory: LongTermMemory):+ super().__init__(title="Long-Term Memory")+ self.memory = memory++ def get_info(self) -> str:+ return self.memory.get_summary()++# Setup+long_term = LongTermMemory()+memory_provider = MemoryContextProvider(long_term)++agent = AtomicAgent[Input, Output](config=AgentConfig(+ client=client,+ model="gpt-5-mini",+ history=ChatHistory(max_messages=20), # Short-term limited+))+agent.register_context_provider("memory", memory_provider)++# Research loop with memory accumulation+topics = ["AI Safety", "Quantum Computing", "Climate Tech"]++for topic in topics:+ response = agent.run(Input(text=f"Research {topic} and identify key facts"))++ # Extract and store important facts in long-term memory+ long_term.add_fact(f"{topic}: {response.response[:200]}")++ # ChatHistory may overflow, but long-term memory persists+ # Agent always has access via context provider++# Final synthesis - agent sees all facts via context provider+final = agent.run(Input(text="Synthesize all research into recommendations"))+```++---++## Best Practices++### When to Use Each Pattern++| Scenario | Recommended Pattern |+|----------|-------------------|+| Single agent chatbot | Basic ChatHistory |+| Multi-turn with context | ChatHistory + Context Providers |+| Parallel independent tasks | Independent Histories |+| Sequential pipeline | Agent-to-Agent Messaging |+| Iterative refinement loops | Agent-to-Agent Messaging |+| Supervisor-worker | Shared Context Providers |+| Long-running processes | Memory-Augmented Loops |++### Managing Context Window Limits++```python+from atomic_agents.utils import get_context_token_count++# Monitor token usage+token_info = agent.get_context_token_count()+print(f"Total tokens: {token_info.total}")+print(f"System prompt: {token_info.system_prompt}")+print(f"History: {token_info.history}")+print(f"Utilization: {token_info.utilization:.1%}")++# Set appropriate limits+if token_info.utilization > 0.8:+ # Consider trimming history or summarizing+ pass+```++### Testing Agents with Memory++```python+import pytest+from atomic_agents.context import ChatHistory++def fresh_history():+ """Provide clean history for each test."""+ return ChatHistory()++def agent_with_history(fresh_history):+ """Agent with clean history."""+ return AtomicAgent[Input, Output](config=AgentConfig(+ client=mock_client,+ model="gpt-5-mini",+ history=fresh_history,+ ))++def test_conversation_continuity(agent_with_history):+ """Test that agent remembers previous messages."""+ agent_with_history.run(Input(text="My name is Bob"))+ response = agent_with_history.run(Input(text="What's my name?"))++ assert "Bob" in response.response++def test_history_persistence(agent_with_history):+ """Test serialization/deserialization."""+ agent_with_history.run(Input(text="Remember: secret=42"))++ # Serialize+ serialized = agent_with_history.history.dump()++ # Create new history and load+ new_history = ChatHistory()+ new_history.load(serialized)++ assert new_history.get_message_count() == 2+```++### Debugging Memory Issues++```python+# Inspect current history+for msg in history.history:+ print(f"[{msg.role}] Turn: {msg.turn_id}")+ print(f" Content: {msg.content.model_dump_json()[:100]}...")+ print()++# Check turn state+print(f"Current turn ID: {history.get_current_turn_id()}")+print(f"Message count: {history.get_message_count()}")+print(f"Max messages: {history.max_messages}")+```++---++## Troubleshooting++### "Messages aren't being added to history"++**Cause:** Calling `run()` without input after resetting history.++```python+# Wrong - no messages to work with+agent.reset_history()+agent.run() # Nothing in history!++# Correct+agent.reset_history()+agent.run(Input(text="Start fresh")) # Provides input+```++### "Agent doesn't remember previous conversation"++**Cause:** Creating new agent instances instead of reusing.++```python+# Wrong - new agent = new history each time+def handle_message(text):+ agent = AtomicAgent[Input, Output](config=config) # New instance!+ return agent.run(Input(text=text))++# Correct - reuse agent instance+agent = AtomicAgent[Input, Output](config=config) # Create once++def handle_message(text):+ return agent.run(Input(text=text)) # Reuse+```++### "How do I pass memory between agents?"++See [Pattern 3: Agent-to-Agent Messaging](#pattern-3-agent-to-agent-messaging).++```python+# Transfer output to another agent's memory+agent_b.history.add_message("user", agent_a_output)+agent_b.run() # Now has context from agent A+```++### "What exactly is a 'turn'?"++A **turn** is a logical unit of conversation, typically containing:+- One user message+- One assistant response+- Both sharing the same `turn_id` (UUID)++```python+# This is ONE turn:+response = agent.run(Input(text="Hello"))+# turn_id "abc-123" assigned to both user message and response++# This starts a NEW turn:+response2 = agent.run(Input(text="Next question"))+# turn_id "def-456" assigned to new pair+```++### "History is too large / context overflow"++```python+# Option 1: Limit history size+history = ChatHistory(max_messages=30)++# Option 2: Monitor and handle+if history.get_message_count() > 40:+ # Summarize or archive old messages+ pass++# Option 3: Use context providers for persistent data+# instead of relying on conversation history+```++---++## API Quick Reference++### ChatHistory++| Method | Description |+|--------|-------------|+| `ChatHistory(max_messages=None)` | Create history with optional limit |+| `add_message(role, content)` | Add message to current turn |+| `initialize_turn()` | Start new turn with new UUID |+| `get_current_turn_id()` | Get current turn's UUID |+| `get_history()` | Get all messages as list of dicts |+| `get_message_count()` | Get number of messages |+| `delete_turn_id(turn_id)` | Delete all messages in a turn |+| `dump()` | Serialize to JSON string |+| `load(data)` | Deserialize from JSON string |+| `copy()` | Create deep copy |++### Message++| Field | Type | Description |+|-------|------|-------------|+| `role` | str | "user", "assistant", or "system" |+| `content` | BaseIOSchema | Message content |+| `turn_id` | Optional[str] | UUID linking related messages |++### BaseDynamicContextProvider++| Method | Description |+|--------|-------------|+| `__init__(title)` | Create with display title |+| `get_info() -> str` | Return context string (override this) |++---++## Next Steps++- [Quickstart Guide](quickstart.md) - Get started with Atomic Agents+- [Tools Guide](tools.md) - Add capabilities to your agents+- [Orchestration Guide](orchestration.md) - Coordinate multiple agents+- [Hooks Guide](hooks.md) - Monitor and customize agent behavior+- [API Reference](/api/context) - Full API documentation++---++## Summary++Key takeaways:++1. **Automatic Memory**: `agent.run(input)` automatically manages history - you don't need to manually add messages+2. **Turns**: A turn groups user input + assistant response with a shared UUID+3. **Persistence**: Use `dump()`/`load()` to save and restore conversations+4. **Context Providers**: Inject dynamic information (RAG, user data, time) into system prompts+5. **Multi-Agent**: Use shared history, agent-to-agent messaging, or context providers depending on your needs++For questions or issues, visit our [GitHub repository](https://github.com/BrainBlend-AI/atomic-agents) or [Reddit community](https://www.reddit.com/r/AtomicAgents/).diff --git a/pyproject.toml b/pyproject.tomlindex f4ecaa0..214afdf 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -60,6 +60,7 @@ dev = ["sphinx-autobuild>=2024.2.4,<2025.0.0","beautifulsoup4>=4.12.3,<5.0.0","markdownify>=0.9.0,<1.0.0",+ "sphinxcontrib-mermaid>=1.2.3",][tool.hatch.build.targets.wheel]diff --git a/uv.lock b/uv.lockindex 7685946..d6c0809 100644--- a/uv.lock+++ b/uv.lock@@ -224,6 +224,7 @@ dev = [{ name = "sphinx-copybutton" },{ name = "sphinx-design" },{ name = "sphinx-rtd-theme" },+ { name = "sphinxcontrib-mermaid" },][package.metadata]@@ -257,6 +258,7 @@ dev = [{ name = "sphinx-copybutton", specifier = ">=0.5.2,<1.0.0" },{ name = "sphinx-design", specifier = ">=0.5.0,<1.0.0" },{ name = "sphinx-rtd-theme", specifier = ">=2.0.0,<3.0.0" },+ { name = "sphinxcontrib-mermaid", specifier = ">=1.2.3" },][[package]]@@ -3872,6 +3874,19 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/c2/42/4c8646762ee83602e3fb3fbe774c2fac12f317deb0b5dbeeedd2d3ba4b77/sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178", size = 5071, upload-time = "2019-01-21T16:10:14.333Z" },]+[[package]]+name = "sphinxcontrib-mermaid"+version = "1.2.3"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "pyyaml" },+ { name = "sphinx" },+]+sdist = { url = "https://files.pythonhosted.org/packages/f5/49/c6ddfe709a4ab76ac6e5a00e696f73626b2c189dc1e1965a361ec102e6cc/sphinxcontrib_mermaid-1.2.3.tar.gz", hash = "sha256:358699d0ec924ef679b41873d9edd97d0773446daf9760c75e18dc0adfd91371", size = 18885, upload-time = "2025-11-26T04:18:32.43Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/d1/39/8b54299ffa00e597d3b0b4d042241a0a0b22cb429ad007ccfb9c1745b4d1/sphinxcontrib_mermaid-1.2.3-py3-none-any.whl", hash = "sha256:5be782b27026bef97bfb15ccb2f7868b674a1afc0982b54cb149702cfc25aa02", size = 13413, upload-time = "2025-11-26T04:18:31.269Z" },+]+[[package]]name = "sphinxcontrib-qthelp"version = "2.0.0"