Semantic Memory

语义记忆MCP

基于语义搜索的人工智能助理个人知识管理

一个自托管的MCP（模型上下文协议）服务器，为Claude和其他AI助手添加持久的、语义可搜索的内存。存储笔记、想法和知识——按意义搜索，而不仅仅是关键字。

✨ 特性

• 语义搜索 --使用384维嵌入（全MiniLM-L6-v2）按意义查找注释
• MCP集成 --通过远程MCP服务器直接与Claude.ai协同工作
• 自托管 --您的数据保留在硬件上
• Docker就绪 --一次指挥部署
• 嵌入一致性 --自动漂移检测保护搜索质量
• 自动备份 --定时备份，易于恢复

🎯 用例

• 个人知识库 --从语义上存储和检索信息
• 研究简报 --组织调查结果，按概念搜索
• 学习日志 --跟踪你学到的东西，找到联系
• 项目上下文 --让你的AI助手记住你的项目

🚀 快速开始

先决条件

• Docker&Docker编写
• ngrok帐户（用于远程访问）
• Python 3.9+（用于本地开发）

1.克隆和配置

git clone https://github.com/artemMprokhorov/semantic-memory-mcp.git
cd semantic-memory-mcp
cp .env.example .env
# Edit .env with your settings

2.启动服务器

docker-compose up -d

3.设置ngrok隧道

ngrok http 5000

4.连接到Claude.ai

1. 转到Claude.ai→ 设置→ 集成
2. 添加远程MCP服务器
3. 输入您的ngrok网址： https://your-subdomain.ngrok-free.app/sse
4. 添加您的API密钥作为URL参数： ?api_key=YOUR_KEY

📋 系统要求

最小

• 猛撞： 4GB（嵌入式型号需要~2GB）
• 磁盘： 2GB可用空间（用于Docker镜像+模型缓存）
• CPU： 任何现代x64/ARM64处理器
• 操作系统： Linux、macOS、Windows（带Docker）

推荐

• 猛撞： 8GB+
• 磁盘： 5GB+（适用于较大的数据库）
• SSD： 建议用于更快的嵌入操作

软件

• Docker&Docker Compose v2.0+
• ngrok帐户（免费版有效）
• Python 3.9+（仅适用于本地开发）

已测试

• macOS（苹果硅M3 Ultra）

应继续工作（未经测试）

• 支持Docker的Linux发行版
• Windows 11+WSL2+Docker桌面
• 其他macOS版本（英特尔/ARM）

📖 文档

• 架构概述
• 安装指南
• MCP集成
• api参考
• 故障排除

🛠️ 可用工具

连接后，Claude可以访问这些工具：

🏗️ 建筑

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│  Claude.ai  │────▶│   ngrok     │────▶│  MCP Server     │
└─────────────┘     └─────────────┘     │  (Flask + SSE)  │
                                        └────────┬────────┘
                                                 │
                    ┌────────────────────────────┼────────────────────────────┐
                    │                            ▼                            │
                    │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐ │
                    │  │  Embedding  │    │   SQLite    │    │ Consistency │ │
                    │  │   Model     │    │  Database   │    │    Check    │ │
                    │  │ (MiniLM-L6) │    │             │    │             │ │
                    │  └─────────────┘    └─────────────┘    └─────────────┘ │
                    │                        Docker Container                 │
                    └─────────────────────────────────────────────────────────┘

🔒 安全

• API密钥验证（URL参数或头）
• 自托管——数据永远不会离开您的服务器
• 可选：使用您自己的证书的SSL/TLS

🧪 嵌入一致性

一个独特的特点： 自动嵌入漂移检测.

当你重建Docker镜像或更新依赖关系时，嵌入模型可能会产生略有不同的向量。这会悄无声息地破坏语义搜索——查询返回错误的结果。

我们的解决方案：

1. 首次启动时，会保存校准嵌入
2. 每次重启时，都会将当前嵌入与校准进行比较
3. 如果检测到漂移→ 警告+重新计算说明

看 故障排除 了解详情。

📦 项目结构

semantic-memory-mcp/
├── src/
│   ├── mcp_sse_handler.py      # MCP protocol + tools
│   ├── stable_embeddings.py    # Embedding model wrapper
│   ├── embedding_check.py      # Consistency verification
│   └── neural_memory_server.py # Main Flask app
├── scripts/
│   ├── backup.sh               # Backup script
│   ├── restore.sh              # Restore script
│   └── recompute_embeddings.py # Fix drift
├── docs/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
└── .env.example

🤝 贡献

欢迎投稿！请阅读 贡献.md 第一。

📄 许可

该项目具有双重许可：

• 开源/个人/非商业用途：MIT许可证\

请参阅 许可证 提交完整条款。

• 商业使用、SaaS集成、专有再分发、闭源衍生作品或任何不符合MIT条款的使用：需要单独的商业许可证。\

联系人：\[system.uid@gmail.com\]有关定价、条款和许可协议。

🙏 致谢

• Anthropic --克劳德和MCP协议
• 句子转换 --用于嵌入模型
• 吸烟 --用于隧道掘进

______________________________________________________________________

👥 作者

阿特姆·普罗霍罗夫 --创建者和主要作者

开发方法： 该系统是通过密集的人工智能协作而出现的。主要的架构贡献——包括语义搜索、嵌入一致性检查和技术文档——是用Claude（Anthropic）迭代开发的。

内置于🧠 作者：阿特姆·普罗霍罗夫