vault语义mcp
Markdown库的本地语义搜索MCP服务器。旨在作为OpenClaw或其他启用MCP的代理的侧车。
它做什么
- 索引 vault根目录下的markdown文件（收件箱、项目、决策、实体、内存、会话、模板）
- 块 内容按标题排列，大部分段落细分
- 嵌入 使用OpenAI的块
text-embedding-3-small（以JSON格式存储在SQLite v1中） - 搜索 将FTS5关键字搜索与余弦相似度语义搜索和基于文件夹的排名相结合
- 相关说明 查找与给定路径类似的注释
- 文件监视器 在文件更改时保持索引同步
- MCP工具 通过stdio将所有内容暴露给代理
重要提示： 保险库标记文件是事实的来源。SQLite数据库只是一个派生搜索索引。如果数据库丢失，可以使用完整的重新索引进行重建。
建筑
- 保险库根目录 → scan
.md文件→ 按标题解析正文 - 块 → OpenAI嵌入→ 使用FTS5存储在SQLite中，用于全文
- 搜索 → 混合FTS+语义→ 文件夹提升（内存/实体/决策>项目/会话>收件箱）
- 主控程序 → stdio传输→ 工具调用搜索/获取/最近/相关/重新索引/状态
设置
- 要求： Node.js 20+
- 安装：
npm install- 配置： 复制
.env.example到.env:
cp .env.example .env集 OPENAI_API_KEY 并调整路径：
- VAULT_ROOT –vault目录（默认 ./data/vault) - SQLITE_PATH –索引数据库（默认 ./data/index/vault.db)
- 运行：
npm run dev # development with watch
npm run build && npm start # production环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
OPENAI_API_KEY | （必需） | 用于嵌入的OpenAI API密钥 |
VAULT_ROOT | ./data/vault | markdown vault的根目录 |
SQLITE_PATH | ./data/index/vault.db | SQLite索引数据库的路径 |
EMBEDDING_MODEL | text-embedding-3-small | OpenAI嵌入模型 |
TOP_K_DEFAULT | 8 | 默认搜索结果数 |
MCP使用
配置您的MCP客户端（例如OpenClaw）以通过stdio运行此服务器：
{
"mcpServers": {
"vault": {
"command": "node",
"args": ["/path/to/vault-semantic-mcp/dist/index.js"],
"env": {
"OPENAI_API_KEY": "...",
"VAULT_ROOT": "/path/to/vault",
"SQLITE_PATH": "/path/to/index/vault.db"
}
}
}
}或者使用tsx进行开发：
{
"mcpServers": {
"vault": {
"command": "npx",
"args": ["tsx", "/path/to/vault-semantic-mcp/src/index.ts"],
"env": { ... }
}
}
}工具
| 工具 | 参数 | 描述 |
|---|---|---|
vault_search | query, folders?, topK? | 对保险库进行混合搜索 |
vault_get | path | 获取文件的完整降价 |
vault_recent | folder?, topK? | 最近索引的文档 |
vault_related | path, topK? | 与给定路径相关的注释 |
vault_reindex | path? | 重新索引一条路径或整个保险库 |
vault_status | – | 保险库根、计数、观察者状态 |
本地验证（测试线束）
在连接到OpenClaw之前，请在本地验证索引和检索：
种子库
回购包括以下示例注释 data/vault/ 跨项目、决策、实体、内存、会话和收件箱。根据需要添加或编辑markdown文件。
运行测试线束
# Reindex and run all evaluation queries (uses OPENAI_API_KEY)
npm run test:search
# Skip reindex, reuse existing index (faster for iterating on queries)
SKIP_REINDEX=1 npm run test:search线束的运行方式相同 hybridSearch 被...使用 vault_search，因此结果反映了真实的MCP行为。
评估查询
| 查询ID | 目的 |
|---|---|
exact_keyword_sqlite | FTS精确术语匹配 |
exact_keyword_chunking | FTS通用术语 |
semantic_memory_routing | 语义：“代理应该如何存储持久知识” |
embedding_cost_strategy | 语义：“为什么选择OpenAI而不是本地嵌入” |
file_watcher_reindex | 语义：“编辑vault文件时会发生什么” |
related_notes_openclaw | 语义：“与语义搜索sidecar相关的注释” |
decision_log_architecture | 语义：“我们在哪里决定将金库文件作为真相的来源？” |
fts_keyword_mcp | FTS精确术语 |
检查什么
- 精确匹配 （SQLite、MCP、分块）：FTS应该将这些笔记浮出水面
- 语义匹配：不同的措辞应找到正确的注释（例如“持久知识”→ 记忆/持久知识存储）
- 去重：结果中每个文档最多一个块
- 文件夹排名：对于类似内容，内存/实体/决策的排名应高于收件箱
- 代码片段：块状文本应可读且相关
仅重新索引
npm run reindex
VERBOSE=1 npm run reindex # log each file嵌入
- v1使用 开放人工智能
text-embedding-3-small并将向量存储为 JSON 在SQLite中。 - 没有sqlite-vec或向量扩展。未来的版本可能会添加Ollama支持。
许可证
麻省理工学院