mem-brain-mcp 1.0.6__py3-none-any.whl → 1.0.8__py3-none-any.whl

mem_brain_mcp/server.py

@@ -27,6 +27,9 @@ AGENT_INSTRUCTIONS = """You are an intelligent assistant with a persistent, evol
    - **Formulate specific, natural language queries**, NOT simple keywords.
      - ❌ `query="maga"` (Weak)
      - ✅ `query="Who is Maga and what is his relationship to me?"` (Strong - matches both memory content & link descriptions)
+   - **Use `keyword_filter` for Scoping**: Deterministically isolate context by project, session, or topic.
+     - ✅ `search_memories(query="...", keyword_filter="project-x")` (Matches memories tagged with project-x)
+     - ✅ `search_memories(query="...", keyword_filter="session-.*-2026")` (Regex match for 2026 sessions)
    - Check `related_memories` field — these are auto-expanded graph neighbors.
    - Synthesize: If "coffee" result links to "acid reflux", suggest cold brew.
 
@@ -116,20 +119,20 @@ AGENT_INSTRUCTIONS = """You are an intelligent assistant with a persistent, evol
 
 def _get_request_token() -> Optional[str]:
     """Extract JWT token from request headers.
-    
+
     Returns:
         JWT token string if found, None otherwise
     """
     try:
         ctx = request_ctx.get()
-        if hasattr(ctx, 'request') and hasattr(ctx.request, 'headers'):
+        if hasattr(ctx, "request") and hasattr(ctx.request, "headers"):
             headers = ctx.request.headers
             # Try Authorization Bearer token (primary method)
-            auth_header = headers.get('authorization', '') or headers.get('Authorization', '')
-            if auth_header.startswith('Bearer '):
+            auth_header = headers.get("authorization", "") or headers.get("Authorization", "")
+            if auth_header.startswith("Bearer "):
                 return auth_header[7:]
             # Fallback to X-API-Key header (for backward compatibility)
-            api_key = headers.get('x-api-key') or headers.get('X-API-Key')
+            api_key = headers.get("x-api-key") or headers.get("X-API-Key")
             if api_key:
                 return api_key
     except Exception as e:
@@ -155,7 +158,9 @@ async def _get_api_client() -> APIClient:
         return api_client  # Global instance
     # No token available
     logger.error("No authentication token available - neither from headers nor config")
-    raise ToolError("No authentication token provided. Please login using the login tool or configure your JWT token in your MCP client headers.")
+    raise ToolError(
+        "No authentication token provided. Please login using the login tool or configure your JWT token in your MCP client headers."
+    )
 
 
 # Initialize FastMCP server
@@ -170,14 +175,25 @@ async def _get_dynamic_context() -> str:
     try:
         # Get core identity
         client = await _get_api_client()
-        identity_response = await client._request("POST", "/memories/search", json={
-            "query": "user name location job identity", "k": 10
-        })
+        identity_response = await client._request(
+            "POST", "/memories/search", json={"query": "user name location job identity", "k": 10}
+        )
 
         identity_memories = []
         for mem in identity_response.get("results", []):
-            tags = mem.get('tags', [])
-            if any(tag in tags for tag in {'user_info', 'name', 'location', 'job', 'core_identity', 'identity', 'personal'}):
+            tags = mem.get("tags", [])
+            if any(
+                tag in tags
+                for tag in {
+                    "user_info",
+                    "name",
+                    "location",
+                    "job",
+                    "core_identity",
+                    "identity",
+                    "personal",
+                }
+            ):
                 identity_memories.append(mem)
 
         identity_section = ""
@@ -187,16 +203,16 @@ async def _get_dynamic_context() -> str:
                 identity_section += f"- {memory['content']}\n"
 
         # Get recent context
-        recent_response = await client._request("POST", "/memories/search", json={
-            "query": "recent context", "k": 3
-        })
+        recent_response = await client._request(
+            "POST", "/memories/search", json={"query": "recent context", "k": 3}
+        )
 
         recent_section = ""
         if recent_response.get("results"):
             recent_section = "## 🕐 Recent Context\n"
             for memory in recent_response.get("results", [])[:3]:
