Memory Service

# mcp-memory-service ## Persistent Shared Memory for AI Agent Pipelines Open-source memory backend for AI agents — **REST API, MCP, OAuth, CLI, dashboard**. One self-hosted service, every transport. 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 · OpenCode** --- [](https://opensource.org/licenses/Apache-2.0) [](https://pypi.org/project/mcp-memory-service/) [](https://pypi.org/project/mcp-memory-service/) [](https://github.com/doobidoo/mcp-memory-service/stargazers) [](https://github.com/langchain-ai/langgraph) [](https://crewai.com) [](https://github.com/microsoft/autogen) [](https://claude.ai) [](https://cursor.sh) [](docs/remote-mcp-setup.md) [](docs/remote-mcp-setup.md) [](docs/oauth-setup.md) [](https://github.com/sponsors/doobidoo) --- ## 🎬 See It in Action [](https://youtu.be/W34r8VFoSdQ) **[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. --- ## 🌐 Works with claude.ai (Browser) Unlike desktop-only MCP servers, **mcp-memory-service supports Remote MCP** for native claude.ai integration. **What this means:** - ✅ Use persistent memory directly in your browser (no Claude Desktop required) - ✅ Works on any device (laptop, tablet, phone) - ✅ Enterprise-ready (OAuth 2.0 + HTTPS + CORS) - ✅ Self-hosted OR cloud-hosted (your choice) **5-Minute Setup:** ```bash # 1. Start server with Remote MCP enabled MCP_STREAMABLE_HTTP_MODE=1 \ MCP_SSE_HOST=0.0.0.0 \ MCP_SSE_PORT=8765 \ MCP_OAUTH_ENABLED=true \ python -m mcp_memory_service.server # 2. Expose via Cloudflare Tunnel (or your own HTTPS setup) cloudflared tunnel --url http://localhost:8765 # → Outputs: https://random-name.trycloudflare.com # 3. In claude.ai: Settings → Connectors → Add Connector # Paste the URL: https://random-name.trycloudflare.com/mcp # OAuth flow will handle authentication automatically ``` **Production Setup:** See [Remote MCP Setup Guide](docs/remote-mcp-setup.md) for Let's Encrypt, nginx, and firewall configuration. **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) --- ## Why Agents Need This | Without mcp-memory-service | With mcp-memory-service | |---|---| | Each agent run starts from zero | Agents retrieve prior decisions in 5ms | | Memory is local to one graph/run | Memory is shared across all agents and runs | | You manage Redis + Pinecone + glue code | One self-hosted service, zero cloud cost | | No causal relationships between facts | Knowledge graph with typed edges (causes, fixes, contradicts) | | Context window limits create amnesia | Autonomous consolidation compresses old memories | **Key capabilities for agent pipelines:** - **Framework-agnostic REST API** — 76 endpoints, no MCP client library needed - **Knowledge graph** — agents share causal chains, not just facts - **`X-Agent-ID` header** — auto-tag memories by agent identity for scoped retrieval - **`conversation_id`** — bypass deduplication for incremental conversation storage - **SSE events** — real-time notifications when any agent stores or deletes a memory - **Embeddings run locally via ONNX** — memory never leaves your infrastructure ## Agent Quick Start ```bash pip install mcp-memory-service MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http # REST API running at http://localhost:8000 ``` ```python import httpx BASE_URL = "http://localhost:8000" # Store — auto-tag with X-Agent-ID header async with httpx.AsyncClient() as client: await client.post(f"{BASE_URL}/api/memories", json={ "content": "API rate limit is 100 req/min", "tags": ["api", "limits"], }, headers={"X-Agent-ID": "researcher"}) # Stored with tags: ["api", "limits", "agent:researcher"] # Search — scope to a specific agent results = await client.post(f"{BASE_URL}/api/memories/search", json={ "query": "API rate limits", "tags": ["agent:researcher"], }) print(results.json()["memories"]) ``` **Framework-specific guides:** [docs/agents/](docs/agents/) ### Real-World: Multi-Agent Cluster with Shared Memory > *"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."* > — [@jeremykoerber](https://github.com/jeremykoerber), [issue #591](https://github.com/doobidoo/mcp-memory-service/issues/591) A 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. ```python # Cluster agent stores a learning and flags it for the local agent await client.post(f"{BASE_URL}/api/memories", json={ "content": "Rate limit on provider X is 50 RPM — switch to provider Y after 40", "tags": ["api", "limits", "msg:cluster"], # sentinel tag }, headers={"X-Agent-ID": "cluster-agent-3"}) # Local agent polls for cluster messages results = await client.post(f"{BASE_URL}/api/memories/search", json={ "query": "messages from cluster", "tags": ["msg:cluster"], }) ``` This pattern — **tags as inter-agent signals** — emerges naturally from the tagging system and requires no additional infrastructure. ### Real-World: Self-Hosted Docker Stack with Cloudflare Tunnel > *"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."* > — [@PL-Peter](https://github.com/PL-Peter), [discussion #602](https://github.com/doobidoo/mcp-memory-service/discussions/602) A production-tested self-hosted deployment using Docker containers behind a Cloudflare tunnel, with [AuthMCP Gateway](https://github.com/loglux/authmcp-gateway) handling authentication: | Layer | Role | |-------|------| | **Cloudflare Tunnel** | Name-based routing, subnet-based access control, authentication before hitting self-hosted resources | | **AuthMCP Gateway** | Auth/aggregation with locally managed users, admin UI, per-user MCP server access control, bearer token auth | | **mcp-memory-service** | Two Docker containers sharing one SQLite backend — one for MCP, one for the web UI (document ingestion) | **Security best practices for this setup:** - Use Cloudflare ZeroTrust with subnet-based access control (e.g., allow Anthropic subnets + your own IPs) - 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 - If using IPv6, include your IPv6 /64 network in the allowlist (Python prefers IPv6 by default) - 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. - 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 ## Comparison with Alternatives ### vs. Commercial Memory APIs | | Mem0 | Zep | DIY Redis+Pinecone | **mcp-memory-service** | |---|---|---|---|---| | License | Proprietary | Enterprise | — | **Apache 2.0** | | Cost | Per-call API | Enterprise | Infra costs | **$0** | | **🌐 claude.ai Browser** | ❌ Desktop only | ❌ Desktop only | ❌ | **✅ Remote MCP** | | **OAuth 2.0 + DCR** | ❓ Unknown | ❓ Unknown | ❌ | **✅ Enterprise-ready** | | **Streamable HTTP** | ❌ | ❌ | ❌ | **✅ (SSE also supported)** | | Framework integration | SDK | SDK | Manual | **REST API (any HTTP client)** | | Knowledge graph | No | Limited | No | **Yes (typed edges)** | | Auto consolidation | No | No | No | **Yes (decay + compression)** | | On-premise embeddings | No | No | Manual | **Yes (ONNX, local)** | | Privacy | Cloud | Cloud | Partial | **100% local** | | Hybrid search | No | Yes | Manual | **Yes (BM25 + vector)** | | MCP protocol | No | No | No | **Yes** | | REST API | Yes | Yes | Manual | **Yes (76 endpoints)** | ### vs. MCP-Native Alternatives [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. | | **MemPalace** | **mcp-memory-service** | |---|---|---| | LongMemEval R@5 (raw ChromaDB, zero LLM) | 96.6%¹ | 86.0% (session) / 80.4% (turn) | | LongMemEval R@5 (with reranking) | 100%² | — | | Storage granularity | Session-level | **Turn-level + session-level** | | Team / multi-device sync | ❌ Local only | **✅ Cloudflare sync** | | REST API / Web dashboard | ❌ | **✅** | | OAuth 2.1 + multi-user | ❌ | **✅** | | Knowledge graph | ❌ | **✅ (typed edges)** | | Auto consolidation | ❌ | **✅ (decay + compression)** | | Compatible AI tools | Claude-focused | **25+ tools** | | License | MIT | **Apache 2.0** | **Why the benchmark gap?** Two independent factors: 1. **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**. 2. **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. > ¹ 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. > > ² 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**. --- ## Stop Re-Explaining Your Project to AI Every Session <p align="center"> <img width="240" alt="MCP Memory Service" src="https://github.com/user-attachments/assets/eab1f341-ca54-445c-905e-273cd9e89555" /> </p> Your AI assistant forgets everything when you start a new chat. After 50 tool uses, context explodes to 500k+ tokens—Claude slows down, you restart, and now it remembers nothing. You spend 10 minutes re-explaining your architecture. **Again.** **MCP Memory Service solves this.** It automatically captures your project context, architecture decisions, and code patterns. When you start fresh sessions, your AI already knows everything—no re-explaining, no context loss, no wasted time. ## 🎥 2-Minute Video Demo <div align="center"> <a href="https://www.youtube.com/watch?v=veJME5qVu-A"> <img src="https://img.youtube.com/vi/veJME5qVu-A/maxresdefault.jpg" alt="MCP Memory Service Demo" width="700"> </a> <p><em>Technical showcase: Performance, Architecture, AI/ML Intelligence & Developer Experience</em></p> </div> ### ⚡ Works With Your Favorite AI Tools #### 🤖 Agent Frameworks (REST API) **LangGraph** · **CrewAI** · **AutoGen** · **Any HTTP Client** · **OpenClaw/Nanobot** · **Custom Pipelines** #### 🖥️ CLI & Terminal AI (MCP) **Claude Code** · **Gemini CLI** · **Gemini Code Assist** · **OpenCode** · **Codex CLI** · **Goose** · **Aider** · **GitHub Copilot CLI** · **Amp** · **Continue** · **Zed** · **Cody** #### 🎨 Desktop & IDE (MCP) **Claude Desktop** · **VS Code** · **Cursor** · **Windsurf** · **Kilo Code** · **Raycast** · **JetBrains** · **Replit** · **Sourcegraph** · **Qodo** #### 💬 Chat Interfaces (MCP) **ChatGPT** (Developer Mode) · **claude.ai** (Remote MCP via HTTPS) **Works seamlessly with any MCP-compatible client or HTTP client** - whether you're building agent pipelines, coding in the terminal, IDE, or browser. > **💡 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) --- ## 🚀 Get Started in 60 Seconds > 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. **1. Install:** ```bash pip install mcp-memory-service ``` **2. Configure your AI client:** <details open> <summary><strong>Claude Desktop</strong></summary> Add to your config file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "memory": { "command": "memory", "args": ["server"] } } } ``` Restart Claude Desktop. Your AI now remembers everything across sessions. </details> <details> <summary><strong>Claude Code</strong></summary> ```bash claude mcp add memory -- memory server ``` Restart Claude Code. Memory tools will appear automatically. </details> <details> <summary><strong>OpenCode</strong></summary> Start the HTTP API: ```bash MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http ``` Install the local plugin: ```bash git clone https://github.com/doobidoo/mcp-memory-service.git cd mcp-memory-service mkdir -p ~/.config/opencode/plugins cp opencode/memory-plugin.js ~/.config/opencode/plugins/ cp opencode/memory-plugin.config.example.json ~/.config/opencode/memory-plugin.json ``` OpenCode automatically loads local plugins from `~/.config/opencode/plugins/` and `.opencode/plugins/`.