Self-hosted mem0 MCP server for Claude Code. Run a complete memory server against self-hosted Qdrant + Neo4j + Ollama, with your choice of Anthropic (Claude) or Ollama as the main LLM.
Uses the mem0ai package directly as a library, supports both Claude's OAT token and fully local Ollama setups, and exposes 11 MCP tools for full memory management.
Self-hosted mem0 MCP server for Claude Code. Run a complete memory server against self-hosted Qdrant + Neo4j + Ollama while using Claude as the main LLM.
ดาว
111
เครื่องมือ
—
อัปไทม์
—
Prerequisites
Service
Required
Purpose
Qdrant
Yes
Vector memory storage and search
Ollama
Yes
Embedding generation (bge-m3) and optionally local LLM
Neo4j 5+
Optional
Knowledge graph (entity relationships)
Google API Key
Optional
Required only for gemini/gemini_split graph providers
Authentication: The default setup uses Claude (Anthropic) as the LLM for fact extraction. No API key needed, the server automatically uses your Claude Code session token. For fully local setups, set MEM0_PROVIDER=ollama. See Authentication for advanced options.
Quick Start
Default (Anthropic)
Add the MCP server globally (available across all projects):
claude mcp add --scope user --transport stdio mem0 \
--env MEM0_USER_ID=your-user-id \
-- uvx --from git+https://github.com/elvismdev/mem0-mcp-selfhosted.git mem0-mcp-selfhosted
All defaults work out of the box: Qdrant on localhost:6333, Ollama embeddings on localhost:11434 with bge-m3 (1024 dims). Override any default via --env (see Configuration).
uvx automatically downloads, installs, and runs the server in an isolated environment, no manual installation needed. Claude Code launches it on demand when the MCP connection starts.
The server auto-reads your OAT token from ~/.claude/.credentials.json, no manual token configuration needed.
Fully Local (Ollama)
For a fully local setup with no cloud dependencies, use Ollama for both the main LLM and embeddings:
MEM0_PROVIDER=ollama cascades to both the main LLM and graph LLM providers. Same infrastructure defaults apply (Qdrant on localhost:6333, bge-m3 embeddings). Per-service overrides (e.g. MEM0_LLM_URL, MEM0_EMBED_URL) still work when needed.
Or add it to a single project by creating .mcp.json in the project root:
> Search my memories for TypeScript preferences
> Remember that I prefer Hatch for Python packaging
> Show me all entities in my knowledge graph
CLAUDE.md Integration
Add these rules to your project's CLAUDE.md (or ~/.claude/CLAUDE.md for global use) so Claude Code proactively uses memory tools throughout the session:
# MCP Servers
- **mem0**: Persistent memory across sessions. At the start of each session, `search_memories` for relevant context before asking the user to re-explain anything. Use `add_memory` whenever you discover project architecture, coding conventions, debugging insights, key decisions, or user preferences. Use `update_memory` when prior context changes. Save information like: "This project uses PostgreSQL with Prisma", "Tests run with pytest -v", "Auth uses JWT validated in middleware". When in doubt, save it, future sessions benefit from over-remembering.
This gives Claude Code behavioral instructions to actively search and save memories during the session. For best results, combine with Claude Code Hooks, the CLAUDE.md rules tell Claude how to use memory tools mid-session, while hooks handle the automatic injection and saving at session boundaries.
Claude Code Hooks
Session hooks automate memory at session boundaries, injecting memories on startup and saving summaries on exit. This happens automatically without manual tool calls.
Hook
Event
What it does
mem0-hook-context
SessionStart (startup, compact)
Searches mem0 for project-relevant memories and injects them as additionalContext
mem0-hook-stop
Stop
Reads the last ~3 user/assistant exchanges from the transcript and saves a summary to mem0 via infer=True
Both hooks are non-fatal, if mem0 is unreachable or any error occurs, Claude Code continues normally.
Install
Install hooks into your project:
mem0-install-hooks
Or install globally (all projects):
mem0-install-hooks --global
This adds the hook entries to .claude/settings.json. The installer is idempotent, running it twice won't create duplicates.
How it works
On session start, the context hook searches mem0 with two queries (project architecture + recent session summaries), deduplicates by memory ID, and formats the results as numbered lines under a # mem0 Cross-Session Memory header. These are injected via the hook's additionalContext response field.
On session stop, the stop hook reads the JSONL transcript, extracts the last 6 user/assistant messages (a sliding window via bounded deque), builds a summary prompt, and calls memory.add(infer=True) to extract atomic facts. Graph is force-disabled in hooks to stay within the 15s/30s timeout budgets.
Entry points
Command
Function
Registered in pyproject.toml
mem0-hook-context
hooks:context_main
SessionStart hook
mem0-hook-stop
hooks:stop_main
Stop hook
mem0-install-hooks
hooks:install_main
CLI installer
Hooks + CLAUDE.md
Hooks and CLAUDE.md are complementary layers that work best together:
Layer
Role
When
Hooks
Automated data flow, injects stored memories on startup, saves session summaries on exit
Session boundaries (start/stop)
CLAUDE.md
Behavioral instructions, tells Claude to actively search and save memories during the session
Throughout the session
Hooks alone give you passive recall (memories appear at startup) and passive saving (summaries saved at exit). CLAUDE.md instructions add active mid-session behavior, Claude searches for relevant memories when encountering new topics, and saves important discoveries immediately rather than waiting for session end.
For the best experience, use both. Hooks ensure memories flow in and out automatically at session boundaries, while CLAUDE.md ensures Claude actively engages with memory tools during the session.
Authentication
The server resolves an Anthropic token using a prioritized fallback chain:
Priority
Source
Details
1
MEM0_ANTHROPIC_TOKEN env var
Explicit, user-controlled
2
~/.claude/.credentials.json
Auto-reads Claude Code's OAT token (zero-config)
3
ANTHROPIC_API_KEY env var
Standard pay-per-use API key
4
Disabled
Warns and disables Anthropic LLM features
In Claude Code, priority 2 always wins, the credentials file exists as long as you're logged in. This means ANTHROPIC_API_KEY (priority 3) is never reached. To override the OAT token in Claude Code, use MEM0_ANTHROPIC_TOKEN (priority 1). ANTHROPIC_API_KEY is only useful for non-Claude-Code deployments (Docker, CI, standalone).
OAT tokens (sk-ant-oat...) use your Claude subscription. The server automatically detects the token type and configures the SDK accordingly. OAT tokens are automatically refreshed before expiry: the server proactively checks the token lifetime and refreshes via the Anthropic OAuth endpoint when nearing expiry (default: 30 minutes). On authentication failures, a 3-step defensive strategy kicks in, piggybacking on Claude Code's credentials file, self-refreshing via OAuth, and wait-and-retry, so long-running sessions survive token rotation seamlessly.
API keys (sk-ant-api...) use standard pay-per-use billing.
Tools
Memory Tools (9 core)
Tool
Description
add_memory
Store text or conversation history as memories. Supports enable_graph, infer, metadata.
search_memories
Semantic search with optional filters, threshold, rerank, enable_graph.
get_memories
List/filter memories (non-search). Supports limit and scope filters.
get_memory
Fetch a single memory by UUID.
update_memory
Replace memory text. Re-embeds and re-indexes in Qdrant.
delete_memory
Delete a single memory by UUID.
delete_all_memories
Bulk-delete all memories in a scope.
list_entities
List users/agents/runs with memory counts. Uses Qdrant Facet API.
delete_entities
Cascade-delete an entity and all its memories.
Graph Tools
Tool
Description
search_graph
Search Neo4j entities by name substring. Returns entities + outgoing relationships.
get_entity
Get all relationships for an entity (bidirectional: incoming + outgoing).
Prompt
The server registers a memory_assistant MCP prompt that provides Claude with a quick-start guide for using the memory tools effectively.
Parameters
All tools use Pydantic Annotated[type, Field(description=...)] for self-documenting parameter schemas. Common patterns:
user_id defaults to MEM0_USER_ID env var when not provided
enable_graph overrides the default MEM0_ENABLE_GRAPH per-call
All responses are JSON strings via json.dumps(result, ensure_ascii=False)
Configuration
All configuration is via environment variables. Create a .env file or set them in your MCP config.
Authentication
Variable
Default
Description
MEM0_ANTHROPIC_TOKEN
--
Anthropic OAT or API token (priority 1)
ANTHROPIC_API_KEY
--
Standard Anthropic API key (priority 3)
MEM0_OAT_HEADERS
auto
OAT identity headers: auto or none
MEM0_OAT_REFRESH_THRESHOLD_SECONDS
1800
Seconds before expiry to trigger proactive OAT token refresh
LLM
Variable
Default
Description
MEM0_PROVIDER
anthropic
Top-level provider (anthropic or ollama). Cascades to MEM0_LLM_PROVIDER and MEM0_GRAPH_LLM_PROVIDER when those are not set. Does not affect MEM0_EMBED_PROVIDER.
MEM0_LLM_PROVIDER
(MEM0_PROVIDER)
Main LLM provider: anthropic or ollama. Inherits from MEM0_PROVIDER when not set.
MEM0_OLLAMA_URL
http://localhost:11434
Shared Ollama base URL. Cascades to MEM0_LLM_URL, MEM0_EMBED_URL, and MEM0_GRAPH_LLM_URL when those are not set.
MEM0_LLM_MODEL
(per-provider)
Model for the selected LLM provider. Defaults to claude-opus-4-6 for Anthropic, qwen3:14b for Ollama
MEM0_LLM_URL
(cascades)
Ollama base URL for the main LLM. Cascades: MEM0_LLM_URL → MEM0_OLLAMA_URL → http://localhost:11434. Only used when MEM0_LLM_PROVIDER=ollama
MEM0_LLM_MAX_TOKENS
16384
Max tokens for LLM responses (Anthropic only)
MEM0_GRAPH_LLM_PROVIDER
(MEM0_PROVIDER)
Graph LLM provider (anthropic, anthropic_oat, ollama, gemini, gemini_split). Inherits from MEM0_PROVIDER when not set.
MEM0_GRAPH_LLM_URL
(cascades)
Ollama base URL for graph LLM. Cascades: MEM0_GRAPH_LLM_URL → MEM0_LLM_URL → MEM0_OLLAMA_URL → http://localhost:11434
MEM0_GRAPH_LLM_MODEL
(varies)
Graph model. Inherits MEM0_LLM_MODEL for anthropic/ollama; defaults to gemini-2.5-flash-lite for gemini/gemini_split
GOOGLE_API_KEY
--
Google API key (required for gemini/gemini_split graph providers)
MEM0_GRAPH_CONTRADICTION_LLM_PROVIDER
anthropic
Contradiction LLM provider in gemini_split mode (anthropic, anthropic_oat, ollama)
MEM0_GRAPH_CONTRADICTION_LLM_MODEL
(provider-aware)
Contradiction model in gemini_split mode. Defaults to claude-opus-4-6 for anthropic/anthropic_oat providers; inherits MEM0_LLM_MODEL for others.
MEM0_OLLAMA_KEEP_ALIVE
30m
How long Ollama keeps the model in VRAM between calls (e.g., 1h, 5m). Prevents model unload during multi-call graph pipelines
MEM0_OLLAMA_THINK
false
Set to true to re-enable qwen3 thinking mode (disabled by default to prevent <think> + format:"json" collision)
Embedder
Variable
Default
Description
MEM0_EMBED_PROVIDER
ollama
Embedding provider (ollama or openai)
MEM0_EMBED_MODEL
bge-m3
Embedding model name
MEM0_EMBED_URL
(cascades)
Ollama URL for embeddings. Cascades: MEM0_EMBED_URL → MEM0_OLLAMA_URL → http://localhost:11434
MEM0_EMBED_DIMS
1024
Embedding vector dimensions
Vector Store (Qdrant)
Variable
Default
Description
MEM0_QDRANT_URL
http://localhost:6333
Qdrant REST API URL
MEM0_QDRANT_API_KEY
--
Qdrant API key (for Qdrant Cloud)
MEM0_QDRANT_ON_DISK
false
Store vectors on disk (reduces RAM, slower search)
MEM0_QDRANT_TIMEOUT
(client default)
Qdrant REST API timeout in seconds (e.g., 30). Only set if you hit ReadTimeout during collection operations
Graph memory is disabled by default (MEM0_ENABLE_GRAPH=false) to protect your Claude quota. Each add_memory with graph enabled triggers 3 additional LLM calls for entity extraction, relationship generation, and conflict resolution.
Using Ollama for Graph Operations
To eliminate Claude quota usage for graph ops, use a local Ollama model:
The gemini_split provider routes graph pipeline calls to different LLMs based on the operation. Entity extraction (Calls 1 & 2) goes to Gemini for speed and cost; contradiction detection (Call 3) goes to Claude for accuracy.
Benchmark results across 248 test cases: Gemini scores 85.4% on entity extraction (vs Claude's 79.1%), while Claude scores 100% on contradiction detection (vs Gemini's 80%). The split-model combines the best of both.
Transport Modes
Mode
Use Case
Config
stdio (default)
Claude Code integration
MEM0_TRANSPORT=stdio
sse
Legacy remote clients
MEM0_TRANSPORT=sse
streamable-http
Modern remote clients
MEM0_TRANSPORT=streamable-http
For remote deployments, MCP SDK >= 1.23.0 enables DNS rebinding protection by default.
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Run unit tests
python3 -m pytest tests/unit/ -v
# Run contract tests (validates mem0ai internal API assumptions)
python3 -m pytest tests/contract/ -v
# Run integration tests (requires live Qdrant + Neo4j + Ollama)
python3 -m pytest tests/integration/ -v
# Run all tests
python3 -m pytest tests/ -v
Test Structure
tests/unit/ -- Pure unit tests with mocked dependencies (env, auth, config, config matrix, concurrency, MCP protocol, helpers, hooks, LLM providers, graph tools, LLM router, server)
tests/integration/ -- Live infrastructure tests (memory lifecycle, graph ops, bulk operations, hooks) against real Qdrant + Neo4j + Ollama. Marked with @pytest.mark.integration.
Contract tests catch breaking changes in mem0ai upgrades before they reach production.
Telemetry
All mem0ai telemetry is suppressed. os.environ["MEM0_TELEMETRY"] = "false" is set at package import time, before any mem0 module is loaded. No PostHog events are sent.
License
MIT
M
Mem0 MCP Selfhosted
elvismdev·111 ดาว·
Self-hosted mem0 MCP server for Claude Code. Run a complete memory server against self-hosted Qdrant + Neo4j + Ollama while using Claude as the main LLM.
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
Mem0 MCP Selfhosted ต้องใช้ API key ไหม?
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Mem0 MCP Selfhosted ใช้ทรานสปอร์ตแบบใด?
Mem0 MCP Selfhosted ทำงานแบบโลคัลผ่าน stdio
Mem0 MCP Selfhosted ถูกตรวจสอบล่าสุดเมื่อใด?
ตรวจสอบล่าสุดเมื่อ 2026-10-27 Self-hosted mem0 MCP server for Claude Code. Run a complete memory server against self-hosted Qdrant + Neo4j + Ollama while using Claude as the main LLM.