MCP Memory Service

An intelligent MCP server providing semantic memory, persistent storage, and autonomous memory consolidation for Claude Desktop. This service combines ChromaDB/SQLite-vec storage with a revolutionary dream-inspired consolidation system that automatically organizes, compresses, and manages memories over time, creating a self-evolving knowledge base.

Help

Talk to the Repo with TalkToGitHub!
Use Gitprobe to digg deeper: GitProbe!

🎯 NEW: Claude Code Commands (v2.2.0)

Get started in 2 minutes with direct memory commands!

# Install with Claude Code commands
python install.py --install-claude-commands

# Start using immediately
claude /memory-store "Important decision about architecture"
claude /memory-recall "what did we decide last week?"
claude /memory-search --tags "architecture,database"
claude /memory-health

✨ 5 conversational commands following CCPlugins pattern
🚀 Zero MCP server configuration required
🧠 Context-aware operations with automatic project detection
🎨 Professional interface with comprehensive guidance

➡️ Quick Start Guide | Full Integration Guide

Features

🧠 Dream-Inspired Memory Consolidation (NEW in v2.0!)

Autonomous memory management inspired by human sleep cycle processing
Multi-layered time horizons (daily → weekly → monthly → quarterly → yearly)
Creative association discovery finding non-obvious connections between memories
Semantic clustering automatically organizing related memories
Intelligent compression preserving key information while reducing storage
Controlled forgetting with safe archival and recovery systems
Performance optimized for processing 10k+ memories efficiently
Health monitoring with comprehensive error handling and alerts

🔍 Core Memory Operations

Semantic search using sentence transformers
Natural language time-based recall (e.g., "last week", "yesterday morning")
Enhanced tag deletion system with flexible multi-tag support
Tag-based memory retrieval system
Exact match retrieval
Debug mode for similarity analysis
Duplicate detection and cleanup

🗄️ Storage & Performance

Dual storage backends: ChromaDB (full-featured) and SQLite-vec (lightweight, fast)
Automatic database backups
Memory optimization tools
Database health monitoring
Customizable embedding model
Cross-platform compatibility (Apple Silicon, Intel, Windows, Linux)
Hardware-aware optimizations for different environments
Graceful fallbacks for limited hardware resources

🔗 Integration & Coordination

🆕 Modern Dashboard UI (v3.3.0) - Professional web interface with live stats and interactive endpoint documentation
🆕 Claude Code Commands (v2.2.0) - Conversational memory commands following CCPlugins pattern
🆕 Multi-client coordination for Claude Desktop + Claude Code concurrent access
🆕 Intelligent coordination modes with automatic WAL/HTTP detection
🆕 mDNS Service Discovery (v2.1.0) - Zero-configuration networking with automatic service discovery
🆕 HTTPS Support with auto-generated certificates for secure connections
7 new MCP tools for consolidation operations
Environment variable-based configuration

Recent Enhancements

v3.3.0 - Modern Dashboard UI

✅ Professional Web Interface: Modern gradient design with card-based layout
✅ Live Statistics: Real-time memory count, model info, server status, and response times
✅ Interactive API Documentation: Organized endpoint cards with direct links to API docs
✅ Tech Stack Display: Visual representation of underlying technologies
✅ Mobile Responsive: Optimized for desktop and mobile devices
✅ Auto-Refresh: Live stats update every 30 seconds automatically

Dashboard screenshot coming soon - shows modern gradient design with live stats, interactive endpoint cards, and tech stack badges

Access the Dashboard:

Local: http://localhost:8000
mDNS: http://mcp-memory-service.local:8000
API Docs: http://localhost:8000/api/docs

v3.2.0 - SQLite-vec Embedding Fixes & Diagnostics

✅ Zero Vector Repair: Comprehensive diagnostic and repair tools for corrupted embeddings
✅ Enhanced Error Handling: Robust validation and initialization for SQLite-vec backend
✅ Migration Tools: Safe migration utilities that preserve existing memories
✅ Dependency Management: Moved core ML dependencies to main requirements for reliability
✅ Database Diagnostics: Advanced tools for analyzing and fixing embedding issues
✅ HTTP API Improvements: Fixed search endpoint compatibility and error handling

