MCP Memory Service

Universal MCP memory service providing semantic memory search and persistent storage for AI assistants. Works with Claude Desktop, VS Code, Cursor, Continue, and 13+ AI applications with SQLite-vec for fast local search and Cloudflare for global distribution.

🚀 Quick Start (2 minutes)

Universal Installer (Recommended)

# Clone and install with automatic platform detection
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
python install.py

Docker (Fastest)

# For MCP protocol (Claude Desktop)
docker-compose up -d

# For HTTP API (Web Dashboard)
docker-compose -f docker-compose.http.yml up -d

Smithery (Claude Desktop)

# Auto-install for Claude Desktop
npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude

⚠️ First-Time Setup Expectations

On your first run, you'll see some warnings that are completely normal:

"WARNING: Failed to load from cache: No snapshots directory" - The service is checking for cached models (first-time setup)
"WARNING: Using TRANSFORMERS_CACHE is deprecated" - Informational warning, doesn't affect functionality
Model download in progress - The service automatically downloads a ~25MB embedding model (takes 1-2 minutes)

These warnings disappear after the first successful run. The service is working correctly! For details, see our First-Time Setup Guide.

🐍 Python 3.13 Compatibility Note

sqlite-vec may not have pre-built wheels for Python 3.13 yet. If installation fails:

The installer will automatically try multiple installation methods
Consider using Python 3.12 for the smoothest experience: brew install [email protected]
Alternative: Use ChromaDB backend with --storage-backend chromadb
See Troubleshooting Guide for details

🍎 macOS SQLite Extension Support

macOS users may encounter enable_load_extension errors with sqlite-vec:

System Python on macOS lacks SQLite extension support by default
Solution: Use Homebrew Python: brew install python && rehash
Alternative: Use pyenv: PYTHON_CONFIGURE_OPTS='--enable-loadable-sqlite-extensions' pyenv install 3.12.0
Fallback: Use ChromaDB backend: export MCP_MEMORY_STORAGE_BACKEND=chromadb
See Troubleshooting Guide for details

📚 Complete Documentation

👉 Visit our comprehensive Wiki for detailed guides:

🚀 Setup & Installation

📋 Installation Guide - Complete installation for all platforms and use cases
🖥️ Platform Setup Guide - Windows, macOS, and Linux optimizations
🔗 Integration Guide - Claude Desktop, Claude Code, VS Code, and more

🧠 Advanced Topics

🧠 Advanced Configuration - Integration patterns, best practices, workflows
⚡ Performance Optimization - Speed up queries, optimize resources, scaling
👨‍💻 Development Reference - Claude Code hooks, API reference, debugging

🔧 Help & Reference

🔧 Troubleshooting Guide - Solutions for common issues
❓ FAQ - Frequently asked questions
📝 Examples - Practical code examples and workflows

✨ Key Features

🧠 Intelligent Memory Management

Semantic search with vector embeddings
Natural language time queries ("yesterday", "last week")
Tag-based organization with smart categorization
Memory consolidation with dream-inspired algorithms

🔗 Universal Compatibility

Claude Desktop - Native MCP integration
Claude Code - Memory-aware development with hooks
VS Code, Cursor, Continue - IDE extensions
13+ AI applications - REST API compatibility

💾 Flexible Storage

SQLite-vec - Fast local storage (recommended)
ChromaDB - Multi-client collaboration
Cloudflare - Global edge distribution
Automatic backups and synchronization

🚀 Production Ready

Cross-platform - Windows, macOS, Linux
Service installation - Auto-start background operation
HTTPS/SSL - Secure connections
Docker support - Easy deployment

💡 Basic Usage

# Store a memory
uv run memory store "Fixed race condition in authentication by adding mutex locks"

# Search for relevant memories  
uv run memory recall "authentication race condition"

# Search by tags
uv run memory search --tags python debugging

# Check system health
uv run memory health

🔧 Configuration

Claude Desktop Integration

Add to your Claude Desktop config (~/.claude/config.json):

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],
      "env": {
        "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"
      }
    }
  }
}

Environment Variables

# Storage backend (sqlite_vec recommended)
export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

# Enable HTTP API
export MCP_HTTP_ENABLED=true
export MCP_HTTP_PORT=8000

# Security  
export MCP_API_KEY="your-secure-key"

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Clients    │    │  MCP Protocol   │    │ Storage Backend │
│                 │    │                 │    │                 │
│ • Claude Desktop│◄──►│ • Memory Store  │◄──►│ • SQLite-vec    │
│ • Claude Code   │    │ • Semantic      │    │ • ChromaDB      │
│ • VS Code       │    │   Search        │    │ • Cloudflare    │
│ • Cursor        │    │ • Tag System    │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🛠️ Development

Project Structure

mcp-memory-service/
├── src/mcp_memory_service/    # Core application
│   ├── models/                # Data models
│   ├── storage/               # Storage backends
│   ├── web/                   # HTTP API & dashboard
│   └── server.py              # MCP server
├── scripts/                   # Utilities & installation
├── tests/                     # Test suite
└── tools/docker/              # Docker configuration

Contributing

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

🆘 Support

📖 Documentation: Wiki - Comprehensive guides
🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
🔧 Troubleshooting: Troubleshooting Guide

📊 In Production

Real-world metrics from active deployments:

750+ memories stored and actively used
**