记忆服务
STDIO支持智能触发器和团队协作的通用MCP记忆服务
支持智能触发器和团队协作的通用MCP记忆服务
Production-ready MCP memory service with zero database locks, hybrid backend (fast local + cloud sync), and intelligent memory search for AI assistants. Features v8.9.0 auto-configuration for multi-client access, 5ms local reads with background Cloudflare sync, Natural Memory Triggers with 85%+ accuracy, and OAuth 2.1 team collaboration. Works with Claude Desktop, VS Code, Cursor, Continue, and 13+ AI applications.
Database Maintenance & Type Consolidation - Professional-grade tools for maintaining memory database health and organization.
What's New:
Database Health:
📖 Full Details: CHANGELOG.md | Maintenance Guide | All Releases
# One-command installation with auto-configuration git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service && python install.py # Choose option 4 (Hybrid - RECOMMENDED) when prompted # Installer automatically configures: # ✅ SQLite pragmas for concurrent access # ✅ Cloudflare credentials for cloud sync # ✅ Claude Desktop integration # Done! Fast local + cloud sync with zero database locks
Install from PyPI:
# Install latest version from PyPI pip install mcp-memory-service # Or with uv (faster) uv pip install mcp-memory-service
Then configure Claude Desktop by adding to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:
{ "mcpServers": { "memory": { "command": "memory", "args": ["server"], "env": { "MCP_MEMORY_STORAGE_BACKEND": "hybrid" } } } }
For advanced configuration with the interactive installer, clone the repo and run python scripts/installation/install.py.
Universal Installer (Most Compatible):
# Clone and install with automatic platform detection git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service # Lightweight installation (SQLite-vec with ONNX embeddings - recommended) python install.py # Add full ML capabilities (torch + sentence-transformers for advanced features) python install.py --with-ml # Install with hybrid backend (SQLite-vec + Cloudflare sync) python install.py --storage-backend hybrid
📝 Installation Options Explained:
--with-ml: Adds PyTorch + sentence-transformers for advanced ML features - heavier but more capable--storage-backend hybrid: Hybrid backend with SQLite-vec + Cloudflare sync - best for multi-device accessDocker (Fastest):
# For MCP protocol (Claude Desktop) docker-compose up -d # For HTTP API + OAuth (Team Collaboration) 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
Updating from an older version? Scripts have been reorganized for better maintainability:
python -m mcp_memory_service.server in your Claude Desktop config (no path dependencies!)uv run memory server with UV toolingscripts/run_memory_server.py to scripts/server/run_memory_server.pyOn your first run, you'll see some warnings that are completely normal:
These warnings disappear after the first successful run. The service is working correctly! For details, see our First-Time Setup Guide.
sqlite-vec may not have pre-built wheels for Python 3.13 yet. If installation fails:
brew install [email protected]--storage-backend cloudflaremacOS users may encounter enable_load_extension errors with sqlite-vec:
brew install python && rehashPYTHON_CONFIGURE_OPTS='--enable-loadable-sqlite-extensions' pyenv install 3.12.0--storage-backend cloudflare or --storage-backend hybrid👉 Visit our comprehensive Wiki for detailed guides:
busy_timeout=15000,cache_size=20000)/session-start command for manual session initialization (workaround for issue #160)Note: All heavy ML dependencies (PyTorch, sentence-transformers) are now optional to dramatically reduce build times and image sizes. SQLite-vec uses lightweight ONNX embeddings by default. Install with
--with-mlfor full ML capabilities.
# Start server with web interface uv run memory server --http # Access interactive dashboard open http://127.0.0.1:8888/ # Upload documents via CLI curl -X POST http://127.0.0.1:8888/api/documents/upload \ -F "[email protected]" \ -F "tags=documentation,reference" # Search document content curl -X POST http://127.0.0.1:8888/api/search \ -H "Content-Type: application/json" \ -d '{"query": "authentication flow", "limit": 10}'
# Start OAuth-enabled server for team collaboration export MCP_OAUTH_ENABLED=true uv run memory server --http # Claude Code team members connect via HTTP transport claude mcp add --transport http memory-service http://your-server:8000/mcp # → Automatic OAuth discovery, registration, and authentication
# 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 (shows OAuth status) uv run memory health
Recommended approach - Add to your Claude Desktop config (~/.claude/config.json):
{ "mcpServers": { "memory": { "command": "python", "args": ["-m", "mcp_memory_service.server"], "env": { "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec" } } } }
Alternative approaches:
// Option 1: UV tooling (if using UV) { "mcpServers": { "memory": { "command": "uv", "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"], "env": { "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec" } } } } // Option 2: Direct script path (v6.17.0+) { "mcpServers": { "memory": { "command": "python", "args": ["/path/to/mcp-memory-service/scripts/server/run_memory_server.py"], "env": { "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec" } } } }
Hybrid Backend (v8.9.0+ RECOMMENDED):
# Hybrid backend with auto-configured pragmas export MCP_MEMORY_STORAGE_BACKEND=hybrid export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000" # Cloudflare credentials (required for hybrid) export CLOUDFLARE_API_TOKEN="your-token" export CLOUDFLARE_ACCOUNT_ID="your-account" export CLOUDFLARE_D1_DATABASE_ID="your-db-id" export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index" # Enable HTTP API export MCP_HTTP_ENABLED=true export MCP_HTTP_PORT=8000 # Security export MCP_API_KEY="your-secure-key"
SQLite-vec Only (Local):
# Local-only storage export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Clients │ │ MCP Memory │ │ Storage Backend │
│ │ │ Service v8.9 │ │ │
│ • Claude Desktop│◄──►│ • MCP Protocol │◄──►│ • Hybrid 🌟 │
│ • Claude Code │ │ • HTTP Transport│ │ (5ms local + │
│ (HTTP/OAuth) │ │ • OAuth 2.1 Auth│ │ cloud sync) │
│ • VS Code │ │ • Memory Store │ │ • SQLite-vec │
│ • Cursor │ │ • Semantic │ │ • Cloudflare │
│ • 13+ AI Apps │ │ Search │ │ │
│ • Web Dashboard │ │ • Doc Ingestion │ │ Zero DB Locks ✅│
│ (Port 8888) │ │ • Zero DB Locks │ │ Auto-Config ✅ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
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
See CONTRIBUTING.md for detailed guidelines.
python scripts/validation/validate_configuration_complete.py to check your setupReal-world metrics from active deployments:
Featured AI ToolApache License 2.0 - see LICENSE for details.
Ready to supercharge your AI workflow? 🚀
👉 Start with our Installation Guide or explore the Wiki for comprehensive documentation.
Transform your AI conversations into persistent, searchable knowledge that grows with you.