Visual Memory MCP

@putervision/vision-memory-mcp

@putervision/vision-memory-mcp 是一款零基础设施、以本地优先的 Model Context Protocol (MCP) 服务和命令行工具，可借助感知哈希、本地 CLIP 嵌入和状态转换图，为 AI 编码助手（如 Cursor、Claude Code、Gemini 或 Copilot）提供视觉状态缓存，从而消除重复的视觉大模型调用。

🌐 官方文档与网站：visionmemorymcp.com

---

⚡ 快速开始与安装

前提条件：Node.js >= 18.18.0

1. 安装

# Global installation via npm
npm install -g @putervision/vision-memory-mcp

2. 工作区初始化

在项目根目录运行 init，以创建数据库目录、.gitignore、.env 和 IDE 规则：

vision-memory-mcp init --yes

3. 基本 MCP 客户端设置

添加到 MCP 客户端配置中（例如 .cursor/mcp.json 或 .vscode/mcp.json）：

{
  "mcpServers": {
    "vision-memory-mcp": {
      "command": "vision-memory-mcp",
      "args": ["run"]
    }
  }
}

其他选项与 CLI 使用示例

# Run stdio MCP server directly via binary (after global install)
vision-memory-mcp run

# Start server skipping heavy CLIP model downloads (air-gapped / offline mode)
vision-memory-mcp run --skip-model-load

# Re-initialize across all registered workspace projects
vision-memory-mcp init-global

# Health check dependencies, sharp bindings, and git safety
vision-memory-mcp doctor

# Run health diagnostics & aggregate metrics across all registered projects
vision-memory-mcp doctor-global

# Inspect stored visual states and metadata in terminal ASCII table
vision-memory-mcp inspect

# Register baseline design mockup contract (Visual SDD)
vision-memory-mcp spec set --name "Dashboard" --file ./dashboard-spec.png

# Save visual memory checkpoint snapshot
vision-memory-mcp snapshot save --name "v1.0-milestone"

# Ingest WebM / MP4 video recording into visual state memory timeline
vision-memory-mcp video ingest ./playwright-test.webm --category playwright_test

# Open interactive force-directed visual graph viewer in browser
vision-memory-mcp view

---

🌟 主要亮点

• 👁️ 感知视觉缓存与紧凑切片：L1/L2 dHash 布局识别快路径耗时不到 5ms、零令牌，并可导出小于 1KB 的 compact_slice，用于组装 Pentad System 1 StatePack。
• 🎬 WebM 与 MP4 视频导入：将端到端测试录屏和屏幕录制解析为可搜索的关键帧视觉状态与状态转换图。
• ⚡ 15 个核心 MCP 工具：高连贯性的整合工具集，涵盖感知、视频记忆、证据包、轨迹比较、语义检索、元素定位、视觉 SDD、快照以及统一上下文与指标。
• 🔗 双 MCP 协同与不可变证据包：深度打通 @putervision/state-memory-mcp 任务 DAG 与视觉状态记忆，生成可进行密码学哈希的证据包，用于合规与审计追踪。
• 📉 降低令牌开销：使用 dHash、本地 CLIP 向量搜索和无障碍树在本地缓存 UI 状态，最大限度节省视觉令牌。
• 🚀 快路径延迟低于 5ms：消除重复的视觉大模型 API 调用，避免视觉幻觉循环。
• 🎯 元素定位与操作目标预测：将屏幕元素映射到 CSS 选择器和坐标，实现确定性的 UI 交互。
• 🎨 视觉规范驱动开发（Visual SDD）：将设计模型或屏幕截图注册为感知基准契约，以验证视觉回归。
• 🛡️ 100% 本地优先的隐私保护：本地 LanceDB 向量存储、本地 CLIP 模型、零云端遥测，并保证对个人身份信息（PII）进行编辑。

---

🛠️ MCP 工具套件

@putervision/vision-memory-mcp 提供 15 个适用于生产环境的整合型 MCP 工具，涵盖 4 个核心视觉感知与自动化领域：

