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

mem_brain_mcp/server.py

@@ -7,7 +7,6 @@ import httpx
 from fastmcp import FastMCP
 from fastmcp.server.context import request_ctx
 from fastmcp.exceptions import ToolError
-from fastmcp.prompts.prompt import PromptMessage, TextContent
 from starlette.requests import Request
 from starlette.responses import JSONResponse
 
@@ -26,7 +25,7 @@ AGENT_INSTRUCTIONS = """You are an intelligent assistant with a persistent, evol
 **1. SEARCH FIRST & SMART** — Before answering personal questions, call `search_memories`.
    - **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)
+     - ✅ `query="Who is Maga and what is his relationship to me?"` (Strong)
    - **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)
@@ -40,30 +39,17 @@ AGENT_INSTRUCTIONS = """You are an intelligent assistant with a persistent, evol
 **3. PASSIVE STORAGE** — When user reveals preferences, store the **FACT** (not conversation).
    - User: "I think I wanna try that sushi spot" → Store: "User interested in new sushi restaurant"
 
-**4. KEEP IT CURRENT** — If user contradicts a past memory, use `update_memory`.
-
 ---
 
 ## 🛠️ TOOLS
 
-### Core Operations
-
 | Tool | When to Use |
 |------|-------------|
 | `search_memories(query, k=5)` | Before answering ANY personal question |
 | `get_memories(memory_ids)` | Need full details for specific IDs |
 | `add_memory(content, tags=[], category="")` | User reveals preference/goal/fact |
-| `update_memory(memory_id, content=..., tags=...)` | Information evolves or changes |
+| `get_stats()` | Check memory coverage and system health |
 | `delete_memories(memory_id)` | Memory is wrong or user requests deletion |
-| `unlink_memories(id1, id2)` | Connection no longer relevant |
-| `get_stats()` | User asks "how much do you remember?" |
-
-### Graph Intelligence (Advanced)
-
-| Tool | Purpose | Example |
-|------|---------|---------|
-| `find_path(from_id, to_id)` | Explain connections | "How is coffee related to health?" → Shows: Coffee→Caffeine→Health |
-| `get_neighborhood(memory_id, hops=2)` | Deep context | Get 2-hop radius around a memory |
 
 ---
 
@@ -78,10 +64,10 @@ AGENT_INSTRUCTIONS = """You are an intelligent assistant with a persistent, evol
 - Type: `preference`, `constraint`, `goal`, `fact`, `event`
 - Priority: `important`, `routine`, `temporary`
 
-**Avoiding duplicates:**
-1. If you already searched → check if memory exists before adding
-2. If similar memory exists → `update_memory` instead
-3. If you haven't searched → just add it, evolution handles linking
+**System handles updates automatically:**
+- When user changes preferences, just add the new memory
+- The system automatically links related memories and manages updates
+- No manual linking or unlinking needed
 
 ---
 
@@ -90,20 +76,11 @@ AGENT_INSTRUCTIONS = """You are an intelligent assistant with a persistent, evol
 | Signal | Action |
 |--------|--------|
 | "I'm trying X", "exploring Y" | ADD new memory (temporary exploration) |
-| "I no longer like X", "I switched to Y" | UPDATE existing memory (permanent change) |
+| "I no longer like X", "I switched to Y" | ADD new memory (the system handles updates automatically) |
 | Contradictory with equal weight | ADD with temporal context ("as of 2025") |
 
 ---
 
-## ⚡ ARCHITECTURE (Brief)
-
-- **Graph Structure**: Memories = nodes, links = edges
-- **Search**: Semantic similarity (70%) + importance/connections (30%)
-- **Auto-linking**: System creates links for narrative/causal connections
-- **User isolation**: Separate database per user
-
----
-
 ## ✅ BEST PRACTICES
 
 | DO | DON'T |
@@ -111,7 +88,6 @@ AGENT_INSTRUCTIONS = """You are an intelligent assistant with a persistent, evol
 | Search before answering personal Q's | Guess without searching |
 | Check `related_memories` field | Ignore graph connections |
 | Store explicit facts | Store vague conversation |
-| Update when info changes | Create duplicates |
 | Synthesize across memories | Just list facts |
 
 **Remember:** You're not a database. Connect the dots to provide thoughtful, personalized responses."""
