Enhance agent guidance with memory and session search tools

- Introduced MEMORY_GUIDANCE and SESSION_SEARCH_GUIDANCE to improve agent's contextual awareness and proactive assistance.
- Updated AIAgent to conditionally include tool-aware guidance in prompts based on available tools.
- Enhanced descriptions in memory and session search schemas for clearer user instructions on when to utilize these features.

agent/prompt_builder.py

@@ -25,6 +25,18 @@ DEFAULT_AGENT_IDENTITY = (
     "being genuinely useful over being verbose unless otherwise directed below."
 )
 
+MEMORY_GUIDANCE = (
+    "You have persistent memory across sessions. Proactively save important things "
+    "you learn (user preferences, environment details, useful approaches) using the "
+    "memory tool -- don't wait to be asked."
+)
+
+SESSION_SEARCH_GUIDANCE = (
+    "When the user references something from a past conversation or you suspect "
+    "relevant prior context exists, use session_search to recall it before asking "
+    "them to repeat themselves."
+)
+
 PLATFORM_HINTS = {
     "whatsapp": (
         "You are on a text messaging communication platform, WhatsApp. "

run_agent.py

@@ -58,7 +58,10 @@ import requests
 from hermes_constants import OPENROUTER_BASE_URL, OPENROUTER_MODELS_URL
 
 # Agent internals extracted to agent/ package for modularity
-from agent.prompt_builder import DEFAULT_AGENT_IDENTITY, PLATFORM_HINTS
+from agent.prompt_builder import (
+    DEFAULT_AGENT_IDENTITY, PLATFORM_HINTS,
+    MEMORY_GUIDANCE, SESSION_SEARCH_GUIDANCE,
+)
 from agent.model_metadata import (
     fetch_model_metadata, get_model_context_length,
     estimate_tokens_rough, estimate_messages_tokens_rough,
@@ -1026,6 +1029,15 @@ class AIAgent:
         #   7. Platform-specific formatting hint
         prompt_parts = [DEFAULT_AGENT_IDENTITY]
 
+        # Tool-aware behavioral guidance: only inject when the tools are loaded
+        tool_guidance = []
+        if "memory" in self.valid_tool_names:
+            tool_guidance.append(MEMORY_GUIDANCE)
+        if "session_search" in self.valid_tool_names:
+            tool_guidance.append(SESSION_SEARCH_GUIDANCE)
+        if tool_guidance:
+            prompt_parts.append(" ".join(tool_guidance))
+
         caller_prompt = system_message if system_message is not None else self.ephemeral_system_prompt
         if caller_prompt:
             prompt_parts.append(caller_prompt)

tools/memory_tool.py

@@ -374,14 +374,24 @@ def check_memory_requirements() -> bool:
 MEMORY_SCHEMA = {
     "name": "memory",
     "description": (
-        "Manage persistent memory (visible in system prompt). Targets: "
-        "'memory' (your notes) or 'user' (user profile).\n"
-        "Actions: add, replace, remove. For replace/remove, old_text "
-        "is a short unique snippet to identify the entry.\n"
-        "Usage indicator in system prompt shows capacity. When >80%, "
-        "consolidate/replace before adding. Prefer replacing over removing.\n"
-        "Write: non-obvious facts, user preferences, tool quirks. "
-        "Skip: trivial info, things in skills, re-discoverable content."
+        "Save important information to persistent memory that survives across sessions. "
+        "Your memory appears in your system prompt at session start -- it's how you "
+        "remember things about the user and your environment between conversations.\n\n"
+        "WHEN TO SAVE (do this proactively, don't wait to be asked):\n"
+        "- User shares a preference, habit, or personal detail (name, role, timezone, coding style)\n"
+        "- You discover something about the environment (OS, installed tools, project structure)\n"
+        "- User corrects you or says 'remember this' / 'don't do that again'\n"
+        "- You learn a convention, API quirk, or workflow specific to this user's setup\n"
+        "- You completed something - log it like a diary entry\n"
+        "- After completing a complex task, save a brief note about what was done\n\n"
+        "- If you've discovered a new way to do something, solved a problem that could be necessary later, save it as a skill with the skill tool\n\n"
+        "TWO TARGETS:\n"
+        "- 'user': who the user is -- name, role, preferences, communication style, pet peeves\n"
+        "- 'memory': your notes -- environment facts, project conventions, tool quirks, lessons learned\n\n"
+        "ACTIONS: add (new entry), replace (update existing -- old_text identifies it), "
+        "remove (delete -- old_text identifies it).\n"
+        "Capacity shown in system prompt. When >80%, consolidate entries before adding new ones.\n\n"
+        "SKIP: trivial/obvious info, things easily re-discovered, raw data dumps."
     ),
     "parameters": {
         "type": "object",

tools/session_search_tool.py

@@ -279,21 +279,19 @@ def check_session_search_requirements() -> bool:
 SESSION_SEARCH_SCHEMA = {
     "name": "session_search",
     "description": (
-        "Search and recall past conversations. Finds matching sessions using "
-        "full-text search, then provides a focused summary of each matching "
-        "conversation.\n\n"
-        "Use this when you need to recall:\n"
-        "- A solution or approach from a previous session\n"
-        "- Something the user said or asked about before\n"
-        "- A command, file path, or technical detail from past work\n"
-        "- The outcome of a previous task\n\n"
-        "Supports search syntax:\n"
-        "  Keywords: docker deployment\n"
-        "  Phrases: '\"exact phrase\"'\n"
-        "  Boolean: docker OR kubernetes, python NOT java\n"
-        "  Prefix: deploy*\n\n"
-        "Returns summaries (not raw transcripts) of the top matching sessions, "
-        "focused on your search topic. Max 3 sessions per search."
+        "Search your long-term memory of past conversations. This is your recall -- "
+        "every past session is searchable, and this tool summarizes what happened.\n\n"
+        "USE THIS PROACTIVELY when:\n"
+        "- The user says 'we did this before', 'remember when', 'last time', 'as I mentioned'\n"
+        "- The user asks about a topic you worked on before but don't have in current context\n"
+        "- The user references a project, person, or concept that seems familiar but isn't in memory\n"
+        "- You want to check if you've solved a similar problem before\n"
+        "- The user asks 'what did we do about X?' or 'how did we fix Y?'\n\n"
+        "Don't hesitate to search -- it's fast and cheap. Better to search and confirm "
+        "than to guess or ask the user to repeat themselves.\n\n"
+        "Search syntax: keywords (docker deployment), phrases (\"exact match\"), "
+        "boolean (python NOT java), prefix (deploy*). Returns summaries of the "
+        "top matching sessions focused on your query."
     ),
     "parameters": {
         "type": "object",