Zymemory MCP Server

Official MCP server that gives Claude Desktop and Claude Code long-term memory powered by Zymemory.

What You Get

Give your AI assistant the ability to:

• Remember information across conversations
• Search past memories using natural language
• Link related memories in a knowledge graph
• Track conversation history automatically
• Isolate memories per user (multi-tenant)

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude connect to external tools and data sources. This server exposes Zymemory's memory API as MCP tools that Claude can use automatically.

In simple terms: Your conversations with Claude become persistent. Claude remembers what you told it yesterday, last week, or last month.

Quick Start

Prerequisites

• Python 3.8 or higher
• Claude Desktop or Claude Code installed
• Zymemory API credentials (get from heymaple.app)

Installation (5 minutes)

Step 1: Install Dependencies

pip install "mcp[cli]" zymemory

Step 2: Download the MCP Server

# Clone the repository
git clone https://github.com/ranjalii/zymemorymcp.git
cd zymemorymcp

Step 3: Get Your Credentials

Sign up at heymaple.app and get:

• Organisation API Key
• Organisation Email
• User Token (create a user if you don't have one)

Step 4: Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zymemory": {
      "command": "python3",
      "args": ["/path/to/zymemorymcp/zymemory_mcp_server.py"],
      "env": {
        "ZYMEMORY_API_KEY": "your-api-key",
        "ZYMEMORY_ORG_EMAIL": "your@email.com",
        "ZYMEMORY_USER_TOKEN": "your-user-token"
      }
    }
  }
}

Step 5: Restart Claude Desktop

Quit completely (Cmd + Q on Mac) and reopen.

Step 6: Test It!

Open Claude Desktop and say:

What memory tools do you have?

You should see tools like create_memory, search_memory, etc.

For Claude Code (CLI)

If you're using Claude Code, create ~/.claude/mcp_servers.json for global access or .claude/mcp_servers.json in your project:

{
  "mcpServers": {
    "zymemory": {
      "command": "python3",
      "args": ["/path/to/zymemorymcp/zymemory_mcp_server.py"],
      "env": {
        "ZYMEMORY_API_KEY": "your-api-key",
        "ZYMEMORY_ORG_EMAIL": "your@email.com",
        "ZYMEMORY_USER_TOKEN": "your-user-token"
      }
    }
  }
}

Restart your Claude Code session.

Tools Reference

1. create_memory

Purpose: Store new information in the knowledge graph

Parameters:

• content (string, required): The information to remember
• auto_merge (boolean, optional): Auto-merge with similar memories
• user_token (string, optional): User-specific token

Returns: Success message with memory ID

Example:

User: Remember that I prefer dark roast coffee
Claude: [Calls create_memory("User prefers dark roast coffee")]
→ "Successfully created memory #42: 'User prefers dark roast coffee'"

2. search_memory

Purpose: Find relevant memories using natural language

Parameters:

• query (string, required): Natural language search query
• top_k (integer, optional, default: 10): Number of results
• user_token (string, optional): User-specific token

Returns: Formatted search results with memories and conversations

Example:

User: What do you know about my food preferences?
Claude: [Calls search_memory("food preferences", top_k=10)]
→ Returns:
   Search results for: 'food preferences'

   === Structured Memories (3) ===
   1. [ID: 42] User prefers dark roast coffee
      Keywords: coffee, preference, morning
   2. [ID: 45] User is allergic to shellfish
      Keywords: allergy, food, health
   ...

3. list_all_memories

Purpose: List all user memories with pagination

Parameters:

• page (integer, optional, default: 1): Page number
• page_size (integer, optional, default: 20): Items per page
• user_token (string, optional): User-specific token

Returns: Formatted list of all memories

4. get_memory

Purpose: Get detailed information about a specific memory

Parameters:

• memory_id (integer, required): ID of the memory
• user_token (string, optional): User-specific token

Returns: Detailed memory information

5. delete_memory

Purpose: Permanently remove a memory

Parameters:

• memory_id (integer, required): ID of the memory to delete
• user_token (string, optional): User-specific token

Returns: Success message

6. edit_memory

Purpose: Update an existing memory (creates new version)

Parameters:

• memory_id (integer, required): ID of the memory to edit
• repr_data (object, required): New representation data
• full_rewrite (boolean, optional, default: false): Replace vs merge
• user_token (string, optional): User-specific token

Returns: Success message with new version number

7. store_conversation

Purpose: Save a conversation turn for automatic clustering

Parameters:

• user_input (string, required): User's message
• assistant_output (string, required): Assistant's response
• user_token (string, optional): User-specific token

Returns: Success message

8. create_memory_link

