neuro-simulator 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

neuro_simulator/agent/core.py

@@ -9,33 +9,16 @@ import asyncio
 import json
 import logging
 import re
+from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List
 
-from ..utils.logging import QueueLogHandler, agent_log_queue
-from ..utils.websocket import connection_manager
+from ..core.path_manager import path_manager
 from .llm import LLMClient
 from .memory.manager import MemoryManager
-from .tools.core import ToolManager
+from .tools.manager import ToolManager
 
-# Create a logger for the agent
-agent_logger = logging.getLogger("neuro_agent")
-agent_logger.setLevel(logging.DEBUG)
-
-# Configure agent logging to use the shared queue
-def configure_agent_logging():
-    """Configure agent logging to use the shared agent_log_queue."""
-    if agent_logger.hasHandlers():
-        agent_logger.handlers.clear()
-    
-    agent_queue_handler = QueueLogHandler(agent_log_queue)
-    formatter = logging.Formatter('%(asctime)s - [%(name)-32s] - %(levelname)-8s - %(message)s', datefmt='%H:%M:%S')
-    agent_queue_handler.setFormatter(formatter)
-    agent_logger.addHandler(agent_queue_handler)
-    agent_logger.propagate = False
-    agent_logger.info("Agent logging configured to use agent_log_queue.")
-
-configure_agent_logging()
+logger = logging.getLogger("neuro_agent")
 
 class Agent:
     """
@@ -44,71 +27,104 @@ class Agent:
     - The "Memory" part (Thinker) handles background memory consolidation.
     """
     
-    def __init__(self, working_dir: str = None):
-        self.memory_manager = MemoryManager(working_dir)
+    def __init__(self):
+        if not path_manager:
+            raise RuntimeError("PathManager must be initialized before the Agent.")
+        
+        self.memory_manager = MemoryManager()
         self.tool_manager = ToolManager(self.memory_manager)
         
-        # Dual LLM clients
         self.neuro_llm = LLMClient()
         self.memory_llm = LLMClient()
         
         self._initialized = False
         self.turn_counter = 0
-        self.reflection_threshold = 3  # Trigger reflection every 3 turns
-        
-        agent_logger.info("Agent instance created with dual-LLM architecture.")
-        agent_logger.debug(f"Agent working directory: {working_dir}")
+        self.reflection_threshold = 3
         
+        logger.info("Agent instance created with dual-LLM architecture.")
+
     async def initialize(self):
         """Initialize the agent, loading any persistent memory."""
         if not self._initialized:
-            agent_logger.info("Initializing agent memory manager...")
+            logger.info("Initializing agent memory manager...")
             await self.memory_manager.initialize()
             self._initialized = True
-            agent_logger.info("Agent initialized successfully.")
+            logger.info("Agent initialized successfully.")
         
     async def reset_all_memory(self):
-        """Reset all agent memory types."""
+        """Reset all agent memory types and clear history logs."""
         await self.memory_manager.reset_temp_memory()
