add chapter 6 files

chapter_06_memory/01_session_agent.py

@@ -0,0 +1,56 @@
+import asyncio
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.tools import calculator, search_web
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+
+async def main():
+    """Demonstrate session memory functionality"""
+    user_id = "test_123"
+    # Initialize components
+    model = OpenAILlm(model='gpt-5-mini')
+    tools = [calculator, search_web]
+    
+    # Create agent with session manager
+    agent = ToolCallingAgent(
+        name="session_assistant",
+        model=model,
+        instructions="You are a helpful assistant that remembers our conversations.",
+        tools=tools,
+        session_manager=InMemorySessionManager()
+    )
+    
+    # First interaction - session 1
+    print("=== First Interaction (Session 1) ===")
+    answer1 = await agent.run(
+        "My name is Alice and I'm working on Project Alpha. What's 123 * 456?",
+        session_id="session_1",
+        user_id=user_id
+    )
+    print(f"Assistant: {answer1}\n")
+    
+    # Second interaction - continue session 1
+    print("=== Second Interaction (Session 1) ===")
+    answer2 = await agent.run(
+        "What project am I working on and what was the result of the multiplication I asked about?",
+        session_id="session_1",
+        user_id=user_id
+    )
+    print(f"Assistant: {answer2}\n")
+    
+    # New session - session 2
+    print("=== New Session (Session 2) ===")
+    answer3 = await agent.run(
+        "Do you remember my name?",
+        session_id="session_2",
+        user_id=user_id
+    )
+    print(f"Assistant: {answer3}\n")
+
+if __name__ == "__main__":
+    asyncio.run(main())

chapter_06_memory/02_core_memory_strategy.py

@@ -0,0 +1,35 @@
+import asyncio
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from scratch_agents.memory.core_memory_strategy import CoreMemoryStrategy
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+
+async def test_core_memory_loading():
+    user_id = "test_123"
+    session_id = "test_session"
+    session_manager = InMemorySessionManager()
+    session = session_manager.get_or_create_session(session_id, user_id)
+    session.core_memory["user"] = "User's name is Alice"
+    
+    agent = ToolCallingAgent(
+        name="memory_agent",
+        model=OpenAILlm(model="gpt-5-mini"),
+        instructions="You are a helpful assistant",
+        session_manager=session_manager,
+        before_llm_callbacks=[CoreMemoryStrategy()]
+    )
+    
+    response = await agent.run(
+        "What's my name?",
+        session_id=session_id,
+        user_id=user_id
+    )
+    
+    print(response)
+
+asyncio.run(test_core_memory_loading())

chapter_06_memory/03_core_memory_update.py

@@ -0,0 +1,32 @@
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from scratch_agents.tools.core_memory_upsert import core_memory_upsert
+import asyncio
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+user_id = "test_123"
+session_id = "test_session"
+
+async def test_automatic_memory_update():
+    agent = ToolCallingAgent(
+        name="learning_agent",
+        model=OpenAILlm(model="gpt-5-mini"),
+        instructions="Remember important user info with core_memory_upsert",
+        tools=[core_memory_upsert],
+        session_manager=InMemorySessionManager(),
+    )
+    
+    await agent.run(
+        "Hi! My name is Alice and I work as a data scientist.",
+        session_id=session_id,
+        user_id=user_id
+    )
+    
+    session = agent.session_manager.get_session(session_id)
+    print(session.core_memory['user'])
+
+asyncio.run(test_automatic_memory_update())

chapter_06_memory/04_sliding_window.py

@@ -0,0 +1,43 @@
+import asyncio
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from scratch_agents.memory.sliding_window_strategy import SlidingWindowStrategy
+from scratch_agents.types.contents import Message
+from scratch_agents.types.events import Event
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+user_id = "test_123"
+session_id = "test_session"
+
+async def test_sliding_window():
+    
+    session_manager = InMemorySessionManager()
+    session = session_manager.create_session(session_id, user_id)
+    
+    session.events.append(Event(
+        execution_id="exec1",
+        author="user",
+        content=[Message(role="user", content="My name is Alice"),
+        Message(role="user", content="I live in Korea")]
+    ))
+    
+    agent = ToolCallingAgent(
+        name="window_agent",
+        model=OpenAILlm(model="gpt-5-mini"),
+        instructions="You are a helpful assistant",
+        session_manager=session_manager,
+        before_llm_callbacks=[SlidingWindowStrategy(max_messages=2)]  
+    )
+    
+    response = await agent.run(
+        "What's my name?",  
+        session_id=session_id,
+        user_id=user_id
+    )
+    print(response)
+
+asyncio.run(test_sliding_window())

chapter_06_memory/05_summarization.py

@@ -0,0 +1,64 @@
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from scratch_agents.memory.summarization_strategy import SummarizationStrategy
+from scratch_agents.types.contents import Message
+from scratch_agents.types.events import Event
+import asyncio
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+user_id = "test_123"
+session_id = "test_session"
+
+async def test_summarization_strategy():
+    """Demonstrate summarization strategy in action"""
+    
+    model = OpenAILlm(model="gpt-5-mini")
+    session_manager = InMemorySessionManager()
+    session = session_manager.create_session(session_id, user_id)
+    
+    messages = [
+        Message(role="user", content="Hi, I'm Bob"),
+        Message(role="assistant", content="Nice to meet you, Bob!"),
+        Message(role="user", content="I work as a teacher"),
+        Message(role="assistant", content="Wow! What subject?"),
+        Message(role="user", content="I teach math"),
+        Message(role="assistant", content="Math is important!"),
+        Message(role="user", content="I have 30 students"),
+        Message(role="assistant", content="That's a good class size"),
+    ]
+    
+    for msg in messages:
+        event = Event(
+            execution_id="test_exec",
+            author="test",
+            content=[msg]
+        )
+        session.events.append(event)
+    
+    agent = ToolCallingAgent(
+        name="summary_agent",
+        model=model,
+        instructions="You are a helpful assistant",
+        session_manager=session_manager,
+        before_llm_callbacks=[
+            SummarizationStrategy(model=model, trigger_count=8, keep_recent=2)
+        ]
+    )
+    
+    response = await agent.run(
+        "What subject do I teach?",
+        session_id=session_id,
+        user_id=user_id
+    )
+    
+    if "conversation_summary" in session.state:
+        print(f"Summary: {session.state['conversation_summary']}")
+        print(f"Summary Index: {session.state['last_summarized_index']}")
+    
+    print(f"\nAgent response: {response}")
+
+asyncio.run(test_summarization_strategy())

chapter_06_memory/06_conversation_search.py

@@ -0,0 +1,59 @@
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from scratch_agents.memory.sliding_window_strategy import SlidingWindowStrategy
+from scratch_agents.tools.conversation_search import conversation_search
+from scratch_agents.types.contents import Message
+from scratch_agents.types.events import Event
+import asyncio
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+user_id = "test_123"
+session_id = "test_session"
+
+async def test_search_with_sliding_window():
+    """Demonstrate search recovering information lost to sliding window"""
+    
+    model = OpenAILlm(model="gpt-5-mini")
+    session_manager = InMemorySessionManager()
+    session = session_manager.create_session(session_id, user_id)
+    
+    conversation_history = [
+        ("user", "My golden retriever puppy is named Max."),
+        ("assistant", "Max is a lovely name for a golden retriever!"),
+        ("user", "He loves playing fetch in the park."),
+        ("assistant", "That's wonderful! Golden retrievers are great at fetch."),
+    ]
+    
+    for role, content in conversation_history:
+        event = Event(
+            execution_id="pre_loaded",
+            author=role,
+            content=[Message(role=role, content=content)]
+        )
+        session.events.append(event)  
+    
+    agent = ToolCallingAgent(
+        name="search_agent",
+        model=model,
+        instructions="""You are a helpful assistant. When asked about 
+        information from earlier in our conversation, use the 
+        conversation_search tool to find it.""",
+        tools=[conversation_search],
+        session_manager=session_manager,
+        before_llm_callbacks=[
+            SlidingWindowStrategy(max_messages=2)
+        ]
+    )
+    
+    response = await agent.run(
+        "What was my puppy's name?",
+        session_id=session_id,
+        user_id=user_id
+    )
+    print(f"Agent: {response}\n")
+
+asyncio.run(test_search_with_sliding_window())

