Restructure memory documentation and add missing eager creation tool

- Restructure working-memory.md to focus on messages and data first, then structured memories
- Combine data examples and improve conversation context examples
- Add comprehensive section on producing long-term memories from working memory
- Cover both server-side and client-side extraction approaches
- Update long-term-memory.md to refer to working memory for automatic promotion
- Add manual creation examples with both API and LLM tool usage
- Add missing create_long_term_memory tool schema to Python client
- Update Python SDK docs with correct tool names (not the non-existent ones)
- Add tool call handler and resolver for eager memory creation
- All client tests passing

Author: abrookins

agent-memory-client/agent_memory_client/client.py

@@ -1612,6 +1612,67 @@ def edit_long_term_memory_tool_schema(cls) -> dict[str, Any]:
             },
         }
 
+    @classmethod
+    def create_long_term_memory_tool_schema(cls) -> dict[str, Any]:
+        """
+        Get OpenAI-compatible tool schema for creating long-term memories directly.
+
+        Returns:
+            Tool schema dictionary compatible with OpenAI tool calling format
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": "create_long_term_memory",
+                "description": (
+                    "Create long-term memories directly for immediate storage and retrieval. "
+                    "Use this for important information that should be permanently stored without going through working memory. "
+                    "This is the 'eager' approach - memories are created immediately in long-term storage. "
+                    "Examples: User preferences, important facts, key events that need to be searchable right away. "
+                    "For episodic memories, include event_date in ISO format."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "memories": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "text": {
+                                        "type": "string",
+                                        "description": "The memory content to store",
+                                    },
+                                    "memory_type": {
+                                        "type": "string",
+                                        "enum": ["episodic", "semantic", "message"],
+                                        "description": "Type of memory: 'episodic' (events/experiences), 'semantic' (facts/preferences), 'message' (conversation snippets)",
+                                    },
+                                    "topics": {
+                                        "type": "array",
+                                        "items": {"type": "string"},
+                                        "description": "Optional topics for categorization",
+                                    },
+                                    "entities": {
+                                        "type": "array",
+                                        "items": {"type": "string"},
+                                        "description": "Optional entities mentioned in the memory",
+                                    },
+                                    "event_date": {
+                                        "type": "string",
+                                        "description": "Optional event date for episodic memories (ISO 8601 format: '2024-01-15T14:30:00Z')",
+                                    },
+                                },
+                                "required": ["text", "memory_type"],
+                            },
+                            "description": "List of memories to create",
+                        },
+                    },
+                    "required": ["memories"],
+                },
+            },
+        }
+
     @classmethod
     def delete_long_term_memories_tool_schema(cls) -> dict[str, Any]:
         """
@@ -1666,6 +1727,7 @@ def get_all_memory_tool_schemas(cls) -> Sequence[dict[str, Any]]:
             cls.get_add_memory_tool_schema(),
             cls.get_update_memory_data_tool_schema(),
             cls.get_long_term_memory_tool_schema(),
+            cls.create_long_term_memory_tool_schema(),
             cls.edit_long_term_memory_tool_schema(),
             cls.delete_long_term_memories_tool_schema(),
             cls.get_current_datetime_tool_schema(),
@@ -1698,6 +1760,7 @@ def get_all_memory_tool_schemas_anthropic(cls) -> Sequence[dict[str, Any]]:
             cls.get_add_memory_tool_schema_anthropic(),
             cls.get_update_memory_data_tool_schema_anthropic(),
             cls.get_long_term_memory_tool_schema_anthropic(),
+            cls.create_long_term_memory_tool_schema_anthropic(),
             cls.edit_long_term_memory_tool_schema_anthropic(),
             cls.delete_long_term_memories_tool_schema_anthropic(),
             cls.get_current_datetime_tool_schema_anthropic(),
@@ -1756,6 +1819,12 @@ def get_long_term_memory_tool_schema_anthropic(cls) -> dict[str, Any]:
         openai_schema = cls.get_long_term_memory_tool_schema()
         return cls._convert_openai_to_anthropic_schema(openai_schema)
 
+    @classmethod
+    def create_long_term_memory_tool_schema_anthropic(cls) -> dict[str, Any]:
+        """Get create long-term memory tool schema in Anthropic format."""
+        openai_schema = cls.create_long_term_memory_tool_schema()
+        return cls._convert_openai_to_anthropic_schema(openai_schema)
+
     @classmethod
     def edit_long_term_memory_tool_schema_anthropic(cls) -> dict[str, Any]:
         """Get edit long-term memory tool schema in Anthropic format."""
