Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/doobidoo/mcp-memory-service

MCP server providing semantic memory and persistent storage capabilities for Claude using ChromaDB and sentence transformers.
https://github.com/doobidoo/mcp-memory-service

chroma-db knowledge localstorage mcp memory semantic-search server tag-based time-based vector-database

Last synced: 10 days ago
JSON representation

MCP server providing semantic memory and persistent storage capabilities for Claude using ChromaDB and sentence transformers.

Awesome Lists containing this project

README 

          
# MCP Memory Service



[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[![PyPI version](https://img.shields.io/pypi/v/mcp-memory-service?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/mcp-memory-service/)

[![Python](https://img.shields.io/pypi/pyversions/mcp-memory-service?logo=python&logoColor=white)](https://pypi.org/project/mcp-memory-service/)

[![GitHub stars](https://img.shields.io/github/stars/doobidoo/mcp-memory-service?style=social)](https://github.com/doobidoo/mcp-memory-service/stargazers)

[![Works with Claude](https://img.shields.io/badge/Works%20with-Claude-blue)](https://claude.ai)

[![Works with Cursor](https://img.shields.io/badge/Works%20with-Cursor-orange)](https://cursor.sh)



## Stop Re-Explaining Your Project to AI Every Session





  MCP Memory Service




Your AI assistant forgets everything when you start a new chat. After 50 tool uses, context explodes to 500k+ tokensโ€”Claude slows down, you restart, and now it remembers nothing. You spend 10 minutes re-explaining your architecture. **Again.**



**MCP Memory Service solves this.**



It automatically captures your project context, architecture decisions, and code patterns. When you start fresh sessions, your AI already knows everythingโ€”no re-explaining, no context loss, no wasted time.



### โšก Works With Your Favorite AI Tools



#### ๐Ÿ–ฅ๏ธ CLI & Terminal AI

**Claude Code** ยท **Gemini Code Assist** ยท **Aider** ยท **GitHub Copilot CLI** ยท **Amp** ยท **Continue** ยท **Zed** ยท **Cody**



#### ๐ŸŽจ Desktop & IDE

**Claude Desktop** ยท **VS Code** ยท **Cursor** ยท **Windsurf** ยท **Raycast** ยท **JetBrains** ยท **Sourcegraph** ยท **Qodo**



**Works seamlessly with any MCP-compatible client** - whether you code in the terminal, IDE, or browser.



---



## ๐Ÿš€ Get Started in 60 Seconds



**Express Install** (recommended for most users):



```bash

pip install mcp-memory-service

# Auto-configure for Claude Desktop (macOS/Linux)

python -m mcp_memory_service.scripts.installation.install --quick

```



**What just happened?**

- โœ… Installed memory service

- โœ… Configured optimal backend (SQLite)

- โœ… Set up Claude Desktop integration

- โœ… Enabled automatic context capture



**Next:** Restart Claude Desktop. Your AI now remembers everything across sessions.



๐Ÿ“ฆ Alternative: PyPI + Manual Configuration



```bash

pip install mcp-memory-service

```



Then add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json

{

  "mcpServers": {

    "memory": {

      "command": "memory",

      "args": ["server"]

    }

  }

}

```



๐Ÿ”ง Advanced: Custom Backends & Team Setup



For production deployments, team collaboration, or cloud sync:



```bash

git clone https://github.com/doobidoo/mcp-memory-service.git

cd mcp-memory-service

python scripts/installation/install.py

```



Choose from:

- **SQLite** (local, fast, single-user)

- **Cloudflare** (cloud, multi-device sync)

- **Hybrid** (best of both: 5ms local + background cloud sync)



---



## ๐Ÿ’ก Why You Need This



### The Problem



| Session 1 | Session 2 (Fresh Start) |

|-----------|-------------------------|

| You: "We're building a Next.js app with Prisma and tRPC" | AI: "What's your tech stack?" โŒ |

| AI: "Got it, I see you're using App Router" | You: *Explains architecture again for 10 minutes* ๐Ÿ˜ค |

| You: "Add authentication with NextAuth" | AI: "Should I use Pages Router or App Router?" โŒ |



### The Solution



| Session 1 | Session 2 (Fresh Start) |

|-----------|-------------------------|

| You: "We're building a Next.js app with Prisma and tRPC" | AI: "I rememberโ€”Next.js App Router with Prisma and tRPC. What should we build?" โœ… |

| AI: "Got it, I see you're using App Router" | You: "Add OAuth login" |

| You: "Add authentication with NextAuth" | AI: "I'll integrate NextAuth with your existing Prisma setup." โœ… |



**Result:** Zero re-explaining. Zero context loss. Just continuous, intelligent collaboration.



---



## โœจ Key Features



๐Ÿง  **Persistent Memory** โ€“ Context survives across sessions with semantic search

๐Ÿ” **Smart Retrieval** โ€“ Finds relevant context automatically using AI embeddings

โšก **5ms Speed** โ€“ Instant context injection, no latency

๐Ÿ”„ **Multi-Client** โ€“ Works across 13+ AI applications

โ˜๏ธ **Cloud Sync** โ€“ Optional Cloudflare backend for team collaboration

๐Ÿ”’ **Privacy-First** โ€“ Local-first, you control your data

๐Ÿ“Š **Web Dashboard** โ€“ Visualize and manage memories at `http://localhost:8000`



---



## ๐Ÿ†• Latest Release: **v8.54.2** (Dec 25, 2025)



**Offline Mode Fix**



- ๐Ÿ”ง **First-Time Install Support** - Offline mode changed from always-on to opt-in

- ๐Ÿ“ฆ **Model Download Enabled** - Fixes "outgoing traffic has been disabled" error during fresh installs

- โš™๏ธ **Explicit Configuration** - Offline mode only activates with `MCP_MEMORY_OFFLINE=1`

- โœ… **Cache Path Preservation** - Automatic cache configuration still works



**Previous Releases**:

- **v8.54.1** - UV Virtual Environment Support (installer compatibility fix)

- **v8.54.0** - Smart Auto-Capture System (intelligent pattern detection, 6 memory types, bilingual support)

- **v8.53.0** - Windows Service Management (Task Scheduler support, auto-startup, watchdog monitoring, 819 lines PowerShell automation)

- **v8.52.2** - Hybrid Backend Maintenance Enhancement (multi-PC association cleanup, drift prevention, Vectorize error handling)

- **v8.52.1** - Windows Embedding Fallback & Script Portability (DLL init failure fix, MCP_HTTP_PORT support)

- **v8.52.0** - Time-of-Day Emoji Icons (8 time-segment indicators, dark mode support, automatic timezone)

- **v8.51.0** - Graph Database Architecture (30x query performance, 97% storage reduction for associations)

- **v8.50.1** - Critical Bug Fixes (MCP_EMBEDDING_MODEL fix, installation script backend support, i18n quality analytics complete)

- **v8.50.0** - Fallback Quality Scoring (DeBERTa + MS-MARCO hybrid, technical content rescue, 20/20 tests passing)

- **v8.49.0** - DeBERTa Quality Classifier (absolute quality assessment, eliminates self-matching bias)

- **v8.48.4** - Cloudflare D1 Drift Detection Performance (10-100x faster queries, numeric comparison fix)

- **v8.48.3** - Code Execution Hook Fix - 75% token reduction now working (fixed time_filter parameter, Python warnings, venv detection)

- **v8.48.2** - HTTP Server Auto-Start & Time Parser Improvements (smart service management, "last N periods" support)

- **v8.48.1** - Critical Hotfix - Startup Failure Fix (redundant calendar import removed, immediate upgrade required)

- **v8.48.0** - CSV-Based Metadata Compression (78% size reduction, 100% sync success, metadata validation)

- **v8.47.1** - ONNX Quality Evaluation Bug Fixes (self-match fix, association pollution, sync queue overflow, realistic distribution)

- **v8.47.0** - Association-Based Quality Boost (connection-based enhancement, network effect leverage, metadata persistence)

- **v8.46.3** - Quality Score Persistence Fix (ONNX scores in hybrid backend, metadata normalization)

- **v8.46.2** - Session-Start Hook Crash Fix + Hook Installer Improvements (client-side tag filtering, isolated version metadata)

- **v8.46.1** - Windows Hooks Installer Fix + Quality System Integration (UTF-8 console configuration, backend quality scoring)

- **v8.45.3** - ONNX Ranker Model Export Fix (automatic model export, offline mode support, 7-16ms CPU performance)

- **v8.45.2** - Dashboard Dark Mode Consistency Fixes (global CSS overrides, Chart.js dark mode support)

- **v8.45.1** - Quality System Test Infrastructure Fixes (HTTP API router, storage retrieval, async test client)

- **v8.45.0** - Memory Quality System - AI-Driven Automatic Quality Scoring (ONNX-powered local SLM, multi-tier fallback, quality-based retention)

- **v8.44.0** - Multi-Language Expansion (Japanese, Korean, German, French, Spanish - 359 keys each, complete i18n coverage)

- **v8.43.0** - Internationalization & Quality Automation (English/Chinese i18n, Claude branch automation, quality gates)

- **v8.42.1** - MCP Resource Handler Fix (`AttributeError` with Pydantic AnyUrl objects)

- **v8.42.0** - Memory Awareness Enhancements (visible memory injection, quality session summaries, LLM-powered summarization)

- **v8.41.2** - Hook Installer Utility File Deployment (ALL 14 utilities copied, future-proof glob pattern)

- **v8.41.1** - Context Formatter Memory Sorting (recency sorting within categories, newest first)

- **v8.41.0** - Session Start Hook Reliability Improvements (error suppression, clean output, memory filtering, classification fixes)

- **v8.40.0** - Session Start Version Display (automatic version comparison, PyPI status labels)

- **v8.39.1** - Dashboard Analytics Bug Fixes: Three critical fixes (top tags filtering, recent activity display, storage report fields)

- **v8.39.0** - Performance Optimization: Storage-layer date-range filtering (10x faster analytics, 97% data transfer reduction)

- **v8.38.1** - Critical Hotfix: HTTP MCP JSON-RPC 2.0 compliance fix (Claude Code/Desktop connection failures resolved)

- **v8.38.0** - Code Quality: Phase 2b COMPLETE (~176-186 lines duplicate code eliminated, 10 consolidations)

- **v8.37.0** - Code Quality: Phase 2a COMPLETE (5 duplicate high-complexity functions eliminated)

- **v8.36.1** - Critical Hotfix: HTTP server startup crash fix (forward reference error in analytics.py)

- **v8.36.0** - Code Quality: Phase 2 COMPLETE (100% of target achieved, -39 complexity points)

- **v8.35.0** - Code Quality: Phase 2 Batch 1 (install.py, cloudflare.py, -15 complexity points)

- **v8.34.0** - Code Quality: Phase 2 Complexity Reduction (analytics.py refactored, 11 โ†’ 6-7 complexity)

- **v8.33.0** - Critical Installation Bug Fix + Code Quality Improvements (dead code cleanup, automatic MCP setup)

- **v8.32.0** - Code Quality Excellence: pyscn Static Analysis Integration (multi-layer QA workflow)

- **v8.31.0** - Revolutionary Batch Update Performance (21,428x faster memory consolidation)

- **v8.30.0** - Analytics Intelligence: Adaptive Charts & Critical Data Fixes (accurate trend visualization)

- **v8.28.1** - Critical HTTP MCP Transport JSON-RPC 2.0 Compliance Fix (Claude Code compatibility)

- **v8.28.0** - Cloudflare AND/OR Tag Filtering (unified search API, 3-5x faster hybrid sync)

- **v8.27.1** - Critical Hotfix: Timestamp Regression (created_at preservation during metadata sync)

- **v8.26.0** - Revolutionary MCP Performance (534,628x faster tools, 90%+ cache hit rate)

- **v8.25.0** - Hybrid Backend Drift Detection (automatic metadata sync, bidirectional awareness)

- **v8.24.4** - Code Quality Improvements from Gemini Code Assist (regex sanitization, DOM caching)

- **v8.24.3** - Test Coverage & Release Agent Improvements (tag+time filtering tests, version history fix)

- **v8.24.2** - CI/CD Workflow Fixes (bash errexit handling, exit code capture)

- **v8.24.1** - Test Infrastructure Improvements (27 test failures resolved, 63% โ†’ 71% pass rate)

- **v8.24.0** - PyPI Publishing Enabled (automated package publishing via GitHub Actions)

- **v8.23.1** - Stale Virtual Environment Prevention System (6-layer developer protection)

- **v8.23.0** - Consolidation Scheduler via Code Execution API (88% token reduction)



**๐Ÿ“– Full Details**: [CHANGELOG.md](CHANGELOG.md#8222---2025-11-09) | [All Releases](https://github.com/doobidoo/mcp-memory-service/releases)



---



## ๐Ÿ“š Documentation & Resources



- **[Installation Guide](docs/installation.md)** โ€“ Detailed setup instructions

- **[Configuration Guide](docs/mastery/configuration-guide.md)** โ€“ Backend options and customization

- **[Architecture Overview](docs/architecture.md)** โ€“ How it works under the hood

- **[Team Setup Guide](docs/teams.md)** โ€“ OAuth and cloud collaboration

- **[Troubleshooting](docs/troubleshooting/)** โ€“ Common issues and solutions

- **[API Reference](docs/api.md)** โ€“ Programmatic usage

- **[Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)** โ€“ Complete documentation

- [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/doobidoo/mcp-memory-service) โ€“ AI-powered documentation assistant



---



## ๐Ÿค Contributing



We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.



**Quick Development Setup:**

```bash

git clone https://github.com/doobidoo/mcp-memory-service.git

cd mcp-memory-service

pip install -e .  # Editable install

pytest tests/      # Run test suite

```



---



## โญ Support



If this saves you time, give us a star! โญ



- **Issues**: [GitHub Issues](https://github.com/doobidoo/mcp-memory-service/issues)

- **Discussions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)

- **Wiki**: [Documentation Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)



---



## ๐Ÿ“„ License



Apache 2.0 โ€“ See [LICENSE](LICENSE) for details.



---





  Never explain your project to AI twice.


  Start using MCP Memory Service today.




## โš ๏ธ 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](docs/first-time-setup.md).



### ๐Ÿ 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 Cloudflare backend with `--storage-backend cloudflare`

- See [Troubleshooting Guide](docs/troubleshooting/general.md#python-313-sqlite-vec-issues) 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 Cloudflare or Hybrid backend: `--storage-backend cloudflare` or `--storage-backend hybrid`

- See [Troubleshooting Guide](docs/troubleshooting/general.md#macos-sqlite-extension-issues) for details



## ๐ŸŽฏ Memory Awareness in Action



**Intelligent Context Injection** - See how the memory service automatically surfaces relevant information at session start:



Memory Awareness Hooks in Action



**What you're seeing:**

- ๐Ÿง  **Automatic memory injection** - 8 relevant memories found from 2,526 total

- ๐Ÿ“‚ **Smart categorization** - Recent Work, Current Problems, Additional Context

- ๐Ÿ“Š **Git-aware analysis** - Recent commits and keywords automatically extracted

- ๐ŸŽฏ **Relevance scoring** - Top memories scored at 100% (today), 89% (8d ago), 84% (today)

- โšก **Fast retrieval** - SQLite-vec backend with 5ms read performance

- ๐Ÿ”„ **Background sync** - Hybrid backend syncing to Cloudflare



**Result**: Claude starts every session with full project context - no manual prompting needed.



## ๐Ÿ“š Complete Documentation



**๐Ÿ‘‰ Visit our comprehensive [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) for detailed guides:**



### ๐Ÿง  v7.1.3 Natural Memory Triggers (Latest)

- **[Natural Memory Triggers v7.1.3 Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)** - 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](https://github.com/doobidoo/mcp-memory-service/wiki/OAuth-2.1-Setup-Guide)** - **NEW!** Complete OAuth 2.1 Dynamic Client Registration guide

- **[๐Ÿ”— Integration Guide](https://github.com/doobidoo/mcp-memory-service/wiki/03-Integration-Guide)** - Claude Desktop, **Claude Code HTTP transport**, VS Code, and more

- **[๐Ÿ›ก๏ธ Advanced Configuration](https://github.com/doobidoo/mcp-memory-service/wiki/04-Advanced-Configuration)** - **Updated!** OAuth security, enterprise features



### ๐Ÿงฌ v8.23.0+ Memory Consolidation

- **[๐Ÿ“Š Memory Consolidation System Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Memory-Consolidation-System-Guide)** - **NEW!** Automated memory maintenance with real-world performance metrics

  - โœ… **Dream-inspired consolidation** (decay scoring, association discovery, compression, archival)

  - โœ… **24/7 automatic scheduling** (daily/weekly/monthly via HTTP server)

  - โœ… **Token-efficient Code Execution API** (90% token reduction vs MCP tools)

  - โœ… **Real-world performance data** (4-6 min for 2,495 memories with hybrid backend)

  - โœ… **Three manual trigger methods** (HTTP API, MCP tools, Python API)



### ๐Ÿš€ Setup & Installation

- **[๐Ÿ“‹ Installation Guide](https://github.com/doobidoo/mcp-memory-service/wiki/01-Installation-Guide)** - Complete installation for all platforms and use cases

- **[๐Ÿ–ฅ๏ธ Platform Setup Guide](https://github.com/doobidoo/mcp-memory-service/wiki/02-Platform-Setup-Guide)** - Windows, macOS, and Linux optimizations

- **[โšก Performance Optimization](https://github.com/doobidoo/mcp-memory-service/wiki/05-Performance-Optimization)** - Speed up queries, optimize resources, scaling



### ๐Ÿง  Advanced Topics

- **[๐Ÿ‘จโ€๐Ÿ’ป Development Reference](https://github.com/doobidoo/mcp-memory-service/wiki/06-Development-Reference)** - Claude Code hooks, API reference, debugging

- **[๐Ÿ”ง Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)** - **Updated!** OAuth troubleshooting + common issues

- **[โ“ FAQ](https://github.com/doobidoo/mcp-memory-service/wiki/08-FAQ)** - Frequently asked questions

- **[๐Ÿ“ Examples](https://github.com/doobidoo/mcp-memory-service/wiki/09-Examples)** - Practical code examples and workflows



### ๐Ÿ“‚ Internal Documentation

- **[๐Ÿ“Š Repository Statistics](docs/statistics/REPOSITORY_STATISTICS.md)** - 10 months of development metrics, activity patterns, and insights

- **[๐Ÿ—๏ธ Architecture Specs](docs/architecture/)** - Search enhancement specifications and design documents

- **[๐Ÿ‘ฉโ€๐Ÿ’ป Development Docs](docs/development/)** - AI agent instructions, release checklist, refactoring notes

- **[๐Ÿš€ Deployment Guides](docs/deployment/)** - Docker, dual-service, and production deployment

- **[๐Ÿ“š Additional Guides](docs/guides/)** - Storage backends, migration, mDNS discovery



## โœจ Key Features



### ๐Ÿ† **Production-Ready Reliability** ๐Ÿ†• v8.9.0

- **Hybrid Backend** - Fast 5ms local SQLite + background Cloudflare sync (RECOMMENDED default)

  - Zero user-facing latency for cloud operations

  - Automatic multi-device synchronization

  - Graceful offline operation

- **Zero Database Locks** - Concurrent HTTP + MCP server access works flawlessly

  - Auto-configured SQLite pragmas (`busy_timeout=15000,cache_size=20000`)

  - WAL mode with proper multi-client coordination

  - Tested: 5/5 concurrent writes succeeded with no errors

- **Auto-Configuration** - Installer handles everything

  - SQLite pragmas for concurrent access

  - Cloudflare credentials with connection testing

  - Claude Desktop integration with hybrid backend

  - Graceful fallback to sqlite_vec if cloud setup fails



### ๐Ÿ“„ **Document Ingestion System** v8.6.0

- **Interactive Web UI** - Drag-and-drop document upload with real-time progress

- **Multiple Formats** - PDF, TXT, MD, JSON with intelligent chunking

- **Document Viewer** - Browse chunks, view metadata, search content

- **Smart Tagging** - Automatic tagging with length validation (max 100 chars)

- **Optional semtools** - Enhanced PDF/DOCX/PPTX parsing with LlamaParse

- **Security Hardened** - Path traversal protection, XSS prevention, input validation

- **7 New Endpoints** - Complete REST API for document management



### ๐Ÿ” **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

- **Document-aware search** - Query across uploaded documents and manual memories



### ๐Ÿ”— **Universal Compatibility**

- **Claude Desktop** - Native MCP integration

- **Claude Code** - **HTTP transport** + Memory-aware development with hooks

  - ๐ŸชŸ **Windows Support**: `/session-start` command for manual session initialization (workaround for issue #160)

  - ๐ŸŽ **macOS/Linux**: Full automatic SessionStart hooks + slash command

- **VS Code, Cursor, Continue** - IDE extensions

- **13+ AI applications** - REST API compatibility



### ๐Ÿ’พ **Flexible Storage**

- **Hybrid** ๐ŸŒŸ (RECOMMENDED) - Fast local SQLite + background Cloudflare sync (v8.9.0 default)

  - 5ms local reads with zero user-facing latency

  - Multi-device synchronization

  - Zero database locks with auto-configured pragmas

  - Automatic backups and cloud persistence

- **SQLite-vec** - Local-only storage (lightweight ONNX embeddings, 5ms reads)

  - Good for single-user offline use

  - No cloud dependencies

- **Cloudflare** - Cloud-only storage (global edge distribution with D1 + Vectorize)

  - Network-dependent performance



> **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-ml` for full ML capabilities.



### ๐Ÿš€ **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

- **Interactive Dashboard** - Web UI at http://127.0.0.1:8000/ for complete management



## ๐Ÿ’ก Basic Usage



### ๐Ÿ“„ **Document Ingestion** (v8.6.0+)

```bash

# Start HTTP dashboard server (separate from MCP server)

uv run python scripts/server/run_http_server.py



# Access interactive dashboard

open http://127.0.0.1:8000/



# Upload documents via CLI

curl -X POST http://127.0.0.1:8000/api/documents/upload \

  -F "file=@document.pdf" \

  -F "tags=documentation,reference"



# Search document content

curl -X POST http://127.0.0.1:8000/api/search \

  -H "Content-Type: application/json" \

  -d '{"query": "authentication flow", "limit": 10}'

```



### ๐Ÿ”— **Team Collaboration with OAuth** (v7.0.0+)

```bash

# Start OAuth-enabled HTTP server for team collaboration

export MCP_OAUTH_ENABLED=true

uv run python scripts/server/run_http_server.py



# 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**

```bash

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



```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



**Hybrid Backend (v8.9.0+ RECOMMENDED):**

```bash

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

```bash

# Local-only storage

export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec

export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"

```



## ๐Ÿ—๏ธ Architecture



```

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”

โ”‚   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 8000)   โ”‚    โ”‚ โ€ข Zero DB Locks โ”‚    โ”‚ Auto-Config โœ…  โ”‚

โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

```



## ๐Ÿ› ๏ธ 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

1. Fork the repository

2. Create a feature branch

3. Make your changes with tests

4. Submit a pull request



See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.



## ๐Ÿ†˜ Support



- **๐Ÿ“– Documentation**: [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) - Comprehensive guides

- **๐Ÿ› Bug Reports**: [GitHub Issues](https://github.com/doobidoo/mcp-memory-service/issues)

- **๐Ÿ’ฌ Discussions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)

- **๐Ÿ”ง Troubleshooting**: [Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)

- **โœ… Configuration Validator**: Run `python scripts/validation/validate_configuration_complete.py` to check your setup

- **๐Ÿ”„ Backend Sync Tools**: See [scripts/README.md](scripts/README.md#backend-synchronization) for Cloudflareโ†”SQLite sync



## ๐Ÿ“Š In Production



**Real-world metrics from active deployments:**

- **1700+ memories** stored and actively used across teams

- **5ms local reads** with hybrid backend (v8.9.0)

- **Zero database locks** with concurrent HTTP + MCP access (v8.9.0)

  - Tested: 5/5 concurrent writes succeeded

  - Auto-configured pragmas prevent lock errors

- **<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** setup success rate: **98.5%** (OAuth + hybrid backend)



## ๐Ÿ† Recognition



- [![Smithery](https://smithery.ai/badge/@doobidoo/mcp-memory-service)](https://smithery.ai/server/@doobidoo/mcp-memory-service) **Verified MCP Server**

- [![Glama AI](https://img.shields.io/badge/Featured-Glama%20AI-blue)](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](LICENSE) for details.



---



**Ready to supercharge your AI workflow?** ๐Ÿš€



๐Ÿ‘‰ **[Start with our Installation Guide](https://github.com/doobidoo/mcp-memory-service/wiki/01-Installation-Guide)** or explore the **[Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)** for comprehensive documentation.



*Transform your AI conversations into persistent, searchable knowledge that grows with you.*