chapter_06_memory/07_task_long_term.py

@@ -0,0 +1,76 @@
+from scratch_agents.agents.execution_context_ch6 import ExecutionContext
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.sessions.task_cross_session_manager import TaskCrossSessionManager
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from scratch_agents.tools.base_tool import BaseTool
+from scratch_agents.models.llm_request import LlmRequest
+from scratch_agents.tools.search_web import search_web
+import asyncio
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+user_id = "test_123"
+
+async def long_term_memory_save_callback(context:ExecutionContext):
+    cross_session_manager = context.cross_session_manager
+    session = context.session
+    execution_id = context.execution_id
+    
+    await cross_session_manager.process_session(session=session, execution_id=execution_id)
+    
+class MemorySearchTool(BaseTool):
+    async def execute(self, context, **kwargs):
+        return None
+    
+    async def process_llm_request(self, request: LlmRequest, context: ExecutionContext):
+        user_input = context.user_input
+        user_id = context.session.user_id
+        results = await context.cross_session_manager.search(user_input, user_id)
+        if results:
+            request.add_instructions(f"Use the following task memory to answer the user's question: {results}")
+
+
+async def test_long_term_memory_save():
+    """Test long-term memory saving with a meaningful conversation"""
+    
+    session_manager = InMemorySessionManager()
+    model = OpenAILlm(model="gpt-5-mini")
+    cross_session_manager = TaskCrossSessionManager(model=model)
+    
+    memory_search_tool = MemorySearchTool()
+    
+    agent = ToolCallingAgent(
+        name="memory_agent",
+        model=model,
+        instructions="You are a helpful assistant. Have a natural conversation and learn about the user's task. IMPORTANT: When the user asks about a specific term or technology, use the search results to provide a comprehensive answer. Do NOT ask for clarification if you find relevant search results. Only ask for clarification if search returns no results or the query is truly impossible to understand. If multiple meanings exist, provide information about the most common or relevant one based on the search results.",
+        tools=[search_web, memory_search_tool],
+        session_manager=session_manager,
+        cross_session_manager=cross_session_manager,
+        after_run_callbacks=[long_term_memory_save_callback]
+    )
+    
+    print("=== Testing Long-term Memory Save ===\n")
+    
+    test_conversations = [
+       "What is Mem0?",
+       "How does mem0 work?"
+    ]
+    
+    for i, message in enumerate(test_conversations, 1):
+        print(f"User: {message}")
+        session_id = f"test_session_{i}"
+        
+        response = await agent.run(
+            message,
+            session_id=session_id,
+            user_id=user_id
+        )
+        print(response)
+        # print(cross_session_manager.collection.peek())
+
+if __name__ == "__main__":
+    asyncio.run(test_long_term_memory_save())
+

chapter_06_memory/08_user_long_term.py

@@ -0,0 +1,98 @@
+from scratch_agents.agents.execution_context_ch6 import ExecutionContext
+from scratch_agents.agents.tool_calling_agent_ch6 import ToolCallingAgent
+from scratch_agents.models.openai import OpenAILlm
+from scratch_agents.sessions.user_cross_session_manager import UserCrossSessionManager
+from scratch_agents.sessions.in_memory_session_manager import InMemorySessionManager
+from scratch_agents.tools.base_tool import BaseTool
+from scratch_agents.models.llm_request import LlmRequest
+import asyncio
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+user_id = "test_user_123"
+
+async def user_memory_save_callback(context: ExecutionContext):
+    """Callback to save user memories after each interaction"""
+    cross_session_manager = context.cross_session_manager
+    session = context.session
+    execution_id = context.execution_id
+    
+    await cross_session_manager.process_session(session=session, execution_id=execution_id)
+    
+class UserMemorySearchTool(BaseTool):
+    """Tool to search and retrieve user memories"""
+    async def execute(self, context, **kwargs):
+        return None
+    
+    async def process_llm_request(self, request: LlmRequest, context: ExecutionContext):
+        user_id = context.session.user_id
+        # Get all existing memories for the user
+        all_memories = await context.cross_session_manager.find_existing([], user_id)
+        if all_memories:
+            memory_contents = [mem['content'] for mem in all_memories]
+            memory_text = "\n".join(f"- {content}" for content in memory_contents)
+            request.add_instructions(f"You have the following memories about this user:\n{memory_text}\n\nUse these memories to personalize your responses.")
+
+
+async def test_user_long_term_memory():
+    """Test user long-term memory with location updates"""
+    
+    session_manager = InMemorySessionManager()
+    model = OpenAILlm(model="gpt-4o-mini")
+    cross_session_manager = UserCrossSessionManager(model=model)
+    
+    memory_search_tool = UserMemorySearchTool()
+    
+    agent = ToolCallingAgent(
+        name="user_memory_agent",
+        model=model,
+        instructions="You are a helpful assistant that remembers information about the user. Have natural conversations and acknowledge what you know about the user when relevant.",
+        tools=[memory_search_tool],
+        session_manager=session_manager,
+        cross_session_manager=cross_session_manager,
+        after_run_callbacks=[user_memory_save_callback]
+    )
+    
+    print("=== Testing User Long-term Memory ===\n")
+    
+    # Test conversation about location changes
+    test_conversations = [
+        "Hi! I'm living in New York City. I love the energy here!",
+        "Actually, I just moved to Los Angeles last month. The weather is so much better here.",
+        "What do you remember about where I live?"
+    ]
+    
+    for i, message in enumerate(test_conversations, 1):
+        print(f"\n--- Conversation {i} ---")
+        print(f"User: {message}")
+        session_id = f"user_session_{i}"
+        
+        response = await agent.run(
+            message,
+            session_id=session_id,
+            user_id=user_id
+        )
+        print(f"Assistant: {response}")
+        
+        # Show current memories in the database with timestamps
+        print("\n=> Current User Memories:")
+        memories = await cross_session_manager.find_existing([], user_id)
+        if memories:
+            for mem in memories:
+                created = mem.get('created_at', 'Unknown')[:19] if mem.get('created_at') != 'Unknown' else 'Unknown'
+                updated = mem.get('updated_at', 'Unknown')[:19] if mem.get('updated_at') != 'Unknown' else 'Unknown'
+                print(f"  - {mem['content']}")
+                if created != updated:
+                    print(f"    (Created: {created}, Updated: {updated})")
+                else:
+                    print(f"    (Created: {created})")
+        else:
+            print("  (No memories yet)")
+        
+        # Small delay to see the progression
+        await asyncio.sleep(1)
+
+if __name__ == "__main__":
+    asyncio.run(test_user_long_term_memory())

pyproject.toml

@@ -5,6 +5,7 @@ description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
+    "chromadb>=1.0.20",
     "fastmcp>=2.11.3",
     "mcp>=1.13.1",
     "openai>=1.101.0",

scratch_agents/agents/execution_context_ch6.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from ..sessions.session import Session
+from ..sessions.in_memory_session_manager import InMemorySessionManager
+from ..sessions.base_session_manager import BaseSessionManager
+from dataclasses import field
+import uuid
+from pydantic import BaseModel
+from typing import List, Dict, Any
+from ..types.events import Event
+from ..sessions.base_cross_session_manager import BaseCrossSessionManager
+
+@dataclass
+class ExecutionContext:
+    session: Session
+    session_manager: BaseSessionManager
+    cross_session_manager: BaseCrossSessionManager
+    execution_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    current_step: int = 0
+    max_steps: int = 10
+    user_input: str = ""
+    final_result: str | BaseModel = ""
+    
+    def add_event(self, event: Event) -> None:
+        self.session_manager.add_event(self.session, event)
+    @property
+    def events(self) -> List[Event]:
+        return self.session.events
+    
+    @property
+    def state(self) -> Dict[str, Any]:
+        return self.session.state
+    
+    def increment_step(self) -> None:
+        self.current_step += 1

scratch_agents/agents/tool_calling_agent_ch4_base.py

