VectorForge
High-Performance Local Vector Database & C++ MCP Server
Installation • Usage • Troubleshooting • Architecture • License
______________________________________________________________________
🚀 概述
VectorForge 是一个本地RAG（检索增强生成）系统，通过将高性能C++向量引擎与TypeScript模型上下文协议（MCP）服务器相结合，为AI助手（如Claude）提供长期内存。
主要观点：
- C++用于快速矢量运算和紧凑的二进制存储。
- Node.js MCP服务器，用于与Claude集成和嵌入生成。
- 仅本地存储（不需要云）。
______________________________________________________________________
✨ 特性
- ⚡ C++核心引擎（C++17，无外部运行时依赖）
- 🔌 MCP集成（Node.js）
- 💾 本地二进制存储(
data/database.bin) - 🔍 余弦相似度搜索
- 🛠️ 可扩展的嵌入后端（OpenAI、Ollama等）
______________________________________________________________________
🏗️ 建筑
graph TD
A[Claude Desktop App] -->|MCP Protocol| B[Node.js Server]
B -->|Executes| C[C++ Binary]
C -->|Reads/Writes| D[(data/database.bin)]
subgraph VectorForge System
B
C
D
end- 前端：Claude通过MCP发送JSON。
- 中间件：TypeScript服务器生成嵌入并转发请求。
- 后端：C++二进制处理I/O和向量数学。
______________________________________________________________________
🛠️ 安装和设置
先决条件
- g++（C++17）
- Node.js v18+
- npm
- 制造
1.克隆和构建
git clone https://github.com/sadatnazarli/VectorForge.git
cd VectorForge
make all2.配置克劳德桌面
编辑Claude配置以添加MCP服务器条目（使用绝对路径）：
MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json\ 窗户： %APPDATA%/Claude/claude_desktop_config.json
下面是两张有用的图片，显示了在Claude Desktop中添加MCP服务器的位置，以及在配置中写入什么来连接VectorForge。将这些文件放在存储库中 images/claude_mcp_location.png 和 images/claude_command_example.png.
Screenshot: where to add an MCP connector in Claude Desktop settings.
Screenshot: example JSON entry to add to claude_desktop_config.json.
示例JSON条目（使用构建服务器的绝对路径）：
{
"mcpServers": {
"vectorforge": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/VectorForge/server/dist/index.js"]
}
}
}3.验证
重新启动Claude Desktop并确认出现VectorForge连接器。
______________________________________________________________________
💻 使用指南
与克劳德（推荐）
- 存储内存：指示Claude记住文本——触发器
store_memory，将文本+嵌入保存到database.bin. - 回忆记忆：问克劳德——触发器
recall_memory，搜索database.bin使用余弦相似性。
CLI（开发人员/调试人员）
添加向量：
./build/vectorforge add "This is a test memory" "[0.1, 0.2, 0.3, ...]"搜索：
./build/vectorforge search "[0.1, 0.2, 0.3, ...]"______________________________________________________________________
⚠️ 错误处理和故障排除
常见错误
| 错误/症状 | 可能原因 | 解决方案 |
|---|---|---|
| “错误：找不到C++可执行文件” | 未生成C++二进制文件 | 运行 make cpp 或 make all |
| “权限被拒绝”（在database.bin上） | 服务器缺少写入权限 | chmod -R 755 data/ |
| “MCP连接被拒绝” | 配置中的路径不正确 | 在中使用绝对路径 claude_desktop_config.json |
| “向量维度不匹配” | 嵌入大小！=预期（1536） | 确保嵌入模型输出1536 dims |
| “打开数据库失败” | 已损坏或丢失.bin | 删除 data/database.bin （将重新创建） |
调试步骤
- 检查MCP日志（示例）：
tail -f ~/Library/Logs/Claude/mcp.log - 手动运行C++二进制文件：
./build/vectorforge - 重建：
make clean && make all
______________________________________________________________________
📂 项目结构
VectorForge/
├── cpp/ # C++ source
│ ├── main.cpp
│ └── vector_store*
├── server/ # TypeScript MCP server
│ └── src/index.ts
├── data/ # Binary storage
│ └── database.bin
├── images/ # README assets
│ ├── logo.png
│ ├── claude_mcp_location.png
│ └── claude_command_example.png
└── LICENSE # License file______________________________________________________________________
🔮 路线图
- 用OpenAI/Ollama集成替换模拟嵌入
- 添加元数据（标签、时间戳）
- 为大规模数据集实施HNSW索引
______________________________________________________________________
📄 许可证
本项目根据MIT许可证条款获得许可。请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
注意：在生产使用之前，请仔细检查配置路径和嵌入尺寸。