📌Overview

Purpose: The MCP Memory Service aims to provide a robust framework for semantic memory and persistent storage, enhancing conversation contexts and maintaining continuity in applications like Claude Desktop.

Overview: This service integrates with ChromaDB and sentence transformers to enable users to manage long-term memory effectively. It offers advanced capabilities such as semantic search, time-based memory recall, and optimized database management, catering to diverse platform requirements.

Key Features:

Semantic Search: Utilizes sentence transformers for efficient and contextual memory retrieval.
Natural Language Time-Based Recall: Allows users to retrieve memories using intuitive time references (e.g., "last week").
Persistent Storage: Employs ChromaDB to ensure reliable long-term memory preservation, integrated with automatic backup functionality.
Cross-Platform Compatibility: Supports various operating systems including macOS, Windows, and Linux with tailored optimizations.
Memory Management Tools: Equipped with features like duplicate detection, health monitoring, and memory optimization to maintain storage efficiency.

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, ideal for maintaining context across conversations.

Features

Semantic search using sentence transformers
Natural language time-based recall
Tag-based memory retrieval system
Persistent storage using ChromaDB
Automatic database backups
Memory optimization tools
Debug mode for similarity analysis
Database health monitoring
Customizable embedding model
Cross-platform compatibility
Hardware-aware optimizations
Graceful fallbacks for limited hardware resources

Installation

Quick Start (Recommended)

Clone the repository and run the installation script:

git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
python install.py

Windows Installation (Special Case)

Windows users may encounter PyTorch installation issues. Use the Windows-specific script:

python scripts/install_windows.py

Installing via Smithery

Install Memory Service automatically via Smithery:

npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude

Detailed Installation Guide

For comprehensive instructions, see the 1.

Configuration

Standard Configuration

Add the following to your claude_desktop_config.json file:

{
  "memory": {
    "command": "uv",
    "args": [
      "--directory",
      "your_mcp_memory_service_directory",
      "run",
      "memory"
    ],
    "env": {
      "MCP_MEMORY_CHROMA_PATH": "your_chroma_db_path",
      "MCP_MEMORY_BACKUPS_PATH": "your_backups_path"
    }
  }
}

Windows-Specific Configuration

For Windows users, use the wrapper script:

{
  "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"
    }
  }
}

Usage

To run the memory server directly:

python scripts/run_memory_server.py

Memory Operations

The memory service provides the following operations:

Core Memory Operations

store_memory - Store new information with optional tags
retrieve_memory - Semantic search for relevant memories
recall_memory - Retrieve memories using natural language time expressions
search_by_tag - Find memories using specific tags
exact_match_retrieve - Find memories with exact content match
debug_retrieve - Retrieve memories with similarity scores

Database Management

create_backup - Create database backup
get_stats - Get memory statistics
optimize_db - Optimize database performance
check_database_health - Get database health metrics

Memory Management

delete_memory - Delete specific memory by hash
delete_by_tag - Delete all memories with specific tag
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 Compatibility

Platform	Architecture	Accelerator	Status
macOS	Apple Silicon	MPS	✅ Supported
Windows	x86_64	CUDA	✅ Supported
Linux	x86_64	CUDA	✅ Supported

Testing

pip install pytest pytest-asyncio
pytest tests/

Troubleshooting

Refer to the Installation Guide for detailed troubleshooting steps.

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
├── memory_wrapper.py            # Windows wrapper script
├── install.py                   # Enhanced installation script
└── tests/                       # Test suite

Development Guidelines

Python 3.10+ with type hints
Use dataclasses for models
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

mcp-memory-service