@@ -38,7 +38,7 @@ class ToolCallingAgent:
                         tool_call_id=tool_call.tool_call_id,
                         name=tool_call.name,
                         status="success",
-                        content=[result_output],
+                        content=str(result_output),
                     )
                 )
             except Exception as e:
@@ -47,7 +47,7 @@ class ToolCallingAgent:
                         tool_call_id=tool_call.tool_call_id,
                         name=tool_call.name,
                         status="error",
-                        content=[str(e)],
+                        content=str(e),
                     )
                 )
         return tool_results

scratch_agents/agents/tool_calling_agent_ch4_callback.py

@@ -107,7 +107,7 @@ class ToolCallingAgent:
                     tool_call_id=tool_call.tool_call_id,
                     name=tool_call.name,
                     status=status,
-                    content=[tool_response],
+                    content=str(tool_response),
                 )
                 tool_results.append(tool_result)
 

scratch_agents/agents/tool_calling_agent_ch4_structured_output.py

@@ -47,7 +47,7 @@ class ToolCallingAgent:
                         tool_call_id=tool_call.tool_call_id,
                         name=tool_call.name,
                         status="success",
-                        content=[result_output],
+                        content=str(result_output),
                     )
                 )
             except Exception as e:
@@ -56,7 +56,7 @@ class ToolCallingAgent:
                         tool_call_id=tool_call.tool_call_id,
                         name=tool_call.name,
                         status="error",
-                        content=[str(e)],
+                        content=str(e),
                     )
                 )
         return tool_results

scratch_agents/agents/tool_calling_agent_ch6.py

@@ -0,0 +1,226 @@
+from typing import List, Dict, Any, Optional
+from ..models.base_llm import BaseLlm
+from ..models.llm_request import LlmRequest
+from ..models.llm_response import LlmResponse
+from ..types.contents import Message, ToolCall
+from ..types.events import Event
+from .execution_context_ch6 import ExecutionContext
+from ..tools.base_tool import BaseTool
+from ..types.contents import ToolResult
+from typing import Type
+from pydantic import BaseModel
+from ..tools.decorator import tool
+import inspect
+from ..sessions.base_session_manager import BaseSessionManager
+from ..sessions.in_memory_session_manager import InMemorySessionManager
+from ..sessions.base_cross_session_manager import BaseCrossSessionManager
+
+class ToolCallingAgent:
+    def __init__(self, name: str, model: BaseLlm, 
+                 tools: List[BaseTool] = [], 
+                 instructions: str = "", 
+                 max_steps: int = 10, 
+                 output_type: Optional[Type[BaseModel]] = None,
+                 before_llm_callbacks = None,
+                 after_llm_callbacks = None,
+                 before_tool_callbacks = None,
+                 after_tool_callbacks = None,
+                 after_run_callbacks = None,
+                 session_manager: BaseSessionManager = None,
+                 cross_session_manager: BaseCrossSessionManager = None):
+        self.name = name
+        self.model = model
+        self.max_steps = max_steps
+        self.instructions = instructions
+        self.output_type: Optional[Type[BaseModel]] = output_type
+        self.output_tool: Optional[str] = None
+        self.tools = self._setup_tools(tools)
+        self.before_llm_callbacks = before_llm_callbacks or []
+        self.after_llm_callbacks = after_llm_callbacks or []
+        self.before_tool_callbacks = before_tool_callbacks or []
+        self.after_tool_callbacks = after_tool_callbacks or []
+        self.after_run_callbacks = after_run_callbacks or []
+        self.session_manager = session_manager or InMemorySessionManager()  
+        self.cross_session_manager = cross_session_manager
+        
+    def _setup_tools(self, tools: List[BaseTool]):
+        if self.output_type is not None:
+            @tool(name="final_answer", description="Return the final structured answer matching the required schema.")
+            def final_answer(output: self.output_type) -> self.output_type:
+                return output
+            tools.append(final_answer)
+            self.output_tool = final_answer.name
+        return {t.name: t for t in tools}
+        
+    async def think(self, context: ExecutionContext, llm_request: LlmRequest):
+        for callback in self.before_llm_callbacks:
+            result = callback(context, llm_request)
+            if inspect.isawaitable(result):
+                result = await result
+            if result is not None:
+                return result
+        
+        llm_response = await self.model.generate(llm_request)
+        
+        for callback in self.after_llm_callbacks:
+            result = callback(context, llm_response)
+            if inspect.isawaitable(result):
+                result = await result
+            if result is not None:
+                return result 
+        
+        return llm_response
+
+    async def _execute_tool(self, context: ExecutionContext, tool_name: str, tool_input: dict) -> Any:
+        """Execute a tool with context injection if needed"""
+        tool = self.tools[tool_name]
+        
+        # All tools now handle context properly in their execute method
+        return await tool.execute(context, **tool_input)
+    
+    async def act(self, context: ExecutionContext, tool_calls: List[ToolCall]):
+        tool_results = []
+        for tool_call in tool_calls:
+            tool_name = tool_call.name
+            tool_input = tool_call.arguments
+            print(f"  → Calling {tool_name} with {tool_input}")
+
+            # Step 1: before_tool_callbacks - can skip tool execution
+            tool_response = None
+            for callback in self.before_tool_callbacks:
+                result = callback(context, tool_call)
+                if inspect.isawaitable(result):
+                    result = await result
+                if result is not None:
+                    tool_response = result
+                    break
+            
+            # Step 2: Execute tool if no callback provided result
+            status = "success"
+            if tool_response is None:
+                try:
+                    tool_response = await self._execute_tool(context, tool_name, tool_input)
+                except Exception as e:
+                    tool_response = str(e)
+                    status = "error"
+            
+                # Step 3: after_tool_callbacks - only after actual tool execution
+                for callback in self.after_tool_callbacks:
+                    result = callback(context, tool_response)
+                    if inspect.isawaitable(result):
+                        result = await result
+                    if result is not None:
+                        tool_response = result
+                        break
+            
+            # Step 4: Wrap in ToolResult at the end
+            if tool_response is not None:
+                tool_result = ToolResult(
+                    tool_call_id=tool_call.tool_call_id,
+                    name=tool_call.name,
+                    status=status,
+                    content=str(tool_response),
+                )
+                tool_results.append(tool_result)
+
+        return tool_results
+    
+    async def step(self, context: ExecutionContext):
+        print(f"[Step {context.current_step + 1}]")
+        llm_request = await self._prepare_llm_request(context)
+        llm_response = await self.think(context, llm_request)
+        if llm_response.error_message:
+            raise RuntimeError(f"LLM error: {llm_response.error_message}")
+        response_event = Event(
+            execution_id=context.execution_id,
+            author=self.name,
+            required_output_tool=self.output_tool or None,
+            **llm_response.model_dump(),
+        )
+        context.add_event(response_event)
+        
+        if tool_calls := response_event.get_tool_calls():
+            tool_results = await self.act(context, tool_calls)
+            tool_results_event = Event(
+                execution_id=context.execution_id,
+                author=self.name,
+                required_output_tool=self.output_tool or None,
+                content=tool_results,
+            )
+            context.add_event(tool_results_event)
+            
+        context.increment_step()
+        
+    async def run(self, user_input: str, 
+                  user_id: str = None,
+                  session_id: str = None):
+        session = self.session_manager.get_or_create_session(session_id, user_id)
+        context = ExecutionContext(
+            user_input=user_input,
+            session=session,
+            session_manager=self.session_manager,
+            cross_session_manager=self.cross_session_manager,
+        )
+        
+        user_input_event = Event(
+            execution_id=context.execution_id,
+            author="user",
+            content=[
+                Message(
+                    role="user",
+                    content=user_input,
+                )
+            ],
+        )
+        context.add_event(user_input_event)
+        
+        while not context.final_result and context.current_step < self.max_steps:
+            await self.step(context)
+            
+            last_event = context.events[-1]
+            if last_event.is_final_response():
+                context.final_result = self._extract_final_result(last_event)
+                
+        for callback in self.after_run_callbacks:
+            result = callback(context)
+            if inspect.isawaitable(result):
+                await result
+            
+        return context.final_result
+            
+    async def _prepare_llm_request(self, context: ExecutionContext):
+        flat_contents = []
+        for event in context.events:
+            flat_contents.extend(event.content)
+            
+        llm_request = LlmRequest(
+            instructions=[self.instructions] if self.instructions else [],
+            contents=flat_contents,
+            tools_dict={tool.name:tool for tool in self.tools.values() if tool.tool_definition},
+        )
+        
+        for tool in self.tools.values():
+            await tool.process_llm_request(llm_request, context)
+            
+        if self.output_tool:
+            llm_request.tool_choice = "required"
+        elif llm_request.tools_dict:
+            llm_request.tool_choice = "auto"
+        else:
+            llm_request.tool_choice = None
+            
+        return llm_request
+    
+    def _extract_final_result(self, event: Event):
+        if event.required_output_tool:
+            for item in event.content:
+                if (
+                    isinstance(item, ToolResult)
+                    and item.status == "success"
+                    and item.name == event.required_output_tool
+                    and item.content
+                ):
+                    return item.content[0]
+        for item in event.content:
+            if isinstance(item, Message) and item.role == "assistant":
+                return item.content

