Vision Memory MCP

@putervision/vision-memory-mcp

@putervision/vision-memory-mcp es un servidor MCP (Model Context Protocol) y herramienta CLI de infraestructura cero y prioridad local que proporciona a los asistentes de codificación con IA (como Cursor, Claude Code, Gemini o Copilot) un caché de estado visual mediante hash perceptual, embeddings CLIP locales y grafos de transición para eliminar llamadas repetitivas a LLM de visión.

🌐 Documentación oficial y sitio web: visionmemorymcp.com

---

⚡ Inicio rápido e instalación

Requisitos previos: Node.js >= 18.18.0

1. Instalación

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

2. Inicialización del espacio de trabajo

Ejecuta init en la raíz de tu proyecto para generar los directorios de base de datos, .gitignore, .env y las reglas del IDE:

vision-memory-mcp init --yes

3. Configuración básica del cliente MCP

Añade a la configuración de tu cliente MCP (por ejemplo, .cursor/mcp.json o .vscode/mcp.json):

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

Opciones alternativas y ejemplos de uso de 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

---

🌟 Características destacadas

• 👁️ Caché visual perceptual y fragmentos compactos: Reconocimiento de diseño de ruta rápida L1/L2 dHash sin tokens en menos de 5 ms y exportación compact_slice de menos de 1 KB para el ensamblaje del StatePack del Sistema 1 de Pentad.
• 🎬 Ingestión de video WebM y MP4: Convierte grabaciones de pruebas E2E y capturas de pantalla en estados visuales de fotogramas clave y grafos de transición de estados buscables.
• ⚡ 15 herramientas MCP principales: Conjunto de herramientas consolidadas de alta coherencia que cubre percepción, memoria de video, paquetes de evidencia, comparación de trayectorias, recuperación semántica, anclaje de elementos, SDD visual, instantáneas y contexto y métricas unificados.
• 🔗 Sinergia MCP dual y paquetes de evidencia inmutables: Conecta profundamente los DAG de tareas de @putervision/state-memory-mcp con la memoria de estado visual, generando paquetes de evidencia con hash criptográfico para cumplimiento y pistas de auditoría.
• 📉 Sobrecarga de tokens reducida: Almacena en caché los estados de la interfaz de usuario localmente mediante dHash, búsqueda de vectores CLIP local y árboles de accesibilidad para maximizar el ahorro de tokens de visión.
• 🚀 Latencia de ruta rápida inferior a 5 ms: Elimina las llamadas repetitivas a la API de LLM de visión y evita los bucles de alucinación visual.
• 🎯 Anclaje de elementos y predicción de objetivos de acción: Asigna elementos de pantalla a selectores CSS y coordenadas para una interacción determinista con la interfaz de usuario.
• 🎨 Desarrollo visual basado en especificaciones (SDD visual): Registra maquetas de diseño o capturas de pantalla como contratos de referencia perceptual para verificar la regresión visual.
• 🛡️ Privacidad 100 % local primero: Almacén de vectores LanceDB local, modelo CLIP local, cero telemetría en la nube y garantías de redacción de PII.

---

🛠️ Conjunto de herramientas MCP

@putervision/vision-memory-mcp proporciona 15 herramientas MCP consolidadas de grado de producción estructuradas en 4 dominios principales de percepción visual y automatización:

• Percepción y búsqueda semántica: analyze_screenshot (análisis perceptual L1/L2 dHash y árbol AX, individual/lote), recall_memory (búsqueda semántica de vectores de texto e imagen), get_session_context (métricas agregadas de aciertos de caché, estados recientes y exportación compact_slice de menos de 1 KB).
• Anclaje de elementos y navegación: predict_next_action (selectores CSS deterministas y coordenadas de delimitación), record_outcome (transiciones de acciones de interfaz de usuario y bloqueadores visuales), get_navigation_paths (planificador de ruta más corta BFS), wait_for_visual_state (sondeo para el estado de interfaz de usuario objetivo).
• Trayectorias de video y paquetes de evidencia: manage_video (ingestión de fotogramas clave WebM/MP4, búsqueda en línea de tiempo), compare_states (diferencias de diseño visual y comparación de trayectorias de video), create_evidence_pack (prueba de auditoría criptográfica que vincula fotogramas clave de video con DAG de memoria de estado), export_trajectories (conjuntos de datos de ajuste fino multimodal).
• Instantáneas y SDD visual: manage_visual_spec (contratos de referencia de maquetas y comprobaciones de regresión), manage_snapshot (puntos de control, exportación, restauración), undo_visual_mutation (ingestión de estado de reversión), forget_state (privacidad y purga de PII).

