memvid mcp
MCP(模型上下文协议)服务器 memvid 的 -AI代理的存储层。
该服务器封装了memvid Rust CLI,提供了40个用于持久内存管理的工具,包括混合搜索(词汇+向量)、时间索引、知识图和RAG功能。
用例
- 代理内存:通过语义搜索和时间感知,为AI代理提供跨会话的持久内存
- 文档智能:通过自动实体提取和事实跟踪摄取文档、代码和网络内容
- 知识库:使用混合词汇/向量搜索和知识图关系构建可搜索的知识库
- 审计与合规:通过引文生成和审计报告跟踪信息来源
- 会话重放:记录和回放代理会话以进行调试和分析
先决条件
- Node.js 18+
- memvid CLI 的 二进制(参见 memvid 的 用于安装)
- 可选的:矢量搜索的嵌入器配置(Embedder.toml)
- 可选的:RAG的LLM配置(LLM.toml)
安装
来源```bash
git clone https://github.com/Tapiocapioca/memvid-mcp.git
cd memvid-mcp
npm install
npm run build
### 验证安装```bash
# Test the server starts
node dist/index.js
# Should output: "memvid-mcp server started"
# Press Ctrl+C to exit
配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
MEMVID_PATH |
memvid |
memvid二进制文件的路径 |
MEMVID_LOG_LEVEL |
warning |
日志级别: debug, info, warning, error |
MEMVID_VERBOSE |
0 |
设置为 1 用于详细的CLI输出 |
MCP 客户端安装
VS代码(副本)
添加到您的VS Code MCP设置中:```json
{
"servers": {
"memvid": {
"command": "node",
"args": ["/path/to/memvid-mcp/dist/index.js"],
"env": {
"MEMVID_PATH": "/path/to/memvid"
}
}
}
}
#### 克劳德桌面版
添加到 `claude_desktop_config.json`:```json
{
"mcpServers": {
"memvid": {
"command": "node",
"args": ["/path/to/memvid-mcp/dist/index.js"],
"env": {
"MEMVID_PATH": "/path/to/memvid"
}
}
}
}
光标
添加到MCP设置:```json
{
"memvid": {
"command": "node",
"args": ["/path/to/memvid-mcp/dist/index.js"],
"env": {
"MEMVID_PATH": "/path/to/memvid"
}
}
}
#### OpenCode
添加到 `opencode.json`:```json
{
"mcp": {
"memvid": {
"type": "stdio",
"command": "node",
"args": ["/path/to/memvid-mcp/dist/index.js"],
"env": {
"MEMVID_PATH": "/path/to/memvid"
}
}
}
}
安全考虑
路径验证
服务器实现了多层路径安全:
- 路径横向保护:块
..模式 - 系统路径阻止列表:防止访问敏感目录(
/etc/,/proc/,\windows\等等) - MCP根验证:尊重客户端提供的根边界(当客户端支持时)
加密
内存文件可以使用AES-256-GCM加密:```
memvid_lock { "file": "data.mv2", "output": "data.mv2e", "password": "secret" }
memvid_unlock { "file": "data.mv2e", "output": "data.mv2", "password": "secret" }
### 建议
- 将内存文件存储在专用目录中
- 使用加密文件(`.mv2e`)敏感数据
- 在客户端中配置MCP根以限制文件访问
- 为每个项目/上下文使用单独的内存文件
## 可用工具(40)
### 生命周期(5个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_create` |创建新的.mv2内存文件|写入|
| `memvid_open` |打开并显示文件元数据|只读|
| `memvid_stats` |显示详细统计信息(帧数、索引大小)|只读|
| `memvid_verify` |通过可选的深度检查验证文件完整性|只读|
| `memvid_doctor` |诊断和修复损坏的索引|破坏性|
### 内容管理(7个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_put` |使用可选嵌入从文件/目录添加内容|写入|
| `memvid_put_many` |批量添加并跟踪进度|写入|
| `memvid_view` |按ID查看框架内容|只读|
| `memvid_update` |替换帧内容|破坏性|
| `memvid_delete` |删除帧|破坏性|
| `memvid_correct` |用审计跟踪修改框架|写入|
| `memvid_api_fetch` |获取URL内容并添加到内存|网络|
### 搜索(5个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_find` |混合/词汇/向量搜索|只读|
| `memvid_vec_search` |仅矢量语义搜索|只读|
| `memvid_ask` |RAG问答|只读|
| `memvid_timeline` |按时间顺序的帧视图|只读|
| `memvid_when` |时态搜索(在提到某事时查找)|只读|
### 分析(6个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_audit` |生成带有引用的审计报告|只读|
| `memvid_debug_segment` |调试内部索引段|只读|
| `memvid_export` |导出为JSON/CSV/JSONL |写入|
| `memvid_tables` |列出内部SQLite表|只读|
| `memvid_schema` |模式推理和摘要|只读|
| `memvid_models` |列出可用的嵌入模型|只读|
### 知识图谱(6个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_enrich` |NER实体提取|写入|
| `memvid_memories` |存储卡操作|只读|
| `memvid_state` |显示当前内存状态|只读|
| `memvid_facts` |事实提取和列表|只读|
| `memvid_follow` |遍历实体关系|只读|
| `memvid_who` |实体查找|只读|
### 会话管理(5个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_session` |开始/停止/列出/重放会话|写入|
| `memvid_binding` |内存绑定操作|破坏性|
| `memvid_status` |系统状态(版本、型号状态)|只读|
| `memvid_sketch` |SimHash草图操作|写入|
| `memvid_nudge` |触发后台处理|写入|
### 加密(2个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_lock` |加密内存文件(AES-256-GCM)|写入|
| `memvid_unlock` |解密内存文件|写入|
### 实用工具(4个工具)
|工具|说明|注释|
|------|-------------|-------------|
| `memvid_process_queue` |处理待处理操作|写入|
| `memvid_verify_single_file` |验证单帧完整性|只读|
| `memvid_config` |显示当前配置|只读|
| `memvid_version` |打印版本信息|只读|
## 示例工作流
### 基本内存设置```
# 1. Create a new memory file
memvid_create { "file": "project.mv2" }
# 2. Ingest documentation
memvid_put {
"file": "project.mv2",
"input": "./docs",
"recursive": true,
"embed": true # Generate vector embeddings
}
# 3. Check statistics
memvid_stats { "file": "project.mv2" }
搜索和检索```
Hybrid search (lexical + vector)
memvid_find {
"file": "project.mv2",
"query": "authentication flow",
"mode": "hybrid",
"limit": 5
}
Semantic search only
memvid_vec_search {
"file": "project.mv2",
"query": "how to handle user sessions"
}
RAG question answering
memvid_ask {
"file": "project.mv2",
"question": "What authentication methods are supported?"
}
### 知识图谱操作```
# Extract entities from all frames
memvid_enrich { "file": "project.mv2", "all": true }
# Look up an entity
memvid_who { "file": "project.mv2", "query": "OAuth" }
# Follow entity relationships
memvid_follow {
"file": "project.mv2",
"entity": "AuthService",
"hops": 2
}
审计和导出```
Generate audit report with sources
memvid_audit {
"file": "project.mv2",
"query": "security requirements",
"include_snippets": true
}
Export for backup
memvid_export {
"file": "project.mv2",
"output": "backup.json",
"format": "json"
}
### 会话录制```
# Start recording a session
memvid_session { "file": "project.mv2", "start": "debug-session-1" }
# ... agent interactions ...
# Stop recording
memvid_session { "file": "project.mv2", "stop": true }
# Replay later
memvid_session { "file": "project.mv2", "replay": "debug-session-1" }
嵌入器配置
对于矢量搜索功能,请创建 ~/.config/memvid/embedder.toml:```toml
[embedder]
provider = "openai"
model = "text-embedding-3-large"
api_key_env = "OPENAI_API_KEY"
dimensions = 3072
或者,对于A4F/OpenRouter兼容的API:```toml
[embedder]
provider = "openai"
model = "provider-3/text-embedding-3-large"
base_url = "https://api.a]4f.co/v1"
api_key_env = "A4F_API_KEY"
性能特征
| 操作 | 典型延迟 | 注意事项 |
|---|---|---|
memvid_create |
\<100ms | 创建空SQLite数据库 |
memvid_put (单个文件) |
100-500ms | 取决于文件大小 |
memvid_put (带嵌入) |
500ms-2s | 包括用于嵌入的API调用 |
memvid_find (词汇) |
\<50ms | Tantivy全文搜索 |
memvid_find (混合) |
100-500ms | 结合词汇+向量 |
memvid_ask (RAG) |
1-5s | 包括LLM API调用 |
超时按操作类型配置:
- 默认值:120秒
- 重型操作(批量投入):300秒
- RAG操作:180秒
发展```bash
npm run dev # Run with tsx (hot reload)
npm run build # Compile TypeScript
npm start # Run compiled version
npm run clean # Remove dist/
## 故障排除
### 服务器无法启动
1. 检查Node.js版本: `node --version` (要求18+)
1. 验证构建: `npm run build`
1. 检查memvid二进制文件: `memvid --version`
### “未找到MEMVID_PATH”
将环境变量设置为完整路径:```bash
export MEMVID_PATH=/path/to/memvid
# or on Windows
set MEMVID_PATH=C:\path\to\memvid.exe
矢量搜索未返回任何结果
- 已生成检查嵌入:
memvid_stats显示vector_count > 0 - 验证嵌入器配置:
memvid_config - 使用嵌入物重新摄入:
memvid_put { ..., "embed": true }
路径验证错误
服务器根据以下内容验证所有路径:
- 路径遍历模式(
..) - 系统目录阻止列表
- MCP根(如果客户端支持根功能)
确保您的路径在允许的目录内。
许可证
麻省理工学院