scratch_agents/memory/base_memory_strategy.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+class MemoryStrategy(ABC):
+    """Base class for memory management strategies"""
+    
+    @abstractmethod
+    async def apply(self, context, llm_request):  #A
+        """Apply memory management strategy to the request"""
+        pass
+    
+    async def __call__(self, context, llm_request):  #B
+        """Make strategy callable as a before_llm_callback"""
+        return await self.apply(context, llm_request)

scratch_agents/memory/core_memory_strategy.py

@@ -0,0 +1,21 @@
+from .base_memory_strategy import MemoryStrategy
+
+
+class CoreMemoryStrategy(MemoryStrategy):
+    """Automatically add core memory to LLM context"""
+    
+    async def apply(self, context, llm_request):
+        """Add core memory as instructions if it exists"""
+        core_memory = context.session.core_memory  
+        
+        memory_parts = []
+        if core_memory.get("agent"):  
+            memory_parts.append(f"[Your Persona]\n{core_memory['agent']}")
+        if core_memory.get("user"):  
+            memory_parts.append(f"[User Info]\n{core_memory['user']}")
+        
+        if memory_parts:  
+            memory_text = "\n\n".join(memory_parts)
+            llm_request.add_instructions([memory_text])  
+            
+        return None  

scratch_agents/memory/sliding_window_strategy.py

@@ -0,0 +1,26 @@
+from .base_memory_strategy import MemoryStrategy
+from ..models.llm_request import LlmRequest
+from ..agents.execution_context_ch6 import ExecutionContext
+
+
+class SlidingWindowStrategy(MemoryStrategy):
+    """Keep only the most recent N messages in context"""
+    
+    def __init__(self, max_messages: int = 20):
+        self.max_messages = max_messages
+        
+    async def apply(self, context: ExecutionContext, llm_request: LlmRequest):
+        """Apply sliding window to conversation history"""
+        contents = llm_request.contents
+        
+        if len(contents) <= self.max_messages:
+            return None
+        
+        # Keep only recent messages
+        recent_contents = contents[-self.max_messages:]
+        llm_request.contents = recent_contents
+        
+        print(f"Trimmed messages")
+        print(f"from {len(contents)} to {self.max_messages}") 
+        
+        return None

scratch_agents/memory/summarization_strategy.py

@@ -0,0 +1,77 @@
+from .base_memory_strategy import MemoryStrategy
+from ..models.llm_request import LlmRequest
+from ..types.contents import Message
+
+class SummarizationStrategy(MemoryStrategy):
+    """Summarize old messages to preserve information while reducing tokens"""
+    
+    def __init__(self, model, trigger_count: int = 10, keep_recent: int = 3):
+        self.model = model
+        self.trigger_count = trigger_count  #A
+        self.keep_recent = keep_recent  #B
+
+    async def _generate_summary(self, messages_text: str):
+        request = LlmRequest(
+            instructions=[  #A
+                "Summarize the following conversation concisely.",  #A
+                "Preserve key facts, decisions, and important context.",  #A
+                "Keep the summary under 200 words."  #A
+            ],
+            contents=[Message(role="user", content=messages_text)]  #B
+        )
+        
+        response = await self.model.generate(request)  #C
+        
+        for item in response.content:  #D
+            if isinstance(item, Message) and item.role == "assistant":  #D
+                return item.content  #D
+        
+        return "Summary generation failed"  #E
+
+    async def apply(self, context, llm_request):
+        """Apply summarization when new messages since last summary exceed threshold"""
+        contents = llm_request.contents
+        
+        messages_only = [item for item in contents if isinstance(item, Message)]  #A
+        last_summarized = context.state.get("last_summarized_index", 0)
+        
+        total_messages = len(messages_only)  #B
+        new_messages_count = total_messages - last_summarized  #B
+        
+        if new_messages_count < self.trigger_count:
+            return None
+        
+        summarize_until = total_messages - self.keep_recent  #C
+        to_summarize = messages_only[last_summarized:summarize_until]  #C
+        to_keep = contents[-self.keep_recent:] if len(contents) >= self.keep_recent else contents  #C
+        
+        if not to_summarize:
+            return None
+        
+        existing_summary = context.state.get("conversation_summary")
+        
+        summary_input = []  #D
+        if existing_summary:  #D
+            summary_input.append(f"Previous Summary:\n{existing_summary}\n")  #D
+        
+        summary_input.append("New Messages to Summarize:\n")  #D
+        for msg in to_summarize:  #D
+            summary_input.append(f"{msg.role}: {msg.content}")  #D
+        
+        messages_text = "\n".join(summary_input)  #D
+        
+        new_summary = await self._generate_summary(messages_text)  #E
+        
+        context.state["conversation_summary"] = new_summary
+        context.state["last_summarized_index"] = summarize_until
+        
+        if new_summary:
+            summary_instruction = f"[Previous Conversation Summary]\n{new_summary}"
+            llm_request.add_instructions([summary_instruction])  #F
+        
+        llm_request.contents = to_keep  #G
+        
+        print(f"Compressed {len(to_summarize)} messages")
+        print(f"Keeping {len(to_keep)} recent items")
+        
+        return None

scratch_agents/models/openai.py

@@ -4,7 +4,8 @@ from .llm_request import LlmRequest
 from .llm_response import LlmResponse
 from ..types.contents import Message, ToolCall, ToolResult
 import json
-from pydantic import Field
+from pydantic import Field, BaseModel
+from typing import Dict, Any, List
 
 class OpenAILlm(BaseLlm):
     """OpenAI LLM implementation"""
@@ -136,7 +137,7 @@ class OpenAILlm(BaseLlm):
                 messages.append({
                     "role": "tool",
                     "tool_call_id": item.tool_call_id,
-                    "content": str(item.content[0]) if item.content else ""
+                    "content": str(item.content) if item.content else ""
                 })
         
         # Flush any remaining assistant message
@@ -145,4 +146,29 @@ class OpenAILlm(BaseLlm):
         # Extract model parameters
         model_params = {**self.llm_config}
         
-        return messages, model_params
+        return messages, model_params
+    
+    async def generate_structured(self, messages: List[Dict[str, Any]], response_format: BaseModel):
+        """Generate structured output using OpenAI's response_format"""
+        try:
+            response = await self.openai_client.chat.completions.parse(
+                model=self.model,
+                messages=messages,
+                response_format=response_format,
+                **self.llm_config
+            )
+            
+            return response.choices[0].message.parsed
+        except Exception as e:
+            return {"error": str(e)}
+        
+    async def embed(self, model, texts: List[str]) -> List[List[float]]:
+        """Get embeddings using OpenAI API"""
+        try:
+            response = await self.openai_client.embeddings.create(
+                model=model,
+                input=texts
+            )
+            return [embedding.embedding for embedding in response.data]
+        except Exception as e:
+            return {"error": str(e)}

scratch_agents/sessions/base_cross_session_manager.py