v3.1.0 - Cross-Platform Service Installation

✅ Native Service Support: Install as system service on Windows, macOS, and Linux
✅ Auto-Startup Configuration: Automatic boot/login startup with service management
✅ mDNS Port Flexibility: Clean access via port 443 without Pi-hole conflicts
✅ Service Management Commands: Start, stop, status, and uninstall operations

v3.0.0 - Autonomous Multi-Client Memory Service (MAJOR RELEASE)

🧠 Dream-Inspired Consolidation: Autonomous memory processing with exponential decay and creative association discovery
🌐 Multi-Client Architecture: Production FastAPI HTTPS server with automatic SSL certificates
🔍 mDNS Service Discovery: Zero-configuration networking with _mcp-memory._tcp.local. advertisement
📡 Server-Sent Events: Real-time updates with 30-second heartbeat for live synchronization
🚀 Production Deployment: Complete systemd service integration with professional management scripts
🔒 Security: API key authentication and user-space execution for enhanced security
📖 Documentation Overhaul: Comprehensive production setup and service lifecycle guides
⚡ Performance: Mathematical consolidation using existing embeddings (no external AI dependencies)

v2.2.0 - Claude Code Commands Integration

5 conversational commands for direct memory operations: /memory-store, /memory-recall, /memory-search, /memory-context, /memory-health
Optional installation integrated into main installer with intelligent prompting
CCPlugins-compatible markdown-based conversational command format
Context-aware operations with automatic project and session detection
Cross-platform support with comprehensive error handling and fallback systems

v2.1.0 - Zero-Configuration Networking

✅ mDNS Service Discovery: Automatic service advertisement and discovery using _mcp-memory._tcp.local.
✅ HTTPS Integration: SSL/TLS support with automatic self-signed certificate generation
✅ Enhanced HTTP-MCP Bridge: Auto-discovery mode with health validation and fallback
✅ Zero-Config Deployment: No manual endpoint configuration needed for local networks

Previous Enhancements

✅ PyTorch Optional: Now works without PyTorch for basic functionality when using SQLite-vec backend
✅ Improved SQLite-vec: Robust error handling and validation for the lightweight backend
✅ Intelligent Health Checks: Backend-specific health monitoring with detailed diagnostics
✅ Comprehensive Testing: Added test scripts for all critical functions
✅ API Consistency: Enhanced delete_by_tag to support both single and multiple tags
✅ New Delete Methods: Added delete_by_tags (OR logic) and delete_by_all_tags (AND logic)
✅ Backward Compatibility: All existing code continues to work unchanged
✅ Dashboard Integration: Enhanced UI with multiple tag selection capabilities

Installation Methods

🚀 Quick Start Options

Method	Best For	Setup Time	Features
Docker	Production, Multi-platform	2 minutes	✅ Isolated, ✅ Multi-client ready
Smithery	Claude Desktop users	1 minute	✅ Auto-config, ✅ One command
Python Installer	Developers, Customization	5 minutes	✅ Hardware detection, ✅ Full control
uvx	Temporary use, Testing	3 minutes	✅ No virtual env, ✅ Clean install

🚀 Intelligent Installer (Recommended)

The new unified installer automatically detects your hardware and selects the optimal configuration:

# Clone the repository
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run the intelligent installer
python install.py

# ✨ NEW: Multi-client setup is now integrated!
# You'll be prompted to configure universal MCP client access
# for Claude Desktop, VS Code, Continue, and other MCP applications

🎯 Hardware-Specific Installation

For Intel Macs: For detailed setup instructions specific to Intel Macs, see our Intel Mac Setup Guide. Intel Mac users should also check out our Legacy Intel Mac Scripts for specialized startup scripts.

For Legacy Hardware (2013-2017 Intel Macs):

python install.py --legacy-hardware

For Server/Headless Deployment:

python install.py --server-mode

For HTTP/SSE API Development:

python install.py --enable-http-api

For Migration from ChromaDB:

python install.py --migrate-from-chromadb

For Multi-Client Setup:

# Automatic multi-client setup during installation
python install.py --setup-multi-client

# Skip the interactive multi-client prompt
python install.py --skip-multi-client-prompt

For Claude Code Commands:

