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

🎬 See It in Action

Watch the Web Dashboard Walkthrough on YouTube — 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:

# 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 for Let's Encrypt, nginx, and firewall configuration. Step-by-Step Tutorial: Blog: 5-Minute claude.ai Setup | Wiki Guide

Why Agents Need This

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

pip install mcp-memory-service
MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http
# REST API running at http://localhost:8000

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/

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, issue #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.

# 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, discussion #602

A production-tested self-hosted deployment using Docker containers behind a Cloudflare tunnel, with AuthMCP Gateway handling authentication:

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 or mcp-auth-proxy for robust session management

Comparison with Alternatives

vs. Commercial Memory APIs

vs. MCP-Native Alternatives

MemPalace is an MCP-native alternative that went viral in April 2026 with strong LongMemEval claims. A community code review (Issue #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.

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

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

Technical showcase: Performance, Architecture, AI/ML Intelligence & Developer Experience

⚡ 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 →

🚀 Get Started in 60 Seconds

Not sure which setup fits your needs? See the Setup Guide — a decision tree walks you to the right path in under a minute.

1. Install:

pip install mcp-memory-service

2. Configure your AI client:

{
  "mcpServers": {
    "memory": {
      "command": "memory",
      "args": ["server"]
    }
  }
}

claude mcp add memory -- memory server

MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http

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

# 1. Start server with Remote MCP
MCP_STREAMABLE_HTTP_MODE=1 \
MCP_SSE_HOST=0.0.0.0 \
MCP_OAUTH_ENABLED=true \
python -m mcp_memory_service.server

# 2. Expose publicly (Cloudflare Tunnel)
cloudflared tunnel --url http://localhost:8765

# 3. Add connector in claude.ai Settings → Connectors with the tunnel URL

git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
python scripts/installation/install.py

🛠️ CLI Server Lifecycle Commands

In addition to memory server --http (foreground mode), the CLI now includes server lifecycle commands for background HTTP management:

# Start HTTP server in background (default host=127.0.0.1, port=8000)
memory launch

# Start on a custom port
memory launch --port 8192

# Check status and health
memory info --port 8192
memory health --port 8192

# View recent logs and stop server
memory logs --lines 50
memory stop --port 8192

These commands are optimized for fast startup and avoid loading heavy ML dependencies unless needed.

⚠️ Security Note: By default, the server binds to 127.0.0.1 (localhost only). To expose the server on your network or allow remote access, you can use --host 0.0.0.0 or set MCP_HTTP_HOST=0.0.0.0. However, this exposes the API to your network and should be done only in trusted environments with proper authentication and firewall rules in production. For untrusted networks, use TLS termination (reverse proxy with HTTPS) or VPN overlays.

💡 Why You Need This

The Problem

The Solution

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

🌐 SHODH Ecosystem Compatibility

MCP Memory Service is fully compatible with the SHODH Unified Memory API Specification v1.0.0, enabling seamless interoperability across the SHODH ecosystem.

Compatible Implementations

Unified Schema Support

All SHODH implementations share the same memory schema:

• ✅ Emotional Metadata: emotion, emotional_valence, emotional_arousal
• ✅ Episodic Memory: episode_id, sequence_number, preceding_memory_id
• ✅ Source Tracking: source_type, credibility
• ✅ Quality Scoring: quality_score, access_count, last_accessed_at

Interoperability Example: Export memories from mcp-memory-service → Import to shodh-cloudflare → Sync across devices → Full fidelity preservation of emotional_valence, episode_id, and all spec fields.

✨ Quick Start Features

🧠 Persistent Memory – Context survives across sessions with semantic search 🔍 Smart Retrieval – Finds relevant context automatically using AI embeddings ⚡ 5ms Speed – Instant context injection, no latency 🔄 Multi-Client – Works across 25+ AI applications ☁️ Cloud Sync – Optional Cloudflare backend for team collaboration 🔒 Privacy-First – Local-first, you control your data 📊 Web Dashboard – Visualize and manage memories at http://localhost:8000 🧬 Knowledge Graph – Interactive D3.js visualization of memory relationships 🏠 Homelab Quality Scoring – Point scoring at any OpenAI-compatible endpoint (Ollama, LiteLLM, vLLM)

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:

MCP_QUALITY_AI_PROVIDER=openai-compatible
MCP_QUALITY_AI_BASE_URL=http://localhost:11434/v1   # Ollama
MCP_QUALITY_AI_MODEL=qwen2.5:7b-instruct
# MCP_QUALITY_AI_API_KEY=ollama                     # optional

Recommended 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.

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:

docker pull doobidoo/mcp-memory-service:quality-cpu

The :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 for details.

🖥️ Dashboard Preview

8 Dashboard Tabs: Dashboard • Search • Browse • Documents • Manage • Analytics • Quality • API Docs

📖 See Web Dashboard Guide for complete documentation.

Latest Release: v10.51.3 (May 8, 2026)

feat(memory_update + memory_graph): versioned update flag and transitive/suggest graph actions (PRs #865, #866, @filhocf)

What's New:

• Versioned memory updates: memory_update now accepts a versioned: bool = False parameter. When True, routes through update_memory_versioned() in sqlite_vec, storing superseded_by in metadata for full audit trail. Returns an explicit error on unsupported backends. (PR #865, @filhocf)
• Transitive inference and relationship suggestions: memory_graph gains infer and suggest actions. Transitive closure uses a recursive CTE in GraphStorage (database-side, no Python BFS), making large graph traversals fast and efficient. (PR #866, @filhocf)

Previous Releases:

• v10.51.2 - fix(oauth): CORS preflight failures and missing resource_metadata; refactor(milvus): opt-in embedding hydration on read paths (PRs #877, #878)
• v10.51.1 - fix(milvus): add delete_memory proxy for consolidation protocol (PR #872, @henry201605)
• v10.51.0 - feat(plugins): live plugin hooks + dynamic type dropdowns + audit-log example (PRs #863, #864, #867, @filhocf)
• v10.50.0 - feat(plugins): plugin hook scaffolding — on_store, on_delete, on_retrieve, on_consolidate (PR #856, @filhocf)
• v10.49.4 - fix(consolidation): protect high-value mistake notes from decay/forgetting (PR #854, @filhocf)
• v10.49.3 - fix(opencode): correct API path, payload field, and client-side tag filter (PRs #849, #850)
• v10.49.2 - fix(ontology): register custom base types with empty subtype lists (PR #846)
• v10.49.1 - fix: surface memory_type ontology coercion warnings + uvx CI flake fix (PR #844)
• v10.49.0 - feat(cli): lazy lifecycle commands and faster startup (PR #841, @creativelaides)
• v10.48.0 - feat: include_superseded retrieval filter + auto-mark on contradiction (PR #814, @filhocf)
• v10.47.2 - fix(consolidation): disable-by-default schedule prevents unintended automatic consolidation (PR #821, closes #808)
• v10.47.1 - fix(web): surface /server/update failures end-to-end (PR #807, closes #729)
• v10.47.0 - feat: memory_quality maintain orchestrator + Docker DeBERTa quantization (PRs #802, #803, @filhocf, closes #799, #793)
• v10.46.0 - feat: stale_days filter for memory_list — dormant memory detection (PR #796, @filhocf, closes #784)
• v10.45.1 - fix: CodeQL redundant import cleanup + soft-delete regression tests (PRs #794, #795, @filhocf)
• v10.45.0 - feat(quality): OpenAI-compatible provider for LiteLLM/Ollama/MLX + soft-delete UPDATE guards (PRs #790, #783, @filhocf)
• v10.44.0 - feat: Mistake Notes — structured error replay (mistake_note_add, mistake_note_search, PR #786, @filhocf)
• v10.43.0 - feat(search): Reciprocal Rank Fusion (RRF) for SQLite-vec hybrid search (PR #773, @filhocf)
• v10.42.1 - fix(milvus): add missing anns_field to search calls for BM25-enabled collections (PR #775, @henry201605)
• v10.42.0 - feat(milvus): MilvusGraphStorage, BM25 hybrid search, and consolidation integration (PR #762, @henry201605)
• v10.41.0 - feat(oauth): OAuth 2.1 refresh_token grant with rotation, memory_graph on streamable-http (PRs #766, #759)
• v10.40.4 - fix(quality): handle shape (1, 1) cross-encoder logits in ONNX ranker (PR #765)
• v10.40.3 - fix(claude-hooks): eliminate socket hang-up and raise hook timeout (PR #761)
• v10.40.2 - fix(docker): correct invalid Python one-liner in ONNX pre-download (PR #757)
• v10.40.1 - fix(sync): CF hybrid sync reliability + reporting accuracy (PRs #751, #753)
• v10.40.0 - feat: Milvus storage backend (Lite / self-hosted / Zilliz Cloud), OAuth XSS hardening, plugin shape validation (PRs #721, #745, #740)
• v10.39.1 - hotfix: plugin.json author field object format — unblocks /plugin install mcp-memory-service (#738, #739)
• v10.39.0 - feat: Claude Code plugin install (/plugin marketplace add doobidoo/mcp-memory-service) + MemoryClient.storeMemory() protocol-native writes (PRs #736, #735)
• v10.38.4 - fix(mcp): return HTTP 202 for JSON-RPC notifications — fixes Codex/strict-client handshake (PR #733)
• v10.38.3 - fix: Server tab auto-check, list_memories total_pages, knowledge graph edge rendering (PRs #728, #731, #730)
• v10.38.2 - fix(windows): PS 7+ cert bypass, per-call SkipCertificateCheck, chicken-egg lib sourcing (PR #723)
• v10.38.1 - fix: OAuth loopback ports (RFC 8252), CLI ingestion NameError, SSE CLI flags, Docker CI bumps (PRs #697, #704, #705, #707-709)
• 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)
• v10.37.0 - feat: POST /api/harvest HTTP endpoint for Session Harvest + CodeQL path-injection hardening (PR #710, 1,547 tests)
• 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)
• 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)
• 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)
• 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)
• 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)

Full version history: CHANGELOG.md | Older versions (v10.36.3 and earlier) | All Releases

📊 Retrieval Benchmarks

Three benchmarks measure retrieval quality (all-MiniLM-L6-v2, 384d embeddings, zero LLM API calls):

LongMemEval (500 questions, ~45–62 distractor sessions per question):

DevBench (practical developer workflow queries):

LoCoMo (ACL 2024 long-term conversational memory):

Run benchmarks: python scripts/benchmarks/benchmark_longmemeval.py, python scripts/benchmarks/benchmark_devbench.py, python scripts/benchmarks/benchmark_locomo.py

# OLD behavior (no longer applies):
result = storage.find_connected(memory_id, relationship_type="causes")

# NEW: use direction parameter explicitly
result = storage.find_connected(
    memory_id,
    relationship_type="causes",
    direction="both"
)

📚 Documentation & Resources

• Agent Integration Guides 🆕 – LangGraph, CrewAI, AutoGen, HTTP generic
• OpenCode Integration 🆕 – Local plugin for memory retrieval and context injection
• Remote MCP Setup (claude.ai) 🆕 – Browser integration via HTTPS + OAuth
• Setup Guide – Decision tree + step-by-step paths for all use cases
• Configuration Guide – Backend options and customization
• Architecture Overview – How it works under the hood
• Team Setup Guide – OAuth and cloud collaboration
• Knowledge Graph Dashboard 🆕 – Interactive graph visualization guide
• Memory Type Ontology 🆕 – Built-in taxonomy and MCP_CUSTOM_MEMORY_TYPES env var
• Troubleshooting – Common issues and solutions
• API Reference – Programmatic usage
• Wiki – Complete documentation
• – AI-powered documentation assistant
• MCP Starter Kit – Build your own MCP server using the patterns from this project

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Development Setup:

git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
pip install -e .  # Editable install
pytest tests/      # Run test suite