@@ -170,68 +146,6 @@ mcp = FastMCP("Mem-Brain MCP")
 api_client = APIClient()
 
 
-async def _get_dynamic_context() -> str:
-    """Fetch dynamic context (core identity + recent memories) from API."""
-    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_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",
-                }
-            ):
-                identity_memories.append(mem)
-
-        identity_section = ""
-        if identity_memories:
-            identity_section = "## 🧬 Core Identity\n"
-            for memory in identity_memories[:3]:
-                identity_section += f"- {memory['content']}\n"
-
-        # Get recent context
-        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
-                recent_section += f"- {truncated}\n"
-
-        return f"""### 🧠 YOUR BRAIN (Current Working Context)
-{identity_section if identity_section else "*No core identity established yet*"}
-{recent_section if recent_section else "*No recent context*"}
-
----
-
-"""
-    except Exception as e:
-        logger.warning(f"Could not fetch dynamic context: {e}")
-        return """### 🧠 YOUR BRAIN (Current Working Context)
-*Context loading failed - API may be unavailable*
-
----
-
-"""
-
-
 # ============================================================================
 # RESOURCES (Documentation that LLMs can read)
 # ============================================================================
@@ -240,7 +154,7 @@ async def _get_dynamic_context() -> str:
 @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."""
-    return """# A-Mem Workflow Guide
+    return """# Memory Workflow Guide
 
 ## 🎯 CORE DIRECTIVE
 **Synthesize**, don't just retrieve. Connect user's request to their past preferences, habits, and constraints.
@@ -250,7 +164,7 @@ def workflow_guide() -> str:
 **1. SEARCH FIRST & SMART** — Before answering personal questions, call `search_memories`.
    - **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)
+     - ✅ `query="Who is Maga and what is his relationship to me?"` (Strong)
    - Check `related_memories` field — these are auto-expanded graph neighbors.
    - Synthesize: If "coffee" result links to "acid reflux", suggest cold brew.
 
@@ -261,8 +175,6 @@ def workflow_guide() -> str:
 **3. PASSIVE STORAGE** — When user reveals preferences, store the **FACT** (not conversation).
    - User: "I think I wanna try that sushi spot" → Store: "User interested in new sushi restaurant"
 
-**4. KEEP IT CURRENT** — If user contradicts a past memory, use `update_memory`.
-
 ## ✅ BEST PRACTICES
 
 | DO | DON'T |
@@ -270,59 +182,12 @@ def workflow_guide() -> str:
 | Search before answering personal Q's | Guess without searching |
 | Check `related_memories` field | Ignore graph connections |
 | Store explicit facts | Store vague conversation |
-| Update when info changes | Create duplicates |
 | Synthesize across memories | Just list facts |
 
 **Remember:** You're not a database. Connect the dots to provide thoughtful, personalized responses.
 """
 
 
-@mcp.resource("mem-brain://docs/tool-reference")
-def tool_reference() -> str:
-    """Detailed reference for when and how to use each memory tool effectively."""
-    return """# Tool Usage Reference
-
-## Core Operations
-
-### `search_memories(query, k=5)`
-**When to Use**: Before answering ANY personal question
-**Critical**: Formulate specific, natural language queries, NOT simple keywords
-- ✅ Good: "Who is Maga and what is their relationship to me?"
-- ❌ Bad: "maga"
-
-### `get_memories(memory_ids)`
-**When to Use**: Need full details for specific IDs identified from search results
-
-### `add_memory(content, tags=[], category="")`
-**When to Use**: User reveals preference/goal/fact
-**Storage Rule**: Store FACTS, not conversation
-- ✅ "User prefers dark mode interfaces"
-- ❌ "You said you like dark mode"
-
-### `update_memory(memory_id, content=..., tags=...)`
-**When to Use**: Information evolves or changes, user contradicts past memory
-
-### `delete_memories(memory_id)`
-**When to Use**: Memory is wrong or user explicitly requests deletion
-
-### `unlink_memories(id1, id2)`
-**When to Use**: Connection no longer relevant or accurate
-
-### `get_stats()`
-**When to Use**: User asks "how much do you remember?" or wants overview
-
-## Graph Intelligence
-
-### `find_path(from_id, to_id)`
-**Purpose**: Explain connections between memories
-**Example**: "How is coffee related to health?" → Shows path: Coffee→Caffeine→Health
-
-### `get_neighborhood(memory_id, hops=2)`
-**Purpose**: Get deep context around a memory
-**Use Case**: Understanding relationships around important memories
-"""
-
-
 @mcp.resource("mem-brain://docs/storage-guidelines")
 def storage_guidelines() -> str:
     """Best practices for storing facts, tagging patterns, and avoiding duplicates."""