# Install with Claude Code commands (prompts if CLI detected)
python install.py --install-claude-commands

# Skip the interactive Claude Code commands prompt
python install.py --skip-claude-commands-prompt

🧠 What the Installer Does

Hardware Detection: CPU, GPU, memory, and platform analysis
Intelligent Backend Selection: ChromaDB vs SQLite-vec based on your hardware
Platform Optimization: macOS Intel fixes, Windows CUDA setup, Linux variations
Dependency Management: Compatible PyTorch and ML library versions
Auto-Configuration: Claude Desktop config and environment variables
Migration Support: Seamless ChromaDB to SQLite-vec migration

📊 Storage Backend Selection

MCP Memory Service supports two optimized storage backends:

SQLite-vec 🪶 (Lightweight & Fast)

Best for: 2015 MacBook Pro, older Intel Macs, low-memory systems, Docker deployments

✅ 10x faster startup (2-3 seconds vs 15-30 seconds)
✅ Single file database (easy backup/sharing)
✅ Minimal memory usage (~150MB vs ~600MB)
✅ No external dependencies
✅ HTTP/SSE API support

ChromaDB 📦 (Full-Featured)

Best for: Modern Macs (M1/M2/M3), GPU-enabled systems, production deployments

✅ Advanced vector search with multiple metrics
✅ Rich metadata support and complex queries
✅ Battle-tested scalability
✅ Extensive ecosystem integration

The installer automatically recommends the best backend for your hardware, but you can override with:

python install.py --storage-backend sqlite_vec    # Lightweight
python install.py --storage-backend chromadb      # Full-featured

Docker Installation

Docker Hub (Recommended)

The easiest way to run the Memory Service is using our pre-built Docker images:

# Pull the latest image
docker pull doobidoo/mcp-memory-service:latest

# Run with default settings (for MCP clients like Claude Desktop)
docker run -d -p 8000:8000 \
  -v $(pwd)/data/chroma_db:/app/chroma_db \
  -v $(pwd)/data/backups:/app/backups \
  doobidoo/mcp-memory-service:latest

# Run in standalone mode (for testing/development)
docker run -d -p 8000:8000 \
  -e MCP_STANDALONE_MODE=1 \
  -v $(pwd)/data/chroma_db:/app/chroma_db \
  -v $(pwd)/data/backups:/app/backups \
  doobidoo/mcp-memory-service:latest

Docker Compose

We provide multiple Docker Compose configurations for different scenarios:

docker-compose.yml - Standard configuration for MCP clients (Claude Desktop)
docker-compose.standalone.yml - Standalone mode for testing/development (prevents boot loops)
docker-compose.uv.yml - Alternative configuration using UV package manager
docker-compose.pythonpath.yml - Configuration with explicit PYTHONPATH settings

# Using Docker Compose (recommended)
docker-compose up

# Standalone mode (prevents boot loops)
docker-compose -f docker-compose.standalone.yml up

Building from Source

If you need to build the Docker image yourself:

# Build the image
docker build -t mcp-memory-service .

# Run the container
docker run -p 8000:8000 \
  -v $(pwd)/data/chroma_db:/app/chroma_db \
  -v $(pwd)/data/backups:/app/backups \
  mcp-memory-service

uvx Installation

You can install and run the Memory Service using uvx for isolated execution:

# Install uv (which includes uvx) if not already installed
pip install uv
# Or use the installer script:
# curl -LsSf https://astral.sh/uv/install.sh | sh

# Install and run the memory service
uvx mcp-memory-service

# Or install from GitHub
uvx --from git+https://github.com/doobidoo/mcp-memory-service.git mcp-memory-service

Windows Installation (Special Case)

Windows users may encounter PyTorch installation issues due to platform-specific wheel availability. Use our Windows-specific installation script:

# After activating your virtual environment
python scripts/install_windows.py

This script handles:

Detecting CUDA availability and version
Installing the appropriate PyTorch version from the correct index URL
Installing other dependencies without conflicting with PyTorch
Verifying the installation

Installing via Smithery

To install Memory Service for Claude Desktop automatically via Smithery:

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

Detailed Installation Guide

For comprehensive installation instructions and troubleshooting, see the Installation Guide.

Claude MCP Configuration