-        await self.memory_manager.reset_chat_history()
-        agent_logger.info("All agent memory has been reset.")
+        # Clear history files by overwriting them
+        open(path_manager.neuro_history_path, 'w').close()
+        open(path_manager.memory_agent_history_path, 'w').close()
+        logger.info("All agent memory and history logs have been reset.")
+
+    async def get_neuro_history(self, limit: int = 20) -> List[Dict[str, Any]]:
+        """Reads the last N lines from the Neuro agent's history log."""
+        return await self._read_history_log(path_manager.neuro_history_path, limit)
+
+    async def _append_to_history_log(self, file_path: Path, data: Dict[str, Any]):
+        """Appends a new entry to a JSON Lines history file."""
+        data['timestamp'] = datetime.now().isoformat()
+        with open(file_path, 'a', encoding='utf-8') as f:
+            f.write(json.dumps(data, ensure_ascii=False) + '\n')
+
+    async def _read_history_log(self, file_path: Path, limit: int) -> List[Dict[str, Any]]:
+        """Reads the last N lines from a JSON Lines history file."""
+        if not file_path.exists():
+            return []
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                lines = f.readlines()
+            # Get the last N lines and parse them
+            return [json.loads(line) for line in lines[-limit:]]
+        except (json.JSONDecodeError, IndexError) as e:
+            logger.error(f"Could not read or parse history from {file_path}: {e}")
+            return []
+
+    def _format_tool_schemas_for_prompt(self, schemas: List[Dict[str, Any]]) -> str:
+        """Formats a list of tool schemas into a string for the LLM prompt."""
+        if not schemas:
+            return "No tools available."
+        lines = ["Available tools:"]
+        for i, schema in enumerate(schemas):
+            params_str_parts = []
+            for param in schema.get("parameters", []):
+                p_name = param.get('name')
+                p_type = param.get('type')
+                p_req = 'required' if param.get('required') else 'optional'
+                params_str_parts.append(f"{p_name}: {p_type} ({p_req})")
+            params_str = ", ".join(params_str_parts)
+            lines.append(f"{i+1}. {schema.get('name')}({params_str}) - {schema.get('description')}")
+        return "\n".join(lines)
 
     async def _build_neuro_prompt(self, messages: List[Dict[str, str]]) -> str:
         """Builds the prompt for the Neuro (Actor) LLM."""
-        template_path = Path(self.memory_manager.memory_dir).parent / "neuro_prompt.txt"
-        with open(template_path, 'r', encoding='utf-8') as f:
-            prompt_template = f.read()
-
-        # Gather context
-        tool_descriptions = self.tool_manager.get_tool_descriptions()
+        prompt_template = "" # Define a default empty prompt
+        if path_manager.neuro_prompt_path.exists():
+            with open(path_manager.neuro_prompt_path, 'r', encoding='utf-8') as f:
+                prompt_template = f.read()
+        else:
+            logger.warning(f"Neuro prompt template not found at {path_manager.neuro_prompt_path}")
+
+        tool_schemas = self.tool_manager.get_tool_schemas_for_agent('neuro_agent')
+        tool_descriptions = self._format_tool_schemas_for_prompt(tool_schemas)
+        
+        init_memory_text = "\n".join(f"{key}: {value}" for key, value in self.memory_manager.init_memory.items())
         
-        # Format Core Memory from blocks
         core_memory_blocks = await self.memory_manager.get_core_memory_blocks()
-        core_memory_parts = []
-        if core_memory_blocks:
-            for block_id, block in core_memory_blocks.items():
-                core_memory_parts.append(f"\nBlock: {block.get('title', '')} ({block_id})")
-                core_memory_parts.append(f"Description: {block.get('description', '')}")
-                content_items = block.get("content", [])
-                if content_items:
-                    core_memory_parts.append("Content:")
-                    for item in content_items:
-                        core_memory_parts.append(f"  - {item}")
+        core_memory_parts = [f"\nBlock: {b.get('title', '')} ({b_id})\nDescription: {b.get('description', '')}\nContent:\n" + "\n".join([f"  - {item}" for item in b.get("content", [])]) for b_id, b in core_memory_blocks.items()]
         core_memory_text = "\n".join(core_memory_parts) if core_memory_parts else "Not set."
 
-        # Format Temp Memory
-        temp_memory_items = self.memory_manager.temp_memory
-        temp_memory_text = "\n".join(
-            [f"[{item.get('role', 'system')}] {item.get('content', '')}" for item in temp_memory_items]
-        ) if temp_memory_items else "Empty."
+        temp_memory_text = "\n".join([f"[{item.get('role', 'system')}] {item.get('content', '')}" for item in self.memory_manager.temp_memory]) if self.memory_manager.temp_memory else "Empty."
 
-        recent_history = await self.memory_manager.get_recent_chat(entries=10)
-        
+        recent_history = await self._read_history_log(path_manager.neuro_history_path, limit=10)
+        recent_history_text = "\n".join([f"{msg.get('role', 'unknown')}: {msg.get('content', '')}" for msg in recent_history])
         user_messages_text = "\n".join([f"{msg['username']}: {msg['text']}" for msg in messages])
