mem-brain-mcp 1.0.1__py3-none-any.whl → 1.0.3__py3-none-any.whl

mem_brain_mcp/__init__.py

@@ -1,4 +1,4 @@
 """Mem-Brain MCP Server - Exposes Mem-Brain API as MCP tools."""
 
-__version__ = "1.0.0"
+__version__ = "1.0.3"
 

mem_brain_mcp/server.py

@@ -1,5 +1,6 @@
 """MCP Server for Mem-Brain API using FastMCP."""
 
+import json
 import logging
 from typing import Any, Dict, List, Optional, Union
 import httpx
@@ -380,112 +381,6 @@ async def refresh_context() -> PromptMessage:
 # TOOLS (Operations)
 # ============================================================================
 
-@mcp.tool()
-async def login(email: str, password: str) -> str:
-    """Login to mem-brain API and get JWT token. Store the token for subsequent requests.
-    
-    Args:
-        email: User email address
-        password: User password
-        
-    Returns:
-        Success message with instructions for using the token
-    """
-    try:
-        import httpx
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            response = await client.post(
-                f"{settings.api_base_url}/api/v1/auth/login",
-                json={"email": email, "password": password},
-                headers={"Content-Type": "application/json"}
-            )
-            response.raise_for_status()
-            data = response.json()
-            
-            access_token = data.get("access_token")
-            refresh_token = data.get("refresh_token")
-            
-            if access_token:
-                # Store tokens in context (in a real implementation, you'd use FastMCP context)
-                logger.info(f"Login successful for {email}")
-                return f"""Login successful!
-
-Access Token: {access_token[:50]}...
-
-Use this token in the Authorization header for subsequent requests:
-  Authorization: Bearer {access_token}
-
-The token will be automatically used for all memory operations.
-Refresh token saved for automatic token renewal."""
-            else:
-                raise ToolError("Login failed: No token received")
-    except httpx.HTTPStatusError as e:
-        if e.response.status_code == 401:
-            raise ToolError("Login failed: Invalid email or password")
-        logger.error(f"Login error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Login failed: {e.response.status_code}")
-    except Exception as e:
-        logger.error(f"Unexpected login error: {e}", exc_info=True)
-        raise ToolError(f"Login failed: {str(e)}")
-
-
-@mcp.tool()
-async def signup(email: str, password: str, full_name: str, organization_name: str) -> str:
-    """Sign up for a new mem-brain account and organization.
-    
-    Args:
-        email: User email address
-        password: User password (min 8 chars, must contain letters and numbers)
-        full_name: User's full name
-        organization_name: Name for your organization
-        
-    Returns:
-        Success message with access token
-    """
-    try:
-        import httpx
-        async with httpx.AsyncClient(timeout=30.0) as client:
-            response = await client.post(
-                f"{settings.api_base_url}/api/v1/auth/signup",
-                json={
-                    "email": email,
-                    "password": password,
-                    "full_name": full_name,
-                    "organization_name": organization_name
-                },
-                headers={"Content-Type": "application/json"}
-            )
-            response.raise_for_status()
-            data = response.json()
-            
-            access_token = data.get("access_token")
-            
-            if access_token:
-                logger.info(f"Signup successful for {email}")
-                return f"""Account created successfully!
-
-Organization: {organization_name}
-Email: {email}
-
-Access Token: {access_token[:50]}...
-
-Use this token in the Authorization header for subsequent requests:
-  Authorization: Bearer {access_token}
-
-The token will be automatically used for all memory operations."""
-            else:
-                raise ToolError("Signup failed: No token received")
-    except httpx.HTTPStatusError as e:
-        error_detail = e.response.text if e.response else "Unknown error"
-        logger.error(f"Signup error: {e.response.status_code} - {error_detail}")
-        if e.response.status_code == 400:
-            raise ToolError(f"Signup failed: {error_detail}")
-        raise ToolError(f"Signup failed: {e.response.status_code}")
-    except Exception as e:
-        logger.error(f"Unexpected signup error: {e}", exc_info=True)
-        raise ToolError(f"Signup failed: {str(e)}")
-
-
 @mcp.tool()
 async def get_agent_instructions(include_dynamic_context: bool = True) -> str:
     """Get comprehensive system prompt and best practices for using the memory system effectively. This contains the intelligence for smart memory management, search strategies, and agent workflows."""
