# localmem-mcp-zh

> 🇨🇳 本地优先、零 API 的中文 AI 记忆 MCP — SQLite + fastembed 中文优化

![Demo](docs/demo.png)

`localmem-mcp-zh` 给任何 MCP 兼容客户端（Claude Code、Codex、Gemini CLI、Cursor、Windsurf、Cline …）一个**完全本地、零云调用**的长期记忆。所有记忆存于一个 SQLite 文件，搜索走本地余弦相似度 + 中文 FTS5 + jieba 分词加权 BM25，**检索不花一个 token**。

灵感来自 [OpenAgentHQ/localmem-mcp](https://github.com/OpenAgentHQ/localmem-mcp)（6 ⭐，2026-08-14 创建），原版纯英文。本仓库做**中文优化**：

- jieba 中文分词，避免英文 unicode61 分词器在中文上失灵
- 默认嵌入模型 `BAAI/bge-small-zh-v1.5`（中文检索 SOTA 小模型）
- 工具说明全部中英双语，方便中文 agent 理解意图

## 为什么需要它

大部分 AI 记忆工具（Mem0、Zep、Graphiti）在存储和检索路径上都要调 LLM。本仓库只在本机跑一次嵌入模型，之后**永远离线**。隐私之外更重要的是成本：存储 1 万条记忆、检索 1 万次，`localmem-mcp-zh` 调用 LLM 的次数是 **0**。

## 安装

```bash
pip install localmem-mcp-zh
# 或
uvx localmem-mcp-zh
```

第一次运行会从 Hugging Face 下载嵌入模型（约 90 MB），之后完全离线。

## 接入客户端

### Claude Code / Codex / Gemini CLI

把下面这段加到 MCP 配置（`~/.config/mcp/servers.json` 或对应客户端的配置文件）：

```json
{
  "mcpServers": {
    "localmem-zh": {
      "command": "uvx",
      "args": ["localmem-mcp-zh"],
      "env": {
        "LOCALMEM_DB": "~/.localmem-mcp-zh/memories.db"
      }
    }
  }
}
```

### Cursor / Windsurf / VS Code

在 IDE 的 MCP 设置里新增同名 server，参数同上。

## 四个工具

| 工具 | 用途 |
| --- | --- |
| `store_memory` | 保存一条持久记忆 — 决策、偏好、事实，可带 tags |
| `search_memory` | 按**语义**查找记忆。"哪个数据库？"能找到"我们选了 SQLite" |
| `recall_memory` | 按 id 重新读取一条记忆，或追最近的几条 |
| `memory_stats` | 数据库在哪、存了多少条 |

## 隐私

没有任何网络请求，除了一次性下载嵌入模型。删掉 `~/.localmem-mcp-zh/memories.db` 记忆就没了。

## 开发

```bash
git clone https://github.com/lvyuan1688/localmem-mcp-zh
cd localmem-mcp-zh
pip install -e ".[dev]"
pytest
```

## License

MIT — 见 `LICENSE`。