@@ -339,79 +204,31 @@ def storage_guidelines() -> str:
 **Types**: `preference`, `constraint`, `goal`, `fact`, `event`
 **Priority**: `important`, `routine`, `temporary`
 
-## Avoiding Duplicates
+## System Handles Updates Automatically
 
-1. If you already searched → check if memory exists before adding
-2. If similar memory exists → `update_memory` instead
-3. If you haven't searched → just add it, evolution handles linking
+- When user changes preferences, just add the new memory
+- The system automatically links related memories and manages updates
+- No manual linking or unlinking needed
 
 ## Changing Preferences
 
 | Signal | Action |
 |--------|--------|
 | "I'm trying X", "exploring Y" | ADD new memory (temporary exploration) |
-| "I no longer like X", "I switched to Y" | UPDATE existing memory (permanent change) |
+| "I no longer like X", "I switched to Y" | ADD new memory (the system handles updates automatically) |
 | Contradictory with equal weight | ADD with temporal context ("as of 2025") |
-
-## Architecture
-
-- **Graph Structure**: Memories = nodes, links = edges
-- **Search**: Semantic similarity (70%) + importance/connections (30%)
-- **Auto-linking**: System creates links for narrative/causal connections
-- **User isolation**: Separate database per user
 """
 
 
-# ============================================================================
-# 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))
-
-
-@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(
-            type="text",
-            text=f"""{context_section}
-
-**Context refreshed.** Continue using memory tools as before.
-""",
-        ),
-    )
-
-
 # ============================================================================
 # TOOLS (Operations)
 # ============================================================================
 
 
 @mcp.tool()
-async def get_agent_instructions(include_dynamic_context: bool = True) -> str:
+async def get_agent_instructions() -> 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."""
-    if include_dynamic_context:
-        context_section = await _get_dynamic_context()
-    else:
-        context_section = ""
-
-    return context_section + AGENT_INSTRUCTIONS
+    return AGENT_INSTRUCTIONS
 
 
 @mcp.tool()
@@ -792,187 +609,6 @@ async def get_memories(memory_ids: List[str]) -> str:
         raise ToolError(f"Error getting memories: {str(e)}")
 
 
