mem0-mcp-server

A local MCP server that exposes Mem0 as persistent memory tools to any MCP client: Codex, Claude Desktop, Cursor, and anything else that speaks MCP over stdio.

Everything runs on your own machine. Data lives under ~/.mem0/, there is no cloud API and no API key required.

Why this exists

MCP clients like Codex already support memory tools over MCP, but most "memory server" setups push you toward a hosted service. This project is the opposite: Mem0 runs locally (Qdrant in embedded mode, SQLite for history), and the server is a thin MCP bridge in front of it.

The server is intentionally small. It implements just enough of the MCP protocol to expose a set of memory tools. No framework, no extra runtime, one Python file.

Related MCP server: GroundMemory

How it works

MCP client ── stdio ──▶ mcp_server.py ──▶ mem0.Memory (your Python env)
                                              │
                                              ├─ Qdrant (local vector store)
                                              └─ SQLite (history)

The client starts mcp_server.py as a subprocess and talks to it over newline-delimited JSON-RPC on stdin/stdout.

Tools

Requirements

• Python 3.10 or newer

• An MCP client (Codex, Claude Desktop, Cursor, ...)

• Optional but recommended: fastembed for local semantic search

Install

The project is pip-installable:

python -m venv .venv
source .venv/bin/activate
pip install .

If you prefer an editable install while developing:

pip install -e .

Optional extras:

pip install ".[fastembed]"   # local embeddings, recommended
pip install ".[ollama]"      # use a local Ollama instance for embeddings

Already have a Python environment with Mem0 installed? Then you don't need to install anything. Just point your MCP client at <REPO_DIR>/mcp_server.py and use that environment's Python.

Quick test

Run this before wiring up a client, so you know the server itself works:

mem0-mcp-server --self-test

Or, without installing:

MEM0_DIR=/tmp/mem0_home \
  <VENV_PYTHON> <REPO_DIR>/mcp_server.py --self-test

The self-test writes one memory ("我喜欢喝美式咖啡"), searches for it, and prints both results.

Register with an MCP client

In the commands below, <VENV_PYTHON> is the absolute path to your Python interpreter and <REPO_DIR> is the absolute path to this repository.

Codex CLI

codex mcp add mem0-local -- \
  <VENV_PYTHON> \
  <REPO_DIR>/mcp_server.py

Restart Codex, then try: "list my mem0 memories" or "remember that I like dark mode".

Claude Desktop

claude mcp add mem0-local -- \
  <VENV_PYTHON> \
  <REPO_DIR>/mcp_server.py

Cursor

Open the MCP settings in Cursor, add a new stdio server, and set the command to:

<VENV_PYTHON> <REPO_DIR>/mcp_server.py

If you installed the package, you can also register the console script mem0-mcp-server directly instead of pointing at mcp_server.py.

Embedding options

The server picks an embedding backend in this order:

1. OPENAI_API_KEY is set → OpenAI embeddings (1536 dims)

2. fastembed is installed → FastEmbed with BAAI/bge-small-zh-v1.5 (512 dims, works well for Chinese, first run downloads the model)

3. Ollama is running and the ollama package is installed → Ollama embeddings

4. Nothing available → MockEmbeddings, fully offline but all scores are 1.0

Environment variables:

Automatic memory hooks (Codex only)

The hooks/ directory contains two scripts that give Codex automatic memory:

• on_session_start.py — prints recent memories at session start; Codex reads them as developer context.

• on_stop.py — saves the last user request + assistant reply after every turn. Each turn is captured once, deduplicated via ~/.mem0/captured_turns/.

Install them:

cp <REPO_DIR>/hooks/hooks.json ~/.codex/hooks.json

Then edit ~/.codex/hooks.json and replace the <VENV_PYTHON> and <REPO_DIR> placeholders with real paths. The first time Codex runs the hooks, it will ask you to review and trust them under /hooks.

These hooks are Codex-specific. Other MCP clients don't have this hook mechanism, so they get the memory tools but not automatic context loading or automatic turn saving.

Data and privacy

• All data stays on your machine under ~/.mem0/ (or $MEM0_DIR).

• Telemetry is disabled: the server sets MEM0_TELEMETRY=false at startup.

• Proxy environment variables are stripped at startup because the server only talks to local services, and a socks:// proxy can crash httpx during initialization.

• With no OPENAI_API_KEY, no network request is made at all.

Known limitations

• Default is infer=False: memories are stored as raw text, without Mem0's LLM-based fact extraction, deduplication, or entity linking.

• This is a minimal MCP implementation. It covers the tools listed above and nothing more.

• The server has been tested mainly with Codex. It speaks standard MCP, so other clients should work, but if something misbehaves, open an issue.

Project layout

mem0-mcp-server/
├── LICENSE
├── README.md
├── pyproject.toml
├── mcp_server.py
└── hooks/
    ├── hooks.json
    ├── on_session_start.py
    └── on_stop.py

License

MIT. See LICENSE.

mem0-mcp-server（中文）

一个本地 MCP 服务器，把 Mem0 的记忆能力以 MCP 工具的形式暴露给任意客户端：Codex、Claude Desktop、Cursor，以及其他支持 stdio MCP 的 agent。

全部在本机运行，数据默认存在 ~/.mem0/，不依赖云端 API，也不需要 API key。

