readme and update update

Author: victordibia

examples/memory/README.md

@@ -1,82 +1,41 @@
-# Memory Tool Examples
+# Memory Examples
 
-This directory contains examples demonstrating PicoAgents' MemoryTool for cross-conversation learning.
+This directory demonstrates two distinct approaches to agent memory in PicoAgents: **agent-managed memory** (agents actively control their knowledge base) and **application-managed memory** (developers control storage, framework injects context).
 
-## Files
+## Agent-Managed Memory (MemoryTool)
 
-- **`memory_tool_example.py`** - Complete examples showing:
-  - Code review with cross-session learning
-  - All memory operations (view, create, edit, delete, rename)
-  - Memory organization patterns
+**File:** [`memory_tool_example.py`](memory_tool_example.py)
 
-## Running the Examples
+Agents explicitly read, write, and organize persistent knowledge through file operations. The agent decides when to check memory, what to store, and how to organize information—enabling cross-session learning where patterns discovered in one conversation can be applied in future sessions.
 
-```bash
-# Navigate to examples directory
-cd /path/to/designing-multiagent-systems/examples/memory
+Memory tools utilize ideas from [Anthropic's context management work](https://www.anthropic.com/news/context-management), particularly their file-based memory system.
 
-# Run all demos
-python memory_tool_example.py
-```
+**Book reference:** Chapter 4, Section 4.10 "Agent-Managed Memory"
 
-## Requirements
-
-Ensure you have your API key configured:
-
-```bash
-# Set environment variable
-export OPENAI_API_KEY="your-key-here"
-
-# Or create .env file in project root
-echo "OPENAI_API_KEY=your-key-here" > ../../.env
-```
+## Application-Managed Memory (ListMemory)
 
-## What You'll See
+**File:** [`list_memory_example.py`](list_memory_example.py)
 
-### Demo 1: Code Review with Cross-Session Learning
+Developers call `memory.add()` to store information (user preferences, facts, conversation summaries), and the framework automatically retrieves and injects relevant context into prompts via `memory.get_context()`. The agent receives this context but does not control storage or retrieval.
 
-- **Session 1**: Agent reviews code with a race condition, stores the pattern in memory
-- **Session 2**: Agent reviews similar async code, applies the learned pattern immediately
+**Book reference:** Chapter 4, Section 4.9 "Adding Memory"
 
-### Demo 2: Memory Operations
+## Running the Examples
 
-Demonstrates all 6 memory operations:
-- `view` - Show directory or file contents
-- `create` - Create new files
-- `str_replace` - Edit file contents
-- `insert` - Insert text at specific line
-- `delete` - Remove files
-- `rename` - Rename or move files
+```bash
+# Navigate to examples directory
+cd /path/to/designing-multiagent-systems/examples/memory
 
-### Demo 3: Memory Organization
+# Run agent-managed memory example
+python memory_tool_example.py
 
-Shows how to organize memory into directories:
+# Run application-managed memory example
+python list_memory_example.py
 ```
