elvismdev/mem0-mcp-selfhosted

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.
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 |
Python >= 3.10 and uv.
> **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):
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:
Try It
Restart Claude Code, then:
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:
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:
Or install globally (all projects):
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 |