Solution Memory MCP Server
跨项目问题解决方案记忆系统 - 为 Windsurf/Cascade 设计的 MCP Server。
功能特性
- 🧠 自动捕获 - 保存问题解决方案，包含问题描述、根因分析、解决步骤
- 🔍 混合搜索 - 结合关键词精确匹配 (FTS5) 和语义相似度 (向量) 搜索
- 🏷️ 智能标签 - 自动分类：技术栈、问题类型、错误代码
- 📦 完全离线 - 所有数据存储在本地，保护隐私
- 🌍 跨项目共享 - 全局注册，所有项目可用，统一存储
安装
前置要求
- Python >= 3.11
- Windsurf IDE
安装步骤
# 1. 克隆或下载项目
cd solution-memory-mcp
# 2. 使用 Python 3.11+ 安装
python3.11 -m pip install -e .
# 或使用 Homebrew 安装的 Python
/opt/homebrew/bin/python3.11 -m pip install -e .Windsurf 配置
MCP 配置文件路径：~/.codeium/windsurf/mcp_config.json
添加以下配置：
{
"mcpServers": {
"solution-memory": {
"command": "/opt/homebrew/bin/python3.11",
"args": ["-m", "solution_memory_mcp"],
"cwd": "/path/to/solution-memory-mcp",
"env": {
"SOLUTION_MEMORY_PATH": "~/.solution-memory"
}
}
}
}注意：请将
command替换为你系统上 Python 3.11+ 的实际路径
配置完成后重启 Windsurf 使配置生效。
Cascade 自动化配置
为了让 Cascade 在工作过程中自动保存和检索解决方案，需要在 Windsurf 的 Memories 或 Global Rules 中添加使用规则：
# Solution Memory 使用规则
1. **遇到问题时** - 先调用 `search_solutions` 搜索是否有类似解决方案
2. **成功解决问题后** - 调用 `save_solution` 保存解决方案
3. **触发条件**：修复 bug、解决配置问题、处理依赖冲突MCP 工具
save_solution
保存新的解决方案。
{
"title": "Docker 容器网络连接失败",
"problem": "API 请求报错 ECONNREFUSED...",
"solution": "检查 Docker 网络配置...",
"root_cause": "容器使用了 bridge 网络但未正确配置端口映射",
"error_messages": ["ECONNREFUSED 127.0.0.1:3000"],
"tags": ["Docker", "networking", "bug"],
"project_name": "my-project"
}search_solutions
搜索相似解决方案。
{
"query": "ECONNREFUSED 连接被拒绝",
"limit": 5,
"tags": ["Docker"],
"search_mode": "hybrid"
}get_solution
获取解决方案完整详情。
{
"id": "uuid-of-solution"
}list_tags
列出所有标签。
{
"category": "tech_stack"
}数据存储
默认存储位置：~/.solution-memory/
~/.solution-memory/
├── solutions.db # SQLite 数据库 (元数据 + FTS5 索引)
└── chroma/ # Chroma 向量数据库 (语义嵌入)数据特点
- 全局存储 - 数据存储在用户 home 目录，不绑定特定项目
- 跨项目共享 - 所有项目的解决方案统一管理
- 双重索引 - FTS5 关键词搜索 + 向量语义搜索
搜索模式
| 模式 | 说明 | 适用场景 | |------|------|----------| | hybrid (默认) | 关键词 + 语义混合 | 通用搜索 | | keyword | 纯关键词 FTS5 | 精确匹配错误信息 | | semantic | 纯语义向量 | 模糊描述、不同表述 |
开发
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest tests/
# 手动测试服务
python -m solution_memory_mcp常见问题
服务状态显示黄色
首次启动时需要下载 embedding 模型（~90MB），可能需要几十秒。完成后变为绿色。
语义搜索分数为 0
确保通过 MCP 工具 save_solution 保存，会自动同步到向量库。直接操作数据库不会触发同步。
License
MIT
