Memorious MCP

memorious-mcp

一款 100% 本地且私密 的语义记忆 MCP（Model Context Protocol）服务，供 AI 助手使用。基于 ChromaDB 实现向量相似度搜索，并使用 FastMCP 2。完全在本地运行——数据绝不会离开你的设备。

概览

memorious-mcp 通过三个核心操作为 AI 助手提供长期记忆能力：store、recall 和 forget。它使用 ChromaDB 向量数据库进行语义相似度搜索，因此即使表述与最初存储时不同，助手也能检索相关记忆。所有处理和存储都在你的设备上本地完成——数据绝不会离开你的设备，确保完全的隐私和安全。

主要功能

• 🏠 100% 本地且私密：所有数据处理和存储都在你的设备上完成，不会上传到云端
• 💾 持久记忆：使用 ChromaDB 基于磁盘的存储，让数据在不同会话间持久保留
• 🔍 语义搜索：通过向量嵌入实现基于相似度的记忆检索
• ⚡ 简洁的 API：提供三个直观的记忆管理工具
• 🚀 FastMCP 集成：基于 FastMCP 构建，高效实现 MCP 服务
• 🎯 规范键设计：针对简短且适合嵌入的键进行了优化（1-5 个词）
• 📂 按文件夹隔离存储：按项目隔离记忆。

为什么要开发这个项目

🔍 MCP 生态中的空缺：尽管记忆 MCP 服务越来越受欢迎，但当时还没有一款现有的记忆服务，能够兼顾语义相似度搜索和完全基于文件、按文件夹隔离的本地存储。大多数记忆解决方案要么：

• ☁️ 需要云服务和外部 API 调用（损害隐私），用于嵌入、存储或两者兼需
• 🔤 只支持精确键值匹配（无法理解语义）
• 📁 不支持按文件夹隔离的本地存储

使用场景

• 个人助手记忆：记住用户偏好、习惯和个人信息
• 保留上下文：在不同会话间保留对话上下文
• 知识管理：存储和检索特定项目的信息
• 个性化：让 AI 助手能够根据存储的偏好提供个性化回复
• 隐私优先的 AI：将敏感个人数据保留在本地，同时拥有持久记忆
• 按文件夹隔离的 AI Agent：非常适合配合 VS Code Copilot Chat 模式和 Claude Code Agent 使用，实现按项目隔离记忆

安装

用于 VS Code

请先确保已安装 uv 及其 uvx 命令。

用于大多数 MCP 客户端

添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "memorious": {
      "command": "uvx",
      "args": ["memorious-mcp"]
    }
  }
}

开发 / 本地安装

uv sync

用于开发/本地安装：

{
  "mcpServers": {
    "memorious": {
      "command": "uv",
      "args": ["run", "memorious-mcp"],
      "cwd": "/path/to/memorious-mcp"
    }
  }
}

工具

store

使用针对向量相似度优化的简短规范键，存储事实、偏好或信息。

参数：

• key（string）：简短的规范键（1-5 个词，以空格分隔）
• value（string）：要存储的实际信息

recall

使用语义相似度搜索检索已存储的记忆。

参数：

• key（string）：用于相似度搜索的查询键
• top_k（int，默认值：3）：要返回的最大结果数

forget

删除与查询键匹配的记忆。

参数：

• key（字符串）：用于查找要删除的记忆的查询键
• top_k（整数，默认值：3）：要考虑的最相近匹配项数量

Claude CLI 配置

要将 memorious-mcp 添加到 Claude CLI，请使用以下命令：

# Add the MCP server using uvx (recommended)
claude mcp add memorious-mcp uvx memorious-mcp

# Alternative: for development/local installation
claude mcp add memorious-mcp uv run --project <memorious_mcp_src> memorious-mcp

然后，你可以列出已配置的 MCP 服务：

claude mcp list

如有需要，也可以移除该服务：

claude mcp remove memorious-mcp

工具签名示例

• store(key: str, value: str) -> {"id": str}
• recall(key: str, top_k: int = 3) -> {"results": [...]}，其中每个结果都包含 id、key、value、distance、timestamp
• forget(key: str, top_k: int = 3) -> {"deleted_ids": [...]}

测试

运行以下命令进行测试：

# Using uv
uv run python -m pytest tests/ -v

# Or if pytest is available globally
pytest tests/ -v

技术详情

• 后端：使用 ChromaDB 进行持久化磁盘存储
• 嵌入：使用 ChromaDB 的默认嵌入函数（本地处理）
• 存储位置：./.memorious 目录（可配置）
• Python 版本：需要 Python ≥3.12
• 许可证：MIT
• 隐私：不发送网络请求，无云依赖，所有数据均保存在本地

软件包结构

项目遵循标准的 Python 软件包布局：

memorious-mcp/
├── src/
│   └── memorious_mcp/
│       ├── __init__.py
│       ├── main.py                 # MCP server entry point
│       └── backends/
│           ├── __init__.py
│           ├── memory_backend.py   # Abstract base class
│           └── chroma_backend.py   # ChromaDB implementation
├── tests/
│   └── test_chroma_backend.py      # Integration tests
├── pyproject.toml                  # Package configuration
└── README.md

该服务通过 stdio 传输方式为本地/CLI 集成而设计，适用于注重隐私和数据安全的个人 AI 助手和开发工作流。

局限性

⚠️ 重要安全注意事项

由于数据永远不会离开你的本地计算机，因此你的数据 100% 安全且私密，但仍应谨慎决定存储哪些内容：

• 数据未加密存储：所有存储的数据均以未加密格式持久化到 .memorious 目录中的磁盘
• 避免存储机密信息：请勿存储密码、API 密钥、私钥、个人身份识别号码、财务信息或任何其他敏感凭据
• 本地文件访问：任何能够访问你的计算机和 .memorious 目录的人都可以读取所有已存储的记忆
• 谨慎行事：虽然 MCP 服务会提醒客户端大模型避免存储敏感信息，但你不应完全依赖这一保护措施
• 备份注意事项：备份或同步包含 .memorious 文件夹的目录时，请务必谨慎

贡献

欢迎贡献。请提交包含测试的 PR。