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
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 automaticallyProduction 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
| 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 — 15 endpoints, no MCP client library needed
- Knowledge graph — agents share causal chains, not just facts
X-Agent-IDheader — auto-tag memories by agent identity for scoped retrievalconversation_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
pip install mcp-memory-service
MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http
# REST API running at http://localhost:8000import 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/
| 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 deprecated) |
| 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 (15 endpoints) |
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.
Technical showcase: Performance, Architecture, AI/ML Intelligence & Developer Experience
LangGraph · CrewAI · AutoGen · Any HTTP Client · OpenClaw/Nanobot · Custom Pipelines
Claude Code · Gemini CLI · Gemini Code Assist · OpenCode · Codex CLI · Goose · Aider · GitHub Copilot CLI · Amp · Continue · Zed · Cody
Claude Desktop · VS Code · Cursor · Windsurf · Kilo Code · Raycast · JetBrains · Replit · Sourcegraph · Qodo
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 →
1. Install:
pip install mcp-memory-service2. Configure your AI client:
Claude Desktop
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
{
"mcpServers": {
"memory": {
"command": "memory",
"args": ["server"]
}
}
}Restart Claude Desktop. Your AI now remembers everything across sessions.
Claude Code
claude mcp add memory -- memory serverRestart Claude Code. Memory tools will appear automatically.
🌐 claude.ai (Browser — Remote MCP)
No local installation required on the client — works directly in your browser:
# 1. Start server with Remote MCP
MCP_STREAMABLE_HTTP_MODE=1 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 URLSee Remote MCP Setup Guide for production deployment with Let's Encrypt, nginx, and Docker.
🔧 Advanced: Custom Backends & Team Setup
For production deployments, team collaboration, or cloud sync:
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
python scripts/installation/install.pyChoose from:
- SQLite (local, fast, single-user)
- Cloudflare (cloud, multi-device sync)
- Hybrid (best of both: 5ms local + background cloud sync)
| Session 1 | Session 2 (Fresh Start) |
|---|---|
| You: "We're building a Next.js app with Prisma and tRPC" | AI: "What's your tech stack?" ❌ |
| AI: "Got it, I see you're using App Router" | You: Explains architecture again for 10 minutes 😤 |
| You: "Add authentication with NextAuth" | AI: "Should I use Pages Router or App Router?" ❌ |
| Session 1 | Session 2 (Fresh Start) |
|---|---|
| You: "We're building a Next.js app with Prisma and tRPC" | AI: "I remember—Next.js App Router with Prisma and tRPC. What should we build?" ✅ |
| AI: "Got it, I see you're using App Router" | You: "Add OAuth login" |
| You: "Add authentication with NextAuth" | AI: "I'll integrate NextAuth with your existing Prisma setup." ✅ |
Result: Zero re-explaining. Zero context loss. Just continuous, intelligent collaboration.
MCP Memory Service is fully compatible with the SHODH Unified Memory API Specification v1.0.0, enabling seamless interoperability across the SHODH ecosystem.
| Implementation | Backend | Embeddings | Use Case |
|---|---|---|---|
| shodh-memory | RocksDB | MiniLM-L6-v2 (ONNX) | Reference implementation |
| shodh-cloudflare | Cloudflare Workers + Vectorize | Workers AI (bge-small) | Edge deployment, multi-device sync |
| mcp-memory-service (this) | SQLite-vec / Hybrid | MiniLM-L6-v2 (ONNX) | Desktop AI assistants (MCP) |
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.
🧠 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 20+ 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 🆕
8 Dashboard Tabs: Dashboard • Search • Browse • Documents • Manage • Analytics • Quality (NEW) • API Docs
📖 See Web Dashboard Guide for complete documentation.
Patch release: Dashboard metadata display fixes + quality scorer resilience improvements
What's New:
- Dashboard: metadata objects now shown as JSON (#582): Object-typed metadata values rendered as
[object Object]are now serialised withJSON.stringify+ HTML-escaped. XSS vector closed. - Dashboard: long content collapsed in detail modal; quality tab fetches full object (#583): Content >500 chars collapses with a Show more/less toggle. Quality-tab clicks now fetch the full memory object before opening the modal.
- Quality scorer: empty-query path uses absolute quality prompt (#584):
store_memorycalls (query = "") no longer produce a 0.0 score — a dedicated absolute quality prompt is used instead of the relevance-based one. - Quality scorer: Groq 429 triggers model fallback chain (#585): Rate-limit responses now try
llama-3.1-8b-instant→llama3-8b-8192→gemma2-9b-itin sequence instead of failing hard.
Previous Releases:
- v10.26.2 - OAuth public PKCE client fix (token exchange 500 error, issue #576) + automated CHANGELOG housekeeping
- v10.26.1 - Hybrid backend correctly reported in MCP health checks (
HealthCheckFactorystructural detection fix for wrapped/delegated backends, issue #570) - v10.26.0 - Credentials tab + Settings restructure + Sync Owner selector in dashboard;
MCP_HYBRID_SYNC_OWNER=httprecommended for hybrid mode - v10.25.3 - Patch release: stdio handshake timeout cap, syntax fixes, hybrid sync fix, dashboard version badge fix
- v10.25.2 - Patch fix:
update_and_restart.shhealth check readsstatusfield instead of removedversionfield - v10.25.1 - Security: CORS wildcard default changed to localhost-only, soft-delete leak in
search_by_tag_chronological()fixed (GHSA-g9rg-8vq5-mpwm) - v10.25.0 - Embedding migration script, 5 soft-delete leak fixes, cosine distance formula fix, substring tag matching fix, O(n²) association sampling fix — 23 new tests, 1,420 total
Full version history: CHANGELOG.md | Older versions (v10.22.0 and earlier) | All Releases
⚡ TL;DR: No manual migration needed - upgrades happen automatically!
Breaking Changes:
- Memory Type Ontology: Legacy types auto-migrate to new taxonomy (task→observation, note→observation)
- Asymmetric Relationships: Directed edges only (no longer bidirectional)
Migration Process:
- Stop your MCP server
- Update to latest version (
git pullorpip install --upgrade mcp-memory-service) - Restart server - automatic migrations run on startup:
- Database schema migrations (009, 010)
- Memory type soft-validation (legacy types → observation)
- No tag migration needed (backward compatible)
Safety: Migrations are idempotent and safe to re-run
What Changed:
- Legacy memory types (task, note, standard) are deprecated
- New formal taxonomy: 5 base types (observation, decision, learning, error, pattern) with 21 subtypes
- Type validation now defaults to 'observation' for invalid types (soft validation)
Migration Process: ✅ Automatic - No manual action required!
When you restart the server with v9.0.0:
- Invalid memory types are automatically soft-validated to 'observation'
- Database schema updates run automatically
- Existing memories continue to work without modification
New Memory Types:
- observation: General observations, facts, and discoveries
- decision: Decisions and planning
- learning: Learnings and insights
- error: Errors and failures
- pattern: Patterns and trends
Backward Compatibility:
- Existing memories will be auto-migrated (task→observation, note→observation, standard→observation)
- Invalid types default to 'observation' (no errors thrown)
What Changed:
- Asymmetric relationships (causes, fixes, supports, follows) now store only directed edges
- Symmetric relationships (related, contradicts) continue storing bidirectional edges
- Database migration (010) removes incorrect reverse edges
Migration Required: No action needed - database migration runs automatically on startup.
Code Changes Required: If your code expects bidirectional storage for asymmetric relationships:
# OLD (will no longer work):
# Asymmetric relationships were stored bidirectionally
result = storage.find_connected(memory_id, relationship_type="causes")
# NEW (correct approach):
# Use direction parameter for asymmetric relationships
result = storage.find_connected(
memory_id,
relationship_type="causes",
direction="both" # Explicit direction required for asymmetric types
)Relationship Types:
- Asymmetric: causes, fixes, supports, follows (A→B ≠ B→A)
- Symmetric: related, contradicts (A↔B)
- ontology validation: 97.5x faster (module-level caching)
- Type lookups: 35.9x faster (cached reverse maps)
- Tag validation: 47.3% faster (eliminated double parsing)
- 829/914 tests passing (90.7%)
- 80 new ontology tests with 100% backward compatibility
- All API/HTTP integration tests passing
If you encounter issues during migration:
- Check Troubleshooting Guide
- Review CHANGELOG.md for detailed changes
- Open an issue: https://github.com/doobidoo/mcp-memory-service/issues
- Agent Integration Guides 🆕 – LangGraph, CrewAI, AutoGen, HTTP generic
- Remote MCP Setup (claude.ai) 🆕 – Browser integration via HTTPS + OAuth
- Installation Guide – Detailed setup instructions
- 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
- 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
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
![@gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=64&v=4){kind=small}
