MCP Memory Service

local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

  • Mentioned as a potential cloud storage option where users should ensure sync is complete before accessing from another device.

MCP Memory Service

An MCP server providing semantic memory and persistent storage capabilities for Claude Desktop using ChromaDB and sentence transformers. This service enables long-term memory storage with semantic search capabilities, making it ideal for maintaining context across conversations and instances.

Features

  • Semantic search using sentence transformers
  • Natural language time-based recall (e.g., "last week", "yesterday morning")
  • Tag-based memory retrieval system
  • Persistent storage using ChromaDB
  • Automatic database backups
  • Memory optimization tools
  • Exact match retrieval
  • Debug mode for similarity analysis
  • Database health monitoring
  • Duplicate detection and cleanup
  • Customizable embedding model
  • Cross-platform compatibility (Apple Silicon, Intel, Windows, Linux)
  • Hardware-aware optimizations for different environments
  • Graceful fallbacks for limited hardware resources

Quick Start

For the fastest way to get started:

# Install UV if not already installed pip install uv # Clone and install git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -r requirements.txt uv pip install -e . # Run the service uv run memory

Docker and Smithery Integration

Docker Usage

The service can be run in a Docker container for better isolation and deployment:

# Build the Docker image docker build -t mcp-memory-service . # Run the container # Note: On macOS, paths must be within Docker's allowed file sharing locations # Default allowed locations include: # - /Users # - /Volumes # - /private # - /tmp # - /var/folders # Example with proper macOS paths: docker run -it \ -v $HOME/mcp-memory/chroma_db:/app/chroma_db \ -v $HOME/mcp-memory/backups:/app/backups \ mcp-memory-service # For production use, you might want to run it in detached mode: docker run -d \ -v $HOME/mcp-memory/chroma_db:/app/chroma_db \ -v $HOME/mcp-memory/backups:/app/backups \ --name mcp-memory \ mcp-memory-service

To configure Docker's file sharing on macOS:

  1. Open Docker Desktop
  2. Go to Settings (Preferences)
  3. Navigate to Resources -> File Sharing
  4. Add any additional paths you need to share
  5. Click "Apply & Restart"

Smithery Integration

The service is configured for Smithery integration through smithery.yaml. This configuration enables stdio-based communication with MCP clients like Claude Desktop.

To use with Smithery:

  1. Ensure your claude_desktop_config.json points to the correct paths:
{ "memory": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "$HOME/mcp-memory/chroma_db:/app/chroma_db", "-v", "$HOME/mcp-memory/backups:/app/backups", "mcp-memory-service" ], "env": { "MCP_MEMORY_CHROMA_PATH": "/app/chroma_db", "MCP_MEMORY_BACKUPS_PATH": "/app/backups" } } }
  1. The smithery.yaml configuration handles stdio communication and environment setup automatically.

Testing with Claude Desktop

To verify your Docker-based memory service is working correctly with Claude Desktop:

  1. Build the Docker image with docker build -t mcp-memory-service .
  2. Create the necessary directories for persistent storage:
    mkdir -p $HOME/mcp-memory/chroma_db $HOME/mcp-memory/backups
  3. Update your Claude Desktop configuration file:
    • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • On Windows: %APPDATA%\Claude\claude_desktop_config.json
    • On Linux: ~/.config/Claude/claude_desktop_config.json
  4. Restart Claude Desktop
  5. When Claude starts up, you should see the memory service initialize with a message:
    MCP Memory Service initialization completed
  6. Test the memory feature:
    • Ask Claude to remember something: "Please remember that my favorite color is blue"
    • Later in the conversation or in a new conversation, ask: "What is my favorite color?"
    • Claude should retrieve the information from the memory service

If you experience any issues:

  • Check the Claude Desktop console for error messages
  • Verify Docker has the necessary permissions to access the mounted directories
  • Ensure the Docker container is running with the correct parameters
  • Try running the container manually to see any error output

For detailed installation instructions, platform-specific guides, and troubleshooting, see our documentation:

Configuration

Add the following to your claude_desktop_config.json file to use UV (recommended for best performance):

