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

---

---

---

Why Agents Need This

Your AI assistant forgets everything when you start a new chat. You spend 10 minutes re-explaining your architecture. Again. MCP Memory Service captures project context, architecture decisions, and code patterns automatically — new sessions start with everything already known.

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 — no MCP client library needed; the live endpoint list is at /api/docs
• 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

---

🚀 Get Started in 60 Seconds

Not sure which setup fits? The Setup Guide walks you to the right path in under a minute.

1. Install:

pip install mcp-memory-service

2. Configure your AI client:

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 mcp add memory -- memory server

Restart Claude Code. Memory tools will appear automatically.

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

Store a memory with POST /api/memories, search with POST /api/search, retrieve by tag with POST /api/search/by-tag. Send X-Agent-ID: <id> on a store request and the server tags the memory agent:<id>, which a tag search then scopes retrieval by.

Worked examples per framework, the tag conventions and the async patterns: docs/agents/

MCP_ALLOW_ANONYMOUS_ACCESS=true memory server --http

The plugin ships as repository files for the local plugin directory, so clone the repository once even if you installed from PyPI. Install steps, the /memory slash command and the endpoint override: opencode/README.md

Start the Memory Service HTTP API, then install the hooks from this repository:

python3 codex/install_hooks.py

Restart Codex and review the hooks with /hooks. They retrieve project context, capture new learnings, and checkpoint outcomes before compaction and at session end. See Codex hook setup for prerequisites, authentication, and project-local installation.

Remote MCP puts persistent memory in the browser on any device, no desktop app required: OAuth 2.0 over HTTPS, self-hosted or cloud-hosted. Both claude.ai and ChatGPT (Developer Mode) connect to the same endpoint.

Cloudflare Tunnel quick start, Let's Encrypt, nginx, Caddy and Docker production setups: Remote MCP Setup · 5-minute tutorial

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

Choose from SQLite (local, fast, single-user), Cloudflare (cloud, multi-device sync), Hybrid (5ms local reads with background cloud sync — recommended for production) or Milvus (dedicated vector DB: Lite file, self-hosted, or Zilliz Cloud). For self-hosted team setups, the Hybrid backend can sync to another HTTP MCP Memory Service instead of Cloudflare using MCP_HYBRID_SECONDARY_BACKEND=http.

For long-lived services, prefer Docker Milvus or Zilliz Cloud over Milvus Lite — why.

---

⚡ Works With Your Favorite AI Tools

• Agent frameworks (REST): LangGraph · CrewAI · AutoGen · OpenClaw/Nanobot · any HTTP client
• CLI and terminal (MCP): Claude Code · Gemini CLI · OpenCode · Codex CLI · Goose · Aider · Amp
• Desktop and IDE (MCP): Claude Desktop · VS Code · Cursor · Windsurf · Raycast · JetBrains · Zed
• Chat (MCP): ChatGPT (Developer Mode) · claude.ai (Remote MCP over HTTPS)

Full list, plus clients without OAuth such as Home Assistant: docs/integrations.md

---

✨ Features

Store and retrieve context

• 🧠 Persistent memory — Keep decisions, notes, and project context across sessions and agents.
• 🔍 Semantic and keyword search — Combine vector search with BM25; use mode="ranked" to weigh recency, access frequency, and quality. An optional fallback cascade tries exact and tag matching when semantic results are sparse.
• 🏷️ Scoped retrieval — Filter by tags with AND/OR matching, natural-language time ranges, and store partitions (default, docs, or all for cross-store search).
• 📝 Optional search summaries — Request summarize=true for query-aware summaries with validated source references. Requires MCP_SEARCH_SUMMARIZE_ENABLED=true and a configured LLM provider; unavailable summaries fall back to raw results. Search API and examples
• 📄 Document ingestion — Import PDF, text, and Markdown with chunking for retrieval. Additional formats such as DOCX and PPTX require optional parsing tools. Document ingestion guide

Capture and maintain knowledge