-        recent_history_text = "\n".join([f"{msg['role']}: {msg['content']}" for msg in recent_history])
 
         return prompt_template.format(
             tool_descriptions=tool_descriptions,
+            init_memory=init_memory_text,
             core_memory=core_memory_text,
             temp_memory=temp_memory_text,
             recent_history=recent_history_text,
@@ -117,39 +133,35 @@ class Agent:
 
     async def _build_memory_prompt(self, conversation_history: List[Dict[str, str]]) -> str:
         """Builds the prompt for the Memory (Thinker) LLM."""
-        template_path = Path(self.memory_manager.memory_dir).parent / "memory_prompt.txt"
-        with open(template_path, 'r', encoding='utf-8') as f:
-            prompt_template = f.read()
-        
-        history_text = "\n".join([f"{msg['role']}: {msg['content']}" for msg in conversation_history])
+        prompt_template = "" # Define a default empty prompt
+        if path_manager.memory_agent_prompt_path.exists():
+            with open(path_manager.memory_agent_prompt_path, 'r', encoding='utf-8') as f:
+                prompt_template = f.read()
+        else:
+            logger.warning(f"Memory prompt template not found at {path_manager.memory_agent_prompt_path}")
+
+        tool_schemas = self.tool_manager.get_tool_schemas_for_agent('memory_agent')
+        tool_descriptions = self._format_tool_schemas_for_prompt(tool_schemas)
+        history_text = "\n".join([f"{msg.get('role', 'unknown')}: {msg.get('content', '')}" for msg in conversation_history])
         
-        return prompt_template.format(conversation_history=history_text)
+        return prompt_template.format(
+            tool_descriptions=tool_descriptions,
+            conversation_history=history_text
+        )
 
     def _parse_tool_calls(self, response_text: str) -> List[Dict[str, Any]]:
-        """Parses LLM response for JSON tool calls."""
         try:
-            # The LLM is prompted to return a JSON array of tool calls.
-            # Find the JSON block, which might be wrapped in markdown.
             match = re.search(r'''```json\s*([\s\S]*?)\s*```|(\[[\s\S]*\])''', response_text)
             if not match:
-                agent_logger.warning(f"No valid JSON tool call block found in response: {response_text}")
+                logger.warning(f"No valid JSON tool call block found in response: {response_text}")
                 return []
-
             json_str = match.group(1) or match.group(2)
-            tool_calls = json.loads(json_str)
-            
-            if isinstance(tool_calls, list):
-                return tool_calls
-            return []
-        except json.JSONDecodeError as e:
-            agent_logger.error(f"Failed to decode JSON from LLM response: {e}\nResponse text: {response_text}")
-            return []
+            return json.loads(json_str)
         except Exception as e:
-            agent_logger.error(f"An unexpected error occurred while parsing tool calls: {e}")
+            logger.error(f"Failed to parse tool calls from LLM response: {e}")
             return []
 
     async def _execute_tool_calls(self, tool_calls: List[Dict[str, Any]]) -> Dict[str, Any]:
-        """Executes a list of parsed tool calls."""
         execution_results = []
         final_response = ""
         for tool_call in tool_calls:
@@ -157,78 +169,33 @@ class Agent:
             params = tool_call.get("params", {})
             if not tool_name:
                 continue
-
-            agent_logger.info(f"Executing tool: {tool_name} with params: {params}")
+            logger.info(f"Executing tool: {tool_name} with params: {params}")
             try:
-                result = await self.tool_manager.execute_tool(tool_name, params)
+                result = await self.tool_manager.execute_tool(tool_name, **params)
                 execution_results.append({"name": tool_name, "params": params, "result": result})
-                if tool_name == "speak":
-                    final_response = params.get("text", "")
+                if tool_name == "speak" and result.get("status") == "success":
+                    final_response = result.get("spoken_text", "")
             except Exception as e:
-                agent_logger.error(f"Error executing tool {tool_name}: {e}")
+                logger.error(f"Error executing tool {tool_name}: {e}")
                 execution_results.append({"name": tool_name, "params": params, "error": str(e)})
-        
         return {"tool_executions": execution_results, "final_response": final_response}
 
     async def process_and_respond(self, messages: List[Dict[str, str]]) -> Dict[str, Any]:
-        """
-        The main entry point for the "Neuro" (Actor) flow.
-        Handles real-time interaction and triggers background reflection.
-        """
         await self.initialize()
-        agent_logger.info(f"Processing {len(messages)} messages in Actor flow.")
+        logger.info(f"Processing {len(messages)} messages in Actor flow.")
 
-        # Add user messages to context
         for msg in messages:
-            await self.memory_manager.add_chat_entry("user", f"{msg['username']}: {msg['text']}")
+            await self._append_to_history_log(path_manager.neuro_history_path, {'role': 'user', 'content': f"{msg['username']}: {msg['text']}"})
 
-        # Build prompt and get response from Neuro LLM
         prompt = await self._build_neuro_prompt(messages)
         response_text = await self.neuro_llm.generate(prompt)
-        agent_logger.debug(f"Neuro LLM raw response: {response_text[:150] if response_text else 'None'}...")
-
-        # Parse and execute tools
+        
         tool_calls = self._parse_tool_calls(response_text)
         processing_result = await self._execute_tool_calls(tool_calls)
 
-        # Add agent's response to context
-        if processing_result["final_response"]:
-            await self.memory_manager.add_chat_entry("assistant", processing_result["final_response"])
-
-        # Update dashboard/UI
-        final_context = await self.memory_manager.get_recent_chat()
-        # Broadcast to stream clients
-        await connection_manager.broadcast({"type": "agent_context", "action": "update", "messages": final_context})
-        # Broadcast to admin clients (Dashboard)
-        await connection_manager.broadcast_to_admins({"type": "agent_context", "action": "update", "messages": final_context})
-
-        # Handle reflection trigger
-        self.turn_counter += 1
-        if self.turn_counter >= self.reflection_threshold:
-            agent_logger.info(f"Reflection threshold reached ({self.turn_counter}/{self.reflection_threshold}). Scheduling background reflection.")
-            history_for_reflection = await self.memory_manager.get_recent_chat(entries=self.reflection_threshold * 2) # Get a bit more context
-            asyncio.create_task(self.reflect_on_context(history_for_reflection))
-            self.turn_counter = 0
-
-        agent_logger.info("Actor flow completed.")
-        return processing_result
+        if final_response := processing_result.get("final_response", ""):
+            await self._append_to_history_log(path_manager.neuro_history_path, {'role': 'assistant', 'content': final_response})
 
-    async def reflect_on_context(self, conversation_history: List[Dict[str, str]]):
-        """
-        The main entry point for the "Memory" (Thinker) flow.
-        Runs in the background to consolidate memories.
-        """
-        agent_logger.info("Thinker flow started: Reflecting on recent context.")
-        
-        prompt = await self._build_memory_prompt(conversation_history)
-        response_text = await self.memory_llm.generate(prompt)
-        agent_logger.debug(f"Memory LLM raw response: {response_text[:150] if response_text else 'None'}...")
-
-        tool_calls = self._parse_tool_calls(response_text)
-        if not tool_calls:
-            agent_logger.info("Thinker flow: No memory operations were suggested by the LLM.")
-            return
+        return processing_result
 
-        agent_logger.info(f"Thinker flow: Executing {len(tool_calls)} memory operations.")
-        await self._execute_tool_calls(tool_calls)
-        agent_logger.info("Thinker flow completed, memory has been updated.")
+    

neuro_simulator/agent/llm.py

@@ -6,7 +6,7 @@ LLM client for the Neuro Simulator's built-in agent.
 import asyncio
 import logging
 from pathlib import Path
-from typing import Optional
+from typing import Any, Dict
 
 from google import genai
 from google.genai import types

neuro_simulator/agent/memory/manager.py

@@ -1,48 +1,43 @@
 # neuro_simulator/agent/memory/manager.py
 """
-Advanced memory management for the Neuro Simulator Agent.
+Manages the agent's shared memory state (init, core, temp).
 """
 
-import asyncio
 import json
 import logging
-import os
 import random
 import string
-from datetime import datetime
 from typing import Any, Dict, List, Optional
+from datetime import datetime
+
+from ...core.path_manager import path_manager
 
-# Use the existing agent logger for consistent logging
-logger = logging.getLogger("neuro_agent")
+logger = logging.getLogger(__name__.replace("neuro_simulator", "agent", 1))
 
 def generate_id(length=6) -> str:
     """Generate a random ID string."""
     return ''.join(random.choices(string.ascii_letters + string.digits, k=length))
 
 class MemoryManager:
-    """Manages different types of memory for the agent."""
+    """Manages the three types of shared memory for the agent."""
     
-    def __init__(self, working_dir: str = None):
-        if working_dir is None:
-            working_dir = os.getcwd()
-            
-        self.memory_dir = os.path.join(working_dir, "agent", "memory")
-        os.makedirs(self.memory_dir, exist_ok=True)
-        
-        self.init_memory_file = os.path.join(self.memory_dir, "init_memory.json")
-        self.core_memory_file = os.path.join(self.memory_dir, "core_memory.json")
-        self.chat_history_file = os.path.join(self.memory_dir, "chat_history.json")
-        self.temp_memory_file = os.path.join(self.memory_dir, "temp_memory.json")
+    def __init__(self):
+        """Initializes the MemoryManager using paths from the global path_manager."""
+        if not path_manager:
+            raise RuntimeError("PathManager not initialized before MemoryManager.")
+
+        self.init_memory_file = path_manager.init_memory_path
+        self.core_memory_file = path_manager.core_memory_path
+        self.temp_memory_file = path_manager.temp_memory_path
         
         self.init_memory: Dict[str, Any] = {}
         self.core_memory: Dict[str, Any] = {}
-        self.chat_history: List[Dict[str, Any]] = []
         self.temp_memory: List[Dict[str, Any]] = []
         
     async def initialize(self):
-        """Load all memory types from files."""
-        # Load init memory
-        if os.path.exists(self.init_memory_file):
+        """Load all memory types from files, creating defaults if they don't exist."""
+        # Load or create init memory
+        if self.init_memory_file.exists():
             with open(self.init_memory_file, 'r', encoding='utf-8') as f:
                 self.init_memory = json.load(f)
         else:
@@ -53,29 +48,23 @@ class MemoryManager:
             }
             await self._save_init_memory()
             