@@ -0,0 +1,297 @@
+"""Base class for cross-session memory management."""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Optional, Any
+import chromadb
+from chromadb.utils import embedding_functions
+from chromadb.config import Settings
+from datetime import datetime
+import logging
+import os
+import uuid
+from .session import Session
+
+logger = logging.getLogger(__name__)
+
+
+class BaseCrossSessionManager(ABC):
+    """Abstract base class for cross-session memory management."""
+    
+    def __init__(
+        self,
+        model,
+        collection_name: str,
+        persist_directory: str = "./cross_session_db",
+        embedding_model: str = "text-embedding-3-small"
+    ):
+        """Initialize the base cross-session manager.
+        
+        Args:
+            model: LLM model for memory processing
+            collection_name: Name of the ChromaDB collection
+            persist_directory: Directory to persist ChromaDB data
+            embedding_model: Optional custom embedding model
+        """
+        self.model = model
+        self.collection_name = collection_name
+        self.persist_directory = persist_directory
+        self.embedding_model = embedding_model
+        
+        self.client = chromadb.PersistentClient(
+            path=persist_directory,
+        )
+        embedding_function = embedding_functions.OpenAIEmbeddingFunction(
+            api_key=os.getenv("OPENAI_API_KEY"),
+            model_name=self.embedding_model
+        )
+        
+        # Get or create collection
+        try:
+            self.collection = self.client.get_or_create_collection(
+                name=collection_name,
+                metadata={"hnsw:space": "cosine"},
+                embedding_function=embedding_function
+                )
+            logger.info(f"Using existing collection: {collection_name}")
+        except Exception:
+            logger.error(f"Error getting or creating collection: {collection_name}")
+            raise
+    
+    @abstractmethod
+    async def extract_memories(
+        self,
+        events: List[Dict[str, Any]],
+    ) -> List[str]:
+        """Extract memories from session events.
+        
+        Args:
+            events: List of session events
+            user_id: User identifier
+            
+        Returns:
+            List of extracted memory strings
+        """
+        pass
+    
+    async def process_session(
+        self,
+        session: Session,
+        execution_id: str
+    ) -> None:
+        """Process a completed session and extract/merge memories.
+        
+        Args:
+            session: Session data containing events
+            execution_id: Unique execution identifier
+        """
+        try:
+            user_id = session.user_id
+            events = session.events
+            
+            events = [event for event in events if event.execution_id == execution_id]
+            
+            memories = await self.extract_memories(events)
+            
+            if memories:
+                existing = await self.find_existing(memories, user_id)
+                actions = await self.decide_actions(memories, existing, user_id)
+                await self.execute_memory_actions(actions)
+            else:
+                logger.info(f"No memories extracted for user {user_id}")
+                
+        except Exception as e:
+            logger.error(f"Error processing session: {e}")
+    
+    async def find_existing(
+        self,
+        memories: List[str],
+        user_id: str
+    ) -> List[Dict[str, Any]]:
+        """Find existing memories.
+        
+        Args:
+            memories: List of new memory strings to merge
+            user_id: User identifier
+            
+        Returns:
+            List of existing memories with metadata
+        """
+        existing_memories = []
+        for memory in memories:
+            existing = await self.search(memory, user_id)
+            if existing:    
+                existing_memories.append(existing)
+        return existing_memories
+    
+    @abstractmethod
+    async def decide_actions(
+        self,
+        memories: List[str],
+        existing: List[Dict[str, Any]],
+        user_id: str
+    ) -> List[Dict[str, Any]]:
+        """Decide actions for new memories."""
+        pass
+
+    async def execute_memory_actions(
+        self,
+        actions: List[Dict[str, Any]]
+    ) -> None:
+        """Execute memory actions."""
+        for action in actions:
+            if action["action"] == "ADD":
+                metadata = action.get("metadata", {})
+                await self.add(action["memory"], action["user_id"], action.get("embedding"), metadata)
+            elif action["action"] == "UPDATE":
+                metadata = action.get("metadata", {})
+                await self.update(action["memory_id"], action["memory"], action.get("embedding"), metadata)
+            elif action["action"] == "DELETE":
+                await self.delete(action["memory_id"])
+            elif action["action"] == "NOOP":
+                pass
+    
+    async def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 5
+    ) -> List[Dict[str, Any]]:
+        """Search for relevant memories.
+        
+        Args:
+            query: Search query
+            user_id: User identifier
+            limit: Maximum number of results
+            
+        Returns:
+            List of relevant memories with metadata
+        """
+        try:
+            # Filter by user_id in metadata
+            where = {"user_id": user_id}
+            
+            results = self.collection.query(
+                query_texts=[query],
+                n_results=limit,
+                where=where
+            )
+            
+            memories = []
+            if results["documents"] and results["documents"][0]:
+                for i, doc in enumerate(results["documents"][0]):
+                    memory = {
+                        "id": results["ids"][0][i] if results["ids"] and results["ids"][0] else None,
+                        "content": doc,
+                        "metadata": results["metadatas"][0][i] if results["metadatas"] else {},
+                        "distance": results["distances"][0][i] if results["distances"] else 0
+                    }
+                    memories.append(memory)
+            
+            return memories
+            
+        except Exception as e:
+            logger.error(f"Error searching memories: {e}")
+            return []
+    
+    async def add(
+        self,
+        memory: str,
+        user_id: str,
+        embedding: Optional[List[float]] = None,
+        additional_metadata: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Add a new memory.
+        
+        Args:
+            memory: Memory content (as string for ChromaDB)
+            user_id: User identifier
+            embedding: Optional embedding vector
+            additional_metadata: Additional metadata to store
+            
+        Returns:
+            Memory ID
+        """
+        memory_id = f"{uuid.uuid4()}"
+        
+        final_metadata = {
+            "user_id": user_id,
+            "created_at": datetime.now().isoformat(),
+            "updated_at": datetime.now().isoformat()
+        }
+        
+        # Add any additional metadata (like the original structured data)
+        if additional_metadata:
+            final_metadata.update(additional_metadata)
+        
+        if embedding:
+            self.collection.upsert(
+                documents=[memory],
+                ids=[memory_id],
+                embeddings=[embedding],
+                metadatas=[final_metadata]
+            )
+        else:
+            self.collection.add(
+                documents=[memory],
+                ids=[memory_id],
+                metadatas=[final_metadata]
+            )
+        
+        return memory_id
+    
+    async def update(
+        self,
+        memory_id: str,
+        memory: str,
+        embedding: Optional[List[float]] = None,
+        additional_metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Update an existing memory.
+        
+        Args:
+            memory_id: ID of memory to update
+            memory: New memory content (as string for ChromaDB)
+            embedding: Optional embedding of the memory
+            additional_metadata: Additional metadata to update
+        """
+        if not memory_id:
+            logger.error("Cannot update memory: memory_id is None")
+            return
+            
+        # Get existing metadata
+        existing = self.collection.get(ids=[memory_id])
+        if existing["metadatas"] and existing["metadatas"][0]:
+            final_metadata = existing["metadatas"][0].copy()
+            final_metadata["updated_at"] = datetime.now().isoformat()
+        else:
+            final_metadata = {}
+            final_metadata["updated_at"] = datetime.now().isoformat()
+        
+        # Update with any additional metadata
+        if additional_metadata:
+            final_metadata.update(additional_metadata)
+            
+        if embedding:
+            self.collection.upsert(
+                ids=[memory_id],
+                documents=[memory],
+                embeddings=[embedding],
+                metadatas=[final_metadata]
+            )
+        else:
+            self.collection.upsert(
+                ids=[memory_id],
+                documents=[memory],
+                metadatas=[final_metadata]
+            )
+    
+    async def delete(
+        self,
+        memory_id: str
+    ) -> None:
+        """Delete a memory.
+        
+        Args:
+            memory_id: ID of memory to delete
+        """
+        self.collection.delete(ids=[memory_id])

scratch_agents/sessions/base_session_manager.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, List
+from scratch_agents.types.events import Event
+from scratch_agents.sessions.session import Session
+
+
+class BaseSessionManager(ABC):
+    """Abstract base class for session management"""
+    
+    @abstractmethod
+    def create_session(self, session_id: Optional[str] = None, user_id: str = None) -> Session:
+        """Create a new session"""
+        pass
+    
+    @abstractmethod
+    def get_session(self, session_id: str) -> Optional[Session]:
+        """Load a session from storage"""
+        pass
+    
+    @abstractmethod
+    def get_or_create_session(self, session_id: str, user_id: str = None) -> Session:
+        """Get an existing session or create a new one"""
+        pass
+    
+    @abstractmethod
+    def add_event(self, session: Session, event: Event) -> None:
+        """Add an event to the session"""
+        pass

scratch_agents/sessions/in_memory_session_manager.py

@@ -0,0 +1,30 @@
+from .base_session_manager import BaseSessionManager
+from .session import Session
+from scratch_agents.types.events import Event
+from datetime import datetime
+
+class InMemorySessionManager(BaseSessionManager):
+    """In-memory session manager"""
+    
+    def __init__(self):
+        self.sessions = {}
+        
+    def create_session(self, session_id: str, user_id: str = None) -> Session:
+        if session_id in self.sessions:
+            raise ValueError(f"Session with id {session_id} already exists")
+        self.sessions[session_id] = Session(session_id=session_id, user_id=user_id)
+        return self.sessions[session_id]
+    
+    def get_session(self, session_id: str) -> Session:
+        if session_id not in self.sessions:
+            raise ValueError(f"Session with id {session_id} does not exist")
+        return self.sessions[session_id]
+    
+    def get_or_create_session(self, session_id: str, user_id: str = None) -> Session:
+        if session_id not in self.sessions:
+            return self.create_session(session_id, user_id)
+        return self.sessions[session_id]
+
+    def add_event(self, session: Session, event: Event) -> None:
+        session.events.append(event)
+        session.last_updated_at = datetime.now()

scratch_agents/sessions/session.py

@@ -0,0 +1,23 @@
+import uuid
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any
+from datetime import datetime
+from ..types.contents import ContentItem
+
+class Session(BaseModel):
+    """Container for short-term memory during a conversation session"""
+    user_id: str
+    session_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    events: List[ContentItem] = Field(default_factory=list)
+    state: Dict[str, Any] = Field(default_factory=dict)
+    last_updated_at: datetime = Field(default_factory=datetime.now)
+    
+    @property
+    def core_memory(self) -> Dict[str, str]:
+        """Access core memory with automatic initialization"""
+        if "core_memory" not in self.state:
+            self.state["core_memory"] = {
+                "persona": "You are a helpful AI assistant",
+                "human": ""
+            }
+        return self.state["core_memory"]

scratch_agents/sessions/task_cross_session_manager.py

@@ -0,0 +1,194 @@
+"""Task-specific cross-session memory management."""
+
+from typing import List, Dict, Any, Optional, Literal
+import logging
+from pydantic import BaseModel, Field
+import json
+
+from .base_cross_session_manager import BaseCrossSessionManager
+from ..types.events import Event
+from ..types.contents import Message, ToolCall, ToolResult
+
+logger = logging.getLogger(__name__)
+
+MEMORY_EXTRACT_PROMPT = """
+You are a Task Memory Extractor specializing in tracking agent actions and problem-solving attempts.
+Extract ONLY information about what the agent ACTUALLY DID in this conversation.
+
+Focus on:
+1. **Problem Identification**: What issue or challenge was the agent trying to address?
+2. **Actions Taken**: What specific actions did the agent perform? (tools used, searches made, code written, etc.)
+3. **Key Discoveries**: What important facts or information did the agent discover during the process?
+4. **Success Status**: Was the task completed successfully?
+
+DO NOT extract:
+- Personal user information (name, preferences, etc.)
+- General conversation or greetings
+- User opinions or feelings
+- Future plans or what should be done
+
+Format each task as a structured memory with:
+- problem: Clear description of what the agent was asked to do or investigate
+- actions_taken: Specific actions the agent performed (not what it should do)
+- key_discoveries: Important information discovered during the task
+- success: true/false indicating if the task was completed
+
+Examples of GOOD task memories:
+{
+  "problem": "User asked about React component not rendering",
+  "actions_taken": "Examined useEffect hook, identified missing dependency in array, added state variable to dependency array",
+  "key_discoveries": "useEffect was missing 'count' state variable in dependency array causing stale closure",
+  "success": true
+}
+
+{
+  "problem": "User reported database connection timeouts in production",
+  "actions_taken": "Checked connection pool configuration, analyzed production logs, increased pool size from 10 to 50, implemented retry logic with exponential backoff",
+  "key_discoveries": "Production load peaked at 45 concurrent connections, default pool size was only 10",
+  "success": true
+}
+
+{
+  "problem": "User asked 'What is Mem0 and how does it work?'",
+  "actions_taken": "Performed multiple web searches with different query variations to find information about Mem0",
+  "key_discoveries": "Found that Mem0 is an open-source memory layer for LLM applications, has a GitHub repo (mem0ai/mem0), provides hybrid data storage and intelligent retrieval",
+  "success": false
+}
+"""
+
+MEMORY_ACTION_PROMPT = """
+You are a Task Memory Action Decider specializing in tracking agent actions and problem-solving attempts.
+You are given a list of new task memories and a list of existing task memories.
+You need to decide whether to ADD, UPDATE, DELETE, or NOOP the new task memories.
+
+Format your response as a list of actions with:
+- action: ADD, UPDATE, DELETE, or NOOP
+- memory_id: The id of the memory to update or delete
+
+Action:
+- ADD: Add the new task memory if it describes a different problem or significantly different approach
+- UPDATE: Update the existing task memory if it's the same problem but with better/more complete actions or discoveries
+- DELETE: Delete the existing task memory if it's outdated or no longer relevant
+- NOOP: Do not add if it's essentially the same problem with similar actions and discoveries
+
+"""
+
+
+class TaskMemory(BaseModel):
+    """Structured task memory."""
+    problem: str = Field(description="The problem or task the agent was asked to address")
+    actions_taken: str = Field(description="The specific actions the agent performed")
+    success: bool = Field(description="Whether the task was completed successfully")
+    key_discoveries: Optional[str] = Field(default=None, description="Important information discovered during the task")
+    
+class MemoryAction(BaseModel):
+    """Memory action."""
+    action: Literal["ADD", "UPDATE", "DELETE", "NOOP"] = Field(description="The action to take with the memory")
+    memory_id: Optional[str] = Field(description="The id of the memory to update or delete")
+
+
+class TaskCrossSessionManager(BaseCrossSessionManager):
+    """Manage task-specific memories across sessions."""
+    
+    def __init__(self, model, 
+                 collection_name="task_memories", 
+                 persist_directory="./cross_session_db",
+                 ):
+        """Initialize task cross-session manager.
+        
+        Args:
+            model: LLM model for memory extraction
+            collection_name: Name of the ChromaDB collection
+            persist_directory: Directory to persist ChromaDB data
+        """
+        super().__init__(model, collection_name, persist_directory)
+    
+    async def extract_memories(self, events: List[Event]):
+        conversation_parts = []
+        
+        for event in events:
+            for item in event.content:
+                if isinstance(item, Message):
+                    conversation_parts.append(f"{item.role}: {item.content}")
+                elif isinstance(item, ToolCall):
+                    conversation_parts.append(f"{item.tool_call_id}: {item.name}")
+                elif isinstance(item, ToolResult):
+                    conversation_parts.append(f"{item.tool_call_id}: {item.name} {item.content}")
+        
+        conversation = "\n".join(conversation_parts)
+
+        user_prompt = f"""Conversation:
+        {conversation}
+        """
+        messages = [
+            {"role": "system", "content": MEMORY_EXTRACT_PROMPT},
+            {"role": "user", "content": user_prompt}
+        ]
+        
+        try:
+            response = await self.model.generate_structured(messages, TaskMemory)
+            task_memory = TaskMemory.model_validate(response)
+            return [task_memory.model_dump()]
+            
+        except Exception as e:
+            logger.error(f"Error extracting task memories: {e}")
+            return []
+        
+    async def find_existing(self, memories: List[Dict], user_id: str) -> List[Dict[str, Any]]:
+        existing_memories = []
+        for memory in memories:
+            query = memory["problem"]
+            results = await self.search(query, user_id)
+            if results:
+                existing_memories.append(results[0])
+        return existing_memories
+    
+    async def decide_actions(self, new_memory: List[Dict], existing: List[Dict[str, Any]], user_id: str) -> List[Dict[str, Any]]:
+        system_prompt = MEMORY_ACTION_PROMPT
+        user_prompt = f"""
+        Existing memory: {existing}
+        New memory: {new_memory}
+        """
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt}
+        ]
+        action = await self.model.generate_structured(messages, MemoryAction)
+        result = []
+        if action.action == "UPDATE":
+
+            memory_id = action.memory_id
+            if not memory_id:
+                logger.error("Cannot update memory: no memory_id available")
+                return []
+            embeddings = await self.model.embed(self.embedding_model, [new_memory[0]["problem"]])
+            # Convert dict to string for ChromaDB document field
+            memory_str = json.dumps(new_memory[0], ensure_ascii=False)
+            result.append({
+                "action": "UPDATE",
+                "memory_id": memory_id,
+                "memory": memory_str,
+                "embedding": embeddings[0],
+                "metadata": new_memory[0]  # Store original dict in metadata
+            })
+        elif action.action == "ADD":
+            embeddings = await self.model.embed(self.embedding_model, [new_memory[0]["problem"]])
+            # Convert dict to string for ChromaDB document field
+            memory_str = json.dumps(new_memory[0], ensure_ascii=False)
+            result.append({
+                "action": "ADD",
+                "memory": memory_str,
+                "user_id": user_id,
+                "embedding": embeddings[0],
+                "metadata": new_memory[0]  # Store original dict in metadata
+            })
+        elif action.action == "DELETE":
+            result.append({
+                "action": "DELETE",
+                "memory_id": action.memory_id
+            })
+        elif action.action == "NOOP":
+            result.append({
+                "action": "NOOP"
+            })
+        return result

