{"id":26641157,"url":"https://github.com/doobidoo/mcp-memory-service","last_synced_at":"2026-05-28T07:03:00.270Z","repository":{"id":269813375,"uuid":"908539519","full_name":"doobidoo/mcp-memory-service","owner":"doobidoo","description":"Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.","archived":false,"fork":false,"pushed_at":"2026-05-23T10:32:45.000Z","size":27457,"stargazers_count":1873,"open_issues_count":7,"forks_count":289,"subscribers_count":12,"default_branch":"main","last_synced_at":"2026-05-23T11:26:37.442Z","etag":null,"topics":["agent-memory","agentic-ai","ai-agents","autogen","claude","crewai","knowledge-graph","langgraph","long-term-memory","mcp","mcp-server","memory","model-context-protocol","multi-agent","open-source","rag","semantic-search","sqlite-vec","vector-database","vector-storage"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/doobidoo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"doobidoo","ko_fi":"doobidoo","custom":["https://www.buymeacoffee.com/doobidoo","https://paypal.me/heinrichkrupp1"]}},"created_at":"2024-12-26T10:15:44.000Z","updated_at":"2026-05-23T10:08:38.000Z","dependencies_parsed_at":"2026-03-07T14:01:08.101Z","dependency_job_id":"cd843c48-82f2-4bf6-83b2-5b938f8da7db","html_url":"https://github.com/doobidoo/mcp-memory-service","commit_stats":null,"previous_names":["doobidoo/mcp-memory-service"],"tags_count":485,"template":false,"template_full_name":null,"purl":"pkg:github/doobidoo/mcp-memory-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2Fmcp-memory-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2Fmcp-memory-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2Fmcp-memory-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2Fmcp-memory-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/doobidoo","download_url":"https://codeload.github.com/doobidoo/mcp-memory-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/doobidoo%2Fmcp-memory-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33597808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agentic-ai","ai-agents","autogen","claude","crewai","knowledge-graph","langgraph","long-term-memory","mcp","mcp-server","memory","model-context-protocol","multi-agent","open-source","rag","semantic-search","sqlite-vec","vector-database","vector-storage"],"created_at":"2025-03-24T18:19:57.246Z","updated_at":"2026-05-28T07:03:00.262Z","avatar_url":"https://github.com/doobidoo.png","language":"Python","funding_links":["https://github.com/sponsors/doobidoo","https://ko-fi.com/doobidoo","https://www.buymeacoffee.com/doobidoo","https://paypal.me/heinrichkrupp1"],"categories":["AI Memory \u0026 RAG","Claude Code Ecosystem","Python","Knowledge \u0026 Memory","📚 Projects (1974 total)","🤖 AI/ML","HarmonyOS","Data Analytics","Containerised MCP Servers","MCP Servers","MCP Servers \u0026 Integrations","MCP Ecosystem","MCP服务器与插件","MCP Servers \u0026 Protocol"],"sub_categories":["Memory","Memory \u0026 Context Management","How to Submit","MCP Servers","Windows Manager","General-Purpose Machine Learning","Database \u0026 Storage","Knowledge \u0026 Memory","Other IDEs","Servers"],"readme":"# mcp-memory-service\n\n## Persistent Shared Memory for AI Agent Pipelines\n\nOpen-source memory backend for AI agents — **REST API, MCP, OAuth, CLI, dashboard**. One self-hosted service, every transport.\nAgents store decisions, share causal knowledge graphs, and retrieve\ncontext in 5ms — without cloud lock-in or API costs.\n\n**Works with LangGraph · CrewAI · AutoGen · any HTTP client · Claude Desktop · OpenCode**\n\n---\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![PyPI version](https://img.shields.io/pypi/v/mcp-memory-service?color=blue\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/mcp-memory-service/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-memory-service?logo=python\u0026logoColor=white)](https://pypi.org/project/mcp-memory-service/)\n[![GitHub stars](https://img.shields.io/github/stars/doobidoo/mcp-memory-service?style=social)](https://github.com/doobidoo/mcp-memory-service/stargazers)\n[![Works with LangGraph](https://img.shields.io/badge/Works%20with-LangGraph-green)](https://github.com/langchain-ai/langgraph)\n[![Works with CrewAI](https://img.shields.io/badge/Works%20with-CrewAI-orange)](https://crewai.com)\n[![Works with AutoGen](https://img.shields.io/badge/Works%20with-AutoGen-purple)](https://github.com/microsoft/autogen)\n[![Works with Claude](https://img.shields.io/badge/Works%20with-Claude-blue)](https://claude.ai)\n[![Works with Cursor](https://img.shields.io/badge/Works%20with-Cursor-orange)](https://cursor.sh)\n[![Remote MCP](https://img.shields.io/badge/MCP-Remote%20Support-blue?logo=anthropic)](docs/remote-mcp-setup.md)\n[![claude.ai Browser Compatible](https://img.shields.io/badge/claude.ai-Browser%20Compatible-orange?logo=anthropic)](docs/remote-mcp-setup.md)\n[![OAuth 2.0](https://img.shields.io/badge/Auth-OAuth%202.0%20%2B%20DCR-green)](docs/oauth-setup.md)\n[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/doobidoo)\n\n---\n\n## 🎬 See It in Action\n\n[![Watch the Dashboard Walkthrough](https://img.youtube.com/vi/W34r8VFoSdQ/maxresdefault.jpg)](https://youtu.be/W34r8VFoSdQ)\n\n**[Watch the Web Dashboard Walkthrough on YouTube](https://youtu.be/W34r8VFoSdQ)** — Semantic search, tag browser, document ingestion, analytics, quality scoring, and API docs in under 2 minutes.\n\n---\n\n## 🌐 Works with claude.ai (Browser)\n\nUnlike desktop-only MCP servers, **mcp-memory-service supports Remote MCP** for native claude.ai integration.\n\n**What this means:**\n- ✅ Use persistent memory directly in your browser (no Claude Desktop required)\n- ✅ Works on any device (laptop, tablet, phone)\n- ✅ Enterprise-ready (OAuth 2.0 + HTTPS + CORS)\n- ✅ Self-hosted OR cloud-hosted (your choice)\n\n**5-Minute Setup:**\n\n```bash\n# 1. Start server with Remote MCP enabled\nMCP_STREAMABLE_HTTP_MODE=1 \\\nMCP_SSE_HOST=0.0.0.0 \\\nMCP_SSE_PORT=8765 \\\nMCP_OAUTH_ENABLED=true \\\npython -m mcp_memory_service.server\n\n# 2. Expose via Cloudflare Tunnel (or your own HTTPS setup)\ncloudflared tunnel --url http://localhost:8765\n# → Outputs: https://random-name.trycloudflare.com\n\n# 3. In claude.ai: Settings → Connectors → Add Connector\n# Paste the URL: https://random-name.trycloudflare.com/mcp\n# OAuth flow will handle authentication automatically\n```\n\n**Production Setup:** See [Remote MCP Setup Guide](docs/remote-mcp-setup.md) for Let's Encrypt, nginx, and firewall configuration.\n**Step-by-Step Tutorial:** [Blog: 5-Minute claude.ai Setup](https://doobidoo.github.io/mcp-memory-service/blog/remote-mcp-tutorial.html) | [Wiki Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Claude-AI-Remote-MCP-Integration)\n\n---\n\n## Why Agents Need This\n\n| Without mcp-memory-service | With mcp-memory-service |\n|---|---|\n| Each agent run starts from zero | Agents retrieve prior decisions in 5ms |\n| Memory is local to one graph/run | Memory is shared across all agents and runs |\n| You manage Redis + Pinecone + glue code | One self-hosted service, zero cloud cost |\n| No causal relationships between facts | Knowledge graph with typed edges (causes, fixes, contradicts) |\n| Context window limits create amnesia | Autonomous consolidation compresses old memories |\n\n**Key capabilities for agent pipelines:**\n- **Framework-agnostic REST API** — 76 endpoints, no MCP client library needed\n- **Knowledge graph** — agents share causal chains, not just facts\n- **`X-Agent-ID` header** — auto-tag memories by agent identity for scoped retrieval\n- **`conversation_id`** — bypass deduplication for incremental conversation storage\n- **SSE events** — real-time notifications when any agent stores or deletes a memory\n- **Embeddings run locally via ONNX** — memory never leaves your infrastructure\n\n## Agent Quick Start\n\n```bash\npip install mcp-memory-service\nMCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http\n# REST API running at http://localhost:8000\n```\n\n```python\nimport httpx\n\nBASE_URL = \"http://localhost:8000\"\n\n# Store — auto-tag with X-Agent-ID header\nasync with httpx.AsyncClient() as client:\n    await client.post(f\"{BASE_URL}/api/memories\", json={\n        \"content\": \"API rate limit is 100 req/min\",\n        \"tags\": [\"api\", \"limits\"],\n    }, headers={\"X-Agent-ID\": \"researcher\"})\n    # Stored with tags: [\"api\", \"limits\", \"agent:researcher\"]\n\n# Search — scope to a specific agent\n    results = await client.post(f\"{BASE_URL}/api/memories/search\", json={\n        \"query\": \"API rate limits\",\n        \"tags\": [\"agent:researcher\"],\n    })\n    print(results.json()[\"memories\"])\n```\n\n**Framework-specific guides:** [docs/agents/](docs/agents/)\n\n### Real-World: Multi-Agent Cluster with Shared Memory\n\n\u003e *\"After I work with one of the cluster agents on something I want my local agent to know about, the cluster agent adds a special tag to the memory entry that my local agent recognizes as a message from a cluster agent. So they end up using it as a comms bridge — and it's pretty delightful.\"*\n\u003e — [@jeremykoerber](https://github.com/jeremykoerber), [issue #591](https://github.com/doobidoo/mcp-memory-service/issues/591)\n\nA 5-agent openclaw cluster uses mcp-memory-service as shared state **and** as an inter-agent messaging bus — without any custom protocol. Cluster agents tag memories with a sentinel like `msg:cluster`, and the local agent filters on that tag to receive cross-cluster signals. The memory service becomes the coordination layer with zero additional infrastructure.\n\n```python\n# Cluster agent stores a learning and flags it for the local agent\nawait client.post(f\"{BASE_URL}/api/memories\", json={\n    \"content\": \"Rate limit on provider X is 50 RPM — switch to provider Y after 40\",\n    \"tags\": [\"api\", \"limits\", \"msg:cluster\"],       # sentinel tag\n}, headers={\"X-Agent-ID\": \"cluster-agent-3\"})\n\n# Local agent polls for cluster messages\nresults = await client.post(f\"{BASE_URL}/api/memories/search\", json={\n    \"query\": \"messages from cluster\",\n    \"tags\": [\"msg:cluster\"],\n})\n```\n\nThis pattern — **tags as inter-agent signals** — emerges naturally from the tagging system and requires no additional infrastructure.\n\n### Real-World: Self-Hosted Docker Stack with Cloudflare Tunnel\n\n\u003e *\"The quality of life that session-independent memory adds to AI workflows is immense. File-based memory demands constant discipline. Semantic recall from a live database doesn't. Storing data on my own hardware while making it remotely accessible across platforms turned out to be a feature I didn't know I needed.\"*\n\u003e — [@PL-Peter](https://github.com/PL-Peter), [discussion #602](https://github.com/doobidoo/mcp-memory-service/discussions/602)\n\nA production-tested self-hosted deployment using Docker containers behind a Cloudflare tunnel, with [AuthMCP Gateway](https://github.com/loglux/authmcp-gateway) handling authentication:\n\n| Layer | Role |\n|-------|------|\n| **Cloudflare Tunnel** | Name-based routing, subnet-based access control, authentication before hitting self-hosted resources |\n| **AuthMCP Gateway** | Auth/aggregation with locally managed users, admin UI, per-user MCP server access control, bearer token auth |\n| **mcp-memory-service** | Two Docker containers sharing one SQLite backend — one for MCP, one for the web UI (document ingestion) |\n\n**Security best practices for this setup:**\n- Use Cloudflare ZeroTrust with subnet-based access control (e.g., allow Anthropic subnets + your own IPs)\n- Add **Client IP Address Filtering** to all Cloudflare API tokens (Dashboard → My Profile → API Tokens → Edit → Client IP Address Filtering) to limit abuse if a token leaks\n- If using IPv6, include your IPv6 /64 network in the allowlist (Python prefers IPv6 by default)\n- For long-running browser sessions, request the `offline_access` scope during authorization to receive a rotating `refresh_token` (lifetime via `MCP_OAUTH_REFRESH_TOKEN_EXPIRE_DAYS`, default 30 days). Without this scope, access tokens are the only credential — extend `MCP_OAUTH_ACCESS_TOKEN_EXPIRE_MINUTES` up to `1440` (24h) if you need longer single-shot sessions.\n- Consider an auth proxy like [AuthMCP](https://github.com/loglux/authmcp-gateway) or [mcp-auth-proxy](https://github.com/sigbit/mcp-auth-proxy) for robust session management\n\n## Comparison with Alternatives\n\n### vs. Commercial Memory APIs\n\n| | Mem0 | Zep | DIY Redis+Pinecone | **mcp-memory-service** |\n|---|---|---|---|---|\n| License | Proprietary | Enterprise | — | **Apache 2.0** |\n| Cost | Per-call API | Enterprise | Infra costs | **$0** |\n| **🌐 claude.ai Browser** | ❌ Desktop only | ❌ Desktop only | ❌ | **✅ Remote MCP** |\n| **OAuth 2.0 + DCR** | ❓ Unknown | ❓ Unknown | ❌ | **✅ Enterprise-ready** |\n| **Streamable HTTP** | ❌ | ❌ | ❌ | **✅ (SSE also supported)** |\n| Framework integration | SDK | SDK | Manual | **REST API (any HTTP client)** |\n| Knowledge graph | No | Limited | No | **Yes (typed edges)** |\n| Auto consolidation | No | No | No | **Yes (decay + compression)** |\n| On-premise embeddings | No | No | Manual | **Yes (ONNX, local)** |\n| Privacy | Cloud | Cloud | Partial | **100% local** |\n| Hybrid search | No | Yes | Manual | **Yes (BM25 + vector)** |\n| MCP protocol | No | No | No | **Yes** |\n| REST API | Yes | Yes | Manual | **Yes (76 endpoints)** |\n\n### vs. MCP-Native Alternatives\n\n[MemPalace](https://github.com/MemPalace/mempalace) is an MCP-native alternative that went viral in April 2026 with strong LongMemEval claims. A [community code review (Issue #27)](https://github.com/MemPalace/mempalace/issues/27) subsequently showed that the headline numbers reflect the underlying vector store rather than the advertised Palace architecture, and the maintainers acknowledged most points. We keep the comparison here for transparency, but readers should interpret the scores with that context in mind.\n\n| | **MemPalace** | **mcp-memory-service** |\n|---|---|---|\n| LongMemEval R@5 (raw ChromaDB, zero LLM) | 96.6%¹ | 86.0% (session) / 80.4% (turn) |\n| LongMemEval R@5 (with reranking) | 100%² | — |\n| Storage granularity | Session-level | **Turn-level + session-level** |\n| Team / multi-device sync | ❌ Local only | **✅ Cloudflare sync** |\n| REST API / Web dashboard | ❌ | **✅** |\n| OAuth 2.1 + multi-user | ❌ | **✅** |\n| Knowledge graph | ❌ | **✅ (typed edges)** |\n| Auto consolidation | ❌ | **✅ (decay + compression)** |\n| Compatible AI tools | Claude-focused | **25+ tools** |\n| License | MIT | **Apache 2.0** |\n\n**Why the benchmark gap?** Two independent factors:\n\n1. **Ingestion granularity.** MemPalace stores each conversation as a single unit (session-level). LongMemEval asks \"which session contains the answer?\" — a question that session-level storage answers structurally. mcp-memory-service defaults to turn-level storage (one entry per message), which enables fine-grained retrieval (\"what exactly did the user say about X?\") but spreads a session's signal across many entries. Using `memory_store_session` (added in v10.35.0) brings our score to **86.0% R@5**.\n2. **What the 96.6% actually measures.** Per Issue #27, MemPalace's headline number is produced in \"raw mode\" — plain text stored in ChromaDB with default embeddings. The Palace architecture (Wings, Rooms, Halls) is **not active** in that configuration; \"Halls\" exist only as metadata strings with no effect on ranking. The 96.6% is therefore a ChromaDB + default-embedding baseline, not a measurement of MemPalace's structural retrieval features. A direct \"apples-to-apples\" architectural comparison is not possible with the published numbers.\n\n\u003e ¹ Measured in MemPalace \"raw mode\" (plain text in ChromaDB with default embeddings). Per [Issue #27](https://github.com/MemPalace/mempalace/issues/27), the Palace structural features are bypassed in this configuration.\n\u003e\n\u003e ² 100% result uses optional LLM reranking (~500 API calls) on a partially tuned test set. Clean held-out score (as reported by the maintainers): **98.4% R@5**.\n\n---\n\n## Stop Re-Explaining Your Project to AI Every Session\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"240\" alt=\"MCP Memory Service\" src=\"https://github.com/user-attachments/assets/eab1f341-ca54-445c-905e-273cd9e89555\" /\u003e\n\u003c/p\u003e\n\nYour 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.**\n\n**MCP Memory Service solves this.**\n\nIt 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.\n\n## 🎥 2-Minute Video Demo\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=veJME5qVu-A\"\u003e\n    \u003cimg src=\"https://img.youtube.com/vi/veJME5qVu-A/maxresdefault.jpg\" alt=\"MCP Memory Service Demo\" width=\"700\"\u003e\n  \u003c/a\u003e\n  \u003cp\u003e\u003cem\u003eTechnical showcase: Performance, Architecture, AI/ML Intelligence \u0026 Developer Experience\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n### ⚡ Works With Your Favorite AI Tools\n\n#### 🤖 Agent Frameworks (REST API)\n**LangGraph** · **CrewAI** · **AutoGen** · **Any HTTP Client** · **OpenClaw/Nanobot** · **Custom Pipelines**\n\n#### 🖥️ CLI \u0026 Terminal AI (MCP)\n**Claude Code** · **Gemini CLI** · **Gemini Code Assist** · **OpenCode** · **Codex CLI** · **Goose** · **Aider** · **GitHub Copilot CLI** · **Amp** · **Continue** · **Zed** · **Cody**\n\n#### 🎨 Desktop \u0026 IDE (MCP)\n**Claude Desktop** · **VS Code** · **Cursor** · **Windsurf** · **Kilo Code** · **Raycast** · **JetBrains** · **Replit** · **Sourcegraph** · **Qodo**\n\n#### 💬 Chat Interfaces (MCP)\n**ChatGPT** (Developer Mode) · **claude.ai** (Remote MCP via HTTPS)\n\n**Works seamlessly with any MCP-compatible client or HTTP client** - whether you're building agent pipelines, coding in the terminal, IDE, or browser.\n\n\u003e **💡 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)\n\n---\n\n## 🚀 Get Started in 60 Seconds\n\n\u003e Not sure which setup fits your needs? See the **[Setup Guide](docs/setup-guide.md)** — a decision tree walks you to the right path in under a minute.\n\n**1. Install:**\n\n```bash\npip install mcp-memory-service\n```\n\n**2. Configure your AI client:**\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Desktop\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"memory\",\n      \"args\": [\"server\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Your AI now remembers everything across sessions.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add memory -- memory server\n```\n\nRestart Claude Code. Memory tools will appear automatically.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpenCode\u003c/strong\u003e\u003c/summary\u003e\n\nStart the HTTP API:\n\n```bash\nMCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http\n```\n\nInstall the local plugin:\n\n```bash\ngit clone https://github.com/doobidoo/mcp-memory-service.git\ncd mcp-memory-service\nmkdir -p ~/.config/opencode/plugins\ncp opencode/memory-plugin.js ~/.config/opencode/plugins/\ncp opencode/memory-plugin.config.example.json ~/.config/opencode/memory-plugin.json\n```\n\nOpenCode automatically loads local plugins from `~/.config/opencode/plugins/` and `.opencode/plugins/`.\n\nOptional: register the `/memory` slash command in `~/.config/opencode/opencode.json` to query status, search, and health from inside the TUI:\n\n```json\n{\n  \"command\": {\n    \"memory\": {\n      \"description\": \"Show MCP Memory Service status. Usage: /memory, /memory search \u003cquery\u003e, /memory health\",\n      \"template\": \"\"\n    }\n  }\n}\n```\n\nSee [OpenCode integration guide](opencode/README.md) for configuration, project-local installs, slash command details, TUI toasts, and current limitations.\n\n\u003e The current OpenCode integration ships as repository files for the local plugin directory. If you installed only the PyPI package, clone the repository once to copy the plugin files.\n\u003e\n\u003e The plugin defaults to `http://127.0.0.1:8000`, but `memoryService.endpoint` and `OPENCODE_MEMORY_ENDPOINT` let you target any reachable HTTP deployment.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🌐 claude.ai (Browser — Remote MCP)\u003c/strong\u003e\u003c/summary\u003e\n\nNo local installation required on the client — works directly in your browser:\n\n```bash\n# 1. Start server with Remote MCP\nMCP_STREAMABLE_HTTP_MODE=1 \\\nMCP_SSE_HOST=0.0.0.0 \\\nMCP_OAUTH_ENABLED=true \\\npython -m mcp_memory_service.server\n\n# 2. Expose publicly (Cloudflare Tunnel)\ncloudflared tunnel --url http://localhost:8765\n\n# 3. Add connector in claude.ai Settings → Connectors with the tunnel URL\n```\n\nSee [Remote MCP Setup Guide](docs/remote-mcp-setup.md) for production deployment with Let's Encrypt, nginx, and Docker.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔧 Advanced: Custom Backends \u0026 Team Setup\u003c/strong\u003e\u003c/summary\u003e\n\nFor production deployments, team collaboration, or cloud sync:\n\n```bash\ngit clone https://github.com/doobidoo/mcp-memory-service.git\ncd mcp-memory-service\npython scripts/installation/install.py\n```\n\nChoose from:\n- **SQLite** (local, fast, single-user)\n- **Cloudflare** (cloud, multi-device sync)\n- **Hybrid** (best of both: 5ms local + background cloud sync)\n- **Milvus** (dedicated vector DB — Milvus Lite file, self-hosted, or Zilliz Cloud)\n\n\u003e ℹ️ For long-lived services (MCP servers, web backends, notebook sessions), prefer Docker Milvus or Zilliz Cloud over Milvus Lite. See [docs/milvus-backend.md](docs/milvus-backend.md#which-uri-to-use) for why.\n\n\u003c/details\u003e\n\n---\n\n## 🛠️ CLI Server Lifecycle Commands\n\nIn addition to `memory server --http` (foreground mode), the CLI now includes\nserver lifecycle commands for background HTTP management:\n\n```bash\n# Start HTTP server in background (default host=127.0.0.1, port=8000)\nmemory launch\n\n# Start on a custom port\nmemory launch --port 8192\n\n# Check status and health\nmemory info --port 8192\nmemory health --port 8192\n\n# View recent logs and stop server\nmemory logs --lines 50\nmemory stop --port 8192\n```\n\nThese commands are optimized for fast startup and avoid loading heavy ML\ndependencies unless needed.\n\n⚠️  **Security Note**: By default, the server binds to `127.0.0.1` (localhost only).\nTo expose the server on your network or allow remote access, you can use\n`--host 0.0.0.0` or set `MCP_HTTP_HOST=0.0.0.0`. However, **this exposes the\nAPI to your network** and should be done only in trusted environments with\nproper authentication and firewall rules in production. For untrusted networks,\nuse TLS termination (reverse proxy with HTTPS) or VPN overlays.\n\n---\n\n## 💡 Why You Need This\n\n### The Problem\n\n| Session 1 | Session 2 (Fresh Start) |\n|-----------|-------------------------|\n| You: \"We're building a Next.js app with Prisma and tRPC\" | AI: \"What's your tech stack?\" ❌ |\n| AI: \"Got it, I see you're using App Router\" | You: *Explains architecture again for 10 minutes* 😤 |\n| You: \"Add authentication with NextAuth\" | AI: \"Should I use Pages Router or App Router?\" ❌ |\n\n### The Solution\n\n| Session 1 | Session 2 (Fresh Start) |\n|-----------|-------------------------|\n| 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?\" ✅ |\n| AI: \"Got it, I see you're using App Router\" | You: \"Add OAuth login\" |\n| You: \"Add authentication with NextAuth\" | AI: \"I'll integrate NextAuth with your existing Prisma setup.\" ✅ |\n\n**Result:** Zero re-explaining. Zero context loss. Just continuous, intelligent collaboration.\n\n---\n\n## 🌐 SHODH Ecosystem Compatibility\n\nMCP 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.\n\n### Compatible Implementations\n\n| Implementation | Backend | Embeddings | Use Case |\n|----------------|---------|------------|----------|\n| **[shodh-memory](https://github.com/varun29ankuS/shodh-memory)** | RocksDB | MiniLM-L6-v2 (ONNX) | Reference implementation |\n| **[shodh-cloudflare](https://github.com/doobidoo/shodh-cloudflare)** | Cloudflare Workers + Vectorize | Workers AI (bge-small) | Edge deployment, multi-device sync |\n| **mcp-memory-service** (this) | SQLite-vec / Hybrid | MiniLM-L6-v2 (ONNX) | Desktop AI assistants (MCP) |\n\n### Unified Schema Support\n\nAll SHODH implementations share the same memory schema:\n- ✅ **Emotional Metadata**: `emotion`, `emotional_valence`, `emotional_arousal`\n- ✅ **Episodic Memory**: `episode_id`, `sequence_number`, `preceding_memory_id`\n- ✅ **Source Tracking**: `source_type`, `credibility`\n- ✅ **Quality Scoring**: `quality_score`, `access_count`, `last_accessed_at`\n\n**Interoperability Example:**\nExport memories from mcp-memory-service → Import to shodh-cloudflare → Sync across devices → Full fidelity preservation of emotional_valence, episode_id, and all spec fields.\n\n---\n\n## ✨ Quick Start Features\n\n🧠 **Persistent Memory** – Context survives across sessions with semantic search\n🔍 **Smart Retrieval** – Finds relevant context automatically using AI embeddings\n⚡ **5ms Speed** – Instant context injection, no latency\n🔄 **Multi-Client** – Works across 25+ AI applications\n☁️ **Cloud Sync** – Optional Cloudflare backend for team collaboration\n🔒 **Privacy-First** – Local-first, you control your data\n📊 **Web Dashboard** – Visualize and manage memories at `http://localhost:8000`\n🧬 **Knowledge Graph** – Interactive D3.js visualization of memory relationships\n🏠 **Homelab Quality Scoring** – Point scoring at any OpenAI-compatible endpoint (Ollama, LiteLLM, vLLM)\n🔗 **Entity Extraction** – Auto-links @mentions, #tags, URLs, and file paths from memory content to a queryable entity graph\n💡 **Insight Cards** – Consolidation detects patterns, trends, and knowledge gaps across your memory corpus and surfaces them as structured insights\n🏷️ **Tag Match Filtering** – `tag_match=AND/OR` on `memory_search` for precise multi-tag queries\n\n**Homelab / self-hosted quality scoring** (v10.45.0+): set `MCP_QUALITY_AI_PROVIDER=openai-compatible` to score memories with your local LLM instead of ONNX or a cloud API:\n\n```bash\nMCP_QUALITY_AI_PROVIDER=openai-compatible\nMCP_QUALITY_AI_BASE_URL=http://localhost:11434/v1   # Ollama\nMCP_QUALITY_AI_MODEL=qwen2.5:7b-instruct\n# MCP_QUALITY_AI_API_KEY=ollama                     # optional\n```\n\nRecommended models: `qwen2.5:7b-instruct` (Ollama), `mlx-community/Qwen2.5-7B-Instruct-4bit` (MLX), or any instruct model via LiteLLM proxy. On endpoint failure, scoring falls back to implicit signals automatically.\n\n**Docker `:quality-cpu` tag** — for users who want the built-in local ONNX quality scoring (`ms-marco-MiniLM-L-6-v2` and `nvidia-quality-classifier-deberta`) without managing the one-time ONNX export themselves, and without shipping `torch`/`transformers` in their container:\n\n```bash\ndocker pull doobidoo/mcp-memory-service:quality-cpu\n```\n\nThe `:quality-cpu` image pre-exports both models at build time and ships only `onnxruntime` at runtime — no PyTorch dependency at deploy time. See [`tools/docker/README.md`](tools/docker/README.md) for details.\n\n### 🖥️ Dashboard Preview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg 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\"/\u003e\n\u003c/p\u003e\n\n**8 Dashboard Tabs:** Dashboard • Search • Browse • Documents • Manage • Analytics • Quality • API Docs\n\n📖 See [Web Dashboard Guide](https://github.com/doobidoo/mcp-memory-service/wiki/Web-Dashboard-Guide) for complete documentation.\n\n---\n\n\n## Latest Release: **v10.67.1** (May 28, 2026)\n\n**Patch: fix(security) enforce authentication on all /api/documents/* routes (GHSA-84hp-mqvj-3p8h, CVSSv3.1 9.8 CRITICAL)**\n\n**What's New:**\n- `fix(security)`: All 7 `/api/documents/*` endpoints (upload, batch-upload, status, history, remove, remove-by-tags, search-content) now require authentication. Previously unauthenticated even when `MCP_API_KEY` or OAuth 2.1 was configured (GHSA-84hp-mqvj-3p8h, CVSSv3.1 9.8 CRITICAL, commit 907bac72).\n\n---\n\n**Previous Releases**:\n- **v10.67.0** - feat(reasoning): NLI contradiction detection (RFC #732 Phase 3, PR #1027, @filhocf) + fix(mcp): full v10 HTTP tool surface (PR #1017, @laanwj) + fix(storage): BM25 log sanitization (CodeQL #440) (May 28, 2026)\n- **v10.66.1** - fix(storage): HttpClientStorage.retrieve signature fix (CodeQL #428) + fix(harvest): multi-CLI session dir resolution + Kiro CLI support (PR #1025, @filhocf) (May 27, 2026)\n- **v10.66.0** - feat(reasoning): transitive closure + abductive inference + entity grouping + insight cards (RFC #732) + fix(time-filter): SQL-level enforcement (May 26, 2026)\n- **v10.65.3** - fix(security): enforce write scope on MCP tools/call (GHSA-2r68-g678-7qr3, CVSS 8.1) + ci: restrict quality-cpu Docker to linux/amd64 (PR #1004, #1003)\n- **v10.65.1** - fix(prompts): guard `learning_session` against unresolved CLI `$N` placeholders (PR #1000) + docs: privacy-safe audit log default (PR #999)\n- **v10.65.0** - feat(opencode): `/memory` slash commands, TUI toasts, status bridge, working Solid TUI sidebar widget, session-summary dedup fix (PR #997)\n- **v10.64.2** - fix(opencode): replace dead chat.message hook with event-based message.part.updated + add export default {id,server} for V1 plugin compat + use node:https Agent with rejectUnauthorized=false for self-signed cert support (PR #995)\n- **v10.64.1** - fix(consolidation): association confidence threshold raised to 0.5 (PR #991) + fix(consolidation): `last_run_at` advance on timeout (#989, closes #986) + fix(oauth): remove `offline_access` per SEP-2207 (#990) + fix(consolidation): temporal proximity 7-day window (#988)\n- **v10.64.0** - feat(consolidation): incremental time_horizon for memory_consolidate (#985, @filhocf) + fix(web): repair /api/quality/trends AttributeError (#982) + docs(research): contradiction resolution approaches (#984)\n- **v10.63.0** - feat(milvus): low-priority overrides completing #888 (search_by_tag_chronological, count_memories_by_tag, is_deleted, purge_deleted) + fix(harvest): Kiro CLI AssistantMessage + 36x parse yield improvement (PRs #978, #979)\n- **v10.62.0** - feat(milvus): native search_memories + retrieve_with_quality_boost + recall_memory (server-side filter pushdown, completes medium-priority #888) + fix(hooks): JSONL transcript parsing (PRs #970, #971)\n- **v10.61.0** - feat(milvus): native update_memory + update_memories_batch (1 round-trip batch upsert) + feat(sse): Last-Event-ID replay on /api/events reconnect (PRs #966, #953)\n- **v10.60.2** - fix(milvus): replace ANN search() with brute-force query() in semantic dedup — fixes Milvus Lite growing-segment visibility bug (#964, closes #938, @henry201605)\n- **v10.60.1** - fix(milvus): tag_match param in get_all_memories/count_all_memories + fix(hooks): session-end port fallback + fix(consolidation): repair contradiction detection (PRs #958, #960, #961)\n- **v10.60.0** - feat(consolidation): temporal contradiction detection + fix(milvus): instance-level graph cache + fix(hooks): tunnel/reverse-proxy port fix + feat(benchmarks): mem0 adapter (PRs #949, #954, #948, #952)\n- **v10.59.2** - fix(oauth): AnyUrl for redirect_uri so IDE schemes (cursor://, vscode://) pass Pydantic validation (#942, @tkislan)\n- **v10.59.1** - fix(oauth): reflect state parameter verbatim per RFC 6749 §4.1.2, fixes Cursor OAuth (#944, @tkislan)\n- **v10.59.0** - feat(oauth): PEM key files + IDE redirect URI schemes; fix(hooks): symmetric project-affinity (PRs #926, #942, #941)\n- **v10.58.0** - feat(insights): configurable exclusion, automated-type heuristic, acknowledgement flow (PR #939); feat(harvest): locale YAML plugins (PR #935, @filhocf); feat(plugin): smart-tagger example (PR #932, @filhocf)\n- **v10.57.3** - feat(milvus): last_accessed tracking via `_access` side-collection (PR #925, @henry201605)\n- **v10.57.2** - fix(deps): pin pymilvus\u003c3.0.0 to restore Milvus Docker CI (PR #921)\n- **v10.57.1** - fix(sqlite): LIKE ESCAPE tag matching + fix(milvus): preserve_timestamps value comparison (PRs #916, #918)\n- **v10.57.0** - feat(memory_list): tag_match AND/OR filtering + feat(session): automatic chunking at turn boundaries (PRs #904, #912, @filhocf)\n- **v10.56.3** - feat(milvus): get_memory_connections() via graph collection + fix(quality): MAINTAIN_SCAN_LIMIT fallback hardening\n- **v10.56.2** - fix(milvus): missing `stale_days` param in `count_all_memories` + fix(quality): graceful `MAINTAIN_SCAN_LIMIT` fallback\n- **v10.56.1** - fix(session): pass session_id as conversation_id to bypass semantic dedup\n- **v10.56.0** - feat(consolidation): configurable maintain scan limit + InsightGenerator gap filter\n- **v10.55.2** - fix(insights): handle None memory\\_type and tags in InsightGenerator sort\n- **v10.55.1** - fix(entities): entity links always 0 in `maintain` Step 5 due to wrong graph accessor (PR #895)\n- **v10.55.0** - feat(reasoning+consolidation): entity extraction, memory-entity linking, and Insight Cards (PRs #868, #869, @filhocf)\n- **v10.54.0** - feat(search): tag_match parameter for memory_search AND/OR tag filtering (PR #890, @filhocf)\n- **v10.53.0** - feat(milvus): activate consolidation embedding hydration end-to-end; security: GitPython 3.1.50 (PRs #885, #886, @henry201605)\n- **v10.52.0** - feat(search): cascading fallback when semantic results are sparse; refactor(storage): include_embeddings on bulk-read ABC methods (PRs #883, #881, @filhocf, @henry201605)\n- **v10.51.3** - feat(memory_update): versioned flag; feat(memory_graph): infer_transitive and suggest_relationships (PRs #865, #866, @filhocf)\n- **v10.51.2** - fix(oauth): CORS preflight failures and missing resource_metadata; refactor(milvus): opt-in embedding hydration on read paths (PRs #877, #878)\n- **v10.51.1** - fix(milvus): add delete_memory proxy for consolidation protocol (PR #872, @henry201605)\n- **v10.51.0** - feat(plugins): live plugin hooks + dynamic type dropdowns + audit-log example (PRs #863, #864, #867, @filhocf)\n- **v10.50.0** - feat(plugins): plugin hook scaffolding — on_store, on_delete, on_retrieve, on_consolidate (PR #856, @filhocf)\n- **v10.49.4** - fix(consolidation): protect high-value mistake notes from decay/forgetting (PR #854, @filhocf)\n- **v10.49.3** - fix(opencode): correct API path, payload field, and client-side tag filter (PRs #849, #850)\n- **v10.49.2** - fix(ontology): register custom base types with empty subtype lists (PR #846)\n- **v10.49.1** - fix: surface memory_type ontology coercion warnings + uvx CI flake fix (PR #844)\n- **v10.49.0** - feat(cli): lazy lifecycle commands and faster startup (PR #841, @creativelaides)\n- **v10.48.0** - feat: include_superseded retrieval filter + auto-mark on contradiction (PR #814, @filhocf)\n- **v10.47.2** - fix(consolidation): disable-by-default schedule prevents unintended automatic consolidation (PR #821, closes #808)\n- **v10.47.1** - fix(web): surface /server/update failures end-to-end (PR #807, closes #729)\n- **v10.47.0** - feat: memory_quality maintain orchestrator + Docker DeBERTa quantization (PRs #802, #803, @filhocf, closes #799, #793)\n- **v10.46.0** - feat: stale_days filter for memory_list — dormant memory detection (PR #796, @filhocf, closes #784)\n- **v10.45.1** - fix: CodeQL redundant import cleanup + soft-delete regression tests (PRs #794, #795, @filhocf)\n- **v10.45.0** - feat(quality): OpenAI-compatible provider for LiteLLM/Ollama/MLX + soft-delete UPDATE guards (PRs #790, #783, @filhocf)\n- **v10.44.0** - feat: Mistake Notes — structured error replay (`mistake_note_add`, `mistake_note_search`, PR #786, @filhocf)\n- **v10.43.0** - feat(search): Reciprocal Rank Fusion (RRF) for SQLite-vec hybrid search (PR #773, @filhocf)\n- **v10.42.1** - fix(milvus): add missing `anns_field` to search calls for BM25-enabled collections (PR #775, @henry201605)\n- **v10.42.0** - feat(milvus): MilvusGraphStorage, BM25 hybrid search, and consolidation integration (PR #762, @henry201605)\n- **v10.41.0** - feat(oauth): OAuth 2.1 refresh_token grant with rotation, memory_graph on streamable-http (PRs #766, #759)\n- **v10.40.4** - fix(quality): handle shape (1, 1) cross-encoder logits in ONNX ranker (PR #765)\n- **v10.40.3** - fix(claude-hooks): eliminate socket hang-up and raise hook timeout (PR #761)\n- **v10.40.2** - fix(docker): correct invalid Python one-liner in ONNX pre-download (PR #757)\n- **v10.40.1** - fix(sync): CF hybrid sync reliability + reporting accuracy (PRs #751, #753)\n- **v10.40.0** - feat: Milvus storage backend (Lite / self-hosted / Zilliz Cloud), OAuth XSS hardening, plugin shape validation (PRs #721, #745, #740)\n- **v10.39.1** - hotfix: plugin.json author field object format — unblocks `/plugin install mcp-memory-service` (#738, #739)\n- **v10.39.0** - feat: Claude Code plugin install (`/plugin marketplace add doobidoo/mcp-memory-service`) + MemoryClient.storeMemory() protocol-native writes (PRs #736, #735)\n- **v10.38.4** - fix(mcp): return HTTP 202 for JSON-RPC notifications — fixes Codex/strict-client handshake (PR #733)\n- **v10.38.3** - fix: Server tab auto-check, list_memories total_pages, knowledge graph edge rendering (PRs #728, #731, #730)\n- **v10.38.2** - fix(windows): PS 7+ cert bypass, per-call SkipCertificateCheck, chicken-egg lib sourcing (PR #723)\n- **v10.38.1** - fix: OAuth loopback ports (RFC 8252), CLI ingestion NameError, SSE CLI flags, Docker CI bumps (PRs #697, #704, #705, #707-709)\n- **v10.38.0** - feat: opt-in Claude Code SessionEnd auto-harvest hook — safe-by-default, zero npm deps, 5s timeout, TLS opt-in (PR #711, 1,547 tests)\n- **v10.37.0** - feat: `POST /api/harvest` HTTP endpoint for Session Harvest + CodeQL path-injection hardening (PR #710, 1,547 tests)\n- **v10.36.8** - fix: event-loop blocking paths in `SqliteVecMemoryStorage.initialize()` — pragma application and hash-embedding fallback now run in worker thread under `_conn_lock` (PR #700, 1,537 tests)\n- **v10.36.7** - security: bump pygments to 2.20.0 (CVE-2026-4539/GHSA-5239-wwwm-4pmq) — ReDoS fix via rich transitive dep (PR #698, 1,537 tests)\n- **v10.36.6** - security: bump cryptography to 46.0.7 (CVE-2026-39892) — buffer overflow fix in non-contiguous buffer handling (PR #690, 1,537 tests)\n- **v10.36.5** - fix: Cloudflare Vectorize API v1 to v2 + test script fixes — fixed error 1010 \"incorrect_api_version\", content_hash arg, sys.path correction (PR #689, @mychaelgo, 1,537 tests)\n- **v10.36.4** - fix(windows): hotfix for Get-McpApiKey returning first char instead of full API key — PowerShell array-enumeration trap fixed (PR #687, 1,537 tests)\n\n**Full version history**: [CHANGELOG.md](CHANGELOG.md) | [Older versions (v10.36.3 and earlier)](docs/archive/CHANGELOG-HISTORIC.md) | [All Releases](https://github.com/doobidoo/mcp-memory-service/releases)\n\n---\n\n## 📊 Retrieval Benchmarks\n\nThree benchmarks measure retrieval quality (all-MiniLM-L6-v2, 384d embeddings, zero LLM API calls):\n\n**LongMemEval** ([500 questions](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned), ~45–62 distractor sessions per question):\n\n| Question Type | R@5 | R@10 | NDCG@10 | MRR |\n|---------------|-----|------|---------|-----|\n| **Overall** | **80.4%** | **90.4%** | **82.2%** | **89.1%** |\n| single-session-assistant | 100.0% | 100.0% | 99.3% | 99.1% |\n| knowledge-update | 84.6% | 96.8% | 86.2% | 95.5% |\n| single-session-user | 91.4% | 92.9% | 86.0% | 83.8% |\n| temporal-reasoning | 72.0% | 84.1% | 75.1% | 85.7% |\n| multi-session | 70.7% | 86.0% | 77.6% | 89.4% |\n\n**DevBench** (practical developer workflow queries):\n\n| Category | Recall@5 | MRR |\n|----------|----------|-----|\n| **Overall** | **91.1%** | **0.861** |\n| exact | 100% | 1.000 |\n| semantic | 80.0% | 0.700 |\n| cross-type | 90.0% | 0.867 |\n\n**LoCoMo** ([ACL 2024](https://github.com/snap-research/locomo) long-term conversational memory):\n\n| Category | Recall@5 | MRR |\n|----------|----------|-----|\n| **Overall** | **49.7%** | **0.414** |\n| multi-hop | 72.0% | 0.600 |\n| temporal | 33.5% | 0.274 |\n\nRun benchmarks: `python scripts/benchmarks/benchmark_longmemeval.py`, `python scripts/benchmarks/benchmark_devbench.py`, `python scripts/benchmarks/benchmark_locomo.py`\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMigration to v9.0.0\u003c/strong\u003e (upgrading from v8.x)\u003c/summary\u003e\n\n**⚡ TL;DR**: No manual migration needed - upgrades happen automatically!\n\n**Breaking Changes:**\n- **Memory Type Ontology**: Legacy types auto-migrate to new taxonomy (task→observation, note→observation)\n- **Asymmetric Relationships**: Directed edges only (no longer bidirectional)\n\n**Migration Process:**\n1. Stop your MCP server\n2. Update to latest version (`git pull` or `pip install --upgrade mcp-memory-service`)\n3. Restart server - automatic migrations run on startup:\n   - Database schema migrations (009, 010)\n   - Memory type soft-validation (legacy types → observation)\n   - No tag migration needed (backward compatible)\n\n**Safety**: Migrations are idempotent and safe to re-run\n\n#### Breaking Change 1: Memory Type Ontology\n\n- Legacy memory types (task, note, standard) are deprecated\n- New formal taxonomy: 5 base types (observation, decision, learning, error, pattern) with 21 subtypes\n- Migration is **automatic** on server restart — no manual action required\n\n#### Breaking Change 2: Asymmetric Relationships\n\n- Asymmetric relationships (causes, fixes, supports, follows) now store only directed edges\n- Symmetric relationships (related, contradicts) continue storing bidirectional edges\n- Database migration (010) runs automatically on startup\n\nIf your code expects bidirectional storage for asymmetric relationships:\n\n```python\n# OLD behavior (no longer applies):\nresult = storage.find_connected(memory_id, relationship_type=\"causes\")\n\n# NEW: use direction parameter explicitly\nresult = storage.find_connected(\n    memory_id,\n    relationship_type=\"causes\",\n    direction=\"both\"\n)\n```\n\nIf you encounter issues: [Troubleshooting Guide](docs/troubleshooting/) · [CHANGELOG.md](CHANGELOG.md) · [Open an issue](https://github.com/doobidoo/mcp-memory-service/issues)\n\n\u003c/details\u003e\n\n---\n\n## 📚 Documentation \u0026 Resources\n\n- **[Agent Integration Guides](docs/agents/)** 🆕 – LangGraph, CrewAI, AutoGen, HTTP generic\n- **[OpenCode Integration](opencode/README.md)** 🆕 – Local plugin for memory retrieval and context injection\n- **[Remote MCP Setup (claude.ai)](docs/remote-mcp-setup.md)** 🆕 – Browser integration via HTTPS + OAuth\n- **[Setup Guide](docs/setup-guide.md)** – Decision tree + step-by-step paths for all use cases\n- **[Configuration Guide](docs/mastery/configuration-guide.md)** – Backend options and customization\n- **[Architecture Overview](docs/architecture.md)** – How it works under the hood\n- **[Team Setup Guide](docs/setup-guide.md#path-4-full-stack)** – OAuth and cloud collaboration\n- **[Knowledge Graph Dashboard](docs/features/knowledge-graph-dashboard.md)** 🆕 – Interactive graph visualization guide\n- **[Memory Type Ontology](docs/memory-ontology.md)** 🆕 – Built-in taxonomy and `MCP_CUSTOM_MEMORY_TYPES` env var\n- **[Troubleshooting](docs/troubleshooting/)** – Common issues and solutions\n- **[API Reference](https://github.com/doobidoo/mcp-memory-service/wiki)** – Programmatic usage\n- **[Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)** – Complete documentation\n- [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/doobidoo/mcp-memory-service) – AI-powered documentation assistant\n- **[MCP Starter Kit](https://kruppster57.gumroad.com/l/glbhd)** – Build your own MCP server using the patterns from this project\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n**Quick Development Setup:**\n```bash\ngit clone https://github.com/doobidoo/mcp-memory-service.git\ncd mcp-memory-service\npip install -e .  # Editable install\npytest tests/      # Run test suite\n```\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoobidoo%2Fmcp-memory-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoobidoo%2Fmcp-memory-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoobidoo%2Fmcp-memory-service/lists"}