MCP Memory Service

What is MCP Memory Service about?

MCP Memory Service offers a persistent, searchable knowledge store that AI assistants can read from and write to automatically. It integrates with the Model Context Protocol to supply relevant memories during a chat, supports natural‑language time and tag queries, and can consolidate memories across sessions.

How to use MCP Memory Service?

Clone and install

git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
python install.py            # default lightweight SQLite‑vec backend
# optional ML stack
# python install.py --with-ml
# optional ChromaDB backend for multi‑client sharing
# python install.py --with-chromadb

Start the server (default MCP protocol)

uv run memory server          # or: python -m mcp_memory_service.server

Enable team collaboration (OAuth 2.1)

export MCP_OAUTH_ENABLED=true
uv run memory server --http  # starts HTTP API on 8000

Connect a client
```
claude mcp add --transport http memory-service http://localhost:8000/mcp
```
The client will auto‑discover OAuth endpoints and obtain a token.

Basic CLI commands

uv run memory store "Fixed authentication race condition"
uv run memory recall "authentication race condition"
uv run memory search --tags python debugging
uv run memory health        # shows server health and OAuth status

Key Features

Semantic search using vector embeddings (SQLite‑vec by default, optional ONNX or PyTorch models).
Natural memory triggers (v7.1.0) that automatically surface relevant memories while coding.
OAuth 2.1 dynamic client registration for secure team collaboration.
Multiple storage backends: lightweight SQLite‑vec, optional ChromaDB for shared team databases, Cloudflare edge distribution.
Multi‑client compatibility with Claude Desktop, Claude Code (HTTP transport), VS Code, Cursor, Continue and 13+ other AI tools.
Tag‑based and time‑based queries (e.g., “yesterday”, “last week”).
Docker support for production deployments and easy scaling.
Zero‑configuration installation scripts for macOS, Windows, Linux, and Python 3.13 workarounds.

Use Cases

Developer assistance: automatically retrieve past fixes, design decisions, or API usage snippets while writing code.
Team knowledge base: share memories across a development team, with OAuth‑protected access and automatic sync.
Research logging: store experiment outcomes and query them by date or tags.
Customer support bots: recall prior interactions or policy documents without manual indexing.
Personal AI assistant: maintain a lifelong memory of personal notes, tasks, and preferences.

FAQ

Q: Do I need heavy ML libraries? A: No. The default installation uses SQLite‑vec with ONNX embeddings (<100 MB). Add --with-ml only if you need advanced models.

Q: My Python version is 3.13 – will it work? A: SQLite‑vec wheels may be missing for 3.13. The installer falls back to building from source or you can switch to the ChromaDB backend.

Q: How does OAuth work for Claude Code? A: Enable MCP_OAUTH_ENABLED=true and start the server with --http. Clients discover the /oauth/.well-known endpoint, register themselves, and receive JWTs for each request.

Q: Can I run the service in Docker? A: Yes. Use the provided docker-compose.yml for MCP protocol or docker-compose.http.yml for the HTTP/OAuth API.

Q: What storage backend should I choose? A: Use SQLite‑vec for single‑user or lightweight scenarios. Choose ChromaDB when multiple users need to share the same memory store.

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):

# 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 && python install_hooks.py --natural-triggers

# 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

🆕 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

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

# 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

# Add ChromaDB backend support (includes full ML stack - for multi-client setups)
python install.py --with-chromadb

📝 Installation Options Explained:

Default (recommended): Lightweight SQLite-vec with ONNX embeddings - fast, works offline, <100MB dependencies
--with-ml: Adds PyTorch + sentence-transformers for advanced ML features - heavier but more capable
--with-chromadb: Multi-client local server support - use only if you need shared team access

Docker (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

⚠️ 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 --with-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 sqlite_vec backend (default) or install ChromaDB with --with-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

📂 Internal Documentation

🏗️ Architecture Specs - Search enhancement specifications and design documents
👩‍💻 Development Docs - AI agent instructions, release checklist, refactoring notes
🚀 Deployment Guides - Docker, dual-service, and production deployment
📚 Additional Guides - Storage backends, migration, mDNS discovery

✨ 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, lightweight ONNX embeddings)
ChromaDB - Multi-client collaboration (optional, heavy dependencies)
Cloudflare - Global edge distribution
Automatic backups and synchronization

Note: All heavy ML dependencies (PyTorch, sentence-transformers, ChromaDB) are now optional to dramatically reduce build times and image sizes. SQLite-vec uses lightweight ONNX embeddings by default. Install with --with-ml for full ML capabilities or --with-chromadb for multi-client features.

🚀 Production Ready

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

💡 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:

// 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/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
✅ 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

Verified MCP Server
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