👉 Para especificaciones completas de parámetros, esquemas de retorno y cargas útiles de ejemplo, consulta la Referencia formal de la API y la Guía de características y arquitectura.

---

🚀 Arquitectura de un vistazo

                     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
              └──────────────┬───────────────┘

---

📚 Directorio de documentación

Explora guías dedicadas y análisis en profundidad en el directorio docs/:

Guía	Descripción
🏗️ Destilación de arquitectura y código	Resumen arquitectónico de alta señal, pipeline de 4 niveles, inventario de módulos y decisiones de diseño.
🚀 Características y arquitectura	Características clave, pipeline de recuperación de 4 niveles, anclaje de elementos y sinergia MCP dual.
📘 Referencia formal de la API	Especificaciones completas, parámetros y esquemas para las 15 herramientas MCP consolidadas.
🔌 Guía de integración multi-IDE	Configuraciones paso a paso para Cursor, Claude Desktop, Antigravity, Windsurf, Zed, Roo Code y reglas de agente.
💻 Referencia de comandos CLI	Guía completa de los 16 comandos de gestión CLI, especificación visual e instantáneas.
⚙️ Guía de configuración	Variables de entorno completas de .env, umbrales y configuración de respaldo de visión L4.
🔒 Cifrado de almacenamiento y seguridad	Detalles de cifrado, privacidad del almacenamiento local y garantías de enmascaramiento de PII.
🤝 Guía de contribución	Configuración de desarrollo, estructura del código y pautas de envío.
🛡️ Política de seguridad	Informe de vulnerabilidades de seguridad y divulgaciones de privacidad.
📜 Registro de cambios	Registro cronológico de características, correcciones y actualizaciones de parches de las versiones.

---

⚠️ Cuándo no usar este servidor

Si bien vision-memory-mcp está diseñado para el almacenamiento en caché de estado visual de frontend, pruebas de interfaz de usuario y flujos de trabajo multimodales, puede no ser apropiado para:

• Desarrollo sin interfaz / solo backend: Herramientas CLI no visuales, scripts de base de datos o microservicios backend puros sin renderizado de interfaz de usuario. (Usa state-memory-mcp de forma independiente en su lugar).
• Transmisión de video en vivo de alta velocidad de fotogramas: Ingestión continua de video en vivo a 60 fps sin límites discretos de fotogramas clave o acciones de prueba.
• Entornos integrados de memoria ultrabaja (<512 MB de RAM): Ejecutar embeddings CLIP neuronales locales completos requiere ~300 MB de RAM (usa --skip-model-load para percepción ligera solo con dHash si la memoria está limitada).

---

🧪 Pruebas

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

---

⚖️ Licencia y avisos legales

Desarrollado y mantenido por PuterVision. Publicado bajo la Licencia MIT.

• Garantía de almacenamiento local: Se proporciona "tal cual" sin garantía. Las capturas de pantalla, los hash perceptuales, los embeddings vectoriales y los grafos de transición se almacenan localmente sin cifrar a nivel de aplicación en .vision-memory-mcp/. Nunca se transmite telemetría ni datos de análisis.
• Marcas comerciales y no afiliación: Los nombres de productos (Cursor, Claude Code, Gemini, Windsurf, VS Code, Sharp, LanceDB, ONNX, HuggingFace) son propiedad de sus respectivos dueños y se utilizan únicamente para identificación de compatibilidad.