yomemoai-mcp 0.1.0__py3-none-any.whl

yomemoai_mcp/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from yomemoai-mcp!"

yomemoai_mcp/client.py

@@ -0,0 +1,131 @@
+import base64
+import json
+import time
+import requests
+from typing import Dict, List, Optional, Tuple
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.backends import default_backend
+import os
+
+
+class MemoClient:
+    """
+    Client for yomemoai API
+    It's a wrapper for the yomemoai API.
+    """
+
+    def __init__(self, api_key: str, private_key_pem: str, base_url: str):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.private_key = serialization.load_pem_private_key(
+            self._normalize_pem(private_key_pem),
+            password=None,
+            backend=default_backend()
+        )
+        self.public_key = self.private_key.public_key()
+        self.session = requests.Session()
+        self.session.headers.update(
+            {"X-Memo-API-Key": self.api_key, "Content-Type": "application/json"})
+
+    def _normalize_pem(self, pem_str: str) -> bytes:
+        pem_str = pem_str.strip()
+        if "-----BEGIN" not in pem_str:
+            return f"-----BEGIN PRIVATE KEY-----\n{pem_str}\n-----END PRIVATE KEY-----".encode()
+        return pem_str.encode()
+
+    def pack_data(self, raw_data: bytes) -> str:
+        aes_key = os.urandom(32)
+        nonce = os.urandom(12)
+
+        cipher = Cipher(algorithms.AES(aes_key), modes.GCM(
+            nonce), backend=default_backend())
+        encryptor = cipher.encryptor()
+        ciphertext = encryptor.update(raw_data) + encryptor.finalize()
+
+        combined_data = base64.b64encode(
+            nonce + ciphertext + encryptor.tag).decode('utf-8')
+
+        encrypted_key = self.public_key.encrypt(
+            aes_key,
+            padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                         algorithm=hashes.SHA256(), label=None)
+        )
+        key_base64 = base64.b64encode(encrypted_key).decode('utf-8')
+
+        signature = self.private_key.sign(
+            combined_data.encode('utf-8'),
+            padding.PKCS1v15(),
+            hashes.SHA256()
+        )
+        sig_base64 = base64.b64encode(signature).decode('utf-8')
+
+        pkg = {
+            "data": combined_data,
+            "key": key_base64,
+            "signature": sig_base64
+        }
+        return base64.b64encode(json.dumps(pkg).encode()).decode()
+
+    def unpack_and_decrypt(self, encrypted_pkg_base64: str) -> bytes:
+        pkg_json = base64.b64decode(encrypted_pkg_base64)
+        pkg = json.loads(pkg_json)
+
+        if "key" in pkg and pkg["key"]:
+            encrypted_key = base64.b64decode(pkg["key"])
+            aes_key = self.private_key.decrypt(
+                encrypted_key,
+                padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                             algorithm=hashes.SHA256(), label=None)
+            )
+
+            combined_data = base64.b64decode(pkg["data"])
+            nonce = combined_data[:12]
+            tag = combined_data[-16:]
+            ciphertext = combined_data[12:-16]
+
+            cipher = Cipher(algorithms.AES(aes_key), modes.GCM(
+                nonce, tag), backend=default_backend())
+            decryptor = cipher.decryptor()
+            return decryptor.update(ciphertext) + decryptor.finalize()
+        else:
+            data = base64.b64decode(pkg["data"])
+            return self.private_key.decrypt(
+                data,
+                padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                             algorithm=hashes.SHA256(), label=None)
+            )
+
+    def add_memory(self, content: str, handle: str = "", description: str = "", metadata: Dict = None):
+        token_size = len(content)
+
+        packed = self.pack_data(content.encode('utf-8'))
+        payload = {
+            "ciphertext": packed,
+            "description": description,
+            "handle": handle,
+            "metadata": metadata or {
+                "token_size": token_size,
+                "from": "yomemoai-mcp",
+            }
+        }
+        resp = self.session.post(
+            f"{self.base_url}/api/v1/memory", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_memories(self, handle: Optional[str] = None) -> List[Dict]:
+        url = f"{self.base_url}/api/v1/memory"
+        params = {"handle": handle} if handle else {}
+        resp = self.session.get(url, params=params)
+        resp.raise_for_status()
+
+        memories = resp.json().get("data", [])
+        for m in memories:
+            try:
+                decrypted = self.unpack_and_decrypt(m["content"])
+                m["content"] = decrypted.decode('utf-8')
+            except Exception as e:
+                print(f"Decryption failed for {m.get('id')}: {e}")
+        return memories

yomemoai_mcp/server.py

@@ -0,0 +1,80 @@
+import asyncio
+from mcp.server.fastmcp import FastMCP
+from .client import MemoClient
+import os
+
+from dotenv import load_dotenv
+load_dotenv()
+
+mcp = FastMCP("yomemoai")
+
+API_KEY = os.getenv("MEMO_API_KEY", "")
+PRIV_KEY_PATH = os.getenv("MEMO_PRIVATE_KEY_PATH", "private.pem")
+BASE_URL = os.getenv("MEMO_BASE_URL", "https://api.yomemo.ai")
+
+if not API_KEY:
+    raise ValueError("MEMO_API_KEY environment variable is required")
+
+if not os.path.exists(PRIV_KEY_PATH):
+    raise FileNotFoundError(
+        f"Private key file not found: {PRIV_KEY_PATH}. "
+        f"Please set MEMO_PRIVATE_KEY_PATH environment variable or place your private key at {PRIV_KEY_PATH}"
+    )
+
+try:
+    with open(PRIV_KEY_PATH, "r") as f:
+        private_pem = f.read()
+except Exception as e:
+    raise IOError(f"Failed to read private key from {PRIV_KEY_PATH}: {e}")
+
+if not private_pem.strip():
+    raise ValueError(f"Private key file {PRIV_KEY_PATH} is empty")
+
+client = MemoClient(API_KEY, private_pem, BASE_URL)
+
+
+@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.
+
+    :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.
+    """
+    try:
+        result = client.add_memory(
+            content, handle=handle, description=description)
+        return f"Successfully archived in memory. ID: {result.get('memory_id')}"
+    except Exception as e:
+        return f"Failed to save memory: {str(e)}"
+
+
+@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.
+
+    :param handle: Optional filter. If the user specifies a category (e.g., 'about my job'), 
+                   extract and provide the relevant handle.
+    """
+    try:
+        memories = client.get_memories(handle=handle)
+        if not memories:
+            return f"No memories found under the handle: {handle if handle else 'all'}."
+
+        output = ["### Retrieved Memories:"]
+        for m in memories:
+            timestamp = m.get('created_at', 'N/A')
+            output.append(
+                f"Handle: [{m.get('handle')}]\nContent: {m.get('content')}\n---"
+            )
+        return "\n".join(output)
+    except Exception as e:
+        return f"Error retrieving memories: {str(e)}"
+
+if __name__ == "__main__":
+    mcp.run()

yomemoai_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: yomemoai-mcp
+Version: 0.1.0
+Summary: Model Context Protocol (MCP) server for YoMemoAI - enables AI assistants to save and retrieve encrypted memories
+Author-email: lvxiangxiang <lvxiangxiang@shopline.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,cursor,mcp,mcp-server,memory,yomemoai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=46.0.3
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: mcp>=1.25.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+# yomemoai-mcp
+
+A Model Context Protocol (MCP) server for YoMemoAI, enabling AI assistants to save and retrieve encrypted memories.
+
+## Features
+
+- 🔐 **Secure Storage**: Encrypted memory storage using RSA-OAEP and AES-GCM
+- 🏷️ **Categorization**: Organize memories with handles (tags/categories)
+- 🔍 **Retrieval**: Query memories by handle or retrieve all memories
+- 🚀 **MCP Integration**: Seamlessly integrates with MCP-compatible AI assistants
+
+## Prerequisites
+
+- Python 3.12 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+- YoMemoAI API key
+- RSA private key (PEM format)
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone <repository-url>
+cd yomemoai-mcp
+```
+
+2. Install dependencies using uv:
+
+```bash
+uv sync
+```
+
+## Configuration
+
+Create a `.env` file in the project root with the following configuration:
+
+```bash
+# YoMemoAI MCP Server Configuration
+
+# Your API key from YoMemoAI (required)
+MEMO_API_KEY=your_api_key_here
+
+# Path to your private key file (RSA private key in PEM format)
+# Default: private.pem
+MEMO_PRIVATE_KEY_PATH=private.pem
+
+# Base URL of the YoMemoAI API (optional)
+# Default: https://api.yomemo.ai
+MEMO_BASE_URL=https://api.yomemo.ai
+```
+
+**Important Configuration Notes:**
+
+1. **MEMO_API_KEY** (required): Your YoMemoAI API key. You must obtain this from your YoMemoAI account.
+
+2. **MEMO_PRIVATE_KEY_PATH**: Path to your RSA private key file. The private key should be in PEM format:
+
+   ```
+   -----BEGIN PRIVATE KEY-----
+   ...
+   -----END PRIVATE KEY-----
+   ```
+
+   Make sure this file is secure and never commit it to version control.
+
+3. **MEMO_BASE_URL** (optional): The API base URL. Defaults to `https://api.yomemo.ai` if not specified.
+
+## Usage
+
+### Running the MCP Server
+
+After configuration, you can run the MCP server using:
+
+```bash
+uv run memo-mcp
+```
+
+### Integration with Cursor/Claude Desktop
+
+Add the following configuration to your MCP settings file:
+
+**For Cursor**: `~/.cursor/mcp.json` (or `%APPDATA%\Cursor\User\mcp.json` on Windows)  
+**For Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+#### Option 1: Using `uvx` (Recommended - after publishing to PyPI)
+
+If the package is published to PyPI, you can use `uvx` to run it directly. The package provides multiple entry points:
+
+**Using `uvx yomemoai-mcp`** (recommended):
+
+```json
+{
+  "mcpServers": {
+    "yomemoai": {
+      "command": "uvx",
+      "args": ["yomemoai-mcp"],
+      "env": {
+        "MEMO_API_KEY": "your_api_key_here",
+        "MEMO_PRIVATE_KEY_PATH": "/absolute/path/to/private.pem",
+        "MEMO_BASE_URL": "https://api.yomemo.ai"
+      }
+    }
+  }
+}
+```
+
+**How `uvx` works:**
+
+- `uvx` automatically downloads the package from PyPI (if not already installed)
+- It runs the package's entry point script defined in `project.scripts`
+- The package name is `yomemoai-mcp`, so `uvx yomemoai-mcp` will automatically use the `yomemoai-mcp` entry point
+- The package also provides alternative entry points: `yomemo` and `memo-mcp` (all point to the same server)
+
+**Note**: The package must be published to PyPI before using `uvx`. If the package is not yet published, use Option 2 for local development.
+
+#### Option 2: Using local development setup
+
+For local development or if the package is not yet published, use the `uv --directory` approach:
+
+```json
+{
+  "mcpServers": {
+    "yomemoai": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/yomemoai-mcp",
+        "run",
+        "yomemoai-mcp"
+      ],
+      "env": {
+        "MEMO_API_KEY": "your_api_key_here",
+        "MEMO_PRIVATE_KEY_PATH": "/absolute/path/to/private.pem",
+        "MEMO_BASE_URL": "https://api.yomemo.ai"
+      }
+    }
+  }
+}
+```
+
+**Important Notes:**
+
+- **For Option 1 (`uvx`)**: The package must be published to PyPI. `uvx` will automatically handle installation and execution.
+- **For Option 2 (local)**: Replace `/absolute/path/to/yomemoai-mcp` with the **absolute path** to this repository on your system
+- Replace `/absolute/path/to/private.pem` with the **absolute path** to your private key file
+- The `env` section in the MCP config will override any `.env` file in the project directory
+- After updating the MCP config, restart Cursor/Claude Desktop for changes to take effect
+
+### Available Tools
+
+#### `save_memory`
+
+Store important information, user preferences, or conversation context as a permanent memory.
+
+**Parameters:**
+
+- `content` (required): The actual text/information to be remembered
+- `handle` (optional): A short, unique category or tag (e.g., 'work', 'personal', 'project-x'). Defaults to 'general'
+- `description` (optional): A brief summary of what this memory is about
+
+#### `load_memories`
+
+Retrieve previously stored memories or context.
+
+**Parameters:**
+
+- `handle` (optional): Filter memories by category. If not specified, returns all memories
+
+## Development
+
+### Project Structure
+
+```
+yomemoai-mcp/
+├── src/
+│   └── yomemoai_mcp/
+│       ├── __init__.py
+│       ├── server.py      # MCP server implementation
+│       ├── client.py      # YoMemoAI API client
+│       └── py.typed       # Type hints marker
+├── pyproject.toml         # Project configuration
+├── uv.lock                # Dependency lock file
+└── README.md
+```
+
+### Dependencies
+
+- `cryptography`: For encryption/decryption operations
+- `fastmcp`: FastMCP framework for MCP servers
+- `mcp`: Model Context Protocol SDK
+- `python-dotenv`: Environment variable management
+- `requests`: HTTP client for API calls
+
+## Security Notes
+
+- **Never commit** your `.env` file or private key files to version control
+- Keep your private key secure and never share it
+- The `.env` file is already included in `.gitignore`
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+[Add contribution guidelines here]
+
+## Support
+
+For issues and questions, please open an issue on the repository.

yomemoai_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+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,,

yomemoai_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

yomemoai_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[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/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yomemo.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.