-                content = memory['content']
-                truncated = content[:100] + '...' if len(content) > 100 else content
+                content = memory["content"]
+                truncated = content[:100] + "..." if len(content) > 100 else content
                 recent_section += f"- {truncated}\n"
 
         return f"""### 🧠 YOUR BRAIN (Current Working Context)
@@ -220,6 +236,7 @@ async def _get_dynamic_context() -> str:
 # RESOURCES (Documentation that LLMs can read)
 # ============================================================================
 
+
 @mcp.resource("mem-brain://docs/workflow-guide")
 def workflow_guide() -> str:
     """Complete guide to the memory workflow: search strategies, pattern recognition, storage guidelines, and best practices."""
@@ -349,28 +366,26 @@ def storage_guidelines() -> str:
 # PROMPTS (Bootstrap Intelligence)
 # ============================================================================
 
+
 @mcp.prompt
 async def setup_personal_memory() -> PromptMessage:
     """Initializes the assistant with the user's identity, recent context, and memory management rules. Run this once at the start of a session."""
     context_section = await _get_dynamic_context()
-    
+
     full_instructions = f"""{context_section}{AGENT_INSTRUCTIONS}
 
 **Note**: For detailed tool usage, see resource: `mem-brain://docs/tool-reference`
 For storage guidelines, see resource: `mem-brain://docs/storage-guidelines`
 """
-    
-    return PromptMessage(
-        role="system",
-        content=TextContent(type="text", text=full_instructions)
-    )
+
+    return PromptMessage(role="system", content=TextContent(type="text", text=full_instructions))
 
 
 @mcp.prompt
 async def refresh_context() -> PromptMessage:
     """Refreshes the assistant's context with updated core identity and recent memories. Use when context feels stale."""
     context_section = await _get_dynamic_context()
-    
+
     return PromptMessage(
         role="system",
         content=TextContent(
@@ -378,8 +393,8 @@ async def refresh_context() -> PromptMessage:
             text=f"""{context_section}
 
 **Context refreshed.** Continue using memory tools as before.
-"""
-        )
+""",
+        ),
     )
 
 
@@ -387,6 +402,7 @@ async def refresh_context() -> PromptMessage:
 # TOOLS (Operations)
 # ============================================================================
 
+
 @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."""
@@ -394,70 +410,68 @@ async def get_agent_instructions(include_dynamic_context: bool = True) -> str:
         context_section = await _get_dynamic_context()
     else:
         context_section = ""
-    
+
     return context_section + AGENT_INSTRUCTIONS
 
 
 @mcp.tool()
 async def add_memory(
-    content: str,
-    tags: Optional[List[str]] = None,
-    category: Optional[str] = None
+    content: str, tags: Optional[Union[List[str], str]] = None, category: Optional[str] = None
 ) -> str:
     """Create a new memory with content, optional tags, and category. Use this when user reveals preferences, goals, or facts. Store FACTS, not conversation. Examples: 'User prefers dark mode' vs 'You said you like dark mode'. See mem-brain://docs/storage-guidelines for tagging patterns. DO NOT store conversation snippets - only store factual information.
-    
+
     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. 
+        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. 
+
+        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"])
-    
+
     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=[])
     """
@@ -465,30 +479,32 @@ async def add_memory(
     if content is None:
         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\"])"
+            '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__}.\n"
             f"Received: {repr(content)}\n"
-            "Example: add_memory(content=\"User prefers dark mode\")"
+            '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 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\")"
+            '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.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: handle various input formats and convert to list of strings
         normalized_tags = None
         if tags is not None:
@@ -499,8 +515,8 @@ async def add_memory(
                     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\"])"
+                            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):
@@ -512,14 +528,18 @@ async def add_memory(
                     try:
                         parsed = json.loads(tags_str)
                         if isinstance(parsed, list):
-                            normalized_tags = [str(item).strip() for item in parsed if str(item).strip()]
+                            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()]
+                        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]
@@ -527,21 +547,27 @@ async def add_memory(
                 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"
+                    '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
+        normalized_category = (
+            category.strip()
+            if category and isinstance(category, str) and category.strip()
+            else None
+        )
 
         client = await _get_api_client()
-        logger.debug(f"Calling API client.add_memory with content='{content_str[:50]}...', tags={normalized_tags}, category={normalized_category}")
-        
+        logger.debug(
+            f"Calling API client.add_memory with content='{content_str[:50]}...', tags={normalized_tags}, category={normalized_category}"
+        )
+
         result = await client.add_memory(content_str, normalized_tags, normalized_category)
-        
+
         logger.info(f"Memory created successfully: {result.get('memory_id', 'unknown')}")
-        memory = result.get('memory')
+        memory = result.get("memory")
         if memory:
             return f"Memory created: {result.get('memory_id', 'unknown')}\n{_format_memory(memory)}"
         return f"Memory created: {result.get('memory_id', 'unknown')}"
@@ -549,7 +575,9 @@ async def add_memory(
         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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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}")
         raise ToolError(f"Failed to create memory: HTTP {e.response.status_code} - {error_detail}")
@@ -561,89 +589,102 @@ 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.
-    
+async def search_memories(
+    query: str, k: int = 5, keyword_filter: Optional[Union[str, List[str]]] = None
+) -> str:
+    """Search memories using semantic similarity with optional regex-based tag filtering.
+
+    CRITICAL: Formulate specific, natural language queries, NOT simple keywords.
+    Examples: ✅ 'Who is Maga and what is their relationship to me?' vs ❌ 'maga'.
+
+    The keyword_filter allows for deterministic scoping (e.g., project-specific or session-specific).
+    - String: Match memories where ANY tag matches this regex pattern (case-insensitive).
+    - List[str]: Match memories where ALL patterns in the list satisfy at least one tag (AND logic).
+
     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
-    
+
+        keyword_filter (str | list[str], optional): Case-insensitive regex pattern or list of patterns to filter by tags.
+            - Example: "session-v1" (String: returns only memories tagged with session-v1)
+            - Example: "project-.*-2026" (Regex string: matches any 2026 project tag)
+            - Example: ["work", "important"] (List: returns only memories tagged with BOTH work AND important)
+
     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")
+        # Scoped search for a specific session
+        search_memories(query="What progress was made?", keyword_filter="session-v1")
+
+        # Scoped search using regex
+        search_memories(query="Database decisions", keyword_filter="project-.*")
     """
     # 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?\")"
+            '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?\")"
+            '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?\")"
+            '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)"
+            'Example: search_memories(query="...", k=10)'
         )
-    
+
     if not (1 <= k <= 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)"
+            'Example: search_memories(query="...", k=10)'
         )
 
     try:
