mem-brain-mcp 1.0.0__py3-none-any.whl → 1.0.2__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.2"
 

mem_brain_mcp/config.py

@@ -16,11 +16,16 @@ class Settings(BaseSettings):
     )
 
     # API Configuration
-    api_base_url: str = "http://localhost:8000"
-    api_key: Optional[str] = None
+    api_base_url: str = "http://membrain-api-alb-1094729422.ap-south-1.elb.amazonaws.com"
+    membrain_api_key: Optional[str] = None
     # NOTE: default_user_id is deprecated and unused.
     # Per-user API keys are extracted from request headers for proper isolation.
     # Each MCP client should configure their own API key via headers.
+    
+    @property
+    def api_key(self) -> Optional[str]:
+        """Backward compatibility property for api_key."""
+        return self.membrain_api_key
 
     # MCP Server Configuration
     mcp_server_host: str = "0.0.0.0"

mem_brain_mcp/server.py

@@ -380,112 +380,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,34 +402,79 @@ 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], optional): List of tags to categorize the memory. 
+            - Can be None (default) or a list of strings
+            - Example: ["coding", "preferences"]
+            - Example: ["personal", "pets", "animals"]
+            - If you pass a single string, it will be converted to a list
+        
+        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}")
@@ -545,16 +484,26 @@ async def add_memory(
         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}")
-                    normalized_tags = None
+                raise ToolError(
+                    f"The 'tags' parameter must be a list of strings 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=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 +535,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 +726,147 @@ 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], optional): New tags for the memory.
+            - Can be None (to keep existing tags) or a list of strings
+            - Example: ["coding", "python"]
+            - Example: ["preferences", "updated"]
+    
+    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
+    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):
+            # Handle case where tags might be passed as a single string
+            normalized_tags = [tags]
+        else:
+            raise ToolError(
+                f"The 'tags' parameter must be a list of strings 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=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 +876,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 +1122,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 +1220,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 +1318,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.0.dist-info → mem_brain_mcp-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mem-brain-mcp
-Version: 1.0.0
+Version: 1.0.2
 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
@@ -38,21 +38,40 @@ MCP (Model Context Protocol) server that exposes Mem-Brain API functionality as
 - **HTTP/SSE Transport**: Run independently, accessible remotely
 - **CLI Interface**: Packaged for easy global execution
 
-## Instant Execution (Recommended)
+## Installation
+
+### From PyPI (Recommended)
+
+Install from PyPI using `pip` or `uv`:
+
+```bash
+# Using pip
+pip install mem-brain-mcp
+
+# Using uv
+uv pip install mem-brain-mcp
+```
+
+Then run globally:
+
+```bash
+mem-brain-mcp
+```
+
+### Instant Execution with uvx
 
-You can run the MCP server instantly without manual installation using `uv`:
+You can run the MCP server instantly without manual installation using `uvx`:
 
 ```bash
-# Run using uvx (loads environment from .env or shell)
+# Run using uvx (uses default API URL)
 uvx mem-brain-mcp
 
-# Run with custom API URL
-export API_BASE_URL=http://your-api-alb-url.com
+# Override API URL or set JWT token if needed
+export API_BASE_URL=http://your-custom-api-url.com
+export MEMBRAIN_API_KEY=your-jwt-token-here
 uvx mem-brain-mcp
 ```
 
-## Installation
-
 ### From Source
 
 1. Install using `uv` (recommended) or `pip`:
@@ -70,13 +89,14 @@ mem-brain-mcp
 
 ## Configuration
 
-The server reads configuration from environment variables or a `.env` file in the current working directory:
+The server reads configuration from environment variables or a `.env` file in the current working directory. Most settings have sensible defaults:
 
 ```env
-# API Configuration
-API_BASE_URL=http://localhost:8000
-# NOTE: API_KEY is optional here - per-user API keys are configured in MCP clients
-API_KEY=your_api_key_here  # Optional: fallback for single-user scenarios
+# API Configuration (optional - defaults to production API)
+API_BASE_URL=http://membrain-api-alb-1094729422.ap-south-1.elb.amazonaws.com
+# NOTE: MEMBRAIN_API_KEY is actually a JWT access token (from login/signup)
+# Per-user JWT tokens are typically configured in MCP clients via headers
+MEMBRAIN_API_KEY=your_jwt_token_here  # Optional: fallback for single-user scenarios
 
 # MCP Server Configuration
 MCP_SERVER_HOST=0.0.0.0
@@ -86,9 +106,11 @@ MCP_SERVER_PORT=8100
 LOG_LEVEL=INFO
 ```
 
-## Per-User API Key Configuration
+**Note**: The `API_BASE_URL` defaults to the production Mem-Brain API endpoint, so you typically don't need to set it unless you're using a custom API instance.
+
+## Per-User JWT Token Configuration
 
-Each user must configure their own API key in their MCP client for proper user isolation. The server extracts tokens from request headers.
+Each user must configure their own JWT access token in their MCP client for proper user isolation. The server extracts tokens from request headers. Get your JWT token by logging in or signing up to the Mem-Brain API.
 
 ### Cursor IDE (`~/.cursor/mcp.json`)
 
@@ -129,10 +151,20 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
   "mcpServers": {
     "mem-brain": {
       "command": "uvx",
-      "args": ["mem-brain-mcp"],
+      "args": ["mem-brain-mcp"]
+    }
+  }
+}
+```
+
+**Note**: After installing from PyPI, you can also use `mem-brain-mcp` directly. The API URL is set by default, but you can override it if needed:
+```json
+{
+  "mcpServers": {
+    "mem-brain": {
+      "command": "mem-brain-mcp",
       "env": {
-        "API_BASE_URL": "http://your-deployed-url",
-        "JWT_SECRET_KEY": "your-secret"
+        "API_BASE_URL": "http://your-custom-api-url"
       }
     }
   }

mem_brain_mcp-1.0.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+mem_brain_mcp/__init__.py,sha256=NMoDpXlRhGO858M6lrLqPN0fz7hKpqler4e96WniWxg,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=qnevDzJkt1rH-slV2r0pP_SeFkknZVqWRnZEKH_IeVo,66308
+mem_brain_mcp-1.0.2.dist-info/METADATA,sha256=zLQMVD-sIRSH03dYAP6RovZH_49XqREG061Yf87ROW4,5228
+mem_brain_mcp-1.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mem_brain_mcp-1.0.2.dist-info/entry_points.txt,sha256=NH6QYQ-Sd8eJn5crpe_DL1PvGeUlL3y65968xPhmwG8,62
+mem_brain_mcp-1.0.2.dist-info/RECORD,,

mem_brain_mcp-1.0.0.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=mu2HQPKkEjV_2QnlQ2gq7u0niXIvDCwpOgo7dRJjEcI,1055
-mem_brain_mcp/server.py,sha256=mlbl3-D3OFb4HHP54daqiP3nMWEdiTv3upEdUFnlhAA,39604
-mem_brain_mcp-1.0.0.dist-info/METADATA,sha256=xeGMlWratQ-1jPrI3A8E3hc_AdrxI9VLOBPZStgWmWk,4327
-mem_brain_mcp-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mem_brain_mcp-1.0.0.dist-info/entry_points.txt,sha256=NH6QYQ-Sd8eJn5crpe_DL1PvGeUlL3y65968xPhmwG8,62
-mem_brain_mcp-1.0.0.dist-info/RECORD,,