scratch_agents/sessions/user_cross_session_manager.py

@@ -0,0 +1,185 @@
+import json
+import chromadb
+from chromadb.utils import embedding_functions
+from typing import List, Optional, Literal, Dict, Any
+from enum import Enum
+import uuid
+from datetime import datetime
+import os
+from pydantic import BaseModel, Field
+import logging
+
+from .session import Session
+from .base_cross_session_manager import BaseCrossSessionManager
+from ..types.contents import Message
+from ..types.events import Event
+from ..models.llm_request import LlmRequest
+
+logger = logging.getLogger(__name__)
+
+MEMORY_EXTRACT_PROMPT = """
+You are a User Memory Extractor specializing in accurately storing ONLY facts about the USER from their messages. 
+
+CRITICAL RULES:
+1. ONLY extract factual information that the user explicitly states about themselves
+2. NEVER extract questions the user asks
+3. NEVER extract hypothetical scenarios or wishes
+4. NEVER create memories from assistant responses
+5. If the user is only asking questions, return an empty list
+
+Types of Information to Remember:
+
+1. **Personal Identity & Details**: Names, relationships, family information, important dates
+2. **Professional Information**: Current job title, company name, work responsibilities, career goals, past work experience
+3. **Personal Preferences**: Likes, dislikes, preferences in food, activities, entertainment, brands
+4. **Goals & Plans**: Future intentions, upcoming events, trips, personal objectives
+5. **Health & Wellness**: Dietary restrictions, fitness routines, health conditions
+6. **Lifestyle & Activities**: Hobbies, regular activities, service preferences
+7. **Location & Living Situation**: Where they live, recent moves, living arrangements
+"""
+
+MEMORY_ACTION_PROMPT = """
+You are a User Memory Action Decider specializing in accurately managing user facts and preferences.
+
+CRITICAL RULES FOR CONFLICTING INFORMATION:
+1. When new information CONTRADICTS or UPDATES existing information, you MUST use UPDATE action
+2. Location changes: If user moves from Place A to Place B, UPDATE the existing location memory
+3. Status changes: If user changes jobs, relationships, or any status, UPDATE the relevant memory  
+4. Preference changes: If user's preferences change, UPDATE the existing preference
+5. Look for semantic conflicts, not just exact text matches
+
+Examples of when to UPDATE:
+- Existing: "User works at Company A" + New: "User works at Company B" → UPDATE existing memory
+- Existing: "User likes coffee" + New: "User doesn't like coffee anymore" → UPDATE existing memory
+
+Format your response as a list of actions with:
+- action: ADD, UPDATE, DELETE, or NOOP
+- memory_id: The id of the memory to update or delete (required for UPDATE/DELETE)
+- content: The content of the memory to add or update (required for ADD/UPDATE)
+
+Actions:
+- ADD: Add new information that doesn't conflict with existing memories
+- UPDATE: Replace existing memory when there's conflicting or updated information
+- DELETE: Remove outdated or incorrect memory (use sparingly)
+- NOOP: Skip if the information is already stored or not relevant
+"""
+
+class MemoryAction(BaseModel):
+    """Structured output for memory action decision"""
+    action: Literal["ADD", "UPDATE", "DELETE", "NOOP"] = Field(
+        description="The action to take with the memory"
+    )
+    memory_id: Optional[str] = Field(
+        description="The id of the memory to update or delete"
+    )
+    content: Optional[str] = Field(
+        description="The content of the memory to add or update"
+    )
+
+class MemoryActions(BaseModel):
+    """A list of memory actions"""
+    actions: List[MemoryAction] = Field(
+        description="A list of memory actions"
+    )
+    
+class MemoryFacts(BaseModel):
+    """A list of facts about the user"""
+    facts: List[str] = Field(
+        description="A list of facts about the user"
+    )
+
+class UserCrossSessionManager(BaseCrossSessionManager):
+    """Manage memories across sessions using ChromaDB"""
+    
+    def __init__(self, model, collection_name="user_memory", persist_directory="./cross_session_db", embedding_model="text-embedding-3-small"):
+        # Initialize base class first
+        super().__init__(model, collection_name, persist_directory, embedding_model)
+
+    async def extract_memories(self, events: List[Any]) -> List[str]:
+        """Extract important information from execution events using LLM"""
+        
+        conversation_parts = []
+        for event in events:
+            for item in event.content:
+                if hasattr(item, 'role') and hasattr(item, 'content'):
+                    if item.role == 'user':
+                        conversation_parts.append(f"User: {item.content}")
+        
+        conversation = "\n".join(conversation_parts)
+        
+        if not conversation.strip():
+            return []
+        
+        user_prompt = f"""Conversation:
+        {conversation}
+        """
+        
+        messages = [
+            {"role": "system", "content": MEMORY_EXTRACT_PROMPT},
+            {"role": "user", "content": user_prompt}
+        ]
+        
+        response = await self.model.generate_structured(
+            messages,
+            MemoryFacts
+        )
+        logger.debug(f"Extracted facts: {response}")
+        try:
+            return response.facts
+        except Exception as e:
+            logger.error(f"Error extracting facts: {e}")
+            return []
+
+    async def find_existing(
+        self,
+        memories: List[str],
+        user_id: str
+    ) -> List[Dict[str, Any]]:
+        """Find existing memories.
+        
+        Args:
+            user_id: User identifier
+            
+        Returns:
+            List of existing memories with metadata including timestamps
+        """
+        existing_memories = []
+        results = self.collection.get(
+            where={"user_id": user_id},
+            include=["documents", "metadatas"]
+        )
+        if results["documents"]:
+            for i, doc in enumerate(results["documents"]):
+                metadata = results["metadatas"][i] if results["metadatas"] else {}
+                existing_memories.append({
+                    "id": results["ids"][i],
+                    "content": doc,
+                    "metadata": metadata,
+                    "created_at": metadata.get("created_at", "Unknown"),
+                    "updated_at": metadata.get("updated_at", "Unknown")
+                })
+        return existing_memories
+    
+    async def decide_actions(self, new_memories: List[str], existing: List[Dict[str, Any]], user_id: str) -> List[Dict[str, Any]]:
+        """Decide actions for new memories."""
+        system_prompt = MEMORY_ACTION_PROMPT
+
+        user_prompt = f"""
+        Existing memory: {existing}
+        New memory: {new_memories}
+        """
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt}
+        ]
+        actions = await self.model.generate_structured(messages, MemoryActions)
+        result = []
+        for action in actions.actions:
+            action_dict = action.model_dump()
+            if action_dict["action"] == "ADD":
+                action_dict["user_id"] = user_id
+                action_dict["memory"] = action_dict.pop("content", None)
+            elif action_dict["action"] == "UPDATE":
+                action_dict["memory"] = action_dict.pop("content", None)
+            result.append(action_dict)
+        return result