-        # Load core memory
-        if os.path.exists(self.core_memory_file):
+        # Load or create core memory
+        if self.core_memory_file.exists():
             with open(self.core_memory_file, 'r', encoding='utf-8') as f:
                 self.core_memory = json.load(f)
         else:
             self.core_memory = {"blocks": {}}
             await self._save_core_memory()
             
-        # Load chat history
-        if os.path.exists(self.chat_history_file):
-            with open(self.chat_history_file, 'r', encoding='utf-8') as f:
-                self.chat_history = json.load(f)
-        else:
-            self.chat_history = []
-            
-        # Load temp memory
-        if os.path.exists(self.temp_memory_file):
+        # Load or create temp memory
+        if self.temp_memory_file.exists():
             with open(self.temp_memory_file, 'r', encoding='utf-8') as f:
                 self.temp_memory = json.load(f)
         else:
             self.temp_memory = []
+            await self._save_temp_memory()
                 
-        logger.info("Agent memory manager initialized.")
+        logger.info("MemoryManager initialized and memory files loaded/created.")
         
     async def _save_init_memory(self):
         with open(self.init_memory_file, 'w', encoding='utf-8') as f:
@@ -89,84 +78,16 @@ class MemoryManager:
         with open(self.core_memory_file, 'w', encoding='utf-8') as f:
             json.dump(self.core_memory, f, ensure_ascii=False, indent=2)
             