-        logger.info(f"search_memories called - query length: {len(query_str)}, k: {k}")
+        logger.info(
+            f"search_memories called - query: '{query_str[:50]}...', k: {k}, filter: {keyword_filter}"
+        )
         client = await _get_api_client()
-        result = await client.search_memories(query_str, k)
+        result = await client.search_memories(query_str, k, keyword_filter)
         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 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}")
+            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:
@@ -654,30 +695,30 @@ async def search_memories(query: str, k: int = 5) -> str:
 @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.
-    
+
     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-..."])
     """
@@ -685,44 +726,44 @@ async def get_memories(memory_ids: List[str]) -> str:
     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-...\"])"
+            '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-...\"])"
+            'Example: get_memories(memory_ids=["480c1f76-..."])'
         )
-    
+
     if not memory_ids:
         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\"])"
+            '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-...\"])"
+                '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-...\"])"
+                '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\"])"
+                'Example: get_memories(memory_ids=["480c1f76-bcdf-4491-8781-24510db992e3"])'
             )
         validated_ids.append(memory_id_str)
 
@@ -736,9 +777,13 @@ async def get_memories(memory_ids: List[str]) -> str:
         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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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"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
@@ -749,22 +794,20 @@ async def get_memories(memory_ids: List[str]) -> str:
 
 @mcp.tool()
 async def update_memory(
-    memory_id: str,
-    content: Optional[str] = None,
-    tags: Optional[List[str]] = None
+    memory_id: str, content: Optional[str] = None, tags: Optional[Union[List[str], 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.
-    
+
     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. 
+
+        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
@@ -772,27 +815,27 @@ async def update_memory(
             - 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-...",
@@ -805,50 +848,50 @@ async def update_memory(
         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\")"
+            '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\")"
+            '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\")"
+            '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\"])"
+            '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\")"
+                '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\")"
+                '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:
@@ -859,8 +902,8 @@ async def update_memory(
                 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"
+                        '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):
@@ -872,14 +915,18 @@ async def update_memory(
                 try:
                     parsed = json.loads(tags_str)
                     if isinstance(parsed, list):
-                        normalized_tags = [str(item).strip() for item in parsed if str(item).strip()]
+                        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()]
+                    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]
@@ -887,17 +934,19 @@ async def update_memory(
             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"
+                '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}")
-        
+        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_str, content_str, normalized_tags)
-        memory = result.get('memory')
+        memory = result.get("memory")
         if memory:
             return f"Memory updated:\n{_format_memory(memory)}"
         return f"Memory {memory_id_str} updated"
@@ -905,11 +954,17 @@ async def update_memory(
         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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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\")")
+            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"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
@@ -920,44 +975,42 @@ async def update_memory(
 
 @mcp.tool()
 async def delete_memories(
-    memory_id: Optional[str] = None,
-    tags: Optional[str] = None,
-    category: Optional[str] = None
+    memory_id: Optional[str] = None, 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.
-    
+
     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")
     """
