Memory MCP Server
一个通用的 MCP (Model Context Protocol) 记忆服务，为任何支持 MCP 协议的 AI 客户端提供长期记忆能力。支持语义搜索、记忆分类和优先级管理。
特性
- 语义搜索 - 使用 Gemini gemini-embedding-001（3072维，100+语言支持，免费）
- 多语言搜索 - 自动翻译查询词，支持中英日跨语言检索
- 记忆分类 - 7 种预设分类，方便组织管理
- 优先级系统 - 5 级重要性标记，影响搜索排序
- 内存缓存 - 启动时加载记忆到内存，搜索更快
- 自动升级 - 检测旧版 embedding 并自动重新生成
- 渐进式注入 - 对话初期返回少量记忆，后期返回更多
- 双版本支持 - 本地 JSON 存储 / 云端 PostgreSQL 存储
- MCP 标准协议 - 兼容任何 MCP 客户端
可用工具
| 工具 | 说明 | 触发场景 |
|---|---|---|
save_memory | 保存重要的用户信息 | 用户提到重要个人信息、偏好、习惯 |
recall_memory | 按关键词/语义检索相关记忆 | 用户问「之前聊过什么」「你还记得吗」 |
update_memory | 更新已保存的记忆 | 需要修改之前保存的信息 |
list_all_memories | 查看所有已保存的记忆 | 用户要求列出所有记忆 |
delete_memory | 删除指定记忆 | 用户要求忘记某些信息 |
memory_stats | 显示记忆统计信息 | 查看记忆概览和分布 |
regenerate_embeddings | 重新生成所有记忆的 embedding | 切换 embedding 模型后使用 |
记忆优先级
每条记忆可以设置优先级（1-5），搜索时高优先级记忆会获得加成：
| 级别 | 说明 | 显示 |
|---|---|---|
| 1 | 最高 - 核心个人信息 | ★★★ |
| 2 | 高 - 重要偏好或习惯 | ★★☆ |
| 3 | 中 - 一般信息（默认） | ★☆☆ |
| 4 | 低 - 临时或次要信息 | ☆☆☆ |
| 5 | 最低 - 可能过时的信息 | · |
记忆分类
每条记忆可以归类到以下分类：
general- 通用（默认）preference- 偏好设置work- 工作相关personal- 个人信息habit- 习惯skill- 技能goal- 目标
渐进式注入
recall_memory 会根据会话中的调用次数，智能调整返回的记忆数量和类型：
| 调用次数 | 返回内容 | 目的 |
|---|---|---|
| 第 1 次 | 最多 3 条核心记忆（优先级 1-2 或 personal 分类） | 身份确认、关系确认、语言风格 |
| 第 2 次 | 1 条最相关记忆 + 提示剩余数量 | 聚焦当前话题，提示可查看更多 |
| 第 3+ 次 | MAX_RESULTS 条（默认 3） | 正常搜索，完整返回 |
会话重置：超过 5 分钟未调用 recall_memory，计数器自动归零这个设计确保：
- 对话开始时快速建立用户画像
- 对话中期聚焦当前话题
- 对话后期提供完整信息
两种部署方式
1. 本地版本 (memory_server.py)
适合本地运行的 MCP 客户端，使用 stdio 传输协议。
- 记忆保存在本地
memories.json文件 - 使用关键词搜索
- 数据完全本地化，隐私保护
运行方式：
python memory_server.pyMCP 客户端配置示例：
{
"mcpServers": {
"memory": {
"command": "python",
"args": ["/path/to/memory_server.py"]
}
}
}2. 云端版本 (memory_server_http.py)
适合远程访问的 MCP 客户端，使用 HTTP/SSE 传输协议。
- 使用 PostgreSQL 数据库存储
- 集成 Gemini Embedding API 进行语义搜索
- 支持多客户端连接
- 需要部署到云平台（Railway、Render、Fly.io 等）或有公网 IP 的服务器
什么时候需要云端版本？ - 使用 Claude.ai 网页版 连接 MCP 服务时（需要公网可访问的 URL） - 需要从多台设备访问同一份记忆时 - 本地版本使用 stdio 协议，仅支持 Claude Desktop 等本地客户端
运行方式：
# 设置环境变量
export DATABASE_URL="postgresql://user:pass@host:5432/dbname"
export GEMINI_API_KEY="your-gemini-api-key" # 可选，用于语义搜索
export PORT=8000
# 可选：设置工具前缀（用于运行多个实例时避免工具名冲突）
export TOOL_PREFIX="work_" # 工具名将变为 work_save_memory, work_recall_memory 等
export SERVER_NAME="work-memory" # 服务器名称
python memory_server_http.py多实例部署
如果需要同时运行多个 Memory MCP 实例（例如工作记忆和个人记忆分开存储），需要设置不同的 TOOL_PREFIX 避免工具名冲突：
实例 1 - 工作记忆：
export TOOL_PREFIX="work_"
export SERVER_NAME="work-memory"
export DATABASE_URL="postgresql://..." # 工作数据库实例 2 - 个人记忆：
export TOOL_PREFIX="personal_"
export SERVER_NAME="personal-memory"
export DATABASE_URL="postgresql://..." # 个人数据库这样工具名会变成：
work_save_memory,work_recall_memory, ...personal_save_memory,personal_recall_memory, ...
MCP 客户端连接：
- SSE 端点:
http://your-server:8000/sse - 健康检查:
http://your-server:8000/health
安装
pip install -r requirements.txt依赖说明：
mcp- MCP 协议库starlette,uvicorn- HTTP 服务器（云端版本）psycopg2-binary- PostgreSQL 驱动（云端版本）numpy- 向量计算requests- HTTP 客户端
云端部署
Railway 部署
- Fork 此仓库到你的 GitHub
- 在 Railway 创建新项目，连接 GitHub 仓库
- 添加 PostgreSQL 数据库服务
- 设置环境变量：
- DATABASE_URL - 自动由 Railway 设置 - GEMINI_API_KEY - 你的 Gemini API 密钥（可选）
- 部署完成后获取服务 URL
其他云平台
项目包含 Procfile，兼容 Heroku、Render 等平台：
web: python memory_server_http.py使用示例
保存记忆
"记住我喜欢用 TypeScript 写代码"
"我的项目用的是 React + Vite，这是工作相关的"
"记住我不喜欢在代码里加太多注释，优先级设为高"回忆信息
"我之前告诉过你什么编程偏好？"
"你还记得我的项目用什么技术栈吗？"
"只在工作分类里找一下相关记忆"更新记忆
"把记忆 3 的优先级改成最高"
"更新记忆 5，把分类改成 work"查看统计
"显示记忆统计"
"列出所有 work 分类的记忆"数据格式
本地 JSON 格式
[
{
"id": 1,
"content": "用户喜欢喝咖啡",
"tags": ["偏好", "饮食"],
"priority": 2,
"category": "preference",
"created_at": "2024-01-01T12:00:00",
"updated_at": "2024-01-01T12:00:00"
}
]云端数据库 Schema
CREATE TABLE memories (
id SERIAL PRIMARY KEY,
content TEXT NOT NULL,
tags TEXT[] DEFAULT '{}',
embedding FLOAT8[],
priority INTEGER DEFAULT 3,
category VARCHAR(50) DEFAULT 'general',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)API 端点（云端版本）
| 端点 | 方法 | 说明 |
|---|---|---|
/sse | GET | MCP SSE 连接端点 |
/messages/ | POST | MCP 消息处理 |
/health | GET | 健康检查 |
健康检查响应示例：
{
"status": "ok",
"service": "memory-mcp",
"storage": "postgresql",
"semantic_search": "enabled"
}技术架构
┌──────────────────────────────────────────────────────────┐
│ MCP Client (任意) │
│ (Claude Desktop, API Client, Custom App) │
└─────────────────────────┬────────────────────────────────┘
│ MCP Protocol
┌───────────────┴───────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────────────┐
│ 本地版本 (stdio) │ │ 云端版本 (HTTP/SSE) │
│ memory_server.py │ │ memory_server_http.py │
├─────────────────────┤ ├─────────────────────────────┤
│ - JSON 文件存储 │ │ - PostgreSQL 数据库 │
│ - 关键词搜索 │ │ - Gemini Embedding 语义搜索 │
│ - 优先级/分类管理 │ │ - 优先级/分类管理 │
└─────────────────────┘ └─────────────────────────────┘兼容的 MCP 客户端
本服务兼容任何支持 MCP 协议的客户端，包括但不限于：
- Claude Desktop
- 自定义 API 客户端
- MCP Inspector（调试工具）
- 其他 MCP 兼容应用
使用建议
关于客户端内置记忆功能 部分 MCP 客户端（如 Claude Desktop）自带记忆功能，其内置记忆的权重通常比外部 MCP 服务更高。 - 建议：根据自身需求决定是否关闭客户端的内置记忆功能 - 注意：如果关闭客户端内置记忆，所有记忆检索都会走本服务的 recall_memory，响应时间可能会稍长（需要进行语义搜索和数据库查询） 请根据实际使用场景自行权衡。故障排除
语义搜索不工作
- 检查
GEMINI_API_KEY环境变量是否设置 - 查看服务日志中的
[EMBEDDING]相关信息 - 如果 API 出错，会自动降级为关键词搜索
数据库连接失败
- 检查
DATABASE_URL格式是否正确 - 确认数据库服务正在运行
- 检查网络连接和防火墙设置
SSE 连接问题
- 确认客户端支持 SSE 传输
- 检查 CORS 设置（如果是跨域访问）
- 确认端口没有被占用
自定义 Embedding 服务
本项目默认使用 Google Gemini Embedding API（免费），但你可以替换为其他 embedding 服务。
当前默认行为
- 有 GEMINI_API_KEY: 使用 Gemini
gemini-embedding-001模型进行语义搜索
- 3072 维向量，精度更高 - 支持 100+ 语言，跨语言检索效果更好 - 启动时自动检测旧版 embedding (768维) 并升级
- 无 GEMINI_API_KEY: 自动降级为关键词搜索（仍然可用）
替换为其他 Embedding 服务
如果你想使用 OpenAI、Cohere、本地模型等其他 embedding 服务，需要修改 memory_server_http.py 中的 get_embedding() 函数：
def get_embedding(text: str) -> list[float] | None:
"""获取文本的 embedding 向量"""
# 替换为你的 embedding API 调用
# 返回值应为 float 列表，如 [0.1, 0.2, ...]
# 返回 None 表示失败，会降级为关键词搜索
pass常见替代方案：
- OpenAI
text-embedding-3-small - Cohere
embed-multilingual-v3.0 - 本地部署的 sentence-transformers
- 其他支持中文的 embedding 模型
后续优化方向
- [x] 语义搜索（Gemini Embedding）
- [x] 多语言搜索（中英日跨语言检索）
- [x] 记忆优先级
- [x] 记忆分类管理
- [x] 记忆更新功能
- [x] 记忆统计功能
- [x] Embedding 自动升级
- [ ] 记忆过期机制
- [ ] 记忆导出/导入
- [ ] 记忆关联功能
- [ ] WebSocket 传输支持
License
MIT
Built with 🌀 Claude Code