1 files changed, 41 insertions, 19 deletions

diff --git a/personal_agent/tools/memory.py b/personal_agent/tools/memory.py
index 851a69d..c84202f 100644
--- a/personal_agent/tools/memory.py
+++ b/personal_agent/tools/memory.py
@@ -62,11 +62,16 @@ class MemoryAddFactTool(Tool):
 
     @property
     def name(self) -> str:
-        return "memory_add_fact"
+        return "working_memory_add_fact"
 
     @property
     def description(self) -> str:
-        return "Add a useful fact to the current working memory."
+        return (
+            "Add a fact to the current task's working memory. Working memory is "
+            "temporary and is used to track information needed during the current "
+            "task or conversation. Do not use this for durable user preferences "
+            "or facts that should survive the conversation."
+        )
 
     @property
     def schema(self) -> dict[str, object]:
@@ -98,11 +103,16 @@ class MemoryAddNoteTool(Tool):
 
     @property
     def name(self) -> str:
-        return "memory_add_note"
+        return "working_memory_add_note"
 
     @property
     def description(self) -> str:
-        return "Add a useful note to the current working memory."
+        return (
+            "Add a temporary note to the current task's working memory. Use this "
+            "for information that may help with the current task or conversation. "
+            "Do not use this for durable information that should survive the "
+            "conversation."
+        )
 
     @property
     def schema(self) -> dict[str, object]:
@@ -134,11 +144,15 @@ class MemoryRemoveFactTool(Tool):
 
     @property
     def name(self) -> str:
-        return "memory_remove_fact"
+        return "working_memory_remove_fact"
 
     @property
     def description(self) -> str:
-        return "Remove a fact from the working memory when it is no longer true or relevant."
+        return (
+            "Remove a fact from the current task's working memory. This only "
+            "changes temporary working memory; it does not delete persistent "
+            "long-term memory."
+        )
 
     @property
     def schema(self) -> dict[str, object]:
@@ -170,11 +184,15 @@ class MemoryRemoveNoteTool(Tool):
 
     @property
     def name(self) -> str:
-        return "memory_remove_note"
+        return "working_memory_remove_note"
 
     @property
     def description(self) -> str:
-        return "Remove a note from the working memory when it is no longer true or relevant."
+        return (
+            "Remove a note from the current task's working memory. This only "
+            "changes temporary working memory; it does not delete persistent "
+            "long-term memory."
+        )
 
     @property
     def schema(self) -> dict[str, object]:
@@ -206,14 +224,15 @@ class LongTermMemorySaveTool(Tool):
 
     @property
     def name(self) -> str:
-        return "memory_save"
+        return "long_term_memory_save"
 
     @property
     def description(self) -> str:
         return (
-            "Save durable information for use across future conversations. "
-            "Use semantic for stable facts or preferences, and episodic for "
-            "meaningful past events."
+            "Save persistent information for use in future conversations. Use "
+            "this for durable user preferences, facts, decisions, goals, "
+            "relationships, or meaningful past experiences. This is long-term "
+            "memory, not temporary working memory."
         )
 
     @property
@@ -267,14 +286,16 @@ class LongTermMemorySearchTool(Tool):
 
     @property
     def name(self) -> str:
-        return "memory_search"
+        return "long_term_memory_search"
 
     @property
     def description(self) -> str:
         return (
-            "Search long-term memory for information relevant to the current "
-            "conversation. Use semantic for stable facts or preferences, and "
-            "episodic for meaningful past events."
+            "Search persistent long-term memories from previous conversations. "
+            "Use this when information from past conversations may be relevant, "
+            "when the user asks what you remember, or when checking whether a "
+            "durable fact or preference is already stored. This does not search "
+            "working memory."
         )
 
     @property
@@ -351,13 +372,14 @@ class LongTermMemoryDeleteTool(Tool):
 
     @property
     def name(self) -> str:
-        return "memory_delete"
+        return "long_term_memory_delete"
 
     @property
     def description(self) -> str:
         return (
-            "Delete a long-term memory by its exact ID. Only delete a memory "
-            "when its ID is known from a previous memory search or save result."
+            "Delete a specific persistent long-term memory by its ID. This "
+            "deletes long-term memory, not working memory. When replacing or "
+            "forgetting an existing memory, search for it first to obtain its ID."
         )
 
     @property