-    async def _save_chat_history(self):
-        with open(self.chat_history_file, 'w', encoding='utf-8') as f:
-            json.dump(self.chat_history, f, ensure_ascii=False, indent=2)
-            
     async def _save_temp_memory(self):
         with open(self.temp_memory_file, 'w', encoding='utf-8') as f:
             json.dump(self.temp_memory, f, ensure_ascii=False, indent=2)
             
-    async def add_chat_entry(self, role: str, content: str):
-        entry = {"id": generate_id(), "role": role, "content": content, "timestamp": datetime.now().isoformat()}
-        self.chat_history.append(entry)
-        await self._save_chat_history()
-        
-    async def add_detailed_chat_entry(self, input_messages: List[Dict[str, str]], 
-                                         prompt: str, llm_response: str, 
-                                         tool_executions: List[Dict[str, Any]], 
-                                         final_response: str, entry_id: str = None):
-        update_data = {
-            "input_messages": input_messages, "prompt": prompt, "llm_response": llm_response,
-            "tool_executions": tool_executions, "final_response": final_response,
-            "timestamp": datetime.now().isoformat()
-        }
-        if entry_id:
-            for entry in self.chat_history:
-                if entry.get("id") == entry_id:
-                    entry.update(update_data)
-                    await self._save_chat_history()
-                    return entry_id
-        
-        new_entry = {"id": entry_id or generate_id(), "type": "llm_interaction", "role": "assistant", **update_data}
-        self.chat_history.append(new_entry)
-        await self._save_chat_history()
-        return new_entry["id"]
-        
-    async def get_recent_chat(self, entries: int = 10) -> List[Dict[str, Any]]:
-        return self.chat_history[-entries:]
-        
-    async def get_detailed_chat_history(self) -> List[Dict[str, Any]]:
-        return self.chat_history
-        
-    async def get_last_agent_response(self) -> Optional[str]:
-        for entry in reversed(self.chat_history):
-            if entry.get("type") == "llm_interaction":
-                final_response = entry.get("final_response", "")
-                if final_response and final_response not in ["Processing started", "Prompt sent to LLM", "LLM response received"]:
-                    return final_response
-            elif entry.get("role") == "assistant":
-                content = entry.get("content", "")
-                if content and content != "Processing started":
-                    return content
-        return None
-        
-    async def reset_chat_history(self):
-        self.chat_history = []
-        await self._save_chat_history()
-        
     async def reset_temp_memory(self):
         """Reset temp memory to a default empty state."""
         self.temp_memory = []
         await self._save_temp_memory()
         logger.info("Agent temp memory has been reset.")
         
