MCP Memory Service

![License: Apache 2.0](https://opensource.org/licenses/Apache-2.0) ![GitHub stars](https://github.com/doobidoo/mcp-memory-service/stargazers) ![Production Ready](https://github.com/doobidoo/mcp-memory-service#-in-production)

![Works with Claude](https://claude.ai) ![Works with Cursor](https://cursor.sh) ![MCP Protocol](https://modelcontextprotocol.io/) ![Multi-Client](https://github.com/doobidoo/mcp-memory-service/wiki)

Universal MCP memory service with intelligent memory triggers, OAuth 2.1 team collaboration, and semantic memory search for AI assistants. Features Natural Memory Triggers v7.1.0 with 85%+ trigger accuracy, Claude Code HTTP transport, zero-configuration authentication, and enterprise security. 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)

🧠 v7.1.0: Natural Memory Triggers for Claude Code

🤖 Intelligent Memory Awareness (Zero Configuration): ```bash

1. Install MCP Memory Service

git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service && python install.py

2. Install Natural Memory Triggers

cd claude-hooks && ./install-natural-triggers.sh

3. Test intelligent triggers

node memory-mode-controller.js status

✅ Done! Claude Code now automatically detects when you need memory context


**📖 Complete Guide**: [Natural Memory Triggers v7.1.0](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)

---

### 🆕 **v7.0.0: OAuth 2.1 & Claude Code HTTP Transport**

**🔗 Claude Code Team Collaboration** (Zero Configuration):

1. Start OAuth-enabled server

export MCP_OAUTH_ENABLED=true uv run memory server --http

2. Add HTTP transport to Claude Code

claude mcp add --transport http memory-service http://localhost:8000/mcp

✅ Done! Claude Code automatically handles OAuth registration and team collaboration


**📖 Complete Setup Guide**: [OAuth 2.1 Setup Guide](https://github.com/doobidoo/mcp-memory-service/wiki/OAuth-2.1-Setup-Guide)

---

### Traditional Setup Options

**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 python install.py ```

Smithery (Claude Desktop): ```bash

Auto-install for Claude Desktop

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

⚠️ v6.17.0+ Script Migration Notice

Updating from an older version? Scripts have been reorganized for better maintainability:

Recommended: Use python -m mcp_memory_service.server in your Claude Desktop config (no path dependencies!)
Alternative 1: Use uv run memory server with UV tooling
Alternative 2: Update path from scripts/run_memory_server.py to scripts/server/run_memory_server.py
Backward compatible: Old path still works with a migration notice

⚠️ 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 python@3.12
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:

🧠 v7.1.0 Natural Memory Triggers (Latest)

Natural Memory Triggers v7.1.0 Guide - Intelligent automatic memory awareness
✅ 85%+ trigger accuracy with semantic pattern detection
✅ Multi-tier performance (50ms instant → 150ms fast → 500ms intensive)
✅ CLI management system for real-time configuration
✅ Git-aware context integration for enhanced relevance
✅ Zero-restart installation with dynamic hook loading

🆕 v7.0.0 OAuth & Team Collaboration

🔐 OAuth 2.1 Setup Guide - NEW! Complete OAuth 2.1 Dynamic Client Registration guide
🔗 Integration Guide - Claude Desktop, Claude Code HTTP transport, VS Code, and more
🛡️ Advanced Configuration - Updated! OAuth security, enterprise features

🚀 Setup & Installation

📋 Installation Guide - Complete installation for all platforms and use cases
🖥️ Platform Setup Guide - Windows, macOS, and Linux optimizations
⚡ Performance Optimization - Speed up queries, optimize resources, scaling

🧠 Advanced Topics

👨‍💻 Development Reference - Claude Code hooks, API reference, debugging
🔧 Troubleshooting Guide - Updated! OAuth troubleshooting + common issues
❓ FAQ - Frequently asked questions
📝 Examples - Practical code examples and workflows

✨ Key Features

🔐 Enterprise Authentication & Team Collaboration 🆕

OAuth 2.1 Dynamic Client Registration - RFC 7591 & RFC 8414 compliant
Claude Code HTTP Transport - Zero-configuration team collaboration
JWT Authentication - Enterprise-grade security with scope validation
Auto-Discovery Endpoints - Seamless client registration and authorization
Multi-Auth Support - OAuth + API keys + optional anonymous access

🧠 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 - HTTP transport + 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 with OAuth 2.1
Team collaboration - OAuth 2.1 with HTTP API support

💡 Basic Usage

🔗 Team Collaboration with OAuth (v7.0.0+)

# 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

🧠 Memory Operations

# 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

🔧 Configuration

Claude Desktop Integration

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: ```json // 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" } } } } ```

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 Memory     │    │ Storage Backend │
│                 │    │  Service v7.0   │    │                 │
│ • Claude Desktop│◄──►│ • MCP Protocol  │◄──►│ • SQLite-vec    │
│ • Claude Code   │    │ • HTTP Transport│    │ • ChromaDB      │
│   (HTTP/OAuth)  │    │ • OAuth 2.1 Auth│    │ • Cloudflare    │
│ • VS Code       │    │ • Memory Store  │    │ • Hybrid        │
│ • Cursor        │    │ • Semantic      │    │                 │
│ • 13+ AI Apps   │    │   Search        │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🛠️ 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/                     # Development tools

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
✅ Configuration Validator: Run python scripts/validation/validate_configuration_complete.py to check your setup
🔄 Backend Sync Tools: See scripts/README.md for Cloudflare↔SQLite sync

📊 In Production

Real-world metrics from active deployments:

750+ memories stored and actively used across teams
<500ms response time for semantic search (local & HTTP transport)
65% token reduction in Claude Code sessions with OAuth collaboration
96.7% faster context setup (15min → 30sec)
100% knowledge retention across sessions and team members
Zero-configuration OAuth setup success rate: 98.5%

🏆 Recognition

![Smithery](https://smithery.ai/server/@doobidoo/mcp-memory-service) Verified MCP Server
![Glama AI](https://glama.ai/mcp/servers/bzvl3lz34o) Featured AI Tool
Production-tested across 13+ AI applications
Community-driven with real-world feedback and improvements

📄 License

Apache 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.

MCP Memory Service