@@ -2135,6 +2204,11 @@ async def resolve_function_call(
             elif function_name == "get_long_term_memory":
                 result = await self._resolve_get_long_term_memory(args)
 
+            elif function_name == "create_long_term_memory":
+                result = await self._resolve_create_long_term_memory(
+                    args, effective_namespace, user_id
+                )
+
             elif function_name == "edit_long_term_memory":
                 result = await self._resolve_edit_long_term_memory(args)
 
@@ -2279,6 +2353,40 @@ async def _resolve_get_long_term_memory(
         result = await self.get_long_term_memory(memory_id=memory_id)
         return {"memory": result}
 
+    async def _resolve_create_long_term_memory(
+        self, args: dict[str, Any], namespace: str | None, user_id: str | None = None
+    ) -> dict[str, Any]:
+        """Resolve create_long_term_memory function call."""
+        memories_data = args.get("memories")
+        if not memories_data:
+            raise ValueError(
+                "memories parameter is required for create_long_term_memory"
+            )
+
+        # Convert dict memories to ClientMemoryRecord objects
+        from .models import ClientMemoryRecord, MemoryTypeEnum
+
+        memories = []
+        for memory_data in memories_data:
+            # Apply defaults
+            if namespace and "namespace" not in memory_data:
+                memory_data["namespace"] = namespace
+            if user_id and "user_id" not in memory_data:
+                memory_data["user_id"] = user_id
+
+            # Convert memory_type string to enum if needed
+            if "memory_type" in memory_data:
+                memory_data["memory_type"] = MemoryTypeEnum(memory_data["memory_type"])
+
+            memory = ClientMemoryRecord(**memory_data)
+            memories.append(memory)
+
+        result = await self.create_long_term_memory(memories)
+        return {
+            "status": result.status,
+            "message": f"Created {len(memories)} memories successfully",
+        }
+
     async def _resolve_edit_long_term_memory(
         self, args: dict[str, Any]
     ) -> dict[str, Any]:

docs/long-term-memory.md

@@ -198,21 +198,70 @@ response = await memory_prompt({
 # - User's query as final message
 ```
 
-## Memory Extraction
+## Creating Long-Term Memories
 
-By default, the system automatically extracts structured memories from
-conversations so they flow from working memory to long-term storage. This
-happens in a background process after clients update working memory. This
-extraction process can be customized using different **memory strategies**.
+There are two main ways to create long-term memories:
 
-The extraction strategy is set in the working memory session and controls what
-the server extracts into long-term memory. When you give an LLM the ability to
-store long-term memories as a tool, the tool description includes information
-about the configured extraction strategy, helping the LLM understand what types
-of memories to create.
+### 1. Automatic Promotion from Working Memory
 
-!!! info "Memory Strategies"
-    The system supports multiple extraction strategies (discrete facts, summaries, preferences, custom prompts) that determine how conversations are processed into memories. The extraction strategy set in working memory is visible to LLMs through strategy-aware tool descriptions. See [Memory Extraction Strategies](memory-extraction-strategies.md) for complete documentation and examples.
+The most common approach is to let the system automatically promote memories from working memory to long-term storage. This handles extraction strategies, background processing, and batch optimization.
+
+!!! info "Working Memory Integration"
+    For automatic memory promotion from conversations, see the [Working Memory documentation](working-memory.md). This covers extraction strategies, background processing, and how to configure the memory server to automatically create long-term memories from conversation content.
+
+### 2. Manual Creation via API
+
+For immediate storage of important facts, you can create long-term memories directly using the API or LLM tools.
+
+#### Direct API Calls
+
+```python
+# Create memories directly via Python client
+await client.create_long_term_memories([
+    {
+        "text": "User prefers dark mode interfaces",
+        "memory_type": "semantic",
+        "topics": ["preferences", "ui"],
+        "entities": ["dark mode"],
+        "user_id": "user_123"
+    },
+    {
+        "text": "User completed Python certification on January 15, 2024",
+        "memory_type": "episodic",
+        "event_date": "2024-01-15T10:00:00Z",
+        "topics": ["education", "certification"],
+        "entities": ["Python certification"],
+        "user_id": "user_123"
+    }
+])
+```
+
+#### LLM Tool Usage (Eager Creation)
+
+Your LLM can use the `create_long_term_memory` tool for immediate storage:
+
+```python
+# LLM tool call for eager memory creation
+tools = [client.create_long_term_memory_tool_schema()]
+
+# LLM can call:
+# create_long_term_memory(
+#     memories=[
+#         {
+#             "text": "User works as a software engineer at TechCorp",
+#             "memory_type": "semantic",
+#             "topics": ["career", "work"],
+#             "entities": ["software engineer", "TechCorp"]
+#         }
+#     ]
+# )
+```
+
+This approach is ideal when:
+- You need memories to be immediately searchable
+- You're processing batch data or imports
+- You want to bypass working memory entirely
+- You have structured data that doesn't need extraction
 
 ## Configuration
 

docs/python-sdk.md

@@ -214,13 +214,14 @@ async def chat_with_memory(message: str, session_id: str):
 
 The SDK provides these tools for LLM integration:
 
-1. **`eagerly_create_long_term_memory`** - Eagerly create a long-term memory by making an API request
-2. **`lazily_create_long_term_memory`** - Lazily create a long-term memory by adding it to working memory (does not require an immediate network request; does require saving working memory afterward)
-3. **`search_long_term_memory`** - Search with semantic similarity
-4. **`edit_memory`** - Update existing memories
-5. **`delete_memory`** - Remove memories
-6. **`set_working_memory`** - Update or create a working memory session
-7. **`get_or_create_working_memory`** - Retrieve or create a working memory session
+1. **`create_long_term_memory`** - Eagerly create long-term memories by making an API request
+2. **`add_memory_to_working_memory`** - Lazily create memories by adding them to working memory (promoted to long-term storage later)
+3. **`search_memory`** - Search with semantic similarity across long-term memories
+4. **`edit_long_term_memory`** - Update existing long-term memories
+5. **`delete_long_term_memories`** - Remove long-term memories
+6. **`get_or_create_working_memory`** - Retrieve or create a working memory session
+7. **`update_working_memory_data`** - Update session-specific data in working memory
+8. **`get_current_datetime`** - Get current UTC datetime for grounding relative time expressions
 
 **Note:** The following tool names have been deprecated for clarity:
 - `create_long_term_memories` (deprecated) → use `eagerly_create_long_term_memory`