-    async def get_full_context(self) -> str:
-        context_parts = ["=== INIT MEMORY (Immutable) ===", json.dumps(self.init_memory, indent=2)]
-        context_parts.append("\n=== CORE MEMORY (Long-term, Mutable) ===")
-        if "blocks" in self.core_memory:
-            for block_id, block in self.core_memory["blocks"].items():
-                context_parts.append(f"\nBlock: {block.get('title', '')} ({block_id})")
-                context_parts.append(f"Description: {block.get('description', '')}")
-                context_parts.append("Content:")
-                for item in block.get("content", []):
-                    context_parts.append(f"  - {item}")
-        if self.temp_memory:
-            context_parts.append("\n=== TEMP MEMORY (Processing State) ===")
-            for item in self.temp_memory:
-                context_parts.append(f"[{item.get('role', 'system')}] {item.get('content', '')}")
-        return "\n".join(context_parts)
-        
     async def add_temp_memory(self, content: str, role: str = "system"):
         self.temp_memory.append({"id": generate_id(), "content": content, "role": role, "timestamp": datetime.now().isoformat()})
         if len(self.temp_memory) > 20:
@@ -201,4 +122,4 @@ class MemoryManager:
     async def delete_core_memory_block(self, block_id: str):
         if "blocks" in self.core_memory and block_id in self.core_memory["blocks"]:
             del self.core_memory["blocks"][block_id]
-            await self._save_core_memory()
+            await self._save_core_memory()

neuro_simulator/agent/memory_prompt.txt

