Skip to content

OVERVIEW.md

Latest commit

 

History

History
260 lines (192 loc) · 12.4 KB

OVERVIEW.md

File metadata and controls

260 lines (192 loc) · 12.4 KB

Mem0 Logo

@pinkpixel/mem0-mcp Project Overview ✨

Current Version: 0.6.1 Last Updated: 2025-05-28T06:52:15.847Z

Project Summary

@pinkpixel/mem0-mcp is a Model Context Protocol (MCP) server that integrates with Mem0.ai to provide persistent memory capabilities for Large Language Models (LLMs). It allows AI agents to store and retrieve information across sessions, enhancing their ability to maintain context and remember important information.

Purpose

The primary purpose of this project is to bridge the gap between LLMs and persistent memory storage. LLMs typically have limited context windows and no built-in ability to remember information across sessions. This MCP server solves that problem by providing tools that allow LLMs to:

  1. Store important information as memories
  2. Search for relevant memories based on semantic similarity
  3. Delete specific memories when they're no longer needed

Architecture

The project follows a simple architecture:

  1. MCP Server Layer: Implements the Model Context Protocol using the @modelcontextprotocol/sdk package
  2. Memory Management Layer: Interfaces with Mem0.ai's API for cloud storage or uses local in-memory storage
  3. Tool Handlers: Implements the functionality for adding, searching, and deleting memories

Key Components

  • Mem0MCPServer Class: The main class that initializes the server, sets up tool handlers, and implements the core functionality
  • SafeLogger Class: An innovative utility class that selectively redirects console.log calls from the mem0ai library to stderr without disrupting MCP protocol communication. This solves a critical issue where library output could break the MCP protocol.
  • Tool Handlers: Functions that handle the add_memory, search_memory, and delete_memory tools with comprehensive error handling
  • Configuration Generator: A sophisticated 403-line bash script with colorful ASCII art, interactive menus, and multiple configuration options
  • Dynamic Client Initialization: Smart detection of available API keys to automatically choose between cloud and local storage modes

Storage Modes

The server supports three storage modes:

  1. Cloud Storage Mode ☁️ (Recommended for production)

    • Uses Mem0's hosted API with a MEM0_API_KEY environment variable
    • Memories are persistently stored on Mem0's cloud servers
    • No local database needed
    • Supports additional features like filtering, thresholds, and metadata

  2. Supabase Storage Mode 🗄️ (Recommended for self-hosting)

    • Uses Supabase PostgreSQL with pgvector for persistent storage
    • Requires SUPABASE_URL, SUPABASE_KEY, and OPENAI_API_KEY environment variables
    • Free tier available, self-hostable, with SQL access and vector search
    • Comprehensive setup documentation with SQL migrations provided

  3. Local Storage Mode 💾 (Development/testing only)

    • Uses in-memory storage with an OPENAI_API_KEY environment variable for embeddings
    • Memories are stored in an in-memory vector database (non-persistent by default)
    • Data is lost when the server restarts unless configured for persistent storage
    • Useful for development or testing purposes

Tools Provided

The server provides three main tools:

  1. add_memory: Stores a piece of text as a memory in Mem0

    • Required parameters: content
    • Optional parameters: userId, sessionId, agentId, appId, metadata
    • Advanced parameters: includes, excludes, infer, outputFormat, customCategories, customInstructions, immutable, expirationDate

  2. search_memory: Searches for memories based on a query

    • Required parameters: query
    • Optional parameters: userId, sessionId, agentId, appId, filters, threshold
    • Advanced parameters: topK, fields, rerank, keywordSearch, filterMemories

  3. delete_memory: Deletes a specific memory by ID

    • Required parameters: memoryId
    • Optional parameters: userId, agentId, appId

Dependencies

The project has the following key dependencies:

  • @modelcontextprotocol/sdk (1.12.0): For implementing the MCP server
  • mem0ai (^2.1.27): The Node.js SDK for Mem0.ai

Development dependencies:

  • @types/node (^22.15.23): TypeScript type definitions for Node.js
  • typescript (^5.8.3): For TypeScript compilation

File Structure

mem0-mcp/
├── src/
│   └── index.ts         # Main TypeScript file implementing the MCP server (853 lines)
├── build/               # Compiled JavaScript files (generated)
├── vsce/                # VS Code extension files (if applicable)
├── config_generator.sh  # Interactive bash script for MCP configuration
├── package.json         # Project metadata and dependencies
├── package-lock.json    # Dependency lock file
├── tsconfig.json        # TypeScript configuration
├── mem0-logo.svg        # Project logo
├── README.md            # Comprehensive project documentation (548 lines)
├── CHANGELOG.md         # Detailed version history and changes (256 lines)
├── CONTRIBUTING.md      # Guidelines for contributing to the project
├── LICENSE              # MIT License
└── OVERVIEW.md          # This file - project overview

Installation & Usage

The server can be installed and used in two main ways:

  1. Using npx (Recommended for quick use)

    • Install globally: npm install -g @pinkpixel/mem0-mcp
    • Configure MCP client to run the server using npx

  2. Running from Cloned Repository

    • Clone the repository: git clone https://github.com/pinkpixel-dev/mem0-mcp
    • Install dependencies: npm install
    • Build the server: npm run build
    • Configure MCP client to run the built script directly using node

Configuration

The server requires configuration in the MCP client's configuration file (e.g., mcp.json). The configuration includes:

  • Command and arguments to run the server
  • Environment variables for API keys and default user ID
  • Tool permissions

Interactive Configuration Generator