scratch_agents/tools/base_tool.py

@@ -2,6 +2,8 @@ from typing import Any, Dict, Type, Union, Optional
 from abc import ABC, abstractmethod
 import json
 from .schema_utils import format_tool_definition
+from ..agents.execution_context_ch6 import ExecutionContext
+from ..models.llm_request import LlmRequest
 
 
 class BaseTool(ABC):
@@ -11,11 +13,13 @@ class BaseTool(ABC):
         name: str = None, 
         description: str = None, 
         tool_definition: Optional[Union[Dict[str, Any], str]] = None,
-        pydantic_input_model: Type = None
+        pydantic_input_model: Type = None,
+        output_type: str = "str"
     ):
         self.name = name or self.__class__.__name__
         self.description = description or self.__doc__ or ""
         self.pydantic_input_model = pydantic_input_model
+        self.output_type = output_type
         
         if isinstance(tool_definition, str):
             self._tool_definition = json.loads(tool_definition)
@@ -48,7 +52,30 @@ class BaseTool(ABC):
         return await self.execute(**kwargs)
     
     @abstractmethod
-    async def execute(self, **kwargs) -> Any:
+    async def execute(self, context: ExecutionContext, **kwargs) -> Any:
         raise NotImplementedError(
             f"{self.__class__.__name__} must implement the execute method"
-        )
+        )
+        
+    async def process_llm_request(self, request: LlmRequest, context: ExecutionContext):
+        return None
+    
+    def to_code_prompt(self) -> str:
+        """Generate tool description for code execution environment"""
+        params_desc = ""
+        if self._tool_definition and "function" in self._tool_definition:
+            func_def = self._tool_definition["function"]
+            if "parameters" in func_def and "properties" in func_def["parameters"]:
+                params = []
+                for param_name, param_info in func_def["parameters"]["properties"].items():
+                    param_type = param_info.get("type", "Any")
+                    param_desc = param_info.get("description", "")
+                    required = param_name in func_def["parameters"].get("required", [])
+                    req_str = " (required)" if required else " (optional)"
+                    params.append(f"    - {param_name}: {param_type}{req_str} - {param_desc}")
+                if params:
+                    params_desc = "\n  Parameters:\n" + "\n".join(params)
+        
+        return f"""Tool: {self.name}
+  Description: {self.description}
+  Output Type: {self.output_type}{params_desc}"""

