Open-source memory backend for multi-agent systems. Agents store decisions, share causal knowledge graphs, and retrieve context in 5ms — without cloud lock-in or API costs. Works with LangGraph · CrewAI · AutoGen · any HTTP client · Claude Desktop Key capabilities for agent pipelines: - Framework-agnostic REST API — 15 endpoints, no MCP client library needed - Knowledge graph — agents share causal
Add this skill
npx mdskills install doobidoo/mcp-memory-serviceComprehensive memory persistence backend with REST API, knowledge graphs, and multi-agent support
1# mcp-memory-service23## Persistent Shared Memory for AI Agent Pipelines45Open-source memory backend for multi-agent systems.6Agents store decisions, share causal knowledge graphs, and retrieve7context in 5ms — without cloud lock-in or API costs.89**Works with LangGraph · CrewAI · AutoGen · any HTTP client · Claude Desktop**1011---1213[](https://opensource.org/licenses/Apache-2.0)14[](https://pypi.org/project/mcp-memory-service/)15[](https://pypi.org/project/mcp-memory-service/)16[](https://github.com/doobidoo/mcp-memory-service/stargazers)17[](https://github.com/langchain-ai/langgraph)18[](https://crewai.com)19[](https://github.com/microsoft/autogen)20[](https://claude.ai)21[](https://cursor.sh)2223---2425## Why Agents Need This2627| Without mcp-memory-service | With mcp-memory-service |28|---|---|29| Each agent run starts from zero | Agents retrieve prior decisions in 5ms |30| Memory is local to one graph/run | Memory is shared across all agents and runs |31| You manage Redis + Pinecone + glue code | One self-hosted service, zero cloud cost |32| No causal relationships between facts | Knowledge graph with typed edges (causes, fixes, contradicts) |33| Context window limits create amnesia | Autonomous consolidation compresses old memories |3435**Key capabilities for agent pipelines:**36- **Framework-agnostic REST API** — 15 endpoints, no MCP client library needed37- **Knowledge graph** — agents share causal chains, not just facts38- **`X-Agent-ID` header** — auto-tag memories by agent identity for scoped retrieval39- **`conversation_id`** — bypass deduplication for incremental conversation storage40- **SSE events** — real-time notifications when any agent stores or deletes a memory41- **Embeddings run locally via ONNX** — memory never leaves your infrastructure4243## Agent Quick Start4445```bash46pip install mcp-memory-service47MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http48# REST API running at http://localhost:800049```5051```python52import httpx5354BASE_URL = "http://localhost:8000"5556# Store — auto-tag with X-Agent-ID header57async with httpx.AsyncClient() as client:58 await client.post(f"{BASE_URL}/api/memories", json={59 "content": "API rate limit is 100 req/min",60 "tags": ["api", "limits"],61 }, headers={"X-Agent-ID": "researcher"})62 # Stored with tags: ["api", "limits", "agent:researcher"]6364# Search — scope to a specific agent65 results = await client.post(f"{BASE_URL}/api/memories/search", json={66 "query": "API rate limits",67 "tags": ["agent:researcher"],68 })69 print(results.json()["memories"])70```7172**Framework-specific guides:** [docs/agents/](docs/agents/)7374## Comparison with Alternatives7576| | Mem0 | Zep | DIY Redis+Pinecone | **mcp-memory-service** |77|---|---|---|---|---|78| License | Proprietary | Enterprise | — | **Apache 2.0** |79| Cost | Per-call API | Enterprise | Infra costs | **$0** |80| Framework integration | SDK | SDK | Manual | **REST API (any HTTP client)** |81| Knowledge graph | No | Limited | No | **Yes (typed edges)** |82| Auto consolidation | No | No | No | **Yes (decay + compression)** |83| On-premise embeddings | No | No | Manual | **Yes (ONNX, local)** |84| Privacy | Cloud | Cloud | Partial | **100% local** |85| Hybrid search | No | Yes | Manual | **Yes (BM25 + vector)** |86| MCP protocol | No | No | No | **Yes** |87| REST API | Yes | Yes | Manual | **Yes (15 endpoints)** |8889---9091## Stop Re-Explaining Your Project to AI Every Session9293<p align="center">94 <img width="240" alt="MCP Memory Service" src="https://github.com/user-attachments/assets/eab1f341-ca54-445c-905e-273cd9e89555" />95</p>9697Your 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.**9899**MCP Memory Service solves this.**100101It 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.102103## 🎥 2-Minute Video Demo104105<div align="center">106 <a href="https://www.youtube.com/watch?v=veJME5qVu-A">107 <img src="https://img.youtube.com/vi/veJME5qVu-A/maxresdefault.jpg" alt="MCP Memory Service Demo" width="700">108 </a>109 <p><em>Technical showcase: Performance, Architecture, AI/ML Intelligence & Developer Experience</em></p>110</div>111112### ⚡ Works With Your Favorite AI Tools113114#### 🤖 Agent Frameworks (REST API)115**LangGraph** · **CrewAI** · **AutoGen** · **Any HTTP Client** · **OpenClaw/Nanobot** · **Custom Pipelines**116117#### 🖥️ CLI & Terminal AI (MCP)118**Claude Code** · **Gemini Code Assist** · **Aider** · **GitHub Copilot CLI** · **Amp** · **Continue** · **Zed** · **Cody**119120#### 🎨 Desktop & IDE (MCP)121**Claude Desktop** · **VS Code** · **Cursor** · **Windsurf** · **Raycast** · **JetBrains** · **Sourcegraph** · **Qodo**122123#### 💬 Chat Interfaces (MCP)124**ChatGPT** (Developer Mode) · **Claude Web**125126**Works seamlessly with any MCP-compatible client or HTTP client** - whether you're building agent pipelines, coding in the terminal, IDE, or browser.127128> **💡 NEW**: ChatGPT now supports MCP! Enable Developer Mode to connect your memory service directly. [See setup guide →](https://github.com/doobidoo/mcp-memory-service/discussions/377#discussioncomment-15605174)129130---131132## 🚀 Get Started in 60 Seconds133134**Express Install** (recommended for most users):135136```bash137pip install mcp-memory-service138# Auto-configure for Claude Desktop (macOS/Linux)139python -m mcp_memory_service.scripts.installation.install --quick140```141142**What just happened?**143- ✅ Installed memory service144- ✅ Configured optimal backend (SQLite)145- ✅ Set up Claude Desktop integration146- ✅ Enabled automatic context capture147148**Next:** Restart Claude Desktop. Your AI now remembers everything across sessions.149150<details>151<summary><strong>📦 Alternative: PyPI + Manual Configuration</strong></summary>152153```bash154pip install mcp-memory-service155```156157Then add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):158```json159{160 "mcpServers": {161 "memory": {162 "command": "memory",163 "args": ["server"]164 }165 }166}167```168169</details>170171<details>172<summary><strong>🔧 Advanced: Custom Backends & Team Setup</strong></summary>173174For production deployments, team collaboration, or cloud sync:175176```bash177git clone https://github.com/doobidoo/mcp-memory-service.git178cd mcp-memory-service179python scripts/installation/install.py180```181182Choose from:183- **SQLite** (local, fast, single-user)184- **Cloudflare** (cloud, multi-device sync)185- **Hybrid** (best of both: 5ms local + background cloud sync)186187</details>188189---190191## 💡 Why You Need This192193### The Problem194195| Session 1 | Session 2 (Fresh Start) |196|-----------|-------------------------|197| You: "We're building a Next.js app with Prisma and tRPC" | AI: "What's your tech stack?" ❌ |198| AI: "Got it, I see you're using App Router" | You: *Explains architecture again for 10 minutes* 😤 |199| You: "Add authentication with NextAuth" | AI: "Should I use Pages Router or App Router?" ❌ |200201### The Solution202203| Session 1 | Session 2 (Fresh Start) |204|-----------|-------------------------|205| 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?" ✅ |206| AI: "Got it, I see you're using App Router" | You: "Add OAuth login" |207| You: "Add authentication with NextAuth" | AI: "I'll integrate NextAuth with your existing Prisma setup." ✅ |208209**Result:** Zero re-explaining. Zero context loss. Just continuous, intelligent collaboration.210211---212213## 🌐 SHODH Ecosystem Compatibility214215MCP Memory Service is **fully compatible** with the [SHODH Unified Memory API Specification v1.0.0](https://github.com/varun29ankuS/shodh-memory/blob/main/specs/openapi.yaml), enabling seamless interoperability across the SHODH ecosystem.216217### Compatible Implementations218219| Implementation | Backend | Embeddings | Use Case |220|----------------|---------|------------|----------|221| **[shodh-memory](https://github.com/varun29ankuS/shodh-memory)** | RocksDB | MiniLM-L6-v2 (ONNX) | Reference implementation |222| **[shodh-cloudflare](https://github.com/doobidoo/shodh-cloudflare)** | Cloudflare Workers + Vectorize | Workers AI (bge-small) | Edge deployment, multi-device sync |223| **mcp-memory-service** (this) | SQLite-vec / Hybrid | MiniLM-L6-v2 (ONNX) | Desktop AI assistants (MCP) |224225### Unified Schema Support226227All SHODH implementations share the same memory schema:228- ✅ **Emotional Metadata**: `emotion`, `emotional_valence`, `emotional_arousal`229- ✅ **Episodic Memory**: `episode_id`, `sequence_number`, `preceding_memory_id`230- ✅ **Source Tracking**: `source_type`, `credibility`231- ✅ **Quality Scoring**: `quality_score`, `access_count`, `last_accessed_at`232233**Interoperability Example:**234Export memories from mcp-memory-service → Import to shodh-cloudflare → Sync across devices → Full fidelity preservation of emotional_valence, episode_id, and all spec fields.235236---237238## ✨ Quick Start Features239240🧠 **Persistent Memory** – Context survives across sessions with semantic search241🔍 **Smart Retrieval** – Finds relevant context automatically using AI embeddings242⚡ **5ms Speed** – Instant context injection, no latency243🔄 **Multi-Client** – Works across 13+ AI applications244☁️ **Cloud Sync** – Optional Cloudflare backend for team collaboration245🔒 **Privacy-First** – Local-first, you control your data246📊 **Web Dashboard** – Visualize and manage memories at `http://localhost:8000`247🧬 **Knowledge Graph** – Interactive D3.js visualization of memory relationships 🆕248249### 🖥️ Dashboard Preview (v9.3.0)250251<p align="center">252 <img src="https://raw.githubusercontent.com/wiki/doobidoo/mcp-memory-service/images/dashboard/mcp-memory-dashboard-v9.3.0-tour.gif" alt="MCP Memory Dashboard Tour" width="800"/>253</p>254255**8 Dashboard Tabs:** Dashboard • Search • Browse • Documents • Manage • Analytics • **Quality** (NEW) • API Docs256257📖 See [Web Dashboard Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Web-Dashboard-Guide) for complete documentation.258259---260261262## 🆕 Latest Release: **v10.17.16** (February 23, 2026)263264**Security: Fix minimatch ReDoS and Replace Abandoned PyPDF2 with pypdf**265266**What's New:**267- **minimatch ReDoS fixed** (Dependabot #3, #6 — High severity): Pinned `minimatch` to `^10.2.1` in npm test packages, eliminating a ReDoS attack vector.268- **PyPDF2 replaced with pypdf** (Dependabot moderate — Infinite Loop): Migrated from the unmaintained `PyPDF2` to its official successor `pypdf`; no functional change to PDF ingestion.269270---271272**Previous Releases**:273- **v10.17.15** - Permission-Request Hook Made Opt-In (no silent global hook installation, CLI flags added)274- **v10.17.14** - Security + Performance: CVE-2024-23342 (ecdsa Minerva attack) eliminated via PyJWT migration, CWE-209 fixed, MCP_ASSOCIATION_MAX_PAIRS raised 100→1000275- **v10.17.13** - Security: Final 4 CodeQL Alerts Resolved (log-injection, stack-trace-exposure) — Zero Open Alerts276- **v10.17.12** - Security: File Restoration + 43 CodeQL Alerts (repeated-import, multiple-definition, log-injection, stack-trace-exposure)277- **v10.17.11** - Security: 6 CodeQL Alerts Resolved (log injection, stack-trace-exposure, unused variable)278- **v10.17.10** - Security: All 30 Remaining CodeQL Alerts Resolved (log injection, clear-text logging, URL redirection, stack-trace-exposure)279- **v10.17.9** - Security: 17 CodeQL Alerts Resolved (clear-text logging, log injection, tarslip, ReDoS, URL redirection)280- **v10.17.8** - Security: 27 CodeQL Alerts Resolved (clear-text logging, log injection, stack-trace-exposure, URL redirection, polynomial ReDoS, empty-except, unused imports)281- **v10.17.7** - Security: 100 CodeQL Alerts Resolved (security + code quality)282- **v10.17.6** - Code Quality: 100 CodeQL Import Alerts Resolved Across 51 Files (unused-import, repeated-import, cyclic-import)283- **v10.17.5** - Security Patch: upgrade 15 vulnerable dependencies (38 Dependabot alerts - h11, aiohttp, starlette, cryptography, pillow, protobuf, and more)284- **v10.17.3** - Security + Code Quality: 21 CodeQL Scanning Alerts Resolved (log injection CWE-117, HTTPClientStorage signature, import-time prints)285- **v10.17.2** - CI Stability Fixes: uv CLI test timeout 60s→120s, CI job timeout 10→20min, root install.py test skip guard286- **v10.17.1** - Hook System Bug Fixes + Root Installer + Session-Start Reliability (session-end SyntaxError on Node.js v24, MCP_HTTP_PORT detection, exponential backoff retry)287- **v10.17.0** - Default "untagged" Tag for All Tagless Memories + Cleanup Script (306 production memories retroactively fixed)288- **v10.16.1** - Windows MCP Initialization Timeout Fix (`MCP_INIT_TIMEOUT` env override, 7 unit tests)289- **v10.16.0** - Agentic AI Market Repositioning with REST API Integration Guides (LangGraph, CrewAI, AutoGen guides, X-Agent-ID header auto-tagging, agent: tag namespace)290- **v10.15.1** - Stale Venv Detection for Moved/Renamed Projects (auto-recreate venv when pip shebang interpreter path is missing)291- **v10.15.0** - Config Validation & Safe Environment Parsing (`validate_config()` at startup, `safe_get_int_env()`, 8 new robustness tests)292- **v10.14.0** - `conversation_id` Support for Incremental Conversation Saves (semantic dedup bypass, metadata storage, all backends)293- **v10.13.2** - Consolidation & Hybrid Storage Bug Fixes (missing StorageProtocol proxy methods, timezone-aware datetime, contributed by @VibeCodeChef)294- **v10.13.1** - Critical Bug Fixes (tag search limits, REST API field access, metadata corruption, hash display, prompt handler crashes)295- **v10.13.0** - Test Suite Stability (100% pass rate, 1,161 passing tests, authentication testing patterns)296- **v10.12.1** - Custom Memory Type Configuration Test Fixes (test isolation, environment cleanup)297- **v10.12.0** - Configurable Memory Type Ontology (75 types supporting PM and knowledge work, custom type configuration)298- **v10.11.2** - Tag Filtering & Security Hardening (DoS protection, SQL-level optimization, comprehensive tests)299- **v10.11.1** - MCP Prompt Handlers Fix (all 5 prompt handlers working, 100% success rate restored)300- **v10.11.0** - SQLite Integrity Monitoring (automatic corruption detection/repair, 3.5ms overhead, emergency export)301- **v10.10.6** - Test Infrastructure Improvements (Python 3.11 compatibility, pytest-benchmark, coverage baseline)302- **v10.10.5** - Embedding Dimension Cache Fix (dimension mismatch prevention, cache consistency)303- **v10.10.4** - CLI Batch Ingestion Fix (async bug causing "NoneType" errors, 100% success rate restored)304- **v10.10.3** - Test Infrastructure & Memory Scoring Fixes (graph validation, test authentication, score capping)305- **v10.10.2** - Memory Injection Filtering (minRelevanceScore enforcement, project-affinity filter, security hardening)306- **v10.10.1** - Search Handler Fix, Import Error Fix, Security Enhancement, Improved Exact Search307- **v10.10.0** - Environment Configuration Viewer (11 categorized parameters, sensitive masking, Settings Panel integration)308- **v10.9.0** - Batched Inference Performance (4-16x GPU speedup, 2.3-2.5x CPU speedup with adaptive GPU dispatch)309- **v10.9.0** - Batched Inference Performance (4-16x GPU speedup, 2.3-2.5x CPU speedup with adaptive GPU dispatch)310- **v10.8.0** - Hybrid BM25 + Vector Search (combines keyword matching with semantic search, solves exact match problem)311- **v10.7.2** - Server Management Button Fix (Settings modal buttons causing page reload)312- **v10.7.1** - Dashboard API Authentication Fix (complete auth coverage for all endpoints)313- **v10.7.0** - Backup UI Enhancements (View Backups modal, backup directory display, enhanced API)314- **v10.6.1** - Dashboard SSE Authentication Fix (EventSource API compatibility with query params)315- **v10.6.0** - Server Management Dashboard: Complete server administration from Dashboard Settings316- **v10.5.1** - Test Environment Safety: 4 critical scripts to prevent production database testing317- **v10.5.0** - Dashboard Authentication UI: Graceful user experience (authentication modal, API key/OAuth flows)318- **v10.4.6** - Documentation Enhancement: HTTP dashboard authentication requirements clarified (authentication setup examples)319- **v10.4.5** - Unified CLI Interface: `memory server --http` flag (easier UX, single command)320- **v10.4.4** - CRITICAL Security Fix: Timing attack vulnerability in API key comparison (CWE-208) + API Key Auth without OAuth321- **v10.4.2** - Docker Container Startup Fix (ModuleNotFoundError: aiosqlite)322- **v10.4.1** - Bug Fix: Time Expression Parsing (natural language time expressions fixed)323- **v10.4.0** - Memory Hook Quality Improvements (semantic deduplication, tag normalization, budget optimization)324- **v10.2.1** - MCP Client Compatibility & Delete Operations Fixes (integer enum fix, method name corrections)325- **v10.2.0** - External Embedding API Support (vLLM, Ollama, TEI, OpenAI integration)326- **v10.1.2** - Windows PowerShell 7+ Service Management Fix (SSL compatibility for manage_service.ps1)327- **v10.1.1** - Dependency & Windows Compatibility Fixes (requests dependency, PowerShell 7+ SSL support)328- **v10.1.0** - Python 3.14 Support (Extended compatibility to 3.10-3.14, tokenizers upgrade)329- **v10.0.3** - CRITICAL FIX: Backup Scheduler Now Works (2 critical bugs fixed, FastAPI lifespan integration)330- **v10.0.2** - Tool List Cleanup (Only 12 unified tools visible, 64% tool reduction complete)331- **v10.0.1** - CRITICAL HOTFIX: MCP tools loading restored (Python boolean fix)332- **v10.0.0** - ⚠️ BROKEN: Major API Redesign (64% Tool Consolidation) - Tools failed to load, use v10.0.2 instead333- **v9.3.1** - Critical shutdown bug fix (SIGTERM/SIGINT handling, clean server termination)334- **v9.3.0** - Relationship Inference Engine (Intelligent association typing, multi-factor analysis, confidence scoring)335- **v9.2.1** - Critical Knowledge Graph bug fix (MigrationRunner, 37 test fixes, idempotent migrations)336- **v9.2.0** - Knowledge Graph Dashboard with D3.js v7.9.0 (Interactive force-directed visualization, 6 typed relationships, 7-language support)337- **v9.0.6** - OAuth Persistent Storage Backend (SQLite-based for multi-worker deployments, <10ms token operations)338- **v9.0.5** - CRITICAL HOTFIX: OAuth 2.1 token endpoint routing bug fixed (HTTP 422 errors eliminated)339- **v9.0.4** - OAuth validation blocking server startup fixed (OAUTH_ENABLED default changed to False, validation made non-fatal)340- **v9.0.2** - Critical hotfix: Includes actual code fix for mass deletion bug (confirm_count parameter now REQUIRED)341- **v9.0.1** - Incorrectly tagged release (⚠️ Does NOT contain fix - use v9.0.2 instead)342- **v9.0.0** - Phase 0 Ontology Foundation (⚠️ Contains critical bug - upgrade to v9.0.2 immediately)343- **v8.76.0** - Official Lite Distribution (90% size reduction: 7.7GB → 805MB, dual publishing workflow)344- **v8.75.1** - Hook Installer Fix (flexible MCP server naming support, custom configurations)345- **v8.75.0** - Lightweight ONNX Quality Scoring (90% installation size reduction: 7.7GB → 805MB, same quality scoring performance)346- **v8.74.0** - Cross-Platform Orphan Process Cleanup (database lock prevention, automatic orphan detection after crashes)347- **v8.73.0** - Universal Permission Request Hook (auto-approves safe operations, eliminates repetitive prompts for 12+ tools)348- **v8.72.0** - Graph Traversal MCP Tools (find_connected_memories, find_shortest_path, get_memory_subgraph - 5-25ms, 30x faster)349- **v8.71.0** - Memory Management APIs and Graceful Shutdown (cache cleanup, process monitoring, production-ready memory management)350- **v8.70.0** - User Override Commands for Memory Hooks (`#skip`/`#remember` for manual memory control)351- **v8.69.0** - MCP Tool Annotations for Improved LLM Decision-Making (readOnlyHint/destructiveHint, auto-approval for 12 tools)352- **v8.68.2** - Platform Detection Improvements (Apple Silicon MPS support, 3-5x faster, comprehensive hardware detection)353- **v8.68.1** - Critical Data Integrity Bug Fix - Hybrid Backend (ghost memories fixed, 5 method fixes)354- **v8.68.0** - Update & Restart Automation (87% time reduction, <2 min workflow, cross-platform scripts)355- **v8.62.13** - HTTP-MCP Bridge API Endpoint Fix (Remote deployments restored with POST endpoints)356- **v8.62.12** - Quality Analytics UI Fixed ("Invalid Date" and "ID: undefined" bugs)357- **v8.62.10** - Document Ingestion Bug Fixed (NameError in web console, circular import prevention)358- **v8.62.8** - Environment Configuration Loading Bug Fixed (.env discovery, python-dotenv dependency)359- **v8.62.7** - Windows SessionStart Hook Bug Fixed in Claude Code 2.0.76+ (no more Windows hanging)360- **v8.62.6** - CRITICAL PRODUCTION HOTFIX: SQLite Pragmas Container Restart Bug (database locking errors after container restarts)361- **v8.62.5** - Test Suite Stability: 40 Tests Fixed (99% pass rate, 68% → 99% improvement)362- **v8.62.4** - CRITICAL BUGFIX: SQLite-Vec KNN Syntax Error (semantic search completely broken on sqlite-vec/hybrid backends)363- **v8.62.3** - CRITICAL BUGFIX: Memory Recall Handler Import Error (time_parser import path correction)364- **v8.62.2** - Test Infrastructure Improvements (5 test failures resolved, consolidation & performance suite stability)365- **v8.62.1** - Critical Bug Fix: SessionEnd Hook Real Conversation Data (hardcoded mock data fix, robust transcript parsing)366- **v8.62.0** - Comprehensive Test Coverage Infrastructure - 100% Handler Coverage Achievement (35 tests, 800+ lines, CI/CD gate)367- **v8.61.2** - CRITICAL HOTFIX: delete_memory KeyError Fix (response parsing, validated delete flow)368- **v8.61.1** - CRITICAL HOTFIX: Import Error Fix (5 MCP tools restored, relative import path correction)369- **v8.60.0** - Health Check Strategy Pattern Refactoring - Phase 3.1 (78% complexity reduction, Strategy pattern)370- **v8.59.0** - Server Architecture Refactoring - Phase 2 (40% code reduction, 29 handlers extracted, 5 specialized modules)371- **v8.58.0** - Test Infrastructure Stabilization - 100% Pass Rate Achievement (81.6% → 100%, 52 tests fixed)372- **v8.57.1** - Hotfix: Python -m Execution Support for CI/CD (server/__main__.py, --version/--help flags)373- **v8.57.0** - Test Infrastructure Improvements - Major Stability Boost (+6% pass rate, 32 tests fixed)374- **v8.56.0** - Server Architecture Refactoring - Phase 1 (4 focused modules, -7% lines, backward compatible)375- **v8.55.0** - AI-Optimized MCP Tool Descriptions (30-50% reduction in incorrect tool selection)376- **v8.54.4** - Critical MCP Tool Bugfix (check_database_health method call correction)377- **v8.54.3** - Chunked Storage Error Reporting Fix (accurate failure messages, partial success tracking)378- **v8.54.2** - Offline Mode Fix (opt-in offline mode, first-time install support)379- **v8.54.1** - UV Virtual Environment Support (installer compatibility fix)380- **v8.54.0** - Smart Auto-Capture System (intelligent pattern detection, 6 memory types, bilingual support)381- **v8.53.0** - Windows Service Management (Task Scheduler support, auto-startup, watchdog monitoring, 819 lines PowerShell automation)382- **v8.52.2** - Hybrid Backend Maintenance Enhancement (multi-PC association cleanup, drift prevention, Vectorize error handling)383- **v8.52.1** - Windows Embedding Fallback & Script Portability (DLL init failure fix, MCP_HTTP_PORT support)384- **v8.52.0** - Time-of-Day Emoji Icons (8 time-segment indicators, dark mode support, automatic timezone)385- **v8.51.0** - Graph Database Architecture (30x query performance, 97% storage reduction for associations)386- **v8.50.1** - Critical Bug Fixes (MCP_EMBEDDING_MODEL fix, installation script backend support, i18n quality analytics complete)387- **v8.50.0** - Fallback Quality Scoring (DeBERTa + MS-MARCO hybrid, technical content rescue, 20/20 tests passing)388- **v8.49.0** - DeBERTa Quality Classifier (absolute quality assessment, eliminates self-matching bias)389- **v8.48.4** - Cloudflare D1 Drift Detection Performance (10-100x faster queries, numeric comparison fix)390- **v8.48.3** - Code Execution Hook Fix - 75% token reduction now working (fixed time_filter parameter, Python warnings, venv detection)391- **v8.48.2** - HTTP Server Auto-Start & Time Parser Improvements (smart service management, "last N periods" support)392- **v8.48.1** - Critical Hotfix - Startup Failure Fix (redundant calendar import removed, immediate upgrade required)393- **v8.48.0** - CSV-Based Metadata Compression (78% size reduction, 100% sync success, metadata validation)394- **v8.47.1** - ONNX Quality Evaluation Bug Fixes (self-match fix, association pollution, sync queue overflow, realistic distribution)395- **v8.47.0** - Association-Based Quality Boost (connection-based enhancement, network effect leverage, metadata persistence)396- **v8.46.3** - Quality Score Persistence Fix (ONNX scores in hybrid backend, metadata normalization)397- **v8.46.2** - Session-Start Hook Crash Fix + Hook Installer Improvements (client-side tag filtering, isolated version metadata)398- **v8.46.1** - Windows Hooks Installer Fix + Quality System Integration (UTF-8 console configuration, backend quality scoring)399- **v8.45.3** - ONNX Ranker Model Export Fix (automatic model export, offline mode support, 7-16ms CPU performance)400- **v8.45.2** - Dashboard Dark Mode Consistency Fixes (global CSS overrides, Chart.js dark mode support)401- **v8.45.1** - Quality System Test Infrastructure Fixes (HTTP API router, storage retrieval, async test client)402- **v8.45.0** - Memory Quality System - AI-Driven Automatic Quality Scoring (ONNX-powered local SLM, multi-tier fallback, quality-based retention)403- **v8.44.0** - Multi-Language Expansion (Japanese, Korean, German, French, Spanish - 359 keys each, complete i18n coverage)404- **v8.43.0** - Internationalization & Quality Automation (English/Chinese i18n, Claude branch automation, quality gates)405- **v8.42.1** - MCP Resource Handler Fix (`AttributeError` with Pydantic AnyUrl objects)406- **v8.42.0** - Memory Awareness Enhancements (visible memory injection, quality session summaries, LLM-powered summarization)407- **v8.41.2** - Hook Installer Utility File Deployment (ALL 14 utilities copied, future-proof glob pattern)408- **v8.41.1** - Context Formatter Memory Sorting (recency sorting within categories, newest first)409- **v8.41.0** - Session Start Hook Reliability Improvements (error suppression, clean output, memory filtering, classification fixes)410- **v8.40.0** - Session Start Version Display (automatic version comparison, PyPI status labels)411- **v8.39.1** - Dashboard Analytics Bug Fixes: Three critical fixes (top tags filtering, recent activity display, storage report fields)412- **v8.39.0** - Performance Optimization: Storage-layer date-range filtering (10x faster analytics, 97% data transfer reduction)413- **v8.38.1** - Critical Hotfix: HTTP MCP JSON-RPC 2.0 compliance fix (Claude Code/Desktop connection failures resolved)414- **v8.38.0** - Code Quality: Phase 2b COMPLETE (~176-186 lines duplicate code eliminated, 10 consolidations)415- **v8.37.0** - Code Quality: Phase 2a COMPLETE (5 duplicate high-complexity functions eliminated)416- **v8.36.1** - Critical Hotfix: HTTP server startup crash fix (forward reference error in analytics.py)417- **v8.36.0** - Code Quality: Phase 2 COMPLETE (100% of target achieved, -39 complexity points)418- **v8.35.0** - Code Quality: Phase 2 Batch 1 (install.py, cloudflare.py, -15 complexity points)419- **v8.34.0** - Code Quality: Phase 2 Complexity Reduction (analytics.py refactored, 11 → 6-7 complexity)420- **v8.33.0** - Critical Installation Bug Fix + Code Quality Improvements (dead code cleanup, automatic MCP setup)421- **v8.32.0** - Code Quality Excellence: pyscn Static Analysis Integration (multi-layer QA workflow)422- **v8.31.0** - Revolutionary Batch Update Performance (21,428x faster memory consolidation)423- **v8.30.0** - Analytics Intelligence: Adaptive Charts & Critical Data Fixes (accurate trend visualization)424- **v8.28.1** - Critical HTTP MCP Transport JSON-RPC 2.0 Compliance Fix (Claude Code compatibility)425- **v8.28.0** - Cloudflare AND/OR Tag Filtering (unified search API, 3-5x faster hybrid sync)426- **v8.27.1** - Critical Hotfix: Timestamp Regression (created_at preservation during metadata sync)427- **v8.26.0** - Revolutionary MCP Performance (534,628x faster tools, 90%+ cache hit rate)428- **v8.25.0** - Hybrid Backend Drift Detection (automatic metadata sync, bidirectional awareness)429- **v8.24.4** - Code Quality Improvements from Gemini Code Assist (regex sanitization, DOM caching)430- **v8.24.3** - Test Coverage & Release Agent Improvements (tag+time filtering tests, version history fix)431- **v8.24.2** - CI/CD Workflow Fixes (bash errexit handling, exit code capture)432- **v8.24.1** - Test Infrastructure Improvements (27 test failures resolved, 63% → 71% pass rate)433- **v8.24.0** - PyPI Publishing Enabled (automated package publishing via GitHub Actions)434- **v8.23.1** - Stale Virtual Environment Prevention System (6-layer developer protection)435- **v8.23.0** - Consolidation Scheduler via Code Execution API (88% token reduction)436437**📖 Full Details**: [CHANGELOG.md](CHANGELOG.md) | [All Releases](https://github.com/doobidoo/mcp-memory-service/releases)438439---440441## Migration to v9.0.0442443**⚡ TL;DR**: No manual migration needed - upgrades happen automatically!444445**Breaking Changes:**446- **Memory Type Ontology**: Legacy types auto-migrate to new taxonomy (task→observation, note→observation)447- **Asymmetric Relationships**: Directed edges only (no longer bidirectional)448449**Migration Process:**4501. Stop your MCP server4512. Update to latest version (`git pull` or `pip install --upgrade mcp-memory-service`)4523. Restart server - automatic migrations run on startup:453 - Database schema migrations (009, 010)454 - Memory type soft-validation (legacy types → observation)455 - No tag migration needed (backward compatible)456457**Safety**: Migrations are idempotent and safe to re-run458459---460461### Breaking Changes462463#### 1. Memory Type Ontology464465**What Changed:**466- Legacy memory types (task, note, standard) are deprecated467- New formal taxonomy: 5 base types (observation, decision, learning, error, pattern) with 21 subtypes468- Type validation now defaults to 'observation' for invalid types (soft validation)469470**Migration Process:**471✅ **Automatic** - No manual action required!472473When you restart the server with v9.0.0:474- Invalid memory types are automatically soft-validated to 'observation'475- Database schema updates run automatically476- Existing memories continue to work without modification477478**New Memory Types:**479- observation: General observations, facts, and discoveries480- decision: Decisions and planning481- learning: Learnings and insights482- error: Errors and failures483- pattern: Patterns and trends484485**Backward Compatibility:**486- Existing memories will be auto-migrated (task→observation, note→observation, standard→observation)487- Invalid types default to 'observation' (no errors thrown)488489#### 2. Asymmetric Relationships490491**What Changed:**492- Asymmetric relationships (causes, fixes, supports, follows) now store only directed edges493- Symmetric relationships (related, contradicts) continue storing bidirectional edges494- Database migration (010) removes incorrect reverse edges495496**Migration Required:**497No action needed - database migration runs automatically on startup.498499**Code Changes Required:**500If your code expects bidirectional storage for asymmetric relationships:501502```python503# OLD (will no longer work):504# Asymmetric relationships were stored bidirectionally505result = storage.find_connected(memory_id, relationship_type="causes")506507# NEW (correct approach):508# Use direction parameter for asymmetric relationships509result = storage.find_connected(510 memory_id,511 relationship_type="causes",512 direction="both" # Explicit direction required for asymmetric types513)514```515516**Relationship Types:**517- Asymmetric: causes, fixes, supports, follows (A→B ≠ B→A)518- Symmetric: related, contradicts (A↔B)519520### Performance Improvements521522- ontology validation: 97.5x faster (module-level caching)523- Type lookups: 35.9x faster (cached reverse maps)524- Tag validation: 47.3% faster (eliminated double parsing)525526### Testing527528- 829/914 tests passing (90.7%)529- 80 new ontology tests with 100% backward compatibility530- All API/HTTP integration tests passing531532### Support533534If you encounter issues during migration:535- Check [Troubleshooting Guide](docs/troubleshooting/)536- Review [CHANGELOG.md](CHANGELOG.md) for detailed changes537- Open an issue: https://github.com/doobidoo/mcp-memory-service/issues538539---540541## 📚 Documentation & Resources542543- **[Agent Integration Guides](docs/agents/)** 🆕 – LangGraph, CrewAI, AutoGen, HTTP generic544- **[Installation Guide](docs/installation.md)** – Detailed setup instructions545- **[Configuration Guide](docs/mastery/configuration-guide.md)** – Backend options and customization546- **[Architecture Overview](docs/architecture.md)** – How it works under the hood547- **[Team Setup Guide](docs/teams.md)** – OAuth and cloud collaboration548- **[Knowledge Graph Dashboard](docs/features/knowledge-graph-dashboard.md)** 🆕 – Interactive graph visualization guide549- **[Troubleshooting](docs/troubleshooting/)** – Common issues and solutions550- **[API Reference](docs/api.md)** – Programmatic usage551- **[Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)** – Complete documentation552- [](https://deepwiki.com/doobidoo/mcp-memory-service) – AI-powered documentation assistant553554---555556## 🤝 Contributing557558We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.559560**Quick Development Setup:**561```bash562git clone https://github.com/doobidoo/mcp-memory-service.git563cd mcp-memory-service564pip install -e . # Editable install565pytest tests/ # Run test suite566```567568---569570## ⭐ Support571572If this saves you time, give us a star! ⭐573574- **Issues**: [GitHub Issues](https://github.com/doobidoo/mcp-memory-service/issues)575- **Discussions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)576- **Wiki**: [Documentation Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)577578---579580## 📄 License581582Apache 2.0 – See [LICENSE](LICENSE) for details.583584---585586<p align="center">587 <strong>Never explain your project to AI twice.</strong><br/>588 Start using MCP Memory Service today.589</p>590591## ⚠️ v6.17.0+ Script Migration Notice592593**Updating from an older version?** Scripts have been reorganized for better maintainability:594- **Recommended**: Use `python -m mcp_memory_service.server` in your Claude Desktop config (no path dependencies!)595- **Alternative 1**: Use `uv run memory server` with UV tooling596- **Alternative 2**: Update path from `scripts/run_memory_server.py` to `scripts/server/run_memory_server.py`597- **Backward compatible**: Old path still works with a migration notice598599## ⚠️ First-Time Setup Expectations600601On your first run, you'll see some warnings that are **completely normal**:602603- **"WARNING: Failed to load from cache: No snapshots directory"** - The service is checking for cached models (first-time setup)604- **"WARNING: Using TRANSFORMERS_CACHE is deprecated"** - Informational warning, doesn't affect functionality605- **Model download in progress** - The service automatically downloads a ~25MB embedding model (takes 1-2 minutes)606607These 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).608609### 🐍 Python 3.13 Compatibility Note610611**sqlite-vec** may not have pre-built wheels for Python 3.13 yet. If installation fails:612- The installer will automatically try multiple installation methods613- Consider using Python 3.12 for the smoothest experience: `brew install python@3.12`614- Alternative: Use Cloudflare backend with `--storage-backend cloudflare`615- See [Troubleshooting Guide](docs/troubleshooting/general.md#python-313-sqlite-vec-issues) for details616617### 🍎 macOS SQLite Extension Support618619**macOS users** may encounter `enable_load_extension` errors with sqlite-vec:620- **System Python** on macOS lacks SQLite extension support by default621- **Solution**: Use Homebrew Python: `brew install python && rehash`622- **Alternative**: Use pyenv: `PYTHON_CONFIGURE_OPTS='--enable-loadable-sqlite-extensions' pyenv install 3.12.0`623- **Fallback**: Use Cloudflare or Hybrid backend: `--storage-backend cloudflare` or `--storage-backend hybrid`624- See [Troubleshooting Guide](docs/troubleshooting/general.md#macos-sqlite-extension-issues) for details625626## 🎯 Memory Awareness in Action627628**Intelligent Context Injection** - See how the memory service automatically surfaces relevant information at session start:629630<img src="docs/assets/images/memory-awareness-hooks-example.png" alt="Memory Awareness Hooks in Action" width="100%" />631632**What you're seeing:**633- 🧠 **Automatic memory injection** - 8 relevant memories found from 2,526 total634- 📂 **Smart categorization** - Recent Work, Current Problems, Additional Context635- 📊 **Git-aware analysis** - Recent commits and keywords automatically extracted636- 🎯 **Relevance scoring** - Top memories scored at 100% (today), 89% (8d ago), 84% (today)637- ⚡ **Fast retrieval** - SQLite-vec backend with 5ms read performance638- 🔄 **Background sync** - Hybrid backend syncing to Cloudflare639640**Result**: Claude starts every session with full project context - no manual prompting needed.641642## 📚 Complete Documentation643644**👉 Visit our comprehensive [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) for detailed guides:**645646### 🧠 v7.1.3 Natural Memory Triggers (Latest)647- **[Natural Memory Triggers v7.1.3 Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Natural-Memory-Triggers-v7.1.0)** - Intelligent automatic memory awareness648 - ✅ **85%+ trigger accuracy** with semantic pattern detection649 - ✅ **Multi-tier performance** (50ms instant → 150ms fast → 500ms intensive)650 - ✅ **CLI management system** for real-time configuration651 - ✅ **Git-aware context** integration for enhanced relevance652 - ✅ **Zero-restart installation** with dynamic hook loading653654### 🆕 v7.0.0 OAuth & Team Collaboration655- **[🔐 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 guide656- **[🔗 Integration Guide](https://github.com/doobidoo/mcp-memory-service/wiki/03-Integration-Guide)** - Claude Desktop, **Claude Code HTTP transport**, VS Code, and more657- **[🛡️ Advanced Configuration](https://github.com/doobidoo/mcp-memory-service/wiki/04-Advanced-Configuration)** - **Updated!** OAuth security, enterprise features658659### 🧬 v8.23.0+ Memory Consolidation660- **[📊 Memory Consolidation System Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Memory-Consolidation-System-Guide)** - **NEW!** Automated memory maintenance with real-world performance metrics661 - ✅ **Dream-inspired consolidation** (decay scoring, association discovery, compression, archival)662 - ✅ **24/7 automatic scheduling** (daily/weekly/monthly via HTTP server)663 - ✅ **Token-efficient Code Execution API** (90% token reduction vs MCP tools)664 - ✅ **Real-world performance data** (4-6 min for 2,495 memories with hybrid backend)665 - ✅ **Three manual trigger methods** (HTTP API, MCP tools, Python API)666667### 🚀 Setup & Installation668- **[📋 Installation Guide](https://github.com/doobidoo/mcp-memory-service/wiki/01-Installation-Guide)** - Complete installation for all platforms and use cases669- **[🖥️ Platform Setup Guide](https://github.com/doobidoo/mcp-memory-service/wiki/02-Platform-Setup-Guide)** - Windows, macOS, and Linux optimizations670- **[⚡ Performance Optimization](https://github.com/doobidoo/mcp-memory-service/wiki/05-Performance-Optimization)** - Speed up queries, optimize resources, scaling671672### 🧠 Advanced Topics673- **[👨💻 Development Reference](https://github.com/doobidoo/mcp-memory-service/wiki/06-Development-Reference)** - Claude Code hooks, API reference, debugging674- **[🔧 Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)** - **Updated!** OAuth troubleshooting + common issues675- **[❓ FAQ](https://github.com/doobidoo/mcp-memory-service/wiki/08-FAQ)** - Frequently asked questions676- **[📝 Examples](https://github.com/doobidoo/mcp-memory-service/wiki/09-Examples)** - Practical code examples and workflows677678### 📂 Internal Documentation679- **[📊 Repository Statistics](docs/statistics/REPOSITORY_STATISTICS.md)** - 10 months of development metrics, activity patterns, and insights680- **[🏗️ Architecture Specs](docs/architecture/)** - Search enhancement specifications and design documents681- **[👩💻 Development Docs](docs/development/)** - AI agent instructions, release checklist, refactoring notes682- **[🚀 Deployment Guides](docs/deployment/)** - Docker, dual-service, and production deployment683- **[📚 Additional Guides](docs/guides/)** - Storage backends, migration, mDNS discovery684685## ✨ Key Features686687### 🏆 **Production-Ready Reliability** 🆕 v8.9.0688- **Hybrid Backend** - Fast 5ms local SQLite + background Cloudflare sync (RECOMMENDED default)689 - Zero user-facing latency for cloud operations690 - Automatic multi-device synchronization691 - Graceful offline operation692- **Zero Database Locks** - Concurrent HTTP + MCP server access works flawlessly693 - Auto-configured SQLite pragmas (`busy_timeout=15000,cache_size=20000`)694 - WAL mode with proper multi-client coordination695 - Tested: 5/5 concurrent writes succeeded with no errors696- **Auto-Configuration** - Installer handles everything697 - SQLite pragmas for concurrent access698 - Cloudflare credentials with connection testing699 - Claude Desktop integration with hybrid backend700 - Graceful fallback to sqlite_vec if cloud setup fails701702### 📄 **Document Ingestion System** v8.6.0703- **Interactive Web UI** - Drag-and-drop document upload with real-time progress704- **Multiple Formats** - PDF, TXT, MD, JSON with intelligent chunking705- **Document Viewer** - Browse chunks, view metadata, search content706- **Smart Tagging** - Automatic tagging with length validation (max 100 chars)707- **Optional semtools** - Enhanced PDF/DOCX/PPTX parsing with LlamaParse708- **Security Hardened** - Path traversal protection, XSS prevention, input validation709- **7 New Endpoints** - Complete REST API for document management710711### 🔐 **Enterprise Authentication & Team Collaboration**712- **OAuth 2.1 Dynamic Client Registration** - RFC 7591 & RFC 8414 compliant713- **Claude Code HTTP Transport** - Zero-configuration team collaboration714- **JWT Authentication** - Enterprise-grade security with scope validation715- **Auto-Discovery Endpoints** - Seamless client registration and authorization716- **Multi-Auth Support** - OAuth + API keys + optional anonymous access717718### 🧠 **Intelligent Memory Management**719- **Hybrid BM25 + Vector Search** 🆕 v10.8.0 - Best of both worlds for exact match + semantic search720 - Solves exact match problem: 60-70% → near-100% scoring for identical text721 - Parallel execution: BM25 keyword + vector similarity (<15ms latency)722 - Configurable fusion: 30% keyword + 70% semantic (adjustable)723 - Automatic FTS5 index sync via database triggers724 - Backward compatible: `mode="semantic"` unchanged, `mode="hybrid"` opt-in725- **Semantic search** with vector embeddings - Context-aware similarity matching726- **Natural language time queries** - "yesterday", "last week", "3 days ago"727- **Tag-based organization** - Smart categorization with hierarchical support728- **Memory consolidation** - Dream-inspired algorithms for importance scoring729- **Document-aware search** - Query across uploaded documents and manual memories730731### 🧬 **Memory Type Ontology** 🆕 v9.0.0732- **Formal Taxonomy** - 5 base types with 21 specialized subtypes733 - `observation` - General observations, facts, discoveries734 - `decision` - Decisions, planning, architecture choices735 - `learning` - Learnings, insights, patterns discovered736 - `error` - Errors, failures, debugging information737 - `pattern` - Patterns, trends, recurring behaviors738- **97.5x Performance** - Module-level caching for validation739- **Auto-Migration** - Backward compatible conversion from legacy types740- **Soft Validation** - Warns but doesn't reject unknown types741742📖 See [Memory Type Ontology Guide](docs/guides/memory-ontology-guide.md) for full taxonomy.743744### 🔗 **Knowledge Graph & Typed Relationships** 🆕 v9.0.0745- **Relationship Types** - Build semantic networks between memories746 - **Asymmetric**: `causes`, `fixes`, `supports`, `opposes`, `follows`747 - **Symmetric**: `related`, `contradicts`748- **Graph Operations** - Query and traverse memory networks749 - `find_connected_memories` - BFS traversal (1-2 hops)750 - `find_shortest_path` - Compute paths between memories751 - `get_memory_subgraph` - Extract subgraph for visualization752- **Semantic Reasoning** - Automatic causal chain analysis and contradiction detection753- **Performance** - 5-25ms queries, 30x faster than table scans754755### 🧬 **Knowledge Graph Dashboard** 🆕 v9.2.0756757Visualize your memory relationships with an interactive force-directed graph powered by D3.js v7.9.0.758759**Features:**760- **Interactive Graph**: Zoom, pan, drag nodes, hover for details761- **6 Typed Relationships**: causes, fixes, contradicts, supports, follows, related762- **Relationship Chart**: Bar chart showing distribution of relationship types763- **Multi-Language Support**: Fully localized in 7 languages (en, zh, de, es, fr, ja, ko)764- **Dark Mode**: Seamless theme integration with dashboard765- **Performance**: Handles thousands of relationships smoothly (tested with 2,730 relationships)766767**Access:** Navigate to Analytics → Knowledge Graph in the dashboard at http://localhost:8000768769**Key Capabilities:**770- **Visual Exploration**: Discover hidden connections between memories771- **Semantic Networks**: See causal chains, fix relationships, and contradictions772- **Memory Types**: Color-coded nodes by memory type (observation, decision, learning, error)773- **Real-time Updates**: Graph automatically updates as you add new relationships774775📖 See [Knowledge Graph Dashboard Guide](docs/features/knowledge-graph-dashboard.md) for complete documentation.776777### 🔗 **Universal Compatibility**778- **Claude Desktop** - Native MCP integration779- **Claude Code** - **HTTP transport** + Memory-aware development with hooks780 - 🪟 **Windows Support**: `/session-start` command for manual session initialization (workaround for issue #160)781 - 🍎 **macOS/Linux**: Full automatic SessionStart hooks + slash command782- **ChatGPT** (Sept 2025+) - **Full MCP support via Developer Mode** [Setup guide →](https://github.com/doobidoo/mcp-memory-service/discussions/377#discussioncomment-15605174)783 - Supports Streaming HTTP/SSE transports784 - OAuth, Bearer token, and no-auth options785 - Available for Pro, Plus, Business, Enterprise, and Edu accounts786- **VS Code, Cursor, Continue** - IDE extensions787- **15+ AI applications** - REST API compatibility788789### 💾 **Flexible Storage**790- **Hybrid** 🌟 (RECOMMENDED) - Fast local SQLite + background Cloudflare sync (v8.9.0 default)791 - 5ms local reads with zero user-facing latency792 - Multi-device synchronization793 - Zero database locks with auto-configured pragmas794 - Automatic backups and cloud persistence795- **SQLite-vec** - Local-only storage (lightweight ONNX embeddings, 5ms reads)796 - Good for single-user offline use797 - No cloud dependencies798- **Cloudflare** - Cloud-only storage (global edge distribution with D1 + Vectorize)799 - Network-dependent performance800801> **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.802803### 🪶 **Lite Distribution** 🆕 v8.76.0804805For resource-constrained environments (CI/CD, edge devices):806807```bash808pip install mcp-memory-service-lite809```810811**Benefits:**812- **90% size reduction**: 7.7GB → 805MB813- **ONNX-only**: No transformers dependency814- **Same performance**: Identical quality scoring815- **Ideal for**: CI/CD pipelines, Docker images, embedded systems816817**Trade-offs:**818- Local-only quality scoring (no Groq/Gemini fallback)819- ONNX embeddings only (no PyTorch)820821### 🚀 **Production Ready**822- **Cross-platform** - Windows, macOS, Linux823- **Service installation** - Auto-start background operation824- **HTTPS/SSL** - Secure connections with OAuth 2.1825- **Docker support** - Easy deployment with team collaboration826- **Interactive Dashboard** - Web UI at http://127.0.0.1:8000/ for complete management827828## 💡 Basic Usage829830### 📄 **Document Ingestion** (v8.6.0+)831```bash832# For local development/single-user: Enable anonymous access833export MCP_ALLOW_ANONYMOUS_ACCESS=true834835# Start HTTP dashboard server (separate from MCP server)836memory server --http837838# Access interactive dashboard839open http://127.0.0.1:8000/840841# Upload documents via CLI842curl -X POST http://127.0.0.1:8000/api/documents/upload \843 -F "file=@document.pdf" \844 -F "tags=documentation,reference"845846# Search document content847curl -X POST http://127.0.0.1:8000/api/search \848 -H "Content-Type: application/json" \849 -d '{"query": "authentication flow", "limit": 10}'850```851852> **⚠️ Authentication Required**: The HTTP dashboard requires authentication by default. For local development, set `MCP_ALLOW_ANONYMOUS_ACCESS=true`. For production, use API key authentication (`MCP_API_KEY`) or OAuth. See [Configuration](#-configuration) for details.853854### 🔗 **Team Collaboration with OAuth** (v7.0.0+)855```bash856# Start OAuth-enabled HTTP server for team collaboration857export MCP_OAUTH_ENABLED=true858memory server --http859860# Claude Code team members connect via HTTP transport861claude mcp add --transport http memory-service http://your-server:8000/mcp862# → Automatic OAuth discovery, registration, and authentication863```864865### 🧠 **Memory Operations**866```bash867# Store a memory868uv run memory store "Fixed race condition in authentication by adding mutex locks"869870# Search for relevant memories (hybrid search - default in v10.8.0+)871uv run memory recall "authentication race condition"872873# Use hybrid search via HTTP API for exact match + semantic874curl -X POST http://127.0.0.1:8000/api/search \875 -H "Content-Type: application/json" \876 -d '{877 "query": "OAuth 2.1 authentication",878 "mode": "hybrid",879 "limit": 10880 }'881882# Search by tags883uv run memory search --tags python debugging884885# Check system health (shows OAuth status)886uv run memory health887```888889## 🔧 Configuration890891### Claude Desktop Integration892**Recommended approach** - Add to your Claude Desktop config (`~/.claude/config.json`):893894```json895{896 "mcpServers": {897 "memory": {898 "command": "python",899 "args": ["-m", "mcp_memory_service.server"],900 "env": {901 "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"902 }903 }904 }905}906```907908**Alternative approaches:**909```json910// Option 1: UV tooling (if using UV)911{912 "mcpServers": {913 "memory": {914 "command": "uv",915 "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory", "server"],916 "env": {917 "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"918 }919 }920 }921}922923// Option 2: Direct script path (v6.17.0+)924{925 "mcpServers": {926 "memory": {927 "command": "python",928 "args": ["/path/to/mcp-memory-service/scripts/server/run_memory_server.py"],929 "env": {930 "MCP_MEMORY_STORAGE_BACKEND": "sqlite_vec"931 }932 }933 }934}935```936937### Environment Variables938939**Hybrid Backend (v8.9.0+ RECOMMENDED):**940```bash941# Hybrid backend with auto-configured pragmas942export MCP_MEMORY_STORAGE_BACKEND=hybrid943export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"944945# Cloudflare credentials (required for hybrid)946export CLOUDFLARE_API_TOKEN="your-token"947export CLOUDFLARE_ACCOUNT_ID="your-account"948export CLOUDFLARE_D1_DATABASE_ID="your-db-id"949export CLOUDFLARE_VECTORIZE_INDEX="mcp-memory-index"950951# Enable HTTP API952export MCP_HTTP_ENABLED=true953export MCP_HTTP_PORT=8000954955# Security (choose one authentication method)956# Option 1: API Key authentication (recommended for production)957export MCP_API_KEY="your-secure-key"958959# Option 2: Anonymous access (local development only)960# export MCP_ALLOW_ANONYMOUS_ACCESS=true961962# Option 3: OAuth team collaboration963# export MCP_OAUTH_ENABLED=true964```965966**SQLite-vec Only (Local):**967```bash968# Local-only storage969export MCP_MEMORY_STORAGE_BACKEND=sqlite_vec970export MCP_MEMORY_SQLITE_PRAGMAS="busy_timeout=15000,cache_size=20000"971```972973**Hybrid Search (v10.8.0+):**974```bash975# Enable hybrid BM25 + vector search (default: enabled)976export MCP_HYBRID_SEARCH_ENABLED=true977978# Configure score fusion weights (must sum to ~1.0)979export MCP_HYBRID_KEYWORD_WEIGHT=0.3 # BM25 keyword match weight980export MCP_HYBRID_SEMANTIC_WEIGHT=0.7 # Vector similarity weight981982# Adjust weights based on your use case:983# - More keyword-focused: 0.5 keyword / 0.5 semantic984# - More semantic-focused: 0.2 keyword / 0.8 semantic985# - Default balanced: 0.3 keyword / 0.7 semantic (recommended)986```987988> **Note:** Hybrid search is only available with `sqlite_vec` and `hybrid` backends. It automatically combines BM25 keyword matching with vector similarity for better exact match scoring while maintaining semantic capabilities.989990### Response Size Management 🆕 v9.0.0991992Control maximum response size to prevent context overflow:993994```bash995# Limit response size (recommended: 30000-50000)996export MCP_MAX_RESPONSE_CHARS=50000 # Default: unlimited997```998999**Applies to all retrieval tools:**1000- `retrieve_memory`, `recall_memory`, `retrieve_with_quality_boost`1001- `search_by_tag`, `recall_by_timeframe`10021003**Behavior:**1004- Truncates at memory boundaries (preserves data integrity)1005- Recommended: 30000-50000 characters for optimal context usage10061007### External Embedding APIs10081009Use external embedding services instead of running models locally:10101011```bash1012# vLLM example1013export MCP_EXTERNAL_EMBEDDING_URL=http://localhost:8890/v1/embeddings1014export MCP_EXTERNAL_EMBEDDING_MODEL=nomic-ai/nomic-embed-text-v1.510151016# Ollama example1017export MCP_EXTERNAL_EMBEDDING_URL=http://localhost:11434/v1/embeddings1018export MCP_EXTERNAL_EMBEDDING_MODEL=nomic-embed-text10191020# OpenAI example1021export MCP_EXTERNAL_EMBEDDING_URL=https://api.openai.com/v1/embeddings1022export MCP_EXTERNAL_EMBEDDING_MODEL=text-embedding-3-small1023export MCP_EXTERNAL_EMBEDDING_API_KEY=sk-xxx1024```10251026**Benefits:**1027- Share embedding infrastructure across multiple MCP instances1028- Offload GPU/CPU to dedicated servers1029- Use models not available in SentenceTransformers1030- Use hosted services (OpenAI, Cohere)10311032**Note:** Only supported with `sqlite_vec` backend. See [`docs/deployment/external-embeddings.md`](docs/deployment/external-embeddings.md) for detailed setup.10331034## 🏗️ Architecture10351036```1037┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐1038│ AI Clients │ │ MCP Memory │ │ Storage Backend │1039│ │ │ Service v8.9 │ │ │1040│ • Claude Desktop│◄──►│ • MCP Protocol │◄──►│ • Hybrid 🌟 │1041│ • Claude Code │ │ • HTTP Transport│ │ (5ms local + │1042│ (HTTP/OAuth) │ │ • OAuth 2.1 Auth│ │ cloud sync) │1043│ • VS Code │ │ • Memory Store │ │ • SQLite-vec │1044│ • Cursor │ │ • Semantic │ │ • Cloudflare │1045│ • 13+ AI Apps │ │ Search │ │ │1046│ • Web Dashboard │ │ • Doc Ingestion │ │ Zero DB Locks ✅│1047│ (Port 8000) │ │ • Zero DB Locks │ │ Auto-Config ✅ │1048└─────────────────┘ └─────────────────┘ └─────────────────┘1049```10501051## 🛠️ Development10521053### Project Structure1054```1055mcp-memory-service/1056├── src/mcp_memory_service/ # Core application1057│ ├── models/ # Data models1058│ ├── storage/ # Storage backends1059│ ├── web/ # HTTP API & dashboard1060│ └── server.py # MCP server1061├── scripts/ # Utilities & installation1062├── tests/ # Test suite1063└── tools/docker/ # Docker configuration1064```10651066### Contributing10671. Fork the repository10682. Create a feature branch10693. Make your changes with tests10704. Submit a pull request10711072See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.10731074## 🆘 Support10751076- **📖 Documentation**: [Wiki](https://github.com/doobidoo/mcp-memory-service/wiki) - Comprehensive guides1077- **🐛 Bug Reports**: [GitHub Issues](https://github.com/doobidoo/mcp-memory-service/issues)1078- **💬 Discussions**: [GitHub Discussions](https://github.com/doobidoo/mcp-memory-service/discussions)1079- **🔧 Troubleshooting**: [Troubleshooting Guide](https://github.com/doobidoo/mcp-memory-service/wiki/07-TROUBLESHOOTING)1080- **✅ Configuration Validator**: Run `python scripts/validation/validate_configuration_complete.py` to check your setup1081- **🔄 Backend Sync Tools**: See [scripts/README.md](scripts/README.md#backend-synchronization) for Cloudflare↔SQLite sync10821083## 📊 In Production10841085**Real-world metrics from active deployments:**1086- **1700+ memories** stored and actively used across teams1087- **5ms local reads** with hybrid backend (v8.9.0)1088- **Zero database locks** with concurrent HTTP + MCP access (v8.9.0)1089 - Tested: 5/5 concurrent writes succeeded1090 - Auto-configured pragmas prevent lock errors1091- **<500ms response time** for semantic search (local & HTTP transport)1092- **65% token reduction** in Claude Code sessions with OAuth collaboration1093- **96.7% faster** context setup (15min → 30sec)1094- **100% knowledge retention** across sessions and team members1095- **Zero-configuration** setup success rate: **98.5%** (OAuth + hybrid backend)10961097## 🏆 Recognition10981099- [](https://smithery.ai/server/@doobidoo/mcp-memory-service) **Verified MCP Server**1100- [](https://glama.ai/mcp/servers/bzvl3lz34o) **Featured AI Tool**1101- **Production-tested** across 13+ AI applications1102- **Community-driven** with real-world feedback and improvements11031104## 📄 License11051106Apache License 2.0 - see [LICENSE](LICENSE) for details.11071108---11091110**Ready to supercharge your AI workflow?** 🚀11111112👉 **[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.11131114*Transform your AI conversations into persistent, searchable knowledge that grows with you.*1115---11161117## Memory Maintenance & Cleanup11181119### Quick Reference11201121| Task | Method | Time | Notes |1122|------|--------|------|-------|1123| Retag single memory | Dashboard UI | 30s | Click memory → Edit → Save |1124| Retag 10+ memories | Dashboard bulk | 5m | Edit each individually |1125| Retag 100+ memories | `retag_valuable_memories.py` | 2m | Automatic, semantic tagging |1126| Delete test data | `delete_test_memories.py` | 1m | Bulk deletion with confirmation |11271128### Workflow: Clean Up Untagged Memories11291130After experiencing sync issues (like hybrid Cloudflare race conditions), untagged memories may accumulate:11311132```bash1133# 1. Start dashboard1134./start_all_servers.sh11351136# 2. Retag valuable memories automatically1137python3 retag_valuable_memories.py1138# → 340+ memories retagged1139# → 0 failures1140```11411142```bash1143# 3. Delete remaining test data1144python3 delete_test_memories.py1145# → 209 test memories deleted1146# → Database reduced from 5359 → 5150 memories1147```11481149### Dashboard Memory Edit11501151Open http://127.0.0.1:800011521153**To edit a single memory:**11541. Find memory (search or filter)11552. Click to view details11563. Click "Edit Memory"11574. Modify tags (comma-separated)11585. Click "Update Memory"11591160**Example:**1161```1162Before: "needs-categorization"1163After: "release, v8.64, bug-fix, sync"1164```11651166### Automatic Tag Suggestions11671168The `retag_valuable_memories.py` script uses intelligent pattern matching:11691170**Keywords detected:**1171- Versions: `release`, `v8`, `v1`1172- Technologies: `api`, `cloudflare`, `sync`1173- Document types: `documentation`, `setup-guide`, `tutorial`1174- Projects: `shodh`, `secondbrain`, `mcp-memory-service`1175- Status: `important`, `needs-categorization`11761177**Content analysis:**1178- Content > 500 chars → `important`1179- Recognizes: release notes, API docs, setup guides, session summaries11801181### Preventing Future Cleanup Issues11821183**Version 8.64.0+:**1184- ✅ Soft-delete with tombstone support (v8.64.0)1185- ✅ Bidirectional sync race condition fix (v8.64.0)1186- ✅ Cloudflare hybrid sync validation (v8.64.1)11871188**Best practices:**11891. Use meaningful tags from the start11902. Review untagged memories regularly11913. Run cleanup scripts after major changes11924. Verify tags in Dashboard before deletion11931194### See Also1195- [AGENTS.md](AGENTS.md) - Memory cleanup commands reference1196- Scripts in `scripts/maintenance/` - Auto-retagging and cleanup tools11971198
Full transparency — inspect the skill content before installing.