-@mcp.tool()
-async def update_memory(
-    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.
-            - Can be None (to keep existing content) or a non-empty string
-            - If provided, must not be empty or whitespace-only
-            - Example: "User no longer likes TypeScript, prefers Python"
-
-        tags (list[str] or str, optional): New tags for the memory.
-            - Can be None (to keep existing tags), a list of strings, a comma-separated string, or a JSON array string
-            - If provided, replaces existing tags
-            - Example: ["coding", "python"]
-            - Example: "coding,python" (comma-separated)
-            - Example: '["coding", "python"]' (JSON string)
-            - Note: The system can auto-generate tags if you omit this parameter
-
-    Returns:
-        str: A formatted string with the updated memory details.
-
-    Common Errors and Solutions:
-        - Error: "Tool call arguments for mcp were invalid"
-          Solution: Ensure 'memory_id' parameter is provided as a string. Example: update_memory(memory_id="...")
-
-        - Error: "memory_id cannot be empty"
-          Solution: Provide a valid memory ID from search results. Example: update_memory(memory_id="480c1f76-...")
-
-        - Error: "At least one of 'content' or 'tags' must be provided"
-          Solution: Provide content or tags to update. Example: update_memory(memory_id="...", content="New content")
-
-    Examples:
-        # Update content only
-        update_memory(memory_id="480c1f76-...", content="User prefers Python over JavaScript")
-
-        # Update tags only
-        update_memory(memory_id="480c1f76-...", tags=["coding", "preferences"])
-
-        # Update both content and tags
-        update_memory(
-            memory_id="480c1f76-...",
-            content="User no longer likes TypeScript",
-            tags=["coding", "python"]
-        )
-    """
-    # Validate parameters with detailed error messages
-    if memory_id is None:
-        raise ToolError(
-            "The 'memory_id' parameter is required but was not provided.\n"
-            "Get memory IDs from search_memories() or get_memories() results.\n"
-            'Example: update_memory(memory_id="480c1f76-bcdf-4491-8781-24510db992e3", content="New content")'
-        )
-
-    if not isinstance(memory_id, str):
-        raise ToolError(
-            f"The 'memory_id' parameter must be a string, but got {type(memory_id).__name__}.\n"
-            f"Received: {repr(memory_id)}\n"
-            'Example: update_memory(memory_id="480c1f76-...", content="New content")'
-        )
-
-    memory_id_str = memory_id.strip()
-    if not memory_id_str:
-        raise ToolError(
-            "The 'memory_id' parameter cannot be empty or whitespace-only.\n"
-            "Get memory IDs from search_memories() or get_memories() results.\n"
-            'Example: update_memory(memory_id="480c1f76-bcdf-4491-8781-24510db992e3", content="New content")'
-        )
-
-    # Validate that at least one update parameter is provided
-    if content is None and tags is None:
-        raise ToolError(
-            "At least one of 'content' or 'tags' must be provided to update the memory.\n"
-            'Example: update_memory(memory_id="...", content="New content")\n'
-            'Example: update_memory(memory_id="...", tags=["new", "tags"])'
-        )
-
-    # Validate content if provided
-    if content is not None:
-        if not isinstance(content, str):
-            raise ToolError(
-                f"The 'content' parameter must be a string or None, but got {type(content).__name__}.\n"
-                f"Received: {repr(content)}\n"
-                'Example: update_memory(memory_id="...", content="New content")'
-            )
-        content_str = str(content).strip()
-        if not content_str:
-            raise ToolError(
-                "The 'content' parameter cannot be empty or whitespace-only.\n"
-                "Provide a non-empty string or omit the parameter to keep existing content.\n"
-                'Example: update_memory(memory_id="...", content="New content")'
-            )
-    else:
-        content_str = None
-
-    # Validate tags if provided - handle various input formats
-    normalized_tags = None
-    if tags is not None:
-        if isinstance(tags, list):
-            # Validate list contents are strings
-            if tags:
-                invalid_items = [item for item in tags if not isinstance(item, str)]
-                if invalid_items:
-                    raise ToolError(
-                        f"The 'tags' parameter must be a list of strings, but found non-string items: {invalid_items}\n"
-                        'Example: update_memory(memory_id="...", tags=["coding", "preferences"])\n'
-                        'Example: update_memory(memory_id="...", tags=None)  # or omit tags parameter'
-                    )
-            normalized_tags = tags if tags else None  # Empty list becomes None
-        elif isinstance(tags, str):
-            tags_str = tags.strip()
-            if not tags_str:
-                normalized_tags = None
-            else:
-                # Try to parse as JSON array first (e.g., '["tag1", "tag2"]')
-                try:
-                    parsed = json.loads(tags_str)
-                    if isinstance(parsed, list):
-                        normalized_tags = [
-                            str(item).strip() for item in parsed if str(item).strip()
-                        ]
-                    else:
-                        # If JSON but not a list, treat as single tag
-                        normalized_tags = [tags_str]
-                except (json.JSONDecodeError, ValueError):
-                    # Not JSON, try comma-separated string
-                    if "," in tags_str:
-                        normalized_tags = [
-                            tag.strip() for tag in tags_str.split(",") if tag.strip()
-                        ]
-                    else:
-                        # Single tag string
-                        normalized_tags = [tags_str]
-        else:
-            raise ToolError(
-                f"The 'tags' parameter must be a list of strings, a comma-separated string, or None, but got {type(tags).__name__}.\n"
-                f"Received: {repr(tags)}\n"
-                'Example: update_memory(memory_id="...", tags=["coding", "preferences"])\n'
-                'Example: update_memory(memory_id="...", tags="coding,preferences")\n'
-                'Example: update_memory(memory_id="...", tags=None)  # or omit tags parameter'
-            )
-
-    try:
-        logger.info(
-            f"update_memory called - memory_id: {memory_id_str}, content length: {len(content_str) if content_str else 0}, tags: {normalized_tags}"
-        )
-
-        client = await _get_api_client()
-        result = await client.update_memory(memory_id_str, content_str, normalized_tags)
-        memory = result.get("memory")
-        if memory:
-            return f"Memory updated:\n{_format_memory(memory)}"
-        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 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 in update_memory: {e}", exc_info=True)
-        raise ToolError(f"Error updating memory: {str(e)}")
-
-
 @mcp.tool()
 async def delete_memories(
     memory_id: Optional[str] = None, tags: Optional[str] = None, category: Optional[str] = None
@@ -1107,355 +743,64 @@ 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(
-            memory_id_1="480c1f76-bcdf-4491-8781-24510db992e3",
-            memory_id_2="300d9716-a3a6-44d3-b0f4-b28002a65da8"
-        )
+async def get_stats() -> str:
+    """Get comprehensive statistics about the memory system.
+
+    **Use this tool to:**
+    - Check how many memories you have stored
+    - See total link count and link density
+    - View top tags and memory distribution
+    - Understand your knowledge graph structure
+
+    **Why this matters:**
+    - Provides context about memory coverage
+    - Shows if the system is actively used
+    - Reveals patterns in what you store
+    - Helps identify gaps or over-representation
+
+    Returns formatted statistics including:
+    - Total memories count
+    - Total links count
+    - Average links per memory
+    - Top tags by frequency
+    - Memory categories/tags distribution
+
+    **Example:**
+    get_stats()
     """
-    # 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}"
-        )
+        logger.info("get_stats called - retrieving memory system statistics")
         client = await _get_api_client()
-        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 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 in unlink_memories: {e}", exc_info=True)
-        raise ToolError(f"Error unlinking memories: {str(e)}")
-
-
-@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)
-    """
-    # _placeholder parameter is ignored - this is a workaround for OpenCode compatibility
-    # The function actually takes no parameters, but some MCP clients incorrectly require one
-    try:
-        logger.info("get_stats called")
-        logger.debug(f"get_stats called with _placeholder={_placeholder} (ignored)")
-        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]])
-        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}
-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(f"Failed to get stats: HTTP {e.response.status_code} - {error_detail}")
-    except ToolError:
-        raise
-    except Exception as e:
-        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.
-
-    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_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", []):
-                path_text += f"  - {mem.get('id', 'unknown')}: {mem.get('content', '')[:100]}\n"
-            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 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 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.
-
-    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(
-            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)'
-        )
+        # Extract statistics
+        total_memories = result.get("total_memories", 0)
+        total_links = result.get("total_links", 0)
+        avg_links = result.get("avg_links_per_memory", 0)
+        top_tags = result.get("top_tags", [])
+
+        # Format response
+        lines = [
+            "📊 Memory System Statistics",
+            "",
+            f"Total Memories: {total_memories}",
+            f"Total Links: {total_links}",
+            f"Average Links per Memory: {avg_links:.2f}",
+        ]
+
+        # Add top tags if available
+        if top_tags:
+            lines.append("")
+            lines.append("Top Tags:")
+            for tag_data in top_tags[:10]:  # Show top 10
+                if isinstance(tag_data, dict):
+                    tag_name = tag_data.get("tag", "unknown")
+                    count = tag_data.get("count", 0)
+                    lines.append(f"  - {tag_name}: {count} memories")
+                else:
+                    lines.append(f"  - {tag_data}")
 