Standard Configuration

Add the following to your claude_desktop_config.json file:

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

Windows-Specific Configuration (Recommended)

For Windows users, we recommend using the wrapper script to ensure PyTorch is properly installed:

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

SQLite-vec Configuration (Lightweight)

For a lighter-weight configuration that doesn't require PyTorch:

{
  "memory": {
    "command": "python",
    "args": ["-m", "mcp_memory_service.server"],
    "cwd": "/path/to/mcp-memory-service",
    "env": {
      "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec",
      "MCP_MEMORY_SQLITE_PATH": "/path/to/mcp-memory/sqlite_vec.db",
      "MCP_MEMORY_BACKUPS_PATH": "/path/to/mcp-memory/backups",
      "MCP_MEMORY_USE_ONNX": "1",
      "PYTHONPATH": "/path/to/mcp-memory-service"
    }
  }
}

The wrapper script will:

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

🌐 Multi-Client Deployment

NEW: Deploy MCP Memory Service for multiple clients sharing the same memory database!

🚀 Centralized Server Deployment (Recommended)

Perfect for distributed teams, multiple devices, or cloud deployment:

# Install and start HTTP/SSE server
python install.py --server-mode --enable-http-api
export MCP_HTTP_HOST=0.0.0.0  # Allow external connections
export MCP_API_KEY="your-secure-key"  # Optional authentication
python scripts/run_http_server.py

✅ Benefits:

🔄 Real-time sync across all clients via Server-Sent Events (SSE)
🌍 Cross-platform - works from any device with HTTP access
🔒 Secure with optional API key authentication
📈 Scalable - handles many concurrent clients
☁️ Cloud-ready - deploy on AWS, DigitalOcean, Docker, etc.

Access via:

API Docs: http://your-server:8000/api/docs
Web Dashboard: http://your-server:8000/
REST API: All MCP operations available via HTTP

⚠️ Why NOT Cloud Storage (Dropbox/OneDrive/Google Drive)

Direct SQLite on cloud storage DOES NOT WORK for multi-client access:

❌ File locking conflicts - Cloud sync breaks SQLite's locking mechanism
❌ Data corruption - Incomplete syncs can corrupt the database
❌ Sync conflicts - Multiple clients create "conflicted copy" files
❌ Performance issues - Full database re-upload on every change

✅ Solution: Use centralized HTTP server deployment instead!

📖 Complete Documentation

For detailed deployment guides, configuration options, and troubleshooting:

📚 Multi-Client Deployment Guide

Covers:

Centralized HTTP/SSE Server setup and configuration
Shared File Access for local networks (limited scenarios)
Cloud Platform Deployment (AWS, DigitalOcean, Docker)
Security & Authentication setup
Performance Tuning for high-load environments
Troubleshooting common multi-client issues

Usage Guide

For detailed instructions on how to interact with the memory service in Claude Desktop:

Invocation Guide - Learn the specific keywords and phrases that trigger memory operations in Claude
Installation Guide - Detailed setup instructions
Demo Session Walkthrough - Real-world development session showcasing advanced features

The memory service is invoked through natural language commands in your conversations with Claude. For example:

To store: "Please remember that my project deadline is May 15th."
To retrieve: "Do you remember what I told you about my project deadline?"

Claude Code Commands Usage

With the optional Claude Code commands installed, you can also use direct command syntax:

# Store information with context
claude /memory-store "Important architectural decision about database backend"

# Recall memories by time
claude /memory-recall "what did we decide about the database last week?"

# Search by tags or content
claude /memory-search --tags "architecture,database"

# Capture current session context
claude /memory-context --summary "Development planning session"

# Check service health
claude /memory-health

To delete: "Please forget what I told you about my address."

See the Invocation Guide for a complete list of commands and detailed usage examples.

Storage Backends

The MCP Memory Service supports multiple storage backends to suit different use cases:

ChromaDB (Default)

Best for: Large memory collections (>100K entries), high-performance requirements
Features: Advanced vector indexing, excellent query performance, rich ecosystem
Memory usage: Higher (~200MB for 1K memories)
Setup: Automatically configured, no additional dependencies

SQLite-vec (Lightweight Alternative)

Best for: Smaller collections (