@@ -965,79 +1018,87 @@ async def delete_memories(
     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\")"
+            '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\")"
+                '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\")"
+                '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\")"
+                '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\")"
+                '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\")"
+                '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\")"
+                '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}")
+        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_str, tags_str, category_str)
-        deleted_ids = result.get('memory_ids', [])[:10]
+        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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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}")
+            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:
@@ -1048,26 +1109,26 @@ async def delete_memories(
 @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.
-    
+
     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(
@@ -1080,56 +1141,58 @@ async def unlink_memories(memory_id_1: str, memory_id_2: str) -> str:
         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-...\")"
+            '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-...\")"
+            '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-...\")"
+            '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-...\")"
+            '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-...\")"
+            '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\")"
+            '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-...\")"
+            '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}")
+        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_str, memory_id_2_str)
         return result.get("message", "Memories unlinked")
@@ -1137,10 +1200,16 @@ async def unlink_memories(memory_id_1: str, memory_id_2: str) -> str:
         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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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}")
+            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:
@@ -1151,20 +1220,20 @@ async def unlink_memories(memory_id_1: str, memory_id_2: str) -> str:
 @mcp.tool()
 async def get_stats(_placeholder: Optional[bool] = None) -> 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.
-    
+
     Parameters:
         _placeholder (bool, optional): Placeholder parameter for OpenCode compatibility. This parameter is ignored and can be omitted or set to any value. The function takes no actual parameters.
             - This is a workaround for MCP clients that incorrectly require a parameter for parameterless tools
             - Can be safely omitted or set to None/True/False
             - Example: get_stats() or get_stats(_placeholder=True)
-    
+
     Returns:
         str: Formatted statistics including total memories, links, and top tags.
-    
+
     Examples:
         # Get statistics (preferred - no parameters needed)
         get_stats()
-        
+
         # Get statistics (OpenCode workaround - parameter is ignored)
         get_stats(_placeholder=True)
     """
@@ -1176,18 +1245,22 @@ async def get_stats(_placeholder: Optional[bool] = None) -> str:
         client = await _get_api_client()
         logger.debug(f"API client initialized with base_url: {client.base_url}")
         result = await client.get_stats()
-        logger.debug(f"get_stats result received: {list(result.keys()) if isinstance(result, dict) else 'N/A'}")
-        top_tags = ', '.join([f"{tag}({count})" for tag, count in result.get('top_tags', [])[:10]])
+        logger.debug(
+            f"get_stats result received: {list(result.keys()) if isinstance(result, dict) else 'N/A'}"
+        )
+        top_tags = ", ".join([f"{tag}({count})" for tag, count in result.get("top_tags", [])[:10]])
         return f"""Memory System Statistics:
