Python MCP Integration

YoMemo provides an out-of-the-box MCP server that enables AI assistants to save and retrieve encrypted memories. This is the easiest way to get started with YoMemo, especially if you’re using Claude Desktop, Cursor, or other MCP-compatible tools.

Video walkthrough (~50 seconds)

Watch the full flow: sign in at yomemo.ai, configure MCP in Cursor, add the system prompt, and test save_memory.

Steps in the video:

1. Sign in and get an API key — Open yomemo.ai, sign in with GitHub, email, or Google. Go to Settings in the left menu, then API Key. New users click Rotate Key to generate a new key.
2. Configure MCP in Cursor — In Cursor, add the YoMemo MCP server using your API key and the path to your private PEM file from the previous step, then enable it.
3. Copy the system prompt — Open github.com/yomemoai/yomemo-prompts and copy the system prompt (e.g. from system-v0.0.0.txt).
4. Add the prompt as a Cursor rule — Paste that system prompt into Cursor as a system rule so the AI can automatically call save_memory at the right moments.
5. Test save — In a Cursor chat, trigger a save (e.g. ask the AI to remember something), then open a new chat and use load_memories to confirm it worked.

Tip

The steps below give the same flow in more detail with exact config paths and JSON snippets.

Prerequisites

Before you begin, you need:

• Python 3.12 or higher
• uv package manager (recommended) or pip
• A YoMemoAI API key
• An RSA private key (PEM format)

Tip

Don’t have an API key yet? Sign up at YoMemoAI to get started.

Quick Start

1. Install the MCP Server

   The easiest way is to use uvx to run it directly without installation:

   uvx yomemoai-mcp --help

   Or install via pip:

   pip install yomemoai-mcp

2. Get Your RSA Key Pair and Register Your Public Key

   You need an RSA private key (PEM) for the MCP server, and the server must have your public key. We recommend creating the key pair locally (zero-trust); you can also generate it in the dashboard for a quick try.

   Follow the dedicated guide: Key Pairs (Public & Private) — it covers online vs. local generation, how to upload your public key if you generate locally, and security notes. Once you have private.pem and the public key is registered, continue below.

3. Configure Your MCP Client

   Add the MCP server configuration to your client. The configuration location depends on your tool:

   For Cursor

   Edit ~/.cursor/mcp.json (Windows: %APPDATA%\Cursor\User\mcp.json):

   {
     "mcpServers": {
       "yomemoai": {
         "command": "uvx",
         "args": ["yomemoai-mcp"],
         "env": {
           "MEMO_API_KEY": "your_api_key_here",
           "MEMO_PRIVATE_KEY_PATH": "/path/to/private.pem",
           "MEMO_BASE_URL": "https://api.yomemo.ai"
         }
       }
     }
   }

   For Claude Desktop

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

   {
     "mcpServers": {
       "yomemoai": {
         "command": "uvx",
         "args": ["yomemoai-mcp"],
         "env": {
           "MEMO_API_KEY": "your_api_key_here",
           "MEMO_PRIVATE_KEY_PATH": "/path/to/private.pem",
           "MEMO_BASE_URL": "https://api.yomemo.ai"
         }
       }
     }
   }

   Note

   Replace /path/to/private.pem with the absolute path to your private key. Use forward slashes on Windows too (e.g. C:/Users/You/private.pem).

4. Restart Your MCP Client

   After saving the configuration, restart Cursor or Claude Desktop for the changes to take effect.

5. Start Using YoMemo

   Once configured, you can use YoMemo in your AI assistant conversations:
   • Save memories: Ask your AI assistant to remember important information
   • Retrieve memories: Ask your AI assistant to recall previously saved information
   • Organize with handles: Use categories like “work”, “personal”, “project-x” to organize memories

Available MCP Tools

save_memory

Store important information, user preferences, or conversation context as a permanent encrypted memory. When you use the same idempotent_key with the same handle, the existing memory is updated (upsert) instead of creating a duplicate.

Parameters:

• content (required): The actual text/information to be remembered
• handle (optional): A category or tag (e.g., ‘work’, ‘personal’, ‘project-x’). Defaults to ‘general’
• description (optional): A brief summary of what this memory is about
• idempotent_key (optional): A stable key for upsert. If a memory with the same (handle, idempotent_key) already exists, it is updated; otherwise a new one is created. Use for project progress, habit tracking, or avoiding duplicate memories.

Example usage in Claude/Cursor:

"Please remember that my coffee machine password is 8888, with handle 'passwords'"

load_memories

Retrieve previously stored memories or context.

Parameters:

• handle (optional): Filter memories by category. If not specified, returns all memories

Example usage in Claude/Cursor:

"Can you recall my passwords?"

Configuration Options

Environment Variables

You can configure the MCP server using environment variables:

• MEMO_API_KEY (required): Your YoMemoAI API key for authentication
• MEMO_PRIVATE_KEY_PATH (required): Absolute path to your RSA private key PEM file
• MEMO_BASE_URL (optional): Base URL of the YoMemoAI API. Defaults to https://api.yomemo.ai

Using .env File (Local Development)

For local development, you can also use a .env file in your project directory:

.env

MEMO_API_KEY=your_api_key_here
MEMO_PRIVATE_KEY_PATH=./private.pem
MEMO_BASE_URL=https://api.yomemo.ai

Then run:

uv run memo-mcp

Caution

Never commit your .env file or private key files to version control. They are already included in .gitignore.

How It Works

The MCP integration works as a bridge between your AI assistant and the YoMemo backend:

1. On Write: When you ask your AI to save a memory:

   • The MCP server encrypts the content using your local private key (AES-GCM + RSA-OAEP)
   • Signs the encrypted data for integrity verification
   • Sends the encrypted data to the YoMemo API
   • The server only stores encrypted ciphertext and cannot see your plaintext

2. On Read: When you ask your AI to recall a memory:

   • The MCP server fetches encrypted data from YoMemo API
   • Decrypts it locally using your private key
   • Returns the plaintext to your AI assistant

Throughout the entire process, the YoMemo server only handles encrypted ciphertext and public keys, ensuring your data remains private.

Troubleshooting

MCP Server Not Starting

If the MCP server fails to start:

1. Check API Key: Verify your MEMO_API_KEY is correct

2. Check Private Key Path: Ensure the path is absolute and the file exists

3. Check Permissions: Make sure the private key file is readable (permissions 600 recommended)

4. Test Locally: Run the server directly to see error messages:

   MEMO_API_KEY="your_api_key" \
     MEMO_PRIVATE_KEY_PATH="/path/to/private.pem" \
     uvx yomemoai-mcp

Connection Issues

If you can’t connect to the YoMemo API:

• Verify MEMO_BASE_URL is correct (default: https://api.yomemo.ai)
• Check your internet connection
• Ensure your API key is valid and not expired

Decryption Errors

If you see decryption errors:

• Verify you’re using the correct private key (the one that matches the public key stored on the server)
• Check that the private key file is not corrupted
• Ensure the private key format is correct (PEM format)

Next Steps

• Learn about Go SDK integration for programmatic access
• Explore How It Works to understand the encryption architecture
• Check out the API reference for direct API access