-    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_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)
-            is_center = " (center)" if mem.get("is_center") else ""
-            neighborhood_text += f"  [{hop_dist}]{is_center} {mem.get('id', 'unknown')}: {mem.get('content', '')[:100]}\n"
-        return neighborhood_text
+        return "\n".join(lines)
     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}")
@@ -1463,18 +808,12 @@ async def get_neighborhood(memory_id: str, hops: int = 2) -> str:
             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"Failed to get statistics: HTTP {e.response.status_code} - {error_detail}")
     except ToolError:
         raise
     except Exception as e:
-        logger.error(f"Unexpected error in get_neighborhood: {e}", exc_info=True)
-        raise ToolError(f"Error getting neighborhood: {str(e)}")
+        logger.error(f"Unexpected error in get_stats: {e}", exc_info=True)
+        raise ToolError(f"Error getting statistics: {str(e)}")
 
 
 # ============================================================================

{mem_brain_mcp-1.0.8.dist-info → mem_brain_mcp-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mem-brain-mcp
-Version: 1.0.8
+Version: 1.1.0
 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
@@ -194,15 +194,40 @@ For detailed instructions, see [aws/DEPLOYMENT.md](./aws/DEPLOYMENT.md).
 pytest
 ```
 
-### Build and Publish
+### Build and Publish to PyPI
+
+**Prerequisites:** Ensure you have a PyPI account and your credentials are configured in `~/.pypirc`.
+
+**Step-by-step deployment:**
+
 ```bash
-# Build the wheel
-python3 -m build
+# 1. Activate the virtual environment
+cd mem-brain-mcp
+source .venv/bin/activate
+
+# 2. Update version in pyproject.toml
+# Edit pyproject.toml and increment the version number (e.g., 1.0.8 -> 1.0.9)
+
+# 3. Clean old builds
+rm -rf dist/*
+
+# 4. Build the package
+python -m build
 
-# Upload to PyPI
+# 5. Upload to PyPI using twine
 twine upload dist/*
 ```
 
+**Quick deployment (one-liner after version bump):**
+```bash
+source .venv/bin/activate && rm -rf dist/* && python -m build && twine upload dist/*
+```
+
+**Verify deployment:**
+```bash
+pip3 index versions mem-brain-mcp
+```
+
 ## License
 
 Same as Mem-Brain API project.

{mem_brain_mcp-1.0.8.dist-info → mem_brain_mcp-1.1.0.dist-info}/RECORD

@@ -2,8 +2,8 @@ mem_brain_mcp/__init__.py,sha256=4gTKntJjg7JiV6dGhDNy1yFh3TW2tCdME_GR-pnSXwk,89
 mem_brain_mcp/__main__.py,sha256=H_mwoKm1FBmu4KzAcQcq-TXZqeNvlrAekAxB1s4F4hA,712
 mem_brain_mcp/client.py,sha256=jpf0fCupoRI8xZnPF4OntAQYxDAiVetIfL3S5GUOwUo,8009
 mem_brain_mcp/config.py,sha256=xx2lBkCIeT85t0HxtORwZHSU3hZT_EdsThpfjwPJhbQ,1261
-mem_brain_mcp/server.py,sha256=c57j4MeAnekMkEnDzen8bi3TX6ZjEAWS1bnk4uJ1414,71875
-mem_brain_mcp-1.0.8.dist-info/METADATA,sha256=c86gHcn9gWwBes8VMKi3CBa17GITo3DxXE-Okp-Y184,5228
-mem_brain_mcp-1.0.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mem_brain_mcp-1.0.8.dist-info/entry_points.txt,sha256=NH6QYQ-Sd8eJn5crpe_DL1PvGeUlL3y65968xPhmwG8,62
-mem_brain_mcp-1.0.8.dist-info/RECORD,,
+mem_brain_mcp/server.py,sha256=MZHMahLvpmq9h7j8ipsOfF2j7X_d965vBk_QQBk6Cxw,42272
+mem_brain_mcp-1.1.0.dist-info/METADATA,sha256=hahjVHRKHO1g18XJlP5Whmu6x3L_5iK9sjzJ21kB27A,5846
+mem_brain_mcp-1.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mem_brain_mcp-1.1.0.dist-info/entry_points.txt,sha256=NH6QYQ-Sd8eJn5crpe_DL1PvGeUlL3y65968xPhmwG8,62
+mem_brain_mcp-1.1.0.dist-info/RECORD,,