• 感知与语义搜索：analyze_screenshot（L1/L2 感知 dHash 与 AX 树解析，支持单个或批量）、recall_memory（文本与图像语义向量搜索）、get_session_context（汇总缓存命中指标、近期状态，并导出小于 1 KB 的 compact_slice）。
• 元素定位与导航：predict_next_action（确定性 CSS 选择器与边界坐标）、record_outcome（UI 操作转换与视觉阻挡因素）、get_navigation_paths（BFS 最短路径规划器）、wait_for_visual_state（轮询目标 UI 状态）。
• 视频轨迹与证据包：manage_video（WebM/MP4 关键帧导入、时间线搜索）、compare_states（视觉布局差异与视频轨迹比较）、create_evidence_pack（通过加密审计证明，将视频关键帧关联到状态记忆 DAG）、export_trajectories（多模态微调数据集）。
• 快照与视觉 SDD：manage_visual_spec（模型图基线契约与回归检查）、manage_snapshot（检查点、导出、恢复）、undo_visual_mutation（撤销状态导入）、forget_state（隐私与 PII 清除）。

👉 有关完整的参数规范、返回架构和示例载荷，请参阅**正式 API 参考和功能与架构指南**。

---

🚀 架构一览

                     Incoming Screen
                            │
                            ▼
              ┌──────────────────────────────┐
              │ L1: In-Memory Cache Lookup   │ ──(Hit)──▶ Return Cached Description & Grounded Elements
              └──────────────┬───────────────┘
                             │ (Miss)
                             ▼
              ┌──────────────────────────────┐
              │ L2: Perceptual Hash Scan     │ ──(Hit)──▶ Return Cached Description & Grounded Elements
              └──────────────┬───────────────┘
                             │ (Miss)
                             ▼
              ┌──────────────────────────────┐
              │ L3: Local CLIP Vector Search │ ──(Hit)──▶ Return Semantically Close
              └──────────────┬───────────────┘
                             │ (Miss)
                             ▼
              ┌──────────────────────────────┐
              │ L4: Vision LLM Fallback      │ ──(Ingest)──▶ Save Redacted State to DB
              └──────────────┬───────────────┘

---

📚 文档目录

在 docs/ 目录中查看专门指南和深入介绍：

指南	描述
🏗️ 架构与代码库提炼	精炼的架构概览、4 层流水线、模块清单和设计决策。
🚀 功能与架构	主要功能、4 层检索流水线、元素定位和 Dual MCP Synergy。
📘 正式 API 参考	全部 15 个整合型 MCP 工具的完整规范、参数和架构。
🔌 多 IDE 集成指南	Cursor、Claude Desktop、Antigravity、Windsurf、Zed、Roo Code 和 Agent Rules 的逐步配置说明。
💻 CLI 命令参考	全部 16 个 CLI 管理、视觉规范和快照命令的完整指南。
⚙️ 配置指南	完整的 .env 环境变量、阈值和 L4 视觉回退配置。
🔒 存储加密与安全	加密详情、本地存储隐私和 PII 遮罩保障。
🤝 贡献指南	开发环境设置、代码库结构和提交指南。
🛡️ 安全策略	安全漏洞报告和隐私披露。
📜 更新日志	按时间顺序记录版本功能、修复和补丁更新。

---

⚠️ 不适用场景

虽然 vision-memory-mcp 面向视觉前端状态缓存、UI 测试和多模态工作流，但以下场景可能并不适用：

• 无头／纯后端开发：非视觉 CLI 工具、数据库脚本或不渲染 UI 的纯后端微服务。（此时可单独使用 state-memory-mcp。）
• 高帧率实时视频流：持续导入 60 fps 的实时视频，且没有离散关键帧或测试操作边界。
• 超低内存嵌入式环境（<512 MB RAM）：运行完整的本地 CLIP 神经嵌入需要约 300 MB RAM（如果内存有限，可使用 --skip-model-load，仅进行轻量级 dHash 感知）。

---

🧪 测试

# Run full unit and integration test suite across all 72 test files (312 tests)
npm run test

---

⚖️ 许可证与免责声明

由 PuterVision 开发和维护。根据 MIT License 发布。

• 本地存储保证：按“原样”提供，不附带任何保证。截图、感知哈希、向量嵌入和转换图均在应用程序层面以未加密的形式存储于 .vision-memory-mcp/ 中。绝不会传输任何遥测或分析数据。
• 商标与非隶属关系：产品名称（Cursor、Claude Code、Gemini、Windsurf、VS Code、Sharp、LanceDB、ONNX、HuggingFace）均归各自所有者所有，仅用于识别兼容性。