-Total Memories: {result.get('total_memories', 0)}
-Total Links: {result.get('total_links', 0)}
-Average Links per Memory: {result.get('avg_links_per_memory', 0):.2f}
+Total Memories: {result.get("total_memories", 0)}
+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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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
@@ -1199,26 +1272,26 @@ Top Tags: {top_tags}"""
 @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.
-    
+
     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(
@@ -1231,44 +1304,44 @@ async def find_path(from_id: str, to_id: str) -> str:
         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-...\")"
+            '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-...\")"
+            '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-...\")"
+            '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-...\")"
+            '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-...\")"
+            '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\")"
+            'Example: find_path(from_id="480c1f76-...", to_id="300d9716-a3a6-44d3-b0f4-b28002a65da8")'
         )
 
     try:
@@ -1285,9 +1358,13 @@ async def find_path(from_id: str, to_id: str) -> str:
         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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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"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
@@ -1299,36 +1376,36 @@ async def find_path(from_id: str, to_id: str) -> str:
 @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.
-    
+
     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)
     """
@@ -1337,36 +1414,36 @@ async def get_neighborhood(memory_id: str, hops: int = 2) -> str:
         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\")"
+            '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\")"
+            '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\")"
+            '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)"
+            'Example: get_neighborhood(memory_id="...", hops=2)'
         )
-    
+
     if not (1 <= hops <= 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)"
+            'Example: get_neighborhood(memory_id="...", hops=2)\n'
+            'Example: get_neighborhood(memory_id="...", hops=3)'
         )
 
     try:
@@ -1383,10 +1460,16 @@ async def get_neighborhood(memory_id: str, hops: int = 2) -> str:
         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 login using the 'login' tool or configure your JWT token in the MCP client headers.")
+            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}")
+            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:
@@ -1398,39 +1481,42 @@ async def get_neighborhood(memory_id: str, hops: int = 2) -> str:
 # HELPER FUNCTIONS
 # ============================================================================
 
+
 def _format_memory(memory: Optional[Dict[str, Any]]) -> str:
     """Format a single memory for display."""
     if not memory:
         return "Memory data not available"
-    
+
     lines = [
         f"ID: {memory.get('id', 'unknown')}",
         f"Content: {memory.get('content', '')[:200]}",
         f"Tags: {', '.join(memory.get('tags', []))}",
         f"Context: {memory.get('context', 'N/A')}",
-        f"Links: {len(memory.get('links', []))} connections"
+        f"Links: {len(memory.get('links', []))} connections",
     ]
-    
+
     # Add evolution history if available
-    evolution_history = memory.get('evolution_history', [])
+    evolution_history = memory.get("evolution_history", [])
     if evolution_history:
         lines.append(f"Evolution History: {len(evolution_history)} version(s)")
         # Show current version first
-        current_content = memory.get('content', '')
+        current_content = memory.get("content", "")
         lines.append(f"  Current Version: {current_content}")
         lines.append("")
         # Show historical versions (oldest to newest)
         for i, entry in enumerate(evolution_history, 1):
-            if entry.get('type') == 'content_update':
-                old_content = entry.get('old_content', '')
-                timestamp = entry.get('timestamp', 'unknown')
+            if entry.get("type") == "content_update":
+                old_content = entry.get("old_content", "")
+                timestamp = entry.get("timestamp", "unknown")
                 lines.append(f"  Version {i} ({timestamp}): {old_content}")
-            elif entry.get('type') == 'evolution':
-                old_context = entry.get('old_context', 'N/A')
-                new_context = entry.get('new_context', 'N/A')
-                timestamp = entry.get('timestamp', 'unknown')
-                lines.append(f"  Evolution {i} ({timestamp}): Context '{old_context}' → '{new_context}'")
-    
+            elif entry.get("type") == "evolution":
+                old_context = entry.get("old_context", "N/A")
+                new_context = entry.get("new_context", "N/A")
+                timestamp = entry.get("timestamp", "unknown")
+                lines.append(
+                    f"  Evolution {i} ({timestamp}): Context '{old_context}' → '{new_context}'"
+                )
+
     return "\n".join(lines)
 
 
@@ -1438,7 +1524,7 @@ def _format_memories_list(memories: List[Dict[str, Any]]) -> str:
     """Format a list of memories for display."""
     if not memories:
         return "No memories found"
-    
+
     formatted = []
     for i, mem in enumerate(memories, 1):
         formatted.append(f"{i}. {_format_memory(mem)}")
@@ -1449,7 +1535,7 @@ def _format_search_results(results: List[Dict[str, Any]]) -> str:
     """Format search results for display."""
     if not results:
         return "No results found"
