AI导哈

本地记忆MCP服务器

一个完全本地化且私有的AI记忆存储与检索服务器，提供持久化、可搜索的长期记忆功能，支持混合搜索架构和硬件加速。

  • by YanZiBin
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 YanZiBin/Local-memory-mcp

使用说明

本地内存MCP服务器（项目内存库）

英语 | 中文说明

🇬🇧 英文描述

🌟 设计理念与动机

“你的记忆属于你，而不是云。”

我创建这个项目有一个简单而强大的目标： 全面数据主权. 在基于订阅的人工智能服务和云依赖的时代，我想要一个解决方案：

  1. 100%本地和私人： 任何数据都不会离开你的机器。无API费用，无隐私风险。
  2. 永久的： 只要你的硬盘存在，你的人工智能的记忆就存在。无需担心服务中断。
  3. 无限容量： 唯一的限制是您的本地磁盘空间。
  4. 高性能： 利用本地GPU加速（TensorRT/CUDA）实现闪电般快速的嵌入和检索。

这是一个 内存上下文协议（MCP） 服务器，为您的AI（如Gemini CLI、Claude Desktop）提供持久、可搜索和不断发展的长期内存。

✨ 主要特点

  • 混合搜索架构： 联合 LanceDB （用于语义理解的矢量搜索）和 SQLite FTS5 （全文搜索以精确匹配关键字）以实现高精度召回。
  • 硬件加速： 由ONNX Runtime提供支持，带有TensorRT/CUDA执行提供程序，用于毫秒级嵌入生成。
  • 标准MCP工具：
    • save_memory：存储片段、代码、文档或个人事实（具有自动重复检测功能）。
    • search_memory：语义和关键字检索。
    • list_memories：查看最近的条目。
    • delete_memory：管理和清理数据。
    • update_memory：按ID更新现有内存。
  • 延迟加载： 通过按需资源初始化优化启动时间。
  • 零成本： 完全在现有硬件上运行。

🛠️ 先决条件

  • 操作系统： Windows（已测试）
  • python 3.10或更高。
  • 硬件： 建议使用NVIDIA GPU（用于TensorRT/CUDA加速），但适用于CPU。
  • MCP客户端： Gemini CLI 或 克劳德桌面版或任何可以配置MCP的IDE。

🚀 安装和设置

1.克隆存储库

git clone https://github.com/YanZiBin/Local-memory-mcp.git
cd Local-memory-mcp

2.创建Python环境（Conda推荐）

为了确保GPU库正常工作，强烈建议使用Conda。

conda create -n Local-memory-mcp python=3.10
conda activate Local-memory-mcp

3.安装依赖项

pip install fastmcp lancedb onnxruntime-gpu transformers numpy uvicorn

（注意：如果您没有GPU，请安装 onnxruntime 而不是 onnxruntime-gpu)

4.下载嵌入模型

此项目使用 BAAI/bge-m3 转换为ONNX这里。您需要将模型文件下载到 bge-m3-onnx 目录。

你可以使用 huggingface-cli 或手动下载这些文件：

  • config.json
  • model.onnx
  • model.onnx_data
  • vocab.txt
  • sentence_transformers.onnx
  • sentence_transformers.onnx_data
  • tokenizer_config.json
  • tokenizer.json

将它们放入名为的文件夹中 bge-m3-onnx 在项目根中。

🏃‍♂️ 运行服务器

由于此服务器使用大量本地型号，我们建议 手动启动（SSE模式） 为了稳定。

  1. 启动服务器： 打开终端并运行：

    python server.py

    等到你看到： INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

  2. 连接您的客户端（例如Gemini CLI）：

    编辑Gemini CLI配置文件（通常在 ~/.gemini/settings.json 或 %USERPROFILE%\.gemini\settings.json 在Windows上）：

    {
  "mcpServers": {
    "local-memory": {
      "url": "http://localhost:8000/sse",
      "type": "sse"
    }
  }
}

  3. 开始使用它！ 打开Gemini CLI并尝试：

    “节省内存：我的项目使用Python 3.10。” “在我的记忆中搜索‘项目’。”

🗺️ 路线图

我们目前正在过渡到 第4阶段（内存管理）.

  • [x] 第一阶段：原型

    • 使用初始化MCP服务器 fastmcp.
    • 基本内存存储（dict）。
    • 实施基本 save_memory & search_memory （关键字匹配）。
    • 使用Gemini CLI进行手动连接测试。

  • [x] 第二阶段：坚持

    • 整合 SQLite FTS5 和 LanceDB.
    • 整合本地 ONNX嵌入模型.
    • 双存储架构（全文+矢量）。
    • list_memories 和 delete_memory 工具。

  • [x] 第三阶段：智能检索（已完成）

    • [x] 实施 RRF（互惠等级融合） 高质量混合搜索算法。
    • [x] 添加相似性阈值和Top-K限制以减少噪声。
    • []实施 上下文检索 （增强的上下文存储）。
    • []（可选）添加Reranker以获得更高的精度。

  • [ ] 阶段4：内存管理

    • [x] 保存时的重复检测（基于相似性）。
    • []生命周期管理（时间衰减、冲突标记）。

  • [ ] 阶段5：高级优化

    • []暴露 资源：项目总结、ADR（建筑决策记录）护栏。
    • []建筑护栏（召回违规ADR）和任务链跟踪。

🇨🇳 中文说明

🌟 设计初衷

“你的记忆属于你，而不是云端。”