Purpose: Link two related memories in knowledge graph

Parameters:

• source_id (integer, required): Source memory ID
• destination_id (integer, required): Destination memory ID
• user_token (string, optional): User-specific token

Returns: Success message

9. register_user

Purpose: Create a new user in the system (multi-tenant)

Parameters:

• external_id (string, required): Your system's user ID
• name (string, required): User's display name
• email (string, optional): User's email address

Returns: Success message with user token

What's Included

This MCP server is a complete, ready-to-use solution. It includes:

No customisation needed - Just install, configure your credentials, and start using!

For Non-MCP Use Cases

If you're building an application that doesn't use Claude Desktop/Code, use the Zymemory Python SDK directly instead of this MCP server:

from zymemory import ZymemoryClient

client = ZymemoryClient(api_key="...", org_email="...", user_token="...")

# Full SDK access
memory = client.create_memory("Your data")
results = client.search("your query", top_k=10)
links = client.get_memory_radius(memory_id=1, depth=2)
# ... and more

See the Zymemory SDK documentation for non-MCP integrations.

Debugging

View Server Logs

Claude Desktop logs appear in:

# macOS
~/Library/Logs/Claude/

# View logs in real-time
tail -f ~/Library/Logs/Claude/mcp*.log

Test Server Standalone

# Set credentials
export ZYMEMORY_API_KEY="your-key"
export ZYMEMORY_ORG_EMAIL="your@email.com"
export ZYMEMORY_USER_TOKEN="your-token"

# Run test suite
python3 test_zymemory_mcp.py

Use MCP Inspector

Interactive testing tool:

npx @modelcontextprotocol/inspector python3 zymemory_mcp_server.py

Security Best Practices

1. Never commit credentials to version control
2. Use environment variables for API keys
3. Isolate per user with user_token parameter
4. Validate inputs before passing to API
5. Handle errors gracefully with user-friendly messages

Multi-Tenant Support

Each user gets isolated memories:

# User A's space
create_memory("A's data", user_token="token_a")

# User B's space
create_memory("B's data", user_token="token_b")

# Searches are isolated
search_memory("data", user_token="token_a")  # Only A's memories
search_memory("data", user_token="token_b")  # Only B's memories

Troubleshooting

Server Won't Start

Problem: ModuleNotFoundError: No module named 'mcp'

Solution: Install MCP library in the correct Python:

/Library/Frameworks/Python.framework/Versions/3.14/bin/python3 -m pip install "mcp[cli]" zymemory

Claude Can't See Tools

Problem: Claude says "I don't have access to memory tools"

Solutions:

1. Verify config file syntax is valid JSON
2. Check Python path in config is correct
3. Completely restart Claude Desktop (Cmd + Q)
4. Check logs: ~/Library/Logs/Claude/

Authentication Errors

Problem: "Invalid API credentials"

Solution: Verify credentials in config match your Zymemory account.

No Memories Found

Problem: Search returns empty results

Solutions:

1. Create some memories first: create_memory("test")
2. Check you're using the right user_token
3. Wait for conversation clustering (takes a few minutes)

Performance Considerations

Tool Call Latency

Typical latency for each operation:

• create_memory: 200-500ms
• search_memory: 300-800ms
• list_all_memories: 150-400ms
• delete_memory: 100-300ms

Optimisation Tips

1. Batch operations: Create multiple memories in sequence
2. Use pagination: Don't fetch all memories at once
3. Cache results: Claude caches tool results during a conversation
4. Limit top_k: Use reasonable top_k values (5-10) for search

Performance & Limits

Typical Response Times:

• Create/Delete: 100-500ms
• Search: 300-800ms
• List: 150-400ms

Rate Limits:

• Free tier: 100 requests/minute
• Pro tier: 1000 requests/minute

The server automatically handles rate limits.

Resources & Links

• MCP Server GitHub: github.com/ranjalii/zymemorymcp
• MCP Protocol: modelcontextprotocol.io
• Zymemory API: heymaple.app
• Zymemory SDK: github.com/ranjalii/zymemory
• Support: contact@heymaple.app

Support & Feedback

Reporting Issues

Found a bug or have a question? Contact us:

Email: contact@heymaple.app

When reporting issues, please include:

• Error message (from Claude or logs)
• Your setup (macOS/Windows/Linux, Claude Desktop/Code version)
• Steps to reproduce

We'll help you get it working!

Feature Requests

Have an idea for a new feature? Let us know! We're always looking to improve the MCP server.

Note: This is a maintained product - we handle updates and improvements. You don't need to modify the code.

Licence

This MCP server is provided by Zymemory for use with the Zymemory API service. See your Zymemory service agreement for terms of use.