• ⚡ Automatic session capture — Configurable Claude Code hooks retrieve context and save session learnings; the local memory_harvest tool extracts decisions, bugs, conventions, and lessons from transcripts. Hooks setup · Harvest configuration
• 💡 Autonomous consolidation — Schedule clustering, compression, association discovery, and controlled forgetting. Insight cards surface patterns, trends, and knowledge gaps. Consolidation guide
• 💭 Beliefs and contradiction handling — Derive confidence-scored beliefs from observations. Heuristic contradiction detection can mark older memories as superseded, hiding them from default retrieval while retaining them for explicit lookup.
• 🤖 Agent bootstrap profiles — get_bootstrap_profile assembles behavioral context for a new agent within a token budget, with optional task-aware retrieval. Requires MCP_BOOTSTRAP_ENABLED=true; profiles are not isolated by project.
• 🧬 Knowledge graph and entities — Explore typed causal relationships in the interactive graph. 🔗 Entity extraction links @mentions, #tags, URLs, and file paths to a queryable entity graph. Knowledge graph guide
• 🏠 Quality scoring — Use your own OpenAI-compatible endpoint, including Ollama, LiteLLM, or vLLM. Configuration guide

Run locally and share across devices

• 🔒 Local-first storage — Local ONNX embeddings and SQLite storage keep core memory operations on your infrastructure. Optional LLM features use the providers you configure.
• ☁️ Cloud or self-hosted sync — Use Cloudflare or another MCP Memory Service instance as a Hybrid secondary. Separately enabled delta-sync exchanges changes between hosts; it is off by default. Self-hosted sync guide
• 📦 Import, export, and migration — Move memories through JSON import/export, including conversion of mem0 exports. Import/export tools · mem0 migration guide
• 💾 Database backups — Configure scheduled backups or trigger one manually through the HTTP API. Inspect backup status and available snapshots through the backup endpoints in the live API reference at /api/docs.
• 📊 Web dashboard — Search, browse, visualize, and manage memories at http://localhost:8000.

The dashboard has eight tabs — Dashboard, Search, Browse, Documents, Manage, Analytics, Quality, API Docs. Two-minute walkthrough on YouTube · Web Dashboard Guide

How it compares to Mem0, Zep and the MCP-native alternatives, benchmark results, and deployments people run in production: mcpmemory.services

---

🛠️ Configuration Highlights

memory launch                  # Start HTTP server in background (127.0.0.1:8000)
memory launch --port 8192      # Custom port
memory info                    # Status and health
memory logs --lines 50         # Recent logs
memory stop                    # Stop server

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

⚠️ Security note: the server binds to 127.0.0.1 (localhost only) by default. --host 0.0.0.0 / MCP_HTTP_HOST=0.0.0.0 exposes the API to your network — do that only in trusted environments with authentication and firewall rules, or behind TLS termination or a VPN overlay.

Backends, embedding models, quality scoring and every environment variable: Configuration Guide

---

📚 Documentation

• Setup Guide – Decision tree and step-by-step paths
• Agent Integration Guides – LangGraph, CrewAI, AutoGen, HTTP generic
• Remote MCP Setup – claude.ai and ChatGPT via HTTPS + OAuth
• Configuration Guide – Backend options and customization
• Architecture Overview – How it works under the hood
• Knowledge Graph Dashboard – Interactive graph visualization
• Benchmarks – LongMemEval, DevBench, LoCoMo, with run commands
• Migration Guide – Upgrading between major versions
• Troubleshooting – Common issues and solutions
• Wiki – Long-form guides and API reference
• Full documentation index – Everything else

Also listed on Glama and Spark.

---

📦 Releases

Every release, with upgrade notes: CHANGELOG.md · GitHub Releases · archived history

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines and SECURITY.md for reporting a vulnerability.

Who authors this project, who holds copyright, and what every change passes before it reaches main: AUTHORSHIP.md.

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

---

Supporting the Project

MCP Memory Service is maintained by one person. If it saves you or your company time, you can support its development via Ko-fi, Buy Me a Coffee or PayPal: SPONSORS.md.