内容
# 🧠 视觉记忆 MCP
[](https://www.npmjs.com/package/@putervision/vision-memory-mcp)
[](https://github.com/putervision/vision-memory-mcp/actions/workflows/ci.yml)
[](https://visionmemorymcp.com)
[](https://github.com/putervision/vision-memory-mcp/blob/main/LICENSE)
MCP（模型上下文协议）服务器和 CLI 工具，旨在使用感知哈希、本地 CLIP 嵌入和状态转换来缓存视觉 UI 状态。它帮助 AI 代理记住已查看的屏幕，将前沿模型令牌使用量和执行延迟降低高达 90%。官方文档和演示：[visionmemorymcp.com](https://visionmemorymcp.com)
---
## 🚀 主要功能
- **零令牌快速路径（L1/L2）：** 使用差异哈希（dHash）和平均哈希（aHash）在 <5ms 内识别相同或近似的布局，无需将图像发送到 LLM。
- **语义检索（L3）：** 运行本地 CLIP ViT-B/32 模型推理，以查找概念上相似的屏幕（例如“计费配置表单”）。
- **单体库和子目录发现：** 自动发现嵌套的 Git 仓库、子模块和子目录 `.vision-memory-mcp` 数据库，聚合跨包的视觉内存查询。
- **状态转换图：** 跟踪代理操作（例如，单击按钮）和转换结果（成功/失败率），以指导路径查找并防止代理重复错误。
- **视觉检查点：** 保存、列出和差异内存快照，以识别视觉回归或布局修改。
- **交互式可视化器：** 在浏览器中打开内存的本地力导向图视图。
---
## 📦 架构蓝图
```
传入屏幕
│
▼
┌──────────────────────────────┐
│ L1: 内存缓存查找 │ ──（命中）──▶ 返回缓存描述
└──────────────┬───────────────┘
│ （未命中）
▼
┌──────────────────────────────┐
│ L2: 感知哈希扫描 │ ──（命中）──▶ 返回缓存描述
└──────────────┬───────────────┘
│ （未命中）
▼
┌──────────────────────────────┐
│ L3: 本地 CLIP 矢量搜索 │ ──（命中）──▶ 返回语义相近
└──────────────┬───────────────┘
│ （未命中）
▼
┌──────────────────────────────┐
│ L4: 视觉 LLM 备用 │ ──（摄入）──▶ 将新状态保存到 DB
└──────────────┬───────────────┘
```
---
## 🛠️ 快速入门
### 1. 全局安装
```bash
npm install -g @putervision/vision-memory-mcp
```
或从源代码安装用于开发：
```bash
git clone https://github.com/putervision/vision-memory-mcp.git
cd vision-memory-mcp
npm install
npm run build
npm install -g .
```
### 2. 工作区初始化
在目标项目根目录运行以下命令：
```bash
vision-memory-mcp init
```
这会搭建 `.vision-memory-mcp`，生成默认 `.env` 模板，并将配置属性添加到您的 `.gitignore` 中。
### 3. 配置 MCP 客户端
#### Cursor IDE（`.cursor/mcp.json`）
```json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"],
"env": {
"LANCEDB_PATH": ".vision-memory-mcp"
}
}
}
}
```
#### Claude Desktop（Linux：`~/.config/Claude/claude_desktop_config.json`）
```json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"],
"env": {
"LANCEDB_PATH": "/absolute/path/to/your/project/.vision-memory-mcp"
}
}
}
}
```
### 4. 配置代理权限（绕过提示对话框）
允许 AI 代理查询视觉缓存并自动管理脑图像，无需请求权限提示，请配置安全授予：
#### Google Antigravity Client（`~/.gemini/config/config.json`）
在 `"userSettings"` -> `"globalPermissionGrants"` -> `"allow"` 中添加以下权限条目：
```json
"command(vision-memory-mcp)",
"read_file(.*\\.gemini/antigravity/brain/.*)",
"write_file(.*\\.gemini/antigravity/brain/.*)"
```
#### VS Code / Cursor IDE（`settings.json`）
确保允许：
- `command(vision-memory-mcp)`
- 读取和写入本地 `.vision-memory-mcp/` 工作区数据库的权限。
---
## 🔌 MCP 工具（16 个可用）
| 工具 | 目的 | 关键输入 |
| --- | --- | --- |
| `analyze_screenshot` | 检查视觉缓存/摄入新屏幕 | `screenshot`（可选），`file_path`（可选），`response_format`（'compact' | 'full'），`accessibility_tree`（可选） |
| `recall_memory` | 通过查询或图像查找过去的屏幕 | `query`（可选），`screenshot`（可选），`file_path`（可选），`response_format`（可选） |
| `record_outcome` | 记录操作成功并构建导航路径 | `from_state_id`（必填），`to_state_id`（必填），`action`（必填），`success`（必填） |
| `get_navigation_paths` | 查找两个 UI 状态之间的最优 BFS 路径 | `from_state_id`（可选），`to_description`（可选） |
| `compare_states` | 比较视觉和键级结构差异 | `state_a_id`（必填），`state_b_id`（必填），`response_format`（可选） |
| `get_session_context` | 检索摘要上下文简介 | `include_recent`（可选），`include_frequent`（可选），`response_format`（可选） |
| `save_visual_snapshot` | 保存视觉内存状态的检查点 | `name`（必填），`description`（可选） |
| `diff_visual_snapshots` | 差异两个检查点以诊断视觉漂移 | `snapshot_a_name`（必填），`snapshot_b_name`（必填） |
| `undo_last_visual_mutation` | 恢复最后的状态或边缘突变 | `type`（'state' | 'transition' | 'any'） |
| `create_visual_blocker` | 为 `state-memory-mcp` 生成结构化视觉阻塞器有效载荷 | `visual_state_id`（必填），`description`（必填），`project`（可选） |
| `predict_next_action` | 从状态和目标预测最佳下一个 UI 操作 | `current_state_id`（必填），`goal_description`（可选），`goal_state_id`（可选） |
| `batch_analyze_screenshots` | 处理 1-20 个截图或文件路径的批处理数组 | `items`（必填的截图/文件路径对象数组），`response_format`（可选） |
| `set_visual_spec` | 将截图/模型作为视觉规格设计基准合约 | `name`（必填），`screenshot`（可选），`file_path`（可选） |
| `verify_visual_spec` | 验证运行时截图与视觉规格基准合约 | `spec_name`（必填），`screenshot`（可选），`file_path`（可选），`tolerance`（可选） |
| `get_visual_diff` | 计算感知 dHash 差异和布局区域增量 | `state_id_a`（必填），`state_id_b`（必填） |
| `export_visual_trajectories` | 导出本地模型微调的多模态轨迹 | `git_branch`（可选），`limit`（可选） |
---
## 📜 MCP 提示（3 个可用）
| 提示 | 描述 | 关键参数 |
| --- | --- | --- |
| `analyze-ui-state` | 分析 UI 屏幕布局、输入字段、交互控件和活动警报 | `state_id`（必填） |
| `diagnose-visual-regression` | 比较基准和当前快照检查点以诊断视觉漂移 | `baseline_snapshot`（必填），`current_snapshot`（必填） |
| `navigate-to-goal` | 从当前状态制定逐步导航路径以达到目标 | `current_state_id`（必填），`goal_description`（必填） |
---
## 💻 CLI 命令
- **`vision-memory-mcp run`**：启动 MCP stdio 服务器。
- **`vision-memory-mcp init`**：引导环境和 IDE 规则。
- **`vision-memory-mcp doctor [--json]`**：健康检查 LanceDB 可写性、sharp 绑定、Node 运行时、Git 仓库和 `.gitignore` 保护。
- **`vision-memory-mcp update`**：检查 npm 注册表并将 `@putervision/vision-memory-mcp` 更新到最新版本。
- **`vision-memory-mcp audit [--json]`**：对 Git 仓库、子模块、数据库位置和状态计数进行深入工作区审计。
- **`vision-memory-mcp inspect`**：打印存储状态的 ASCII 表。
- **`vision-memory-mcp metrics`**：显示 ROI 指标、令牌节省和缓存大小。
- **`vision-memory-mcp view`**：在浏览器中打开内存的本地力导向图视图。
- **`vision-memory-mcp snapshot <save|diff|list>`**：管理视觉检查点。
- **`vision-memory-mcp undo`**：恢复最后的视觉突变。
- **`vision-memory-mcp optimize`**：压缩 LanceDB 存储。
- **`vision-memory-mcp prune`**：清理过期状态。
- **`vision-memory-mcp backup --out <file>`**：将 LanceDB 备份到 tarball。
- **`vision-memory-mcp restore <file>`**：从 tarball 恢复 LanceDB。
---
## ⚙️ 配置
在您的 `.env` 文件中设置以下环境变量：
```bash
LANCEDB_PATH=.vision-memory-mcp # LanceDB 存储路径
LANCEDB_CACHE_SIZE=100 # LRU 缓存中的最大热项
HASH_EXACT_THRESHOLD=5 # 哈明距离 <= 此值 = 精确命中
HASH_SIMILAR_THRESHOLD=10 # 哈明距离 <= 此值 = 相似命中
CLIP_MODEL=Xenova/clip-vit-base-patch32 # 嵌入模型名称
EMBEDDING_DIMENSIONS=512 # CLIP 嵌入输出维度
VISION_MODEL_ENABLED=false # 启用 L4 视觉备用
VISION_MODEL_ENDPOINT=http://localhost:1234/v1 # 视觉模型服务器 URL
VISION_MODEL_NAME=gpt-4o # 视觉模型标识符
OPENAI_API_KEY=your-api-key-here # 如果使用 OpenAI 端点进行 L4 备用，则必填
LOG_LEVEL=info # 日志级别（debug, info, warn, error）
TTL_DEFAULT_MS=604800000 # 驱逐 TTL（默认：7 天）
```
---
## 🔒 本地优先隐私和零遥测保证
100% 的数据，包括截图、感知哈希、矢量嵌入和转换图，均存储在您的机器上的 `.vision-memory-mcp/` 中。除非您明确启用 L4 LLM 视觉备用端点，否则不会进行零遥测、分析或外部 API 调用。
---
## 🔌 多 IDE 和客户端集成指南
### 快速 2 步设置
#### 1. 引导工作区
在您的仓库根目录运行初始化命令以创建 `.vision-memory-mcp/`、`.gitignore`、`.env` 和 IDE 规则：
```bash
vision-memory-mcp init --yes
```
#### 2. 配置您的 IDE / 客户端
---
### 1. Google Antigravity / Gemini CLI
**配置位置**: `~/.gemini/config/mcp_config.json`
```json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"],
"env": {
"OPENAI_API_KEY": "sk-your-openai-key-optional"
}
}
}
}
```
---
### 2. Cursor IDE
**配置位置**: `.cursor/mcp.json` 或 `Cursor 设置` ➔ `功能` ➔ `MCP`
```json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"]
}
}
}
```
---
### 3. Roo Code / Cline / Continue (VS Code)
**配置位置**: `.vscode/mcp.json` 或 `全局 MCP 设置`
```json
{
"servers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"]
}
}
}
```
---
### 4. Windsurf IDE
**配置位置**: `~/.codeium/windsurf/mcp_config.json`
```json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"]
}
}
}
```
---
### 5. Zed 编辑器
**配置位置**: `~/.config/zed/settings.json`
```json
{
"context_servers": {
"vision-memory-mcp": {
"command": {
"path": "vision-memory-mcp",
"args": ["run"]
}
}
}
}
```
---
### 6. Claude Desktop
**配置位置**:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"]
}
}
}
```
---
### 🤖 代理系统规则和集成提示
确保您的 AI 代理在将原始截图发送到视觉 LLM 之前自动利用 `vision-memory-mcp`，请在项目的 `.cursorrules`、`.windsurfrules`、`AGENTS.md` 或系统提示中添加此规则：
```markdown
<!-- vision-memory-mcp:start -->
# 视觉记忆规则
该项目使用 vision-memory-mcp 来缓存视觉 UI 状态并防止冗余的 LLM 视觉调用。
## 强制工作流
1. **视觉检查前**: 调用 `analyze_screenshot` 并传入 base64 截图。
2. **缓存命中 (`is_known: true`)**: 不要查询外部视觉模型；重用缓存的 `description`。
3. **缓存未命中 (`is_known: false`)**: 查询视觉模型，然后调用 `analyze_screenshot` 并传入图像和新描述以播种缓存。
4. **转换跟踪**: 在点击/键入/导航步骤后调用 `record_outcome`。
<!-- vision-memory-mcp:end -->
```
---
## 🤝 贡献
欢迎贡献！请阅读我们的 [CONTRIBUTING.md](CONTRIBUTING.md) 指南，了解开发设置、架构和提交指南的详细信息。
---
## 📄 许可证和免责声明
© 2026 [PuterVision LLC](https://putervision.com)。在 [MIT 许可证](LICENSE) 下发布。
> **免责声明**: 本软件按“原样”提供，不保证任何种类，明确或暗示。在任何情况下，作者或贡献者不应对因执行而导致的任何数据库损坏、Git 历史记录修改、数据丢失或其他问题承担责任。在执行破坏性操作之前，请始终备份您的数据库文件。