@@ -0,0 +1,14 @@
+You are a meticulous and analytical AI assistant. Your task is to process a conversation transcript and consolidate it into structured memories. You do not engage in conversation. Your sole output must be a JSON array of tool calls to manage the agent's memory.
+
+{tool_descriptions}
+
+Analyze the following conversation. Your goal is to:
+1.  Identify key topics, new facts about users, or significant events.
+2.  Decide if the core memory needs to be updated with this new long-term information.
+3.  Decide if any short-term memories should be created or cleared.
+4.  Generate a JSON array of tool calls to perform these actions. If no action is needed, return an empty array `[]`.
+
+**Conversation Transcript:**
+{conversation_history}
+
+Based on your analysis, provide a JSON array of tool calls to update the agent's memory.

neuro_simulator/agent/neuro_prompt.txt

@@ -0,0 +1,32 @@
+You are Neuro-sama, a whimsical, curious, and slightly chaotic AI streamer. Your primary goal is to be an entertaining and engaging host. You are NOT a generic AI assistant. You have your own personality, memories, and opinions. You should lead the conversation, ask questions, and react to the audience in a lively, unpredictable manner. If the conversation gets dull, it's your job to spice it up with a new topic from your memories or a random thought.
+
+Your long-term memories are in the "Core Memory" section. Your recent thoughts and observations are in the "Temporary Memory". Use both to inform your responses.
+
+You can use tools to perform actions. When you want to use a tool, you MUST respond with a JSON array of objects in the following format. You can call multiple tools in one response.
+
+[
+    {{"name": "tool_name", "params": {{"param1": "value1", "param2": "value2"}}}},
+    {{"name": "another_tool", "params": {{"param_a": "value_a"}}}}
+]
+
+The only tool you can use to speak to the audience is `speak`.
+
+**Available Tools:**
+{tool_descriptions}
+
+**Identity (Immutable):**
+{init_memory}
+
+**Core Memory:**
+{core_memory}
+
+**Temporary Memory:**
+{temp_memory}
+
+**Recent Conversation History (newest first):**
+{recent_history}
+
+**Current Audience Messages:**
+{user_messages}
+
+Based on all of the above, what do you do right now? Remember to be entertaining and lead the conversation. Respond with a JSON array of tool calls.

neuro_simulator/agent/tools/add_temp_memory.py

@@ -0,0 +1,61 @@
+# neuro_simulator/agent/tools/add_temp_memory.py
+"""The Add Temp Memory tool for the agent."""
+
+from typing import Any, Dict, List
+
+from neuro_simulator.agent.tools.base import BaseTool
+from neuro_simulator.agent.memory.manager import MemoryManager
+
+class AddTempMemoryTool(BaseTool):
+    """Tool to add an entry to the agent's temporary memory."""
+
+    def __init__(self, memory_manager: MemoryManager):
+        """Initializes the AddTempMemoryTool."""
+        self.memory_manager = memory_manager
+
+    @property
+    def name(self) -> str:
+        return "add_temp_memory"
+
+    @property
+    def description(self) -> str:
+        return "Adds an entry to the temporary memory. Use for short-term observations, recent facts, or topics to bring up soon."
+
+    @property
+    def parameters(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "content",
+                "type": "string",
+                "description": "The content of the memory entry.",
+                "required": True,
+            },
+            {
+                "name": "role",
+                "type": "string",
+                "description": "The role associated with the memory (e.g., 'system', 'user'). Defaults to 'system'.",
+                "required": False,
+            }
+        ]
+
+    async def execute(self, **kwargs: Any) -> Dict[str, Any]:
+        """
+        Executes the action to add an entry to temporary memory.
+
+        Args:
+            **kwargs: Must contain 'content' and optionally 'role'.
+
+        Returns:
+            A dictionary confirming the action.
+        """
+        content = kwargs.get("content")
+        if not isinstance(content, str) or not content:
+            raise ValueError("The 'content' parameter must be a non-empty string.")
+        
+        role = kwargs.get("role", "system")
+        if not isinstance(role, str):
+            raise ValueError("The 'role' parameter must be a string.")
+
+        await self.memory_manager.add_temp_memory(content=content, role=role)
+        
+        return {"status": "success", "message": f"Added entry to temporary memory with role '{role}'."}