The project includes a sophisticated bash script (config_generator.sh) that provides an interactive menu for:

  • 🔧 Generating mcp.json configurations with guided setup
  • 📖 Viewing README.md documentation
  • 🔄 Restarting the Mem0-MCP server with environment variables
  • 🎨 Colorful ASCII banner and styled output
  • 💾 Multiple save options (Cursor IDE, custom file, clipboard)
  • ⚙️ Support for both installation methods (local build vs npm package)

Example configuration for cloud storage mode:

{
  "mcpServers": {
    "mem0-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@pinkpixel/mem0-mcp"
      ],
      "env": {
        "MEM0_API_KEY": "YOUR_MEM0_API_KEY_HERE",
        "DEFAULT_USER_ID": "user123",
        "DEFAULT_AGENT_ID": "your-agent-id",
        "DEFAULT_APP_ID": "your-app-id"
      },
      "disabled": false,
      "alwaysAllow": [
        "add_memory",
        "search_memory"
      ]
    }
  }
}

Development

For development:

  1. Clone the repository: git clone https://github.com/pinkpixel-dev/mem0-mcp
  2. Install dependencies: npm install
  3. Build the server: npm run build
  4. For auto-rebuild on file changes: npm run watch
  5. For debugging: npm run inspector

Technical Challenges & Solutions

MCP Protocol Communication

Challenge: MCP servers communicate over stdout, and any libraries or code that writes to stdout may interfere with the protocol.

Solution: The project implements an innovative SafeLogger class that:

  • Intercepts console.log calls and examines stack traces to determine source
  • Only redirects log calls from mem0ai library or project code to stderr
  • Preserves clean stdout for MCP protocol communication
  • Automatically cleans up resources on process exit

Storage Mode Selection

Challenge: Supporting both cloud and local storage modes with different requirements and capabilities.

Solution: The server dynamically selects the storage mode based on available environment variables and initializes the appropriate client using dynamic imports to handle TypeScript compatibility issues.

Memory Deletion Complexity

Challenge: The mem0ai library doesn't expose consistent delete methods across cloud and local modes.

Solution: Implements fallback strategies using direct API calls for cloud mode and accessing internal vectorstore methods for local mode, with proper error handling for unsupported operations.

Parameter Handling Evolution (v0.5.0)

Challenge: Critical issues with organization and project ID parameters not working properly, and incorrect parameter usage.

Solution: Major breaking change in v0.5.0 that:

  • BREAKING CHANGE: Replaced incorrect orgId/projectId parameters with correct Mem0 API parameters
  • New Parameter Mapping: agentId (LLM identifier), userId (user), appId (project scope), sessionId (session tracking)
  • Root Cause Fix: org_id and project_id are auto-assigned by Mem0 and cannot be changed by users
  • Correct Scope Control: app_id is what actually controls the user's project scope in Mem0
  • Enhanced Environment Fallbacks: Added DEFAULT_AGENT_ID and DEFAULT_APP_ID environment variables
  • API Compliance: Now uses correct Mem0 API parameters instead of non-functional org/project IDs

Current Status & Quality Assessment

Project Maturity

This is a production-ready, high-quality MCP server that demonstrates excellent software engineering practices:

✅ Comprehensive Documentation: 548-line README with multiple installation methods, configuration examples, and troubleshooting ✅ Active Maintenance: Regular updates addressing security vulnerabilities and user feedback ✅ Innovative Technical Solutions: SafeLogger class solving MCP protocol compatibility issues ✅ Robust Error Handling: Comprehensive try-catch blocks with detailed error messages ✅ Security Conscious: Recent updates addressing CVEs in axios and undici dependencies ✅ User-Focused: Environment variable fallbacks and multiple installation methods for ease of use

Recent Improvements (v0.5.0-0.6.1)

  • 🚀 NEW FEATURE (v0.6.0-0.6.1): Added Supabase as a third storage option with persistent storage, free tier, and self-hosting capabilities
  • 🗄️ Supabase Integration: Full vector search with pgvector, SQL access, and comprehensive setup documentation
  • 🎯 BREAKING CHANGE: Fixed incorrect parameter implementation by replacing orgId/projectId with correct agentId/appId parameters
  • 🔧 Root Cause Resolution: Addressed fundamental misunderstanding of Mem0 API parameter usage
  • ✅ Parameter Functionality Confirmed: app_id and run_id parameters now working correctly (v0.5.4)
  • 📊 Dashboard Integration: Parameters appear in Mem0 dashboard Event Details as expected
  • 📝 Enhanced Documentation: Comprehensive parameter configuration guide with system prompt recommendations
  • 🚀 Improved API Compliance: Now uses correct Mem0 API parameters for proper project scoping
  • 🛡️ Security updates addressing high-severity vulnerabilities

Minor Areas for Enhancement

  • Testing Framework: Could benefit from unit and integration tests
  • Batch Operations: Potential for batch memory operations for efficiency
  • Monitoring & Analytics: Could add comprehensive logging and usage analytics

Future Improvements

Potential areas for future improvement include:

  1. Advanced Filtering: Expand support for more complex filtering options and search capabilities
  2. Batch Operations: Implement batch operations for adding or deleting multiple memories efficiently
  3. Memory Versioning: Add support for memory versioning and history tracking
  4. Enhanced Error Handling: Improve error handling and recovery mechanisms with more detailed error messages
  5. Monitoring & Analytics: Add comprehensive logging, monitoring, and usage analytics capabilities
  6. Performance Optimization: Optimize memory search performance and implement caching strategies
  7. Testing Framework: Add comprehensive unit and integration tests
  8. Documentation: Expand API documentation with more examples and use cases

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by Pink Pixel