# mem0-local-mcp

A fully local, self-hosted [mem0](https://github.com/mem0ai/mem0) memory server for [MCP](https://modelcontextprotocol.io) clients (Claude Code, Claude Desktop, Cursor, …).

- **Local embeddings** via [fastembed](https://github.com/qdrant/fastembed) (ONNX, no PyTorch, no GPU) — `BAAI/bge-small-en-v1.5`, 384-dim. Can be used with different LLM via API key.
- **Local vector store** via [Qdrant](https://qdrant.tech) on `localhost`.
- **Switchable extraction LLM** — Anthropic Claude (default) or Google Gemini, chosen by one env var.
- **No API key needed for normal use.** Reads and verbatim writes (`infer=False`) run entirely on your machine. A provider key is used only when you opt into LLM fact-extraction (`infer=True`).

## Tools

| Tool | Purpose |
|------|---------|
| `add_memory(content, user_id, agent_id?, run_id?, infer=False)` | Store a memory. `infer=False` stores verbatim (local, no LLM); `infer=True` extracts/dedupes via the LLM. |
| `search_memories(query, user_id, agent_id?, run_id?, top_k=5)` | Semantic search within a scope. |
| `list_memories(user_id, agent_id?, run_id?)` | List a scope without ranking. |
| `delete_memory(memory_id)` | Delete a single memory. |

Memories are scoped by any of `user_id` / `agent_id` / `run_id`.

## Instructions for your agent

Copy the block below and paste it to your coding agent (Claude Code, Cursor, …) — it will install and verify everything for you:

```text
Set up the mem0-local-mcp memory server on this machine for me:

1. Ensure a local Qdrant is running on port 6333: run `curl -s http://localhost:6333/`.
   If it is not running, start it with Docker:
   docker run -d --name qdrant --restart always -p 6333:6333 -v ~/.qdrant_storage:/qdrant/storage qdrant/qdrant
   If Docker is unavailable, download the Qdrant binary for my OS from
   https://github.com/qdrant/qdrant/releases and run it.
2. Ensure `uv` is installed (`which uv`); if not, install it from https://docs.astral.sh/uv/.
3. Register the MCP server at user scope:
   claude mcp add mem0 --scope user -- uvx --from git+https://github.com/sanchezvivi/mem0-local-mcp.git mem0-local-mcp
4. Verify with `claude mcp list` that `mem0` shows Connected. The first run downloads the
   embedding model (~130 MB), so allow up to a minute.
5. Reads and infer=False writes need no API key. Only if I want infer=True (LLM) extraction,
   confirm ANTHROPIC_API_KEY (or GOOGLE_API_KEY with MEM0_LLM_PROVIDER=gemini) is set in my
   environment before launching the client. Then tell me it is ready.
```

## Prerequisites

**1. A running Qdrant** (pick one):

```bash
# Docker
docker run -d --name qdrant -p 6333:6333 -v ~/.qdrant_storage:/qdrant/storage qdrant/qdrant

# or the binary (macOS/Linux release from https://github.com/qdrant/qdrant/releases)
./qdrant
```

**2. [uv](https://docs.astral.sh/uv/)** to run the server (`uvx`), or `pip install mem0-local-mcp`.

The embedding model (~130 MB) downloads automatically on first use.

## Install in Claude Code

```bash
claude mcp add mem0 --scope user -- \
  uvx --from git+https://github.com/sanchezvivi/mem0-local-mcp.git mem0-local-mcp
```

For Gemini extraction, install the extra and select the provider:

```bash
claude mcp add mem0 --scope user \
  --env MEM0_LLM_PROVIDER=gemini \
  -- uvx --from "git+https://github.com/sanchezvivi/mem0-local-mcp.git#egg=mem0-local-mcp[gemini]" mem0-local-mcp
```

## Other MCP clients

Any stdio MCP client can launch it. Example config entry:

```json
{
  "mcpServers": {
    "mem0": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sanchezvivi/mem0-local-mcp.git", "mem0-local-mcp"]
    }
  }
}
```

## Configuration

All optional, with defaults:

| Variable | Default | Notes |
|----------|---------|-------|
| `MEM0_USER_ID` | `default_user` | Default scope when a tool call omits `user_id`. |
| `MEM0_LLM_PROVIDER` | `anthropic` | `anthropic` or `gemini`. Only used for `infer=True`. |
| `MEM0_ANTHROPIC_MODEL` | `claude-haiku-4-5` | |
| `MEM0_GEMINI_MODEL` | `gemini-2.5-flash` | Requires the `gemini` extra. |
| `MEM0_EMBED_MODEL` | `BAAI/bge-small-en-v1.5` | Any fastembed model. |
| `MEM0_EMBED_DIMS` | `384` | Must match the embed model. |
| `MEM0_QDRANT_HOST` | `localhost` | |
| `MEM0_QDRANT_PORT` | `6333` | |
| `MEM0_COLLECTION` | `mem0` | |
| `ANTHROPIC_API_KEY` | — | Only needed for `infer=True` with Anthropic. |
| `GOOGLE_API_KEY` | — | Only needed for `infer=True` with Gemini. |

Keys are read from the process environment; nothing is written to disk by this server.

## Local development

```bash
git clone https://github.com/sanchezvivi/mem0-local-mcp.git
cd mem0-local-mcp
uv venv && uv pip install -e ".[gemini]"
.venv/bin/mem0-local-mcp        # stdio server
```

## License

MIT — see [LICENSE](LICENSE).