开发这个项目的初衷非常纯粹：实现完全的数据主权。 在这个万物订阅制、隐私担忧日益严重的时代，我希望构建一个这样的解决方案：

  1. 完全本地化 & 隐私安全： 没有任何数据会上传云端。没有 API 调用费，没有隐私泄露风险。
  2. 永久存储： 只要你的硬盘还在，你的 AI 记忆就在。不必担心服务商倒闭或“跑路”。
  3. 无限容量： 唯一的限制是你本地硬盘的大小（相当于无限）。
  4. 极致性能： 利用本地 GPU 加速（TensorRT/CUDA），实现毫秒级的记忆存取。

这是一个 MCP（模型上下文协议） 服务器，它为你的 AI 工具（如 Gemini CLI, Claude Desktop）提供了一个持久化、可搜索、不断进化的“外脑”。

✨ 核心功能

  • 混合搜索架构： 结合了 LanceDB（向量搜索，理解语义）和 SQLite FTS5（全文搜索，精准匹配关键词），并通过 RRF (倒数排名融合) 算法进行智能排序，确保召回率和准确率。
  • 硬件加速： 基于 ONNX Runtime 和 TensorRT/CUDA，充分释放本地显卡性能。
  • 标准 MCP 工具集：
    • save_memory: 保存代码片段、文档总结或个人事实（自动检测重复内容）。
    • search_memory: 语义或关键词检索（支持相似度阈值过滤）。
    • list_memories: 查看最近的记忆。
    • delete_memory: 删除过时信息。
    • update_memory: 按 ID 更新现有记忆。
  • 懒加载设计 (Lazy Loading)： 优化启动流程，按需加载重型模型，拒绝卡顿。
  • 零成本： 以前需要付费购买的向量存储服务，现在免费运行在你自己的电脑上。

🛠️ 环境要求

  • 操作系统： Windows (已充分测试)
  • python 3.10 或更高版本。
  • 硬件： 推荐使用 NVIDIA 显卡（以获得 TensorRT/CUDA 加速），但也支持 CPU 运行。
  • MCP 客户端： Gemini CLI 或 克劳德桌面版。或者任何可以配置mcp的IDE。

🚀 安装与配置指南

1. 克隆项目

git clone https://github.com/YanZiBin/Local-memory-mcp.git
cd Local-memory-mcp

2. 创建 Python 环境 (强烈推荐 Conda)

为了避免 CUDA 依赖冲突，建议使用 Conda。

conda create -n Local-memory-mcp python=3.10
conda activate Local-memory-mcp

3. 安装依赖库

pip install fastmcp lancedb onnxruntime-gpu transformers numpy uvicorn

（注：如果你没有 NVIDIA 显卡，请将 onnxruntime-gpu 替换为 onnxruntime）

4. 下载嵌入模型 (Embedding Model)

本项目使用 BAAI/bge-m3 的 ONNX 量化版本这里。你需要将模型文件下载到项目根目录下的 bge-m3-onnx 文件夹中。

你可以使用 huggingface-cli 或手动下载以下文件：

  • config.json
  • model.onnx
  • model.onnx_data
  • vocab.txt
  • sentence_transformers.onnx
  • sentence_transformers.onnx_data
  • tokenizer_config.json
  • tokenizer.json

确保它们都在 bge-m3-onnx 文件夹内。

🏃‍♂️ 运行与使用

由于本项目加载了本地大模型，为了稳定性，我们推荐使用 手动启动 (SSE 模式)。

  1. 启动服务器： 打开终端（CMD/PowerShell），运行：

    python server.py

    等待直到看到提示：INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

  2. 连接客户端 (以 Gemini CLI 为例)：

    编辑你的 Gemini CLI 配置文件（通常位于 ~/.gemini/settings.json 或 Windows 的 %USERPROFILE%\.gemini\settings.json）：

    {
  "mcpServers": {
    "local-memory": {
      "url": "http://localhost:8000/sse",
      "type": "sse"
    }
  }
}

  3. 开始体验！ 打开 Gemini CLI，直接对话：

    “帮我记住：我的项目运行在 Python 3.10 环境下。” “搜索记忆：关于项目环境的信息。”

🗺️ 开发路线图 (Roadmap)

目前项目正过渡到 第四阶段：记忆管理。

  • [x] 第一阶段：原型验证

    • 使用 fastmcp 初始化 MCP 服务器。
    • 使用内存字典进行临时存储。
    • 实现基础的 save_memory 和 search_memory（关键词匹配）。
    • 配置 stdio 并在 Gemini CLI 中测试手动连接。

  • [x] 第二阶段：持久化存储

    • 引入 SQLite FTS5 和 LanceDB。
    • 集成本地 ONNX 嵌入模型 生成向量。
    • 实现双库存储（全文 + 向量）。
    • 新增 list_memories（列出记忆）和 delete_memory（删除记忆）工具。

  • [x] 第三阶段：智能筛选 (已完成)

    • [x] 实现 RRF (倒数排名融合) 算法，实现高质量混合检索。
    • [x] 增加相似度阈值和 Top-K 限制，减少噪声。
    • [ ] 实现 上下文检索（增强文本存储）。
    • [ ] （可选）加入 Reranker 重排序模型以提升精度。

  • [ ] 第四阶段：记忆管理

    • [x] 保存时自动检测重复内容（基于相似度）
    • [ ] 实现生命周期管理（时间衰减、冲突标记）。

  • [ ] 第五阶段：高级优化

    • [ ] 暴露 资源（资源）：项目摘要、ADR 架构决策记录守栏等。
    • [ ] 实现架构守栏（违规时自动召回 ADR）和任务链跟踪。

许可证： 麻省理工学院 作者 [晏子斌]

相关 MCP