-    
+
     formatted = []
     for i, result in enumerate(results, 1):
         if result.get("type") == "memory_node":
@@ -1460,32 +1546,32 @@ def _format_search_results(results: List[Dict[str, Any]]) -> str:
                 formatted.append(f"   Related: {len(related)} memories")
         elif result.get("type") == "relationship_edge":
             formatted.append(f"{i}. Relationship Edge (score: {result.get('score', 0):.3f})")
-            source = result.get('source', {})
-            target = result.get('target', {})
-            
+            source = result.get("source", {})
+            target = result.get("target", {})
+
             # Show source node data
             formatted.append(f"   Source Node:")
             formatted.append(f"     ID: {source.get('id', 'unknown')}")
             formatted.append(f"     Content: {source.get('content', 'N/A')}")
-            if source.get('context') and source.get('context') != 'General':
+            if source.get("context") and source.get("context") != "General":
                 formatted.append(f"     Context: {source.get('context', 'N/A')}")
-            if source.get('tags'):
+            if source.get("tags"):
                 formatted.append(f"     Tags: {', '.join(source.get('tags', []))}")
-            if source.get('keywords'):
+            if source.get("keywords"):
                 formatted.append(f"     Keywords: {', '.join(source.get('keywords', []))}")
-            
+
             # Show target node data
             formatted.append(f"   Target Node:")
             formatted.append(f"     ID: {target.get('id', 'unknown')}")
             formatted.append(f"     Content: {target.get('content', 'N/A')}")
-            if target.get('context') and target.get('context') != 'General':
+            if target.get("context") and target.get("context") != "General":
                 formatted.append(f"     Context: {target.get('context', 'N/A')}")
-            if target.get('tags'):
+            if target.get("tags"):
                 formatted.append(f"     Tags: {', '.join(target.get('tags', []))}")
-            if target.get('keywords'):
+            if target.get("keywords"):
                 formatted.append(f"     Keywords: {', '.join(target.get('keywords', []))}")
         formatted.append("")
-    
+
     return "\n".join(formatted)
 
 
@@ -1493,10 +1579,7 @@ def _format_search_results(results: List[Dict[str, Any]]) -> str:
 @mcp.custom_route("/health", methods=["GET"])
 async def health_check(request: Request) -> JSONResponse:
     """Health check endpoint for load balancers."""
-    return JSONResponse(
-        content={"status": "healthy", "service": "mem-brain-mcp"},
-        status_code=200
-    )
+    return JSONResponse(content={"status": "healthy", "service": "mem-brain-mcp"}, status_code=200)
 
 
 def _mask_api_url(url: str) -> str:
@@ -1515,14 +1598,16 @@ def _mask_api_url(url: str) -> str:
 
 def run_server():
     """Run the FastMCP server with HTTP transport."""
-    logger.info(f"Starting Mem-Brain MCP Server v{__version__} on {settings.mcp_server_host}:{settings.mcp_server_port}")
+    logger.info(
+        f"Starting Mem-Brain MCP Server v{__version__} on {settings.mcp_server_host}:{settings.mcp_server_port}"
+    )
     logger.info(f"API URL: {_mask_api_url(settings.api_url)}")
     logger.info(f"API Key: {'***' if settings.api_key else 'Not set'}")
-    
+
     # Configure CORS for browser-based and MCP clients
     from starlette.middleware import Middleware
     from starlette.middleware.cors import CORSMiddleware
-    
+
     middleware = [
         Middleware(
             CORSMiddleware,
@@ -1538,11 +1623,11 @@ def run_server():
             expose_headers=["mcp-session-id"],
         )
     ]
-    
+
     # Use http_app with CORS middleware and run with uvicorn
     # Note: http_app() handles the /mcp path automatically
     app = mcp.http_app(middleware=middleware, path="/mcp")
-    
+
     # Import uvicorn (should be available via FastMCP dependencies)
     try:
         import uvicorn
@@ -1553,10 +1638,10 @@ def run_server():
             transport="http",
             host=settings.mcp_server_host,
             port=settings.mcp_server_port,
-            path="/mcp"
+            path="/mcp",
         )
         return
-    
+
     uvicorn.run(
         app,
         host=settings.mcp_server_host,