为什么做这个

Codex 这类 MCP 客户端本身支持通过 MCP 调用记忆工具，但常见的“记忆服务器”方案 往往把你往托管服务上引。这个项目反过来：Mem0 完全本地运行（Qdrant 嵌入式模式 + SQLite 历史记录），服务器只是它前面的一层很薄的 MCP 桥。

实现刻意保持精简：只实现了一组记忆工具需要的 MCP 协议部分，没有框架、没有额外 运行时，核心就是一个 Python 文件。

工作原理

MCP 客户端 ── stdio ──▶ mcp_server.py ──▶ mem0.Memory（你的 Python 环境）
                                              │
                                              ├─ Qdrant（本地向量库）
                                              └─ SQLite（历史记录）

客户端把 mcp_server.py 作为子进程启动，通过 stdin/stdout 上的换行分隔 JSON-RPC 通信。

可用工具

环境要求

• Python 3.10 及以上

• 一个 MCP 客户端（Codex、Claude Desktop、Cursor 等）

• 可选但推荐：fastembed，用于本地语义检索

安装

项目支持 pip 安装：

python -m venv .venv
source .venv/bin/activate
pip install .

开发时可以用可编辑安装：

pip install -e .

可选依赖：

pip install ".[fastembed]"   # 本地 embedding，推荐
pip install ".[ollama]"      # 用本地 Ollama 做 embedding

如果你已经有一个装好 Mem0 的 Python 环境，那什么都不用装，直接用那个环境的 Python 指向 <REPO_DIR>/mcp_server.py 注册即可。

快速自测

接客户端之前先跑一下，确认服务器本身没问题：

mem0-mcp-server --self-test

不想安装也可以：

MEM0_DIR=/tmp/mem0_home \
  <VENV_PYTHON> <REPO_DIR>/mcp_server.py --self-test

自测会写入一条记忆（“我喜欢喝美式咖啡”）、检索它，然后打印结果。

注册到 MCP 客户端

下面命令里的 <VENV_PYTHON> 是你的 Python 解释器绝对路径，<REPO_DIR> 是 本仓库的绝对路径。

Codex CLI

codex mcp add mem0-local -- \
  <VENV_PYTHON> \
  <REPO_DIR>/mcp_server.py

重启 Codex 后试试：“列出我的 mem0 记忆”，或者“记住我喜欢深色模式”。

Claude Desktop

claude mcp add mem0-local -- \
  <VENV_PYTHON> \
  <REPO_DIR>/mcp_server.py

Cursor

打开 Cursor 的 MCP 设置，新增一个 stdio 服务器，命令填：

<VENV_PYTHON> <REPO_DIR>/mcp_server.py

如果用 pip 安装过，也可以直接把控制台命令 mem0-mcp-server 注册进去，不用 指向 mcp_server.py。

Embedding 说明

服务器按下面的优先级选择 embedding：

1. 设置了 OPENAI_API_KEY → OpenAI embedding（1536 维）

2. 装了 fastembed → FastEmbed + BAAI/bge-small-zh-v1.5（512 维，中文效果 好，首次运行会自动下载模型）

3. 本地 Ollama 在运行且装了 ollama 包 → Ollama embedding

4. 都没有 → MockEmbeddings，完全离线，但所有分数都是 1.0

环境变量：

自动记忆钩子（仅 Codex）

hooks/ 里有两个脚本，给 Codex 提供自动记忆：

• on_session_start.py：会话开始时打印最近的记忆，Codex 会把它当作 developer context 读入。

• on_stop.py：每轮回复结束后，把“用户请求 + Codex 回复”存进本地 Mem0， 每个 turn 只存一次，通过 ~/.mem0/captured_turns/ 去重。

安装：

cp <REPO_DIR>/hooks/hooks.json ~/.codex/hooks.json

然后把 ~/.codex/hooks.json 里的 <VENV_PYTHON> 和 <REPO_DIR> 占位符换成 真实路径。Codex 第一次运行钩子时，会要求你在 /hooks 里审查并信任它们。

这套钩子是 Codex 专用的。其他 MCP 客户端没有这种钩子机制，所以它们能用记忆 工具，但没有自动加载上下文和自动保存每一轮对话的功能。

数据与隐私

• 所有数据都在本机 ~/.mem0/（或 $MEM0_DIR）下。

• 遥测已关闭：服务器启动时会设置 MEM0_TELEMETRY=false。

• 启动时会清掉代理环境变量，因为本服务只访问本地服务，而 socks:// 代理会让 httpx 初始化崩溃。

• 不设置 OPENAI_API_KEY 时，完全不会发起网络请求。

已知边界

• 默认 infer=False：记忆按原文存储，不做 Mem0 的 LLM 事实抽取、去重和实体 链接。

• 这是最小实现，MCP 协议只覆盖上面列出的工具。

• 目前主要用 Codex 测过。它实现的是标准 MCP，其他客户端理论上能用，但如果出 问题，欢迎提 issue。

目录结构

mem0-mcp-server/
├── LICENSE
├── README.md
├── pyproject.toml
├── mcp_server.py
└── hooks/
    ├── hooks.json
    ├── on_session_start.py
    └── on_stop.py

许可证

MIT，见 LICENSE。