-/memories/
-  ├── patterns/     # Code patterns
-  ├── bugs/         # Known bugs
-  ├── projects/     # Project notes
-  └── users/        # User preferences
-```
-
-## Key Concepts Demonstrated
 
-1. **Cross-Session Learning**: Memory persists between agent conversations
-2. **Agent Autonomy**: Agents actively manage their own knowledge
-3. **File Organization**: Structured memory with directories
-4. **Pattern Recognition**: Applying learned patterns to new problems
+Both examples require `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT` environment variables.
 
 ## Related Documentation
 
-- [Memory Tool Documentation](../../picoagents/docs/memory_tool.md)
-- [PicoAgents README](../../picoagents/README.md)
-- [Book Chapter on Memory](../../../../chapters/) (coming soon)
-
-## Comparison with Anthropic
-
-This implementation mirrors Anthropic's memory tool:
-- Same 6 operations
-- Same file-based approach
-- Same agent-driven memory management
-
-See [Memory Comparison](../../../../misc/memory_comparison_summary.md) for detailed comparison.
+- [PicoAgents Memory Documentation](../../picoagents/docs/memory.md)
+- [Book Chapter 4: Building Your First Agent](../../../../chapters/ch04-building-first-agent.qmd)

examples/memory/list_memory_example.py

@@ -0,0 +1,136 @@
+"""
+Example: Application-managed memory with ListMemory.
+
+Demonstrates how applications control memory storage and retrieval,
+automatically injecting relevant context into agent prompts.
+
+The developer calls memory.add() to store information, and the framework
+automatically retrieves and injects context via memory.get_context().
+The agent receives this context but does not control what gets stored.
+"""
+
+import asyncio
+
+from picoagents import Agent
+from picoagents.llm import AzureOpenAIChatCompletionClient
+from picoagents.memory import ListMemory, MemoryContent
+
+
+async def demo_list_memory():
+    """
+    Demonstrate application-managed memory.
+
+    The application stores user preferences in memory, and the framework
+    automatically injects this context into the agent's prompts.
+    """
+    # Initialize model client
+    client = AzureOpenAIChatCompletionClient(model="gpt-4.1-mini")
+
+    # Create memory - application manages storage
+    memory = ListMemory(max_memories=100)
+
+    # Application stores user preferences
+    await memory.add(
+        MemoryContent(
+            content="User prefers concise responses without verbose explanations",
+            mime_type="text/plain",
+        )
+    )
+    await memory.add(
+        MemoryContent(
+            content="User works as a Python developer, familiar with async/await",
+            mime_type="text/plain",
+        )
+    )
+    await memory.add(
+        MemoryContent(
+            content="User's timezone is PST (UTC-8)",
+            mime_type="text/plain",
+        )
+    )
+
+    # Create agent with memory - framework handles context injection
+    agent = Agent(
+        name="assistant",
+        description="Helpful programming assistant",
+        instructions="""You are a helpful programming assistant.
+Use any relevant context from memory to personalize your responses.""",
+        model_client=client,
+        memory=memory,
+    )
+
+    print("=" * 60)
+    print("APPLICATION-MANAGED MEMORY DEMO")
+    print("=" * 60)
+    print()
+    print(f"Stored {len(memory.memories)} preferences in memory")
+    print()
+
+    # Agent automatically receives memory context
+    task = "Explain how to use asyncio.gather()"
+
+    print(f"User: {task}")
+    print()
+
+    response = await agent.run(task)
+
+    print(f"{agent.name}: {response.messages[-1].content}")
+    print()
+
+    print("=" * 60)
+    print("Notice how the agent's response reflects the stored preferences:")
+    print("- Concise (no verbose explanations)")
+    print("- Assumes Python/async knowledge")
+    print("- The agent did NOT call any memory tools")
+    print("- The framework automatically injected context")
+    print("=" * 60)
+
+
+async def demo_memory_query():
+    """Demonstrate querying memory for relevant context."""
+    print("\n" + "=" * 60)
+    print("MEMORY QUERY DEMO")
+    print("=" * 60)
+    print()
+
+    client = AzureOpenAIChatCompletionClient(model="gpt-4.1-mini")
+    memory = ListMemory(max_memories=100)
+
+    # Store various facts
+    facts = [
+        "Project deadline is March 15th",
+        "Team meeting every Monday at 10am PST",
+        "Code review checklist: tests, docs, type hints",
+        "Production deployment happens on Fridays",
+        "Database backup runs at 2am daily",
+    ]
+
+    for fact in facts:
+        await memory.add(MemoryContent(content=fact))
+
+    print(f"Stored {len(memory.memories)} facts in memory")
+    print()
+
+    # Query for relevant memories
+    query = "when is the deadline"
+    results = await memory.query(query, limit=2)
+
+    print(f"Query: '{query}'")
+    print(f"Found {len(results.results)} relevant memories:")
+    for i, result in enumerate(results.results, 1):
+        print(f"  {i}. {result.content}")
+    print()
+
+    # The framework uses similar logic internally when preparing prompts
+    print("(The framework uses similar querying when injecting context)")
+
+
+if __name__ == "__main__":
+    print("📝 PicoAgents Application-Managed Memory Examples\n")
+
+    asyncio.run(demo_list_memory())
+    asyncio.run(demo_memory_query())
+
+    print("\n✨ Examples completed!")
+    print("\nNext: Try ChromaDB for semantic search with vector embeddings")
+    print("Install: pip install 'picoagents[rag]'")

examples/memory/memory_tool.py

@@ -1,10 +1,12 @@
 """
-Example: Using MemoryTool for cross-conversation learning.
+Example: Agent-managed memory using MemoryTool for cross-session learning.
 
-Demonstrates how agents can store and retrieve information across sessions,
-similar to Anthropic's memory tool functionality.
+Demonstrates how agents explicitly control their own persistent knowledge
+through file operations—storing patterns, organizing information, and
+retrieving learned insights across conversation sessions.
 
-Modelled around ideas from Anthropic's Memory Tool:
+Memory tools utilize ideas from Anthropic's context management work:
+https://www.anthropic.com/news/context-management
 """
 
 import asyncio