@@ -508,53 +403,128 @@ async def add_memory(
     IMPORTANT: Before creating a new memory, you MUST first search existing memories using search_memories() to check if a similar memory already exists. This prevents duplicates and helps maintain memory quality. Only create a new memory if no similar memory is found.
     
     Parameters:
-        content (str, required): The memory content to store. Must be a non-empty string. Example: "User prefers Python over JavaScript"
-        tags (list[str], optional): List of tags to categorize the memory. Example: ["coding", "preferences"] or None
-        category (str, optional): Category name for the memory. Example: "interests" or None
+        content (str, REQUIRED): The memory content to store. Must be a non-empty string. 
+            - Cannot be None, empty string, or whitespace-only
+            - Example: "User prefers Python over JavaScript"
+            - Example: "User prefers dark mode interfaces"
+        
+        tags (list[str] or str, optional): Tags to categorize the memory. 
+            - Can be None (default), a list of strings, a comma-separated string, or a JSON array string
+            - If omitted, the system will auto-generate tags based on content
+            - Example: ["coding", "preferences"]
+            - Example: "coding,preferences" (comma-separated)
+            - Example: '["coding", "preferences"]' (JSON string)
+            - Note: The system auto-generates relevant tags, so providing tags is optional
+        
+        category (str, optional): Category name for the memory.
+            - Can be None (default) or a non-empty string
+            - Example: "interests"
+            - Example: "preferences"
     
     Returns:
         str: A formatted string with the memory ID and details of the created memory.
     
+    Common Errors and Solutions:
+        - Error: "Tool call arguments for mcp were invalid"
+          Solution: Ensure 'content' parameter is provided as a string. Example: add_memory(content="User prefers dark mode")
+        
+        - Error: "The 'content' parameter cannot be empty"
+          Solution: Provide non-empty content. Example: add_memory(content="User loves Python programming")
+        
+        - Error: "tags must be a list"
+          Solution: Pass tags as a list. Example: add_memory(content="...", tags=["coding"]) not tags="coding"
+    
     Example workflow:
         1. search_memories(query="User prefers Python")  # Check for existing memories
         2. If no similar memory found, then: add_memory(content="User prefers Python over JavaScript", tags=["coding", "preferences"])
     
-    Example:
+    Examples:
+        # Basic usage (required parameter only)
+        add_memory(content="User prefers dark mode")
+        
+        # With tags
+        add_memory(content="User loves Python programming", tags=["coding", "preferences"])
+        
+        # With tags and category
         add_memory(
             content="User loves working with TypeScript",
             tags=["coding", "typescript"],
             category="interests"
         )
+        
+        # Tags as empty list (treated as None)
+        add_memory(content="User prefers coffee", tags=[])
     """
     # Validate parameters with detailed error messages
     if content is None:
-        raise ToolError("The 'content' parameter is required but was not provided. Please provide the memory content as a string.")
+        raise ToolError(
+            "The 'content' parameter is required but was not provided.\n"
+            "Example: add_memory(content=\"User prefers dark mode\")\n"
+            "Example: add_memory(content=\"User loves Python programming\", tags=[\"coding\"])"
+        )
     
     if not isinstance(content, str):
-        raise ToolError(f"The 'content' parameter must be a string, but got {type(content).__name__}. Please provide the memory content as a string.")
+        raise ToolError(
+            f"The 'content' parameter must be a string, but got {type(content).__name__}.\n"
+            f"Received: {repr(content)}\n"
+            "Example: add_memory(content=\"User prefers dark mode\")"
+        )
     
     content_str = str(content).strip()
     if not content_str:
-        raise ToolError("The 'content' parameter cannot be empty. Please provide the memory content as a non-empty string.")
+        raise ToolError(
+            "The 'content' parameter cannot be empty or whitespace-only.\n"
+            "Please provide a non-empty string with actual content.\n"
+            "Example: add_memory(content=\"User prefers dark mode\")\n"
+            "Example: add_memory(content=\"User loves Python programming\")"
+        )
 
     try:
         logger.info(f"add_memory called - content length: {len(content_str)}, tags: {tags}, category: {category}")
         logger.debug(f"add_memory full content: {content_str[:100]}...")
         
-        # Normalize tags: convert empty list to None, ensure it's a list if provided
+        # Normalize tags: handle various input formats and convert to list of strings
         normalized_tags = None
         if tags is not None:
             if isinstance(tags, list):
+                # Validate list contents are strings
+                if tags:
+                    invalid_items = [item for item in tags if not isinstance(item, str)]
+                    if invalid_items:
+                        raise ToolError(
+                            f"The 'tags' parameter must be a list of strings, but found non-string items: {invalid_items}\n"
+                            f"Example: add_memory(content=\"...\", tags=[\"coding\", \"preferences\"])\n"
+                            f"Example: add_memory(content=\"...\", tags=[\"personal\", \"pets\"])"
+                        )
                 normalized_tags = tags if tags else None  # Empty list becomes None
             elif isinstance(tags, str):
-                # Handle case where tags might be passed as a single string
-                normalized_tags = [tags]
-            else:
-                try:
-                    normalized_tags = list(tags) if tags else None
-                except (TypeError, ValueError):
-                    logger.warning(f"Could not convert tags to list: {tags}")
+                tags_str = tags.strip()
+                if not tags_str:
                     normalized_tags = None
+                else:
+                    # Try to parse as JSON array first (e.g., '["tag1", "tag2"]')
+                    try:
+                        parsed = json.loads(tags_str)
+                        if isinstance(parsed, list):
+                            normalized_tags = [str(item).strip() for item in parsed if str(item).strip()]
+                        else:
+                            # If JSON but not a list, treat as single tag
+                            normalized_tags = [tags_str]
+                    except (json.JSONDecodeError, ValueError):
+                        # Not JSON, try comma-separated string
+                        if ',' in tags_str:
+                            normalized_tags = [tag.strip() for tag in tags_str.split(',') if tag.strip()]
+                        else:
+                            # Single tag string
+                            normalized_tags = [tags_str]
+            else:
+                raise ToolError(
+                    f"The 'tags' parameter must be a list of strings, a comma-separated string, or None, but got {type(tags).__name__}.\n"
+                    f"Received: {repr(tags)}\n"
+                    "Example: add_memory(content=\"...\", tags=[\"coding\", \"preferences\"])\n"
+                    "Example: add_memory(content=\"...\", tags=\"coding,preferences\")\n"
+                    "Example: add_memory(content=\"...\", tags=None)  # or omit tags parameter"
+                )
         
         # Normalize category: convert empty string to None
         normalized_category = category.strip() if category and isinstance(category, str) and category.strip() else None
@@ -586,49 +556,188 @@ async def add_memory(
 
 @mcp.tool()
 async def search_memories(query: str, k: int = 5) -> str:
-    """Search memories using semantic similarity. CRITICAL: Formulate specific, natural language queries, NOT simple keywords. Examples: ✅ 'Who is Maga and what is their relationship to me?' vs ❌ 'maga'. Check related_memories field for graph connections and synthesize across results. See mem-brain://docs/workflow-guide for search strategies. DO NOT use vague keywords - always use full questions."""
-    # Validate parameters
-    if not query or not query.strip():
-        raise ToolError("Query cannot be empty")
+    """Search memories using semantic similarity. CRITICAL: Formulate specific, natural language queries, NOT simple keywords. Examples: ✅ 'Who is Maga and what is their relationship to me?' vs ❌ 'maga'. Check related_memories field for graph connections and synthesize across results. See mem-brain://docs/workflow-guide for search strategies. DO NOT use vague keywords - always use full questions.
+    
+    Parameters:
+        query (str, REQUIRED): Search query string. Use natural language questions, not keywords.
+            - Example: "Who is Rakshith and what did he build?"
+            - Example: "What are the user's preferences for programming languages?"
+            - Example: "Tell me about memories related to the Dubai presentation"
+        
+        k (int, optional): Number of results to return. Default is 5.
+            - Must be between 1 and 100
+            - Example: 5 (default)
+            - Example: 10
+    
+    Returns:
+        str: Formatted search results with memory nodes and relationship edges.
+    
+    Common Errors and Solutions:
+        - Error: "Query cannot be empty"
+          Solution: Provide a non-empty search query. Example: search_memories(query="What is the user's name?")
+        
+        - Error: "k must be between 1 and 100"
+          Solution: Provide k between 1 and 100. Example: search_memories(query="...", k=10)
+    
+    Examples:
+        # Basic search
+        search_memories(query="Who is Rakshith?")
+        
+        # Search with more results
+        search_memories(query="What are the user's programming preferences?", k=10)
+        
+        # Complex query
+        search_memories(query="Tell me about memories related to mem-brain and its features")
+    """
+    # Validate parameters with detailed error messages
+    if query is None:
+        raise ToolError(
+            "The 'query' parameter is required but was not provided.\n"
+            "Example: search_memories(query=\"Who is Rakshith?\")\n"
+            "Example: search_memories(query=\"What are the user's preferences?\")"
+        )
+    
+    if not isinstance(query, str):
+        raise ToolError(
+            f"The 'query' parameter must be a string, but got {type(query).__name__}.\n"
+            f"Received: {repr(query)}\n"
+            "Example: search_memories(query=\"Who is Rakshith?\")"
+        )
+    
+    query_str = query.strip()
+    if not query_str:
+        raise ToolError(
+            "The 'query' parameter cannot be empty or whitespace-only.\n"
+            "Provide a natural language question or search query.\n"
+            "Example: search_memories(query=\"Who is Rakshith?\")\n"
+            "Example: search_memories(query=\"What are the user's preferences?\")"
+        )
+    
+    if not isinstance(k, int):
+        raise ToolError(
+            f"The 'k' parameter must be an integer, but got {type(k).__name__}.\n"
+            f"Received: {repr(k)}\n"
+            "Example: search_memories(query=\"...\", k=10)"
+        )
+    
     if not (1 <= k <= 100):
-        raise ToolError("k must be between 1 and 100")
+        raise ToolError(
+            f"The 'k' parameter must be between 1 and 100, but got {k}.\n"
+            "Example: search_memories(query=\"...\", k=5)\n"
+            "Example: search_memories(query=\"...\", k=10)"
+        )
 
     try:
+        logger.info(f"search_memories called - query length: {len(query_str)}, k: {k}")
         client = await _get_api_client()
-        result = await client.search_memories(query, k)
+        result = await client.search_memories(query_str, k)
         return f"Found {result.get('count', 0)} results:\n{_format_search_results(result.get('results', []))}"
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to search memories: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        raise ToolError(f"Failed to search memories: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in search_memories: {e}", exc_info=True)
         raise ToolError(f"Error searching memories: {str(e)}")
 
 
 @mcp.tool()
 async def get_memories(memory_ids: List[str]) -> str:
-    """Retrieve one or more memories by ID. Use this when you need full details for specific memories identified from search results."""
-    # Validate parameters
+    """Retrieve one or more memories by ID. Use this when you need full details for specific memories identified from search results.
+    
+    Parameters:
+        memory_ids (list[str], REQUIRED): List of memory IDs to retrieve. Must be a non-empty list.
+            - Example: ["480c1f76-bcdf-4491-8781-24510db992e3"]
+            - Example: ["480c1f76-...", "300d9716-...", "6fb6b23f-..."]
+            - Get memory IDs from search_memories() results
+    
+    Returns:
+        str: Formatted details of the retrieved memories.
+    
+    Common Errors and Solutions:
+        - Error: "memory_ids cannot be empty"
+          Solution: Provide a list with at least one memory ID. Example: get_memories(memory_ids=["480c1f76-..."])
+        
+        - Error: "Memory IDs cannot be empty"
+          Solution: Ensure all IDs in the list are non-empty strings. Example: get_memories(memory_ids=["480c1f76-..."])
+        
+        - Error: "memory_ids must be a list"
+          Solution: Pass memory_ids as a list. Example: get_memories(memory_ids=["..."]) not memory_ids="..."
+    
+    Examples:
+        # Get single memory
+        get_memories(memory_ids=["480c1f76-bcdf-4491-8781-24510db992e3"])
+        
+        # Get multiple memories
+        get_memories(memory_ids=["480c1f76-...", "300d9716-...", "6fb6b23f-..."])
+    """
+    # Validate parameters with detailed error messages
+    if memory_ids is None:
+        raise ToolError(
+            "The 'memory_ids' parameter is required but was not provided.\n"
+            "Example: get_memories(memory_ids=[\"480c1f76-bcdf-4491-8781-24510db992e3\"])\n"
+            "Example: get_memories(memory_ids=[\"480c1f76-...\", \"300d9716-...\"])"
+        )
+    
+    if not isinstance(memory_ids, list):
+        raise ToolError(
+            f"The 'memory_ids' parameter must be a list of strings, but got {type(memory_ids).__name__}.\n"
+            f"Received: {repr(memory_ids)}\n"
+            "Example: get_memories(memory_ids=[\"480c1f76-...\"])"
+        )
+    
     if not memory_ids:
-        raise ToolError("memory_ids cannot be empty")
-    for memory_id in memory_ids:
-        if not memory_id or not memory_id.strip():
-            raise ToolError("Memory IDs cannot be empty")
+        raise ToolError(
+            "The 'memory_ids' parameter cannot be an empty list.\n"
+            "Provide at least one memory ID.\n"
+            "Example: get_memories(memory_ids=[\"480c1f76-bcdf-4491-8781-24510db992e3\"])"
+        )
+    
+    # Validate each memory ID in the list
+    validated_ids = []
+    for i, memory_id in enumerate(memory_ids):
+        if memory_id is None:
+            raise ToolError(
+                f"Memory ID at index {i} is None. All memory IDs must be non-empty strings.\n"
+                "Example: get_memories(memory_ids=[\"480c1f76-...\"])"
+            )
+        if not isinstance(memory_id, str):
+            raise ToolError(
+                f"Memory ID at index {i} must be a string, but got {type(memory_id).__name__}.\n"
+                f"Received: {repr(memory_id)}\n"
+                "Example: get_memories(memory_ids=[\"480c1f76-...\"])"
+            )
+        memory_id_str = memory_id.strip()
+        if not memory_id_str:
+            raise ToolError(
+                f"Memory ID at index {i} cannot be empty or whitespace-only.\n"
+                "Get memory IDs from search_memories() or get_memories() results.\n"
+                "Example: get_memories(memory_ids=[\"480c1f76-bcdf-4491-8781-24510db992e3\"])"
+            )
+        validated_ids.append(memory_id_str)
 
     try:
+        logger.info(f"get_memories called - count: {len(validated_ids)}")
         client = await _get_api_client()
-        result = await client.get_memories(memory_ids)
+        result = await client.get_memories(validated_ids)
         memories = result.get("memories", [])
         return f"Retrieved {len(memories)} memories:\n{_format_memories_list(memories)}"
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to get memories: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        elif e.response.status_code == 404:
+            raise ToolError(f"One or more memories not found.\nVerify the memory IDs are correct by searching for them first.")
+        raise ToolError(f"Failed to get memories: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in get_memories: {e}", exc_info=True)
         raise ToolError(f"Error getting memories: {str(e)}")
 
 
@@ -638,25 +747,168 @@ async def update_memory(
     content: Optional[str] = None,
     tags: Optional[List[str]] = None
 ) -> str:
-    """Update an existing memory when information evolves or changes. Use this when user contradicts a past memory ('I no longer like X') or when details need updating."""
-    # Validate parameters
-    if not memory_id or not memory_id.strip():
-        raise ToolError("memory_id cannot be empty")
+    """Update an existing memory when information evolves or changes. Use this when user contradicts a past memory ('I no longer like X') or when details need updating.
+    
+    Parameters:
+        memory_id (str, REQUIRED): The ID of the memory to update. Must be a non-empty string.
+            - Example: "480c1f76-bcdf-4491-8781-24510db992e3"
+            - Get memory IDs from search_memories() or get_memories() results
+        
+        content (str, optional): New content for the memory. 
+            - Can be None (to keep existing content) or a non-empty string
+            - If provided, must not be empty or whitespace-only
+            - Example: "User no longer likes TypeScript, prefers Python"
+        
+        tags (list[str] or str, optional): New tags for the memory.
+            - Can be None (to keep existing tags), a list of strings, a comma-separated string, or a JSON array string
+            - If provided, replaces existing tags
+            - Example: ["coding", "python"]
+            - Example: "coding,python" (comma-separated)
+            - Example: '["coding", "python"]' (JSON string)
+            - Note: The system can auto-generate tags if you omit this parameter
+    
+    Returns:
+        str: A formatted string with the updated memory details.
+    
+    Common Errors and Solutions:
+        - Error: "Tool call arguments for mcp were invalid"
+          Solution: Ensure 'memory_id' parameter is provided as a string. Example: update_memory(memory_id="...")
+        
+        - Error: "memory_id cannot be empty"
+          Solution: Provide a valid memory ID from search results. Example: update_memory(memory_id="480c1f76-...")
+        
+        - Error: "At least one of 'content' or 'tags' must be provided"
+          Solution: Provide content or tags to update. Example: update_memory(memory_id="...", content="New content")
+    
+    Examples:
+        # Update content only
+        update_memory(memory_id="480c1f76-...", content="User prefers Python over JavaScript")
+        
+        # Update tags only
+        update_memory(memory_id="480c1f76-...", tags=["coding", "preferences"])
+        
+        # Update both content and tags
+        update_memory(
+            memory_id="480c1f76-...",
+            content="User no longer likes TypeScript",
+            tags=["coding", "python"]
+        )
+    """
+    # Validate parameters with detailed error messages
+    if memory_id is None:
+        raise ToolError(
+            "The 'memory_id' parameter is required but was not provided.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: update_memory(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\", content=\"New content\")"
+        )
+    
+    if not isinstance(memory_id, str):
+        raise ToolError(
+            f"The 'memory_id' parameter must be a string, but got {type(memory_id).__name__}.\n"
+            f"Received: {repr(memory_id)}\n"
+            "Example: update_memory(memory_id=\"480c1f76-...\", content=\"New content\")"
+        )
+    
+    memory_id_str = memory_id.strip()
+    if not memory_id_str:
+        raise ToolError(
+            "The 'memory_id' parameter cannot be empty or whitespace-only.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: update_memory(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\", content=\"New content\")"
+        )
+    
+    # Validate that at least one update parameter is provided
+    if content is None and tags is None:
+        raise ToolError(
+            "At least one of 'content' or 'tags' must be provided to update the memory.\n"
+            "Example: update_memory(memory_id=\"...\", content=\"New content\")\n"
+            "Example: update_memory(memory_id=\"...\", tags=[\"new\", \"tags\"])"
+        )
+    
+    # Validate content if provided
+    if content is not None:
+        if not isinstance(content, str):
+            raise ToolError(
+                f"The 'content' parameter must be a string or None, but got {type(content).__name__}.\n"
+                f"Received: {repr(content)}\n"
+                "Example: update_memory(memory_id=\"...\", content=\"New content\")"
+            )
+        content_str = str(content).strip()
+        if not content_str:
+            raise ToolError(
+                "The 'content' parameter cannot be empty or whitespace-only.\n"
+                "Provide a non-empty string or omit the parameter to keep existing content.\n"
+                "Example: update_memory(memory_id=\"...\", content=\"New content\")"
+            )
+    else:
+        content_str = None
+    
+    # Validate tags if provided - handle various input formats
+    normalized_tags = None
+    if tags is not None:
+        if isinstance(tags, list):
+            # Validate list contents are strings
+            if tags:
+                invalid_items = [item for item in tags if not isinstance(item, str)]
+                if invalid_items:
+                    raise ToolError(
+                        f"The 'tags' parameter must be a list of strings, but found non-string items: {invalid_items}\n"
+                        "Example: update_memory(memory_id=\"...\", tags=[\"coding\", \"preferences\"])\n"
+                        "Example: update_memory(memory_id=\"...\", tags=None)  # or omit tags parameter"
+                    )
+            normalized_tags = tags if tags else None  # Empty list becomes None
+        elif isinstance(tags, str):
+            tags_str = tags.strip()
+            if not tags_str:
+                normalized_tags = None
+            else:
+                # Try to parse as JSON array first (e.g., '["tag1", "tag2"]')
+                try:
+                    parsed = json.loads(tags_str)
+                    if isinstance(parsed, list):
+                        normalized_tags = [str(item).strip() for item in parsed if str(item).strip()]
+                    else:
+                        # If JSON but not a list, treat as single tag
+                        normalized_tags = [tags_str]
+                except (json.JSONDecodeError, ValueError):
+                    # Not JSON, try comma-separated string
+                    if ',' in tags_str:
+                        normalized_tags = [tag.strip() for tag in tags_str.split(',') if tag.strip()]
+                    else:
+                        # Single tag string
+                        normalized_tags = [tags_str]
+        else:
+            raise ToolError(
+                f"The 'tags' parameter must be a list of strings, a comma-separated string, or None, but got {type(tags).__name__}.\n"
+                f"Received: {repr(tags)}\n"
+                "Example: update_memory(memory_id=\"...\", tags=[\"coding\", \"preferences\"])\n"
+                "Example: update_memory(memory_id=\"...\", tags=\"coding,preferences\")\n"
+                "Example: update_memory(memory_id=\"...\", tags=None)  # or omit tags parameter"
+            )
 
     try:
+        logger.info(f"update_memory called - memory_id: {memory_id_str}, content length: {len(content_str) if content_str else 0}, tags: {normalized_tags}")
+        
         client = await _get_api_client()
-        result = await client.update_memory(memory_id, content, tags)
+        result = await client.update_memory(memory_id_str, content_str, normalized_tags)
         memory = result.get('memory')
         if memory:
             return f"Memory updated:\n{_format_memory(memory)}"
-        return f"Memory {memory_id} updated"
+        return f"Memory {memory_id_str} updated"
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to update memory: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        elif e.response.status_code == 400:
+            raise ToolError(f"Invalid request: {error_detail}\nExample: update_memory(memory_id=\"...\", content=\"New content\")")
+        elif e.response.status_code == 404:
+            raise ToolError(f"Memory not found: {memory_id_str}\nVerify the memory_id is correct by searching for it first.")
+        raise ToolError(f"Failed to update memory: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in update_memory: {e}", exc_info=True)
         raise ToolError(f"Error updating memory: {str(e)}")
 
 
@@ -666,49 +918,243 @@ async def delete_memories(
     tags: Optional[str] = None,
     category: Optional[str] = None
 ) -> str:
-    """Delete memories by ID or by filter (tags/category). If memory_id is provided, it takes precedence over filters. Use for removing wrong memories or when user explicitly requests deletion."""
+    """Delete memories by ID or by filter (tags/category). If memory_id is provided, it takes precedence over filters. Use for removing wrong memories or when user explicitly requests deletion.
+    
+    Parameters:
+        memory_id (str, optional): Specific memory ID to delete. Takes precedence over filters.
+            - Example: "480c1f76-bcdf-4491-8781-24510db992e3"
+            - Get memory IDs from search_memories() or get_memories() results
+        
+        tags (str, optional): Comma-separated tags for filter-based deletion.
+            - Example: "coding,preferences"
+            - Example: "personal,pets"
+            - Only used if memory_id is not provided
+        
+        category (str, optional): Category name for filter-based deletion.
+            - Example: "interests"
+            - Example: "preferences"
+            - Only used if memory_id is not provided
+    
+    Returns:
+        str: A message indicating how many memories were deleted and their IDs.
+    
+    Common Errors and Solutions:
+        - Error: "At least one parameter must be provided"
+          Solution: Provide memory_id, tags, or category. Example: delete_memories(memory_id="...")
+        
+        - Error: "memory_id cannot be empty"
+          Solution: Provide a valid memory ID or omit the parameter. Example: delete_memories(memory_id="480c1f76-...")
+    
+    Examples:
+        # Delete by memory ID
+        delete_memories(memory_id="480c1f76-bcdf-4491-8781-24510db992e3")
+        
+        # Delete by tags
+        delete_memories(tags="coding,preferences")
+        
+        # Delete by category
+        delete_memories(category="interests")
+    """
+    # Validate that at least one parameter is provided
+    if memory_id is None and tags is None and category is None:
+        raise ToolError(
+            "At least one parameter (memory_id, tags, or category) must be provided to delete memories.\n"
+            "Example: delete_memories(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\")\n"
+            "Example: delete_memories(tags=\"coding,preferences\")\n"
+            "Example: delete_memories(category=\"interests\")"
+        )
+    
+    # Validate memory_id if provided
+    if memory_id is not None:
+        if not isinstance(memory_id, str):
+            raise ToolError(
+                f"The 'memory_id' parameter must be a string or None, but got {type(memory_id).__name__}.\n"
+                f"Received: {repr(memory_id)}\n"
+                "Example: delete_memories(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\")"
+            )
+        memory_id_str = memory_id.strip()
+        if not memory_id_str:
+            raise ToolError(
+                "The 'memory_id' parameter cannot be empty or whitespace-only.\n"
+                "Get memory IDs from search_memories() or get_memories() results.\n"
+                "Example: delete_memories(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\")"
+            )
+    else:
+        memory_id_str = None
+    
+    # Validate tags if provided
+    if tags is not None:
+        if not isinstance(tags, str):
+            raise ToolError(
+                f"The 'tags' parameter must be a string or None, but got {type(tags).__name__}.\n"
+                f"Received: {repr(tags)}\n"
+                "Example: delete_memories(tags=\"coding,preferences\")"
+            )
+        tags_str = tags.strip()
+        if not tags_str:
+            raise ToolError(
+                "The 'tags' parameter cannot be empty or whitespace-only.\n"
+                "Provide comma-separated tags or omit the parameter.\n"
+                "Example: delete_memories(tags=\"coding,preferences\")"
+            )
+    else:
+        tags_str = None
+    
+    # Validate category if provided
+    if category is not None:
+        if not isinstance(category, str):
+            raise ToolError(
+                f"The 'category' parameter must be a string or None, but got {type(category).__name__}.\n"
+                f"Received: {repr(category)}\n"
+                "Example: delete_memories(category=\"interests\")"
+            )
+        category_str = category.strip()
+        if not category_str:
+            raise ToolError(
+                "The 'category' parameter cannot be empty or whitespace-only.\n"
+                "Provide a category name or omit the parameter.\n"
+                "Example: delete_memories(category=\"interests\")"
+            )
+    else:
+        category_str = None
+    
     try:
+        logger.info(f"delete_memories called - memory_id: {memory_id_str}, tags: {tags_str}, category: {category_str}")
         client = await _get_api_client()
-        result = await client.delete_memories(memory_id, tags, category)
+        result = await client.delete_memories(memory_id_str, tags_str, category_str)
         deleted_ids = result.get('memory_ids', [])[:10]
         return f"Deleted {result.get('deleted_count', 0)} memories. IDs: {', '.join(deleted_ids)}"
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to delete memories: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        elif e.response.status_code == 404:
+            raise ToolError(f"Memory not found: {memory_id_str}\nVerify the memory_id is correct by searching for it first.")
+        raise ToolError(f"Failed to delete memories: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in delete_memories: {e}", exc_info=True)
         raise ToolError(f"Error deleting memories: {str(e)}")
 
 
 @mcp.tool()
 async def unlink_memories(memory_id_1: str, memory_id_2: str) -> str:
-    """Remove link between two memories when the connection is no longer relevant or accurate."""
-    # Validate parameters
-    if not memory_id_1 or not memory_id_1.strip():
-        raise ToolError("memory_id_1 cannot be empty")
-    if not memory_id_2 or not memory_id_2.strip():
-        raise ToolError("memory_id_2 cannot be empty")
+    """Remove link between two memories when the connection is no longer relevant or accurate.
+    
+    Parameters:
+        memory_id_1 (str, REQUIRED): First memory ID in the link to remove.
+            - Example: "480c1f76-bcdf-4491-8781-24510db992e3"
+            - Get memory IDs from search_memories() or get_memories() results
+        
+        memory_id_2 (str, REQUIRED): Second memory ID in the link to remove.
+            - Example: "300d9716-a3a6-44d3-b0f4-b28002a65da8"
+            - Get memory IDs from search_memories() or get_memories() results
+    
+    Returns:
+        str: Confirmation message that the memories were unlinked.
+    
+    Common Errors and Solutions:
+        - Error: "memory_id_1 cannot be empty"
+          Solution: Provide a valid memory ID. Example: unlink_memories(memory_id_1="480c1f76-...", memory_id_2="300d9716-...")
+        
+        - Error: "memory_id_2 cannot be empty"
+          Solution: Provide a valid memory ID. Example: unlink_memories(memory_id_1="480c1f76-...", memory_id_2="300d9716-...")
+    
+    Examples:
+        # Unlink two memories
+        unlink_memories(
+            memory_id_1="480c1f76-bcdf-4491-8781-24510db992e3",
+            memory_id_2="300d9716-a3a6-44d3-b0f4-b28002a65da8"
+        )
+    """
+    # Validate parameters with detailed error messages
+    if memory_id_1 is None:
+        raise ToolError(
+            "The 'memory_id_1' parameter is required but was not provided.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: unlink_memories(memory_id_1=\"480c1f76-...\", memory_id_2=\"300d9716-...\")"
+        )
+    
+    if not isinstance(memory_id_1, str):
+        raise ToolError(
+            f"The 'memory_id_1' parameter must be a string, but got {type(memory_id_1).__name__}.\n"
+            f"Received: {repr(memory_id_1)}\n"
+            "Example: unlink_memories(memory_id_1=\"480c1f76-...\", memory_id_2=\"300d9716-...\")"
+        )
+    
+    memory_id_1_str = memory_id_1.strip()
+    if not memory_id_1_str:
+        raise ToolError(
+            "The 'memory_id_1' parameter cannot be empty or whitespace-only.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: unlink_memories(memory_id_1=\"480c1f76-bcdf-4491-8781-24510db992e3\", memory_id_2=\"300d9716-...\")"
+        )
+    
+    if memory_id_2 is None:
+        raise ToolError(
+            "The 'memory_id_2' parameter is required but was not provided.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: unlink_memories(memory_id_1=\"480c1f76-...\", memory_id_2=\"300d9716-...\")"
+        )
+    
+    if not isinstance(memory_id_2, str):
+        raise ToolError(
+            f"The 'memory_id_2' parameter must be a string, but got {type(memory_id_2).__name__}.\n"
+            f"Received: {repr(memory_id_2)}\n"
+            "Example: unlink_memories(memory_id_1=\"480c1f76-...\", memory_id_2=\"300d9716-...\")"
+        )
+    
+    memory_id_2_str = memory_id_2.strip()
+    if not memory_id_2_str:
+        raise ToolError(
+            "The 'memory_id_2' parameter cannot be empty or whitespace-only.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: unlink_memories(memory_id_1=\"480c1f76-...\", memory_id_2=\"300d9716-a3a6-44d3-b0f4-b28002a65da8\")"
+        )
+    
+    # Ensure the IDs are different
+    if memory_id_1_str == memory_id_2_str:
+        raise ToolError(
+            "memory_id_1 and memory_id_2 must be different.\n"
+            "You cannot unlink a memory from itself.\n"
+            "Example: unlink_memories(memory_id_1=\"480c1f76-...\", memory_id_2=\"300d9716-...\")"
+        )
 
     try:
+        logger.info(f"unlink_memories called - memory_id_1: {memory_id_1_str}, memory_id_2: {memory_id_2_str}")
         client = await _get_api_client()
-        result = await client.unlink_memories(memory_id_1, memory_id_2)
+        result = await client.unlink_memories(memory_id_1_str, memory_id_2_str)
         return result.get("message", "Memories unlinked")
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to unlink memories: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        elif e.response.status_code == 404:
+            raise ToolError(f"One or both memories not found.\nVerify the memory IDs are correct by searching for them first.")
+        raise ToolError(f"Failed to unlink memories: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in unlink_memories: {e}", exc_info=True)
         raise ToolError(f"Error unlinking memories: {str(e)}")
 
 
 @mcp.tool()
 async def get_stats() -> str:
-    """Get memory system statistics including total memories, links, and top tags. Use this when user asks 'how much do you remember?' or wants an overview of their memory system."""
+    """Get memory system statistics including total memories, links, and top tags. Use this when user asks 'how much do you remember?' or wants an overview of their memory system.
+    
+    Returns:
+        str: Formatted statistics including total memories, links, and top tags.
+    
+    Examples:
+        # Get statistics
+        get_stats()
+    """
     try:
+        logger.info("get_stats called")
         client = await _get_api_client()
         result = await client.get_stats()
         top_tags = ', '.join([f"{tag}({count})" for tag, count in result.get('top_tags', [])[:10]])
@@ -718,27 +1164,97 @@ Total Links: {result.get('total_links', 0)}
 Average Links per Memory: {result.get('avg_links_per_memory', 0):.2f}
 Top Tags: {top_tags}"""
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to get stats: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        raise ToolError(f"Failed to get stats: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in get_stats: {e}", exc_info=True)
         raise ToolError(f"Error getting stats: {str(e)}")
 
 
 @mcp.tool()
 async def find_path(from_id: str, to_id: str) -> str:
-    """Find shortest path between two memories in the memory graph. Use this to explain connections between seemingly unrelated memories."""
-    # Validate parameters
-    if not from_id or not from_id.strip():
-        raise ToolError("from_id cannot be empty")
-    if not to_id or not to_id.strip():
-        raise ToolError("to_id cannot be empty")
+    """Find shortest path between two memories in the memory graph. Use this to explain connections between seemingly unrelated memories.
+    
+    Parameters:
+        from_id (str, REQUIRED): Source memory ID to start the path from.
+            - Example: "480c1f76-bcdf-4491-8781-24510db992e3"
+            - Get memory IDs from search_memories() or get_memories() results
+        
+        to_id (str, REQUIRED): Target memory ID to find path to.
+            - Example: "300d9716-a3a6-44d3-b0f4-b28002a65da8"
+            - Get memory IDs from search_memories() or get_memories() results
+    
+    Returns:
+        str: The shortest path between the two memories, or a message if no path exists.
+    
+    Common Errors and Solutions:
+        - Error: "from_id cannot be empty"
+          Solution: Provide a valid memory ID. Example: find_path(from_id="480c1f76-...", to_id="300d9716-...")
+        
+        - Error: "to_id cannot be empty"
+          Solution: Provide a valid memory ID. Example: find_path(from_id="480c1f76-...", to_id="300d9716-...")
+    
+    Examples:
+        # Find path between two memories
+        find_path(
+            from_id="480c1f76-bcdf-4491-8781-24510db992e3",
+            to_id="300d9716-a3a6-44d3-b0f4-b28002a65da8"
+        )
+    """
+    # Validate parameters with detailed error messages
+    if from_id is None:
+        raise ToolError(
+            "The 'from_id' parameter is required but was not provided.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: find_path(from_id=\"480c1f76-...\", to_id=\"300d9716-...\")"
+        )
+    
+    if not isinstance(from_id, str):
+        raise ToolError(
+            f"The 'from_id' parameter must be a string, but got {type(from_id).__name__}.\n"
+            f"Received: {repr(from_id)}\n"
+            "Example: find_path(from_id=\"480c1f76-...\", to_id=\"300d9716-...\")"
+        )
+    
+    from_id_str = from_id.strip()
+    if not from_id_str:
+        raise ToolError(
+            "The 'from_id' parameter cannot be empty or whitespace-only.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: find_path(from_id=\"480c1f76-bcdf-4491-8781-24510db992e3\", to_id=\"300d9716-...\")"
+        )
+    
+    if to_id is None:
+        raise ToolError(
+            "The 'to_id' parameter is required but was not provided.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: find_path(from_id=\"480c1f76-...\", to_id=\"300d9716-...\")"
+        )
+    
+    if not isinstance(to_id, str):
+        raise ToolError(
+            f"The 'to_id' parameter must be a string, but got {type(to_id).__name__}.\n"
+            f"Received: {repr(to_id)}\n"
+            "Example: find_path(from_id=\"480c1f76-...\", to_id=\"300d9716-...\")"
+        )
+    
+    to_id_str = to_id.strip()
+    if not to_id_str:
+        raise ToolError(
+            "The 'to_id' parameter cannot be empty or whitespace-only.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: find_path(from_id=\"480c1f76-...\", to_id=\"300d9716-a3a6-44d3-b0f4-b28002a65da8\")"
+        )
 
     try:
+        logger.info(f"find_path called - from_id: {from_id_str}, to_id: {to_id_str}")
         client = await _get_api_client()
-        result = await client.find_path(from_id, to_id)
+        result = await client.find_path(from_id_str, to_id_str)
         if result.get("status") == "success":
             path_text = f"Path found (length: {result.get('length', 0)}):\n"
             for mem in result.get("memories", []):
@@ -746,27 +1262,97 @@ async def find_path(from_id: str, to_id: str) -> str:
             return path_text
         return result.get("message", "No path found")
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to find path: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        elif e.response.status_code == 404:
+            raise ToolError(f"One or both memories not found.\nVerify the memory IDs are correct by searching for them first.")
+        raise ToolError(f"Failed to find path: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in find_path: {e}", exc_info=True)
         raise ToolError(f"Error finding path: {str(e)}")
 
 
 @mcp.tool()
 async def get_neighborhood(memory_id: str, hops: int = 2) -> str:
-    """Get all memories within N hops of a given memory. Use this for deep context and understanding relationships around important memories."""
-    # Validate parameters
-    if not memory_id or not memory_id.strip():
-        raise ToolError("memory_id cannot be empty")
+    """Get all memories within N hops of a given memory. Use this for deep context and understanding relationships around important memories.
+    
+    Parameters:
+        memory_id (str, REQUIRED): Center memory ID to get neighborhood around.
+            - Example: "480c1f76-bcdf-4491-8781-24510db992e3"
+            - Get memory IDs from search_memories() or get_memories() results
+        
+        hops (int, optional): Number of hops to traverse. Default is 2.
+            - Must be between 1 and 5
+            - 1 hop = direct connections only
+            - 2 hops = direct connections + their connections
+            - Example: 2 (default)
+            - Example: 3
+    
+    Returns:
+        str: Formatted list of memories in the neighborhood with their hop distances.
+    
+    Common Errors and Solutions:
+        - Error: "memory_id cannot be empty"
+          Solution: Provide a valid memory ID. Example: get_neighborhood(memory_id="480c1f76-...")
+        
+        - Error: "hops must be between 1 and 5"
+          Solution: Provide hops between 1 and 5. Example: get_neighborhood(memory_id="...", hops=3)
+    
+    Examples:
+        # Get neighborhood with default 2 hops
+        get_neighborhood(memory_id="480c1f76-bcdf-4491-8781-24510db992e3")
+        
+        # Get neighborhood with 3 hops
+        get_neighborhood(memory_id="480c1f76-bcdf-4491-8781-24510db992e3", hops=3)
+        
+        # Get direct connections only (1 hop)
+        get_neighborhood(memory_id="480c1f76-bcdf-4491-8781-24510db992e3", hops=1)
+    """
+    # Validate parameters with detailed error messages
+    if memory_id is None:
+        raise ToolError(
+            "The 'memory_id' parameter is required but was not provided.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: get_neighborhood(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\")"
+        )
+    
+    if not isinstance(memory_id, str):
+        raise ToolError(
+            f"The 'memory_id' parameter must be a string, but got {type(memory_id).__name__}.\n"
+            f"Received: {repr(memory_id)}\n"
+            "Example: get_neighborhood(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\")"
+        )
+    
+    memory_id_str = memory_id.strip()
+    if not memory_id_str:
+        raise ToolError(
+            "The 'memory_id' parameter cannot be empty or whitespace-only.\n"
+            "Get memory IDs from search_memories() or get_memories() results.\n"
+            "Example: get_neighborhood(memory_id=\"480c1f76-bcdf-4491-8781-24510db992e3\")"
+        )
+    
+    if not isinstance(hops, int):
+        raise ToolError(
+            f"The 'hops' parameter must be an integer, but got {type(hops).__name__}.\n"
+            f"Received: {repr(hops)}\n"
+            "Example: get_neighborhood(memory_id=\"...\", hops=2)"
+        )
+    
     if not (1 <= hops <= 5):
-        raise ToolError("hops must be between 1 and 5")
+        raise ToolError(
+            f"The 'hops' parameter must be between 1 and 5, but got {hops}.\n"
+            "Example: get_neighborhood(memory_id=\"...\", hops=2)\n"
+            "Example: get_neighborhood(memory_id=\"...\", hops=3)"
+        )
 
     try:
+        logger.info(f"get_neighborhood called - memory_id: {memory_id_str}, hops: {hops}")
         client = await _get_api_client()
-        result = await client.get_neighborhood(memory_id, hops)
+        result = await client.get_neighborhood(memory_id_str, hops)
         neighborhood_text = f"Neighborhood (hops={result.get('hops', 2)}, total={result.get('total_in_neighborhood', 0)}):\n"
         for mem in result.get("neighborhood", []):
             hop_dist = mem.get("hop_distance", 0)
@@ -774,12 +1360,17 @@ async def get_neighborhood(memory_id: str, hops: int = 2) -> str:
             neighborhood_text += f"  [{hop_dist}]{is_center} {mem.get('id', 'unknown')}: {mem.get('content', '')[:100]}\n"
         return neighborhood_text
     except httpx.HTTPStatusError as e:
+        error_detail = e.response.text if e.response else "Unknown error"
+        logger.error(f"API error: {e.response.status_code} - {error_detail}")
         if e.response.status_code == 401:
-            raise ToolError("Authentication failed. Please check your API key.")
-        logger.error(f"API error: {e.response.status_code} - {e.response.text}")
-        raise ToolError(f"Failed to get neighborhood: {e.response.status_code}")
+            raise ToolError("Authentication failed. Please login using the 'login' tool or configure your JWT token in the MCP client headers.")
+        elif e.response.status_code == 404:
+            raise ToolError(f"Memory not found: {memory_id_str}\nVerify the memory_id is correct by searching for it first.")
+        raise ToolError(f"Failed to get neighborhood: HTTP {e.response.status_code} - {error_detail}")
+    except ToolError:
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error: {e}", exc_info=True)
+        logger.error(f"Unexpected error in get_neighborhood: {e}", exc_info=True)
         raise ToolError(f"Error getting neighborhood: {str(e)}")
 
 

{mem_brain_mcp-1.0.1.dist-info → mem_brain_mcp-1.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mem-brain-mcp
-Version: 1.0.1
+Version: 1.0.3
 Summary: MCP Server for Mem-Brain API - Exposes memory operations as MCP tools
 Keywords: ai,claude,cursor,llm,mcp,memory,model-context-protocol
 Classifier: Development Status :: 4 - Beta

mem_brain_mcp-1.0.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+mem_brain_mcp/__init__.py,sha256=4mabvpmReQ0ZVZ-xw8FrwHAdGDhjWQDpHhWg_11lxmY,89
+mem_brain_mcp/__main__.py,sha256=H_mwoKm1FBmu4KzAcQcq-TXZqeNvlrAekAxB1s4F4hA,712
+mem_brain_mcp/client.py,sha256=7KFGcLoPDaOOLiuG2lygQK7xH5Kio-YifDjuSpDoDJ8,6993
+mem_brain_mcp/config.py,sha256=xx2lBkCIeT85t0HxtORwZHSU3hZT_EdsThpfjwPJhbQ,1261
+mem_brain_mcp/server.py,sha256=ieSIkwWp3777ETa1M3J_SBMRUu571e3YsJj_C70UXRM,68812
+mem_brain_mcp-1.0.3.dist-info/METADATA,sha256=dR7sgte11k7CQyL38FTrsRDVBjx4hhil8HCXtbl9abQ,5228
+mem_brain_mcp-1.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mem_brain_mcp-1.0.3.dist-info/entry_points.txt,sha256=NH6QYQ-Sd8eJn5crpe_DL1PvGeUlL3y65968xPhmwG8,62
+mem_brain_mcp-1.0.3.dist-info/RECORD,,

mem_brain_mcp-1.0.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-mem_brain_mcp/__init__.py,sha256=DifX5h1zBo_ResWlU7kT_HFCeptgPaJouZ03wxBUSqc,89
-mem_brain_mcp/__main__.py,sha256=H_mwoKm1FBmu4KzAcQcq-TXZqeNvlrAekAxB1s4F4hA,712
-mem_brain_mcp/client.py,sha256=7KFGcLoPDaOOLiuG2lygQK7xH5Kio-YifDjuSpDoDJ8,6993
-mem_brain_mcp/config.py,sha256=xx2lBkCIeT85t0HxtORwZHSU3hZT_EdsThpfjwPJhbQ,1261
-mem_brain_mcp/server.py,sha256=mlbl3-D3OFb4HHP54daqiP3nMWEdiTv3upEdUFnlhAA,39604
-mem_brain_mcp-1.0.1.dist-info/METADATA,sha256=AaOmWLOT6mGIrw7CysLZMacG3PbrzuOHD-K9XbuNsUs,5228
-mem_brain_mcp-1.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mem_brain_mcp-1.0.1.dist-info/entry_points.txt,sha256=NH6QYQ-Sd8eJn5crpe_DL1PvGeUlL3y65968xPhmwG8,62
-mem_brain_mcp-1.0.1.dist-info/RECORD,,