{ "memory": { "command": "uv", "args": [ "--directory", "your_mcp_memory_service_directory", // e.g., "C:\\REPOSITORIES\\mcp-memory-service" "run", "memory" ], "env": { "MCP_MEMORY_CHROMA_PATH": "your_chroma_db_path", // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\chroma_db" "MCP_MEMORY_BACKUPS_PATH": "your_backups_path" // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\backups" } } }

For Windows users, we recommend using the wrapper script to ensure PyTorch is properly installed. See our Windows Setup Guide for detailed instructions.

{ "memory": { "command": "python", "args": [ "C:\\path\\to\\mcp-memory-service\\memory_wrapper.py" ], "env": { "MCP_MEMORY_CHROMA_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\chroma_db", "MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\backups" } } }

The wrapper script will:

  1. Check if PyTorch is installed and properly configured
  2. Install PyTorch with the correct index URL if needed
  3. Run the memory server with the appropriate configuration

Hardware Compatibility

PlatformArchitectureAcceleratorStatus
macOSApple Silicon (M1/M2/M3)MPS✅ Fully supported
macOSApple Silicon under Rosetta 2CPU✅ Supported with fallbacks
macOSIntelCPU✅ Fully supported
Windowsx86_64CUDA✅ Fully supported
Windowsx86_64DirectML✅ Supported
Windowsx86_64CPU✅ Supported with fallbacks
Linuxx86_64CUDA✅ Fully supported
Linuxx86_64ROCm✅ Supported
Linuxx86_64CPU✅ Supported with fallbacks
LinuxARM64CPU✅ Supported with fallbacks

Memory Operations

The memory service provides the following operations through the MCP server:

Core Memory Operations

  1. store_memory - Store new information with optional tags
  2. retrieve_memory - Perform semantic search for relevant memories
  3. recall_memory - Retrieve memories using natural language time expressions
  4. search_by_tag - Find memories using specific tags
  5. exact_match_retrieve - Find memories with exact content match
  6. debug_retrieve - Retrieve memories with similarity scores

For detailed information about tag storage and management, see our Tag Storage Documentation.

Database Management

  1. create_backup - Create database backup
  2. get_stats - Get memory statistics
  3. optimize_db - Optimize database performance
  4. check_database_health - Get database health metrics
  5. check_embedding_model - Verify model status

Memory Management

  1. delete_memory - Delete specific memory by hash
  2. delete_by_tag - Delete all memories with specific tag
  3. cleanup_duplicates - Remove duplicate entries

Configuration Options

Configure through environment variables:

CHROMA_DB_PATH: Path to ChromaDB storage BACKUP_PATH: Path for backups AUTO_BACKUP_INTERVAL: Backup interval in hours (default: 24) MAX_MEMORIES_BEFORE_OPTIMIZE: Threshold for auto-optimization (default: 10000) SIMILARITY_THRESHOLD: Default similarity threshold (default: 0.7) MAX_RESULTS_PER_QUERY: Maximum results per query (default: 10) BACKUP_RETENTION_DAYS: Number of days to keep backups (default: 7) LOG_LEVEL: Logging level (default: INFO) # Hardware-specific environment variables PYTORCH_ENABLE_MPS_FALLBACK: Enable MPS fallback for Apple Silicon (default: 1) MCP_MEMORY_USE_ONNX: Use ONNX Runtime for CPU-only deployments (default: 0) MCP_MEMORY_USE_DIRECTML: Use DirectML for Windows acceleration (default: 0) MCP_MEMORY_MODEL_NAME: Override the default embedding model MCP_MEMORY_BATCH_SIZE: Override the default batch size

Getting Help

If you encounter any issues:

  1. Check our Troubleshooting Guide
  2. Review the Installation Guide
  3. For Windows-specific issues, see our Windows Setup Guide
  4. Contact the developer via Telegram: t.me/doobeedoo

Project Structure

mcp-memory-service/ ├── src/mcp_memory_service/ # Core package code │ ├── __init__.py │ ├── config.py # Configuration utilities │ ├── models/ # Data models │ ├── storage/ # Storage implementations │ ├── utils/ # Utility functions │ └── server.py # Main MCP server ├── scripts/ # Helper scripts │ ├── convert_to_uv.py # Script to migrate to UV │ └── install_uv.py # UV installation helper ├── .uv/ # UV configuration ├── memory_wrapper.py # Windows wrapper script ├── memory_wrapper_uv.py # UV-based wrapper script ├── uv_wrapper.py # UV wrapper script ├── install.py # Enhanced installation script └── tests/ # Test suite

Development Guidelines

  • Python 3.10+ with type hints
  • Use dataclasses for models
  • Triple-quoted docstrings for modules and functions
  • Async/await pattern for all I/O operations
  • Follow PEP 8 style guidelines
  • Include tests for new features

License

MIT License - See LICENSE file for details

Acknowledgments

  • ChromaDB team for the vector database
  • Sentence Transformers project for embedding models
  • MCP project for the protocol specification

Contact

t.me/doobidoo

ID: bzvl3lz34o