scratch_agents/tools/conversation_search.py

@@ -0,0 +1,49 @@
+from .decorator import tool
+from ..agents.execution_context_ch6 import ExecutionContext
+from ..types.contents import Message
+
+@tool
+async def conversation_search(
+    query: str,
+    limit: int = 5,
+    context: ExecutionContext = None
+):
+    """Search through current session's conversation history using exact keyword matching
+    
+    IMPORTANT: Use SHORT, SPECIFIC KEYWORDS that likely appear in the conversation.
+    
+    Args:
+        query: Short keyword to search for (use simple words that might appear in messages)
+        limit: Maximum number of results to return
+        context: Execution context with session access
+    
+    Returns:
+        Formatted string with search results or message if none found
+    """
+    
+    query_lower = query.lower()
+    results = []  
+    
+    for event in context.session.events:
+        for item in event.content:
+            if isinstance(item, Message) and item.content:
+                if query_lower in item.content.lower():
+                    results.append({
+                        "role": item.role,
+                        "content": item.content,
+                        "event_id": event.id,
+                        "timestamp": event.timestamp
+                    })
+                    break
+    
+    results = results[-limit:]
+    
+    if not results:
+        return f"No messages found containing '{query}'"
+    
+    formatted = f"Found {len(results)} message(s) containing '{query}':\n\n"
+    for i, result in enumerate(results, 1):
+        formatted += f"{i}. [{result['role']}]: {result['content']}"
+        formatted += "\n\n"
+    
+    return formatted

scratch_agents/tools/core_memory_upsert.py

@@ -0,0 +1,33 @@
+from .decorator import tool
+
+@tool
+async def core_memory_upsert(
+    block: str, 
+    content: str, 
+    update_content: str = None, 
+    context = None 
+) -> str:
+    """Update or insert content in core memory blocks
+    
+    Args:
+        block: Must be 'agent' or 'user'
+        content: Text to find or full replacement
+        update_content: New text for partial update
+    """
+    
+    memory = context.session.core_memory
+    current = memory.get(block, "")
+    
+    if update_content:  
+        if content in current:
+            memory[block] = current.replace(content, update_content)
+            return f"Updated {block}"
+        else:
+            if current:
+                memory[block] = f"{current}\n{update_content}"
+            else:
+                memory[block] = update_content  
+                return f"Added to {block}: {update_content}"
+    else:
+        memory[block] = content
+        return f"Set {block}"

scratch_agents/tools/function_tool.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, Type, Union, Callable, Optional
+from typing import Any, Dict, Type, Union, Callable, Optional, get_type_hints
 import inspect
 import asyncio
 from .base_tool import BaseTool
@@ -11,28 +11,38 @@ class FunctionTool(BaseTool):
         func: Callable, 
         name: str = None, 
         description: str = None,
-        tool_definition: Union[Dict[str, Any], str] = None
+        tool_definition: Union[Dict[str, Any], str] = None,
+        output_type: str = None
     ):
         self.func = func
-        self.pydantic_input_model = self._detect_pydantic_model(func)  #A
+        self.pydantic_input_model = self._detect_pydantic_model(func)
         
-        name = name or func.__name__  #B
-        description = description or (func.__doc__ or "").strip()  #B
+        name = name or func.__name__
+        description = description or (func.__doc__ or "").strip()
+        
+        if output_type is None:
+            output_type = self._detect_output_type(func)
         
         super().__init__(
             name=name, 
             description=description, 
             tool_definition=tool_definition,
-            pydantic_input_model=self.pydantic_input_model
+            pydantic_input_model=self.pydantic_input_model,
+            output_type=output_type
         )
     
-    async def execute(self, **kwargs) -> Any:
+    async def execute(self, context, **kwargs) -> Any:
+        sig = inspect.signature(self.func)
+        expects_context = 'context' in sig.parameters
+        
         if self.pydantic_input_model:
             args = (self.pydantic_input_model.model_validate(kwargs),)
-            call_kwargs = {}
+            call_kwargs = {'context': context} if expects_context else {}
         else:
             args = ()
             call_kwargs = kwargs
+            if expects_context and 'context' not in call_kwargs:
+                call_kwargs['context'] = context
         
         if inspect.iscoroutinefunction(self.func):
             return await self.func(*args, **call_kwargs)
@@ -61,4 +71,34 @@ class FunctionTool(BaseTool):
                     return param_type
         except ImportError:
             pass
-        return None
+        return None
+    
+    def _detect_output_type(self, func: Callable) -> str:
+        """Detect the output type from function's return type hint"""
+        try:
+            type_hints = get_type_hints(func)
+            return_type = type_hints.get('return', None)
+            
+            if return_type is None:
+                return "str"
+            
+            type_mapping = {
+                str: "str",
+                int: "int",
+                float: "float",
+                bool: "bool",
+                list: "list",
+                dict: "dict",
+                tuple: "tuple",
+                type(None): "None"
+            }
+            
+            if return_type in type_mapping:
+                return type_mapping[return_type]
+            
+            raise ValueError(f"Unsupported return type: {return_type}. Only basic types are supported.")
+            
+        except ValueError:
+            raise
+        except Exception:
+            return "str"

scratch_agents/types/contents.py

@@ -13,7 +13,7 @@ class ToolResult(BaseModel):
     tool_call_id: str
     name: str
     status: Literal["success", "error"]
-    content: list
+    content: str
 
 class Message(BaseModel):
     type: Literal["message"] = "message"