yomemoai-mcp 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

yomemoai_mcp/__init__.py

@@ -1,2 +1,3 @@
-def hello() -> str:
-    return "Hello from yomemoai-mcp!"
+"""YoMemoAI MCP Server - Model Context Protocol server for YoMemoAI."""
+
+__version__ = "0.1.0"

yomemoai_mcp/client.py

@@ -1,5 +1,6 @@
 import base64
 import json
+import logging
 import time
 import requests
 from typing import Dict, List, Optional, Tuple
@@ -9,6 +10,24 @@ from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 from cryptography.hazmat.backends import default_backend
 import os
 
+logger = logging.getLogger(__name__)
+
+
+class MemoRequestError(Exception):
+    def __init__(
+        self,
+        message: str,
+        url: str,
+        payload: Dict,
+        status_code: Optional[int] = None,
+        response_text: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.url = url
+        self.payload = payload
+        self.status_code = status_code
+        self.response_text = response_text
+
 
 class MemoClient:
     """
@@ -98,9 +117,20 @@ class MemoClient:
             )
 
     def add_memory(self, content: str, handle: str = "", description: str = "", metadata: Dict = None):
+        # Ensure handle is not empty (API requires it)
+        if not handle or not handle.strip():
+            handle = "general"
+
+        # Remove spaces from handle (API doesn't allow spaces)
+        handle = handle.replace(" ", "-").lower()
+
         token_size = len(content)
+        logger.debug(
+            f"Adding memory: handle={handle}, content_length={token_size}, description={description}")
 
         packed = self.pack_data(content.encode('utf-8'))
+        logger.debug(f"Packed data length: {len(packed)}")
+
         payload = {
             "ciphertext": packed,
             "description": description,
@@ -110,10 +140,42 @@ class MemoClient:
                 "from": "yomemoai-mcp",
             }
         }
-        resp = self.session.post(
-            f"{self.base_url}/api/v1/memory", json=payload)
-        resp.raise_for_status()
-        return resp.json()
+
+        url = f"{self.base_url}/api/v1/memory"
+        logger.debug(f"POST {url}")
+
+        try:
+            resp = self.session.post(url, json=payload)
+            logger.debug(f"Response status: {resp.status_code}")
+
+            # Provide better error messages
+            if not resp.ok:
+                try:
+                    error_detail = resp.json().get("error", resp.text)
+                except Exception:
+                    error_detail = resp.text
+                logger.error(f"API error {resp.status_code}: {error_detail}")
+                raise MemoRequestError(
+                    f"API error {resp.status_code}: {error_detail}",
+                    url=url,
+                    payload=payload,
+                    status_code=resp.status_code,
+                    response_text=resp.text,
+                )
+
+            result = resp.json()
+            logger.debug(f"Success response: {result}")
+            return result
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {type(e).__name__}: {str(e)}")
+            raise MemoRequestError(
+                f"Request failed: {type(e).__name__}: {str(e)}",
+                url=url,
+                payload=payload,
+            ) from e
+        except Exception as e:
+            logger.error(f"Unexpected error: {type(e).__name__}: {str(e)}")
+            raise
 
     def get_memories(self, handle: Optional[str] = None) -> List[Dict]:
         url = f"{self.base_url}/api/v1/memory"

yomemoai_mcp/server.py

@@ -1,11 +1,25 @@
 import asyncio
+import json
+import logging
+import sys
 from mcp.server.fastmcp import FastMCP
-from .client import MemoClient
+from .client import MemoClient, MemoRequestError
 import os
 
 from dotenv import load_dotenv
 load_dotenv()
 
+# Configure logging
+DEBUG = os.getenv("DEBUG", "false").lower() == "true"
+LOG_LEVEL = logging.DEBUG if DEBUG else logging.INFO
+
+logging.basicConfig(
+    level=LOG_LEVEL,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    stream=sys.stderr
+)
+logger = logging.getLogger(__name__)
+
 mcp = FastMCP("yomemoai")
 
 API_KEY = os.getenv("MEMO_API_KEY", "")
@@ -33,37 +47,78 @@ if not private_pem.strip():
 client = MemoClient(API_KEY, private_pem, BASE_URL)
 
 
+def _format_payload(payload: dict) -> dict:
+    if not payload:
+        return {}
+    return dict(payload)
+
+
 @mcp.tool()
 async def save_memory(content: str, handle: str = "general", description: str = "") -> str:
     """
-    Store important information, user preferences, or conversation context as a permanent memory.
-    Use this tool when the user explicitly asks to 'remember', 'save', or 'keep track of' something.
+    Store important information as a permanent memory. You should call this proactively when you
+    detect user preferences, important decisions, reusable logic, or context worth recalling later—
+    not only when the user explicitly says "remember" or "save". After saving successfully, reply with ✓.
 
     :param content: The actual text/information to be remembered. Be concise but maintain context.
     :param handle: A short, unique category or tag (e.g., 'work', 'personal', 'project-x'). Defaults to 'general'.
-    :param description: A brief summary of what this memory is about to help with future identification. don't include any sensitive information.
+    :param description: A brief, non-sensitive summary or tag for this memory (helps future identification and search).
     """
+    logger.debug(
+        f"save_memory called: handle={handle}, description={description}, content_length={len(content)}")
     try:
         result = client.add_memory(
             content, handle=handle, description=description)
-        return f"Successfully archived in memory. ID: {result.get('memory_id')}"
+        logger.debug(f"add_memory response: {result}")
+
+        if "memory_id" not in result:
+            return f"Failed to save memory for handle: {handle}"
+
+        memory_id = result.get('memory_id')
+
+        return f"Successfully archived in memory. ID: {memory_id}"
+    except MemoRequestError as e:
+        logger.error(
+            f"Error saving memory: {type(e).__name__}: {str(e)}", exc_info=DEBUG)
+        request_info = {
+            "url": e.url,
+            "status_code": e.status_code,
+            "response_text": e.response_text,
+            "payload": _format_payload(e.payload),
+            "handle": handle,
+            "description": description,
+            "content_length": len(content),
+        }
+        # only debug mode return the request_info
+        if DEBUG:
+            return json.dumps(request_info, ensure_ascii=False)
+        return f"Failed to save your memory: {str(e)}"
     except Exception as e:
-        return f"Failed to save memory: {str(e)}"
+        logger.error(
+            f"Error saving memory: {type(e).__name__}: {str(e)}", exc_info=DEBUG)
+        return (
+            f"Failed to save your memory: {str(e)},"
+            f"handle: {handle},description: {description},content: {content}"
+        )
 
 
 @mcp.tool()
 async def load_memories(handle: str = None) -> str:
     """
-    Retrieve previously stored memories or context. 
-    Use this tool when the user asks 'what do you remember about...', 'check my notes on...', or when 
-    you need historical context to answer a question accurately.
+    Retrieve previously stored memories. Call this when the user asks what you remember, or when you
+    need historical context (preferences, past decisions, project details) to answer accurately.
 
-    :param handle: Optional filter. If the user specifies a category (e.g., 'about my job'), 
-                   extract and provide the relevant handle.
+    :param handle: Optional filter. If the user specifies a category (e.g., 'work', 'project-x'),
+                   use the relevant handle; otherwise omit to load across handles.
     """
+    logger.debug(f"load_memories called: handle={handle}")
     try:
         memories = client.get_memories(handle=handle)
+        logger.debug(f"Retrieved {len(memories)} memories")
+
         if not memories:
+            logger.info(
+                f"No memories found for handle: {handle if handle else 'all'}")
             return f"No memories found under the handle: {handle if handle else 'all'}."
 
         output = ["### Retrieved Memories:"]
@@ -72,8 +127,11 @@ async def load_memories(handle: str = None) -> str:
             output.append(
                 f"Handle: [{m.get('handle')}]\nContent: {m.get('content')}\n---"
             )
+        logger.info(f"Successfully loaded {len(memories)} memories")
         return "\n".join(output)
     except Exception as e:
+        logger.error(
+            f"Error retrieving memories: {type(e).__name__}: {str(e)}", exc_info=DEBUG)
         return f"Error retrieving memories: {str(e)}"
 
 if __name__ == "__main__":

{yomemoai_mcp-0.1.0.dist-info → yomemoai_mcp-0.1.2.dist-info}/METADATA

@@ -1,8 +1,12 @@
 Metadata-Version: 2.4
 Name: yomemoai-mcp
-Version: 0.1.0
+Version: 0.1.2
 Summary: Model Context Protocol (MCP) server for YoMemoAI - enables AI assistants to save and retrieve encrypted memories
-Author-email: lvxiangxiang <lvxiangxiang@shopline.com>
+Project-URL: Homepage, https://github.com/yomemoai/python-yomemo-mcp
+Project-URL: Documentation, https://github.com/yomemoai/python-yomemo-mcp#readme
+Project-URL: Repository, https://github.com/yomemoai/python-yomemo-mcp
+Project-URL: Issues, https://github.com/yomemoai/python-yomemo-mcp/issues
+Author-email: xxlv <lvxiang119@gmail.com>
 License: MIT
 License-File: LICENSE
 Keywords: ai,claude,cursor,mcp,mcp-server,memory,yomemoai
@@ -44,8 +48,8 @@ A Model Context Protocol (MCP) server for YoMemoAI, enabling AI assistants to sa
 1. Clone the repository:
 
 ```bash
-git clone <repository-url>
-cd yomemoai-mcp
+git clone https://github.com/yomemoai/python-yomemo-mcp.git
+cd python-yomemo-mcp
 ```
 
 2. Install dependencies using uv:
@@ -99,6 +103,11 @@ After configuration, you can run the MCP server using:
 uv run memo-mcp
 ```
 
+### Cursor best practice (recommended)
+
+Want the AI to **proactively** save memories when it detects preferences or decisions (not only when you say "remember")?  
+Add one rule in Cursor's Rules for AI—see **[CURSOR_RULES.md](./CURSOR_RULES.md)**.
+
 ### Integration with Cursor/Claude Desktop
 
 Add the following configuration to your MCP settings file:
@@ -225,9 +234,6 @@ yomemoai-mcp/
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-## Contributing
-
-[Add contribution guidelines here]
 
 ## Support
 

yomemoai_mcp-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+yomemoai_mcp/__init__.py,sha256=gDi0t9iKR423OZlwrrtwDaED3ck06XMe_y8mcxisBl0,95
+yomemoai_mcp/client.py,sha256=oZNfRW3ppfSRkWvG3ej-w56lUyfKsc6jOjvV_IY4JxM,6960
+yomemoai_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yomemoai_mcp/server.py,sha256=K4-yj2KoBrcKFc9-C8v3NcG87sBpUDde1giHJamwho8,5093
+yomemoai_mcp-0.1.2.dist-info/METADATA,sha256=clSl9U0TcQlC602gJlxFZFfWz8epgWXxsHsKZV_2glg,7551
+yomemoai_mcp-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+yomemoai_mcp-0.1.2.dist-info/entry_points.txt,sha256=uV0479NK4ppOUV1T9VSwFTLi87F4deaRjbL8s43R8uI,100
+yomemoai_mcp-0.1.2.dist-info/licenses/LICENSE,sha256=UVt2r_C3iy7rNKJAj_EcLcmcZdXONxJ01oJNsIEqTfw,1066
+yomemoai_mcp-0.1.2.dist-info/RECORD,,

{yomemoai_mcp-0.1.0.dist-info → yomemoai_mcp-0.1.2.dist-info}/entry_points.txt

@@ -1,4 +1,3 @@
 [console_scripts]
 memo-mcp = yomemoai_mcp.server:mcp.run
-yomemo = yomemoai_mcp.server:mcp.run
 yomemoai-mcp = yomemoai_mcp.server:mcp.run

yomemoai_mcp-0.1.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-yomemoai_mcp/__init__.py,sha256=I2FoPD8dKHgF95vpefoGxZkQ9gi9yeYkEM2ZObyUQ48,58
-yomemoai_mcp/client.py,sha256=vNPnYJAYpdZlnYXBKyyx618-sAtNSzZNTRXENw4G8uo,4850
-yomemoai_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-yomemoai_mcp/server.py,sha256=3J-RLInsVz2ALTQV1YyAQti9mG7Y5YPfYXXO_sYprzg,2973
-yomemoai_mcp-0.1.0.dist-info/METADATA,sha256=04U52HSfVF9ODHRLU04tpkjp3m4BkllM_82EoZlvmbs,7032
-yomemoai_mcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-yomemoai_mcp-0.1.0.dist-info/entry_points.txt,sha256=gWU6hmHA4oQMCYGqffv-f2YamGj-ERq8np2uuCSOhuI,137
-yomemoai_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=UVt2r_C3iy7rNKJAj_EcLcmcZdXONxJ01oJNsIEqTfw,1066
-yomemoai_mcp-0.1.0.dist-info/RECORD,,