Vision Memory MCP

Cache visual persistente para desenvolvimento de software orientado por LLM. Armazena capturas de tela em cache usando hashing perceptual, busca vetorial e árvores AX para evitar sobrecarga de tokens e loops de alucinação visual.

GitHub

Experimente este MCPPatrocinado

Documentação

@putervision/vision-memory-mcp

@putervision/vision-memory-mcp é um servidor Model Context Protocol (MCP) e ferramenta de linha de comando sem infraestrutura e com foco local, que fornece a assistentes de codificação de IA (como Cursor, Claude Code, Gemini ou Copilot) cache de estado visual usando hash perceptual, embeddings CLIP locais e grafos de transição para eliminar chamadas repetitivas de LLM de visão.

🌐 Documentação Oficial e Site: visionmemorymcp.com

⚡ Início Rápido e Instalação

Pré-requisitos: Node.js >= 18.18.0

1. Instalação

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

2. Inicialização do Workspace

Execute init na raiz do seu projeto para criar os diretórios do banco de dados, .gitignore, .env e regras de IDE:

vision-memory-mcp init --yes

3. Configuração Básica do Cliente MCP

Adicione à configuração do seu cliente MCP (ex.: .cursor/mcp.json ou .vscode/mcp.json):

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

Opções Alternativas e Exemplos de Uso da 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

🌟 Principais Destaques

👁️ Cache Visual Perceptual: Reconhecimento de layout de caminho rápido com zero tokens em L1/L2 dHash em menos de 5ms.
🎬 Ingestão de Vídeo WebM e MP4: Digere gravações de testes E2E e capturas de tela em estados visuais de keyframes pesquisáveis e grafos de transição de estado.
⚡ 15 Ferramentas MCP Principais: Conjunto consolidado de alta coerência cobrindo percepção, memória de vídeo, pacotes de evidência, comparação de trajetórias, recuperação semântica, ancoragem de elementos, SDD visual, snapshots e contexto unificado e métricas.
🔗 Sinergia Dual-MCP e Pacotes de Evidência Imutáveis: Conecta profundamente os DAGs de tarefas do @putervision/state-memory-mcp com a memória de estado visual, gerando pacotes de evidência com hash criptográfico para conformidade e trilhas de auditoria.
📉 Overhead de Tokens Reduzido: Armazena estados de UI localmente usando dHash, busca vetorial CLIP local e árvores de acessibilidade para maximizar a economia de tokens de visão.
🚀 Latência de Caminho Rápido em Menos de 5ms: Elimina chamadas repetitivas de API de LLM de visão e evita loops de alucinação visual.
🎯 Ancoragem de Elementos e Previsão de Alvo de Ação: Mapeia elementos de tela para seletores CSS e coordenadas para interação de UI determinística.
🎨 Desenvolvimento Orientado por Spec Visual (Visual SDD): Registra mockups de design ou capturas de tela como contratos de linha de base perceptual para verificar regressão visual.
🛡️ Privacidade 100% Local-Primeiro: Armazenamento vetorial LanceDB local, modelo CLIP local, zero telemetria em nuvem e garantia de redação de PII.

🛠️ Suíte de Ferramentas MCP

@putervision/vision-memory-mcp fornece 15 ferramentas MCP consolidadas de nível de produção estruturadas em 4 domínios principais de percepção visual e automação:

Percepção e Busca Semântica: analyze_screenshot (análise perceptual L1/L2 dHash e árvore AX, única/em lote), recall_memory (busca semântica vetorial de texto e imagem), get_session_context (métricas agregadas de acerto de cache, estados recentes).
Ancoragem de Elementos e Navegação: predict_next_action (seletores CSS determinísticos e coordenadas de delimitação), record_outcome (transições de ação de UI e bloqueadores visuais), get_navigation_paths (planejador de caminho mais curto BFS), wait_for_visual_state (polling para estado de UI alvo).
Trajetórias de Vídeo e Pacotes de Evidência: manage_video (ingestão de keyframes WebM/MP4, busca de linha do tempo), compare_states (diffs de layout visual e comparação de trajetórias de vídeo), create_evidence_pack (prova de auditoria criptográfica vinculando keyframes de vídeo a DAGs de memória de estado), export_trajectories (conjuntos de dados de fine-tuning multimodal).
Snapshots e SDD Visual: manage_visual_spec (contratos de linha de base de mockup e verificações de regressão), manage_snapshot (checkpoints, exportação, restauração), undo_visual_mutation (reversão de ingestão de estado), forget_state (privacidade e purga de PII).

👉 Para especificações completas de parâmetros, esquemas de retorno e exemplos de payload, consulte a Referência Formal da API e o Guia de Recursos e Arquitetura.

🚀 Arquitetura em Resumo

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

📚 Diretório de Documentação

Explore guias dedicados e mergulhos profundos no diretório docs/:

Guia	Descrição
🏗️ Destilação de Arquitetura e Código	Visão geral arquitetural de alto sinal, pipeline de 4 camadas, inventário de módulos e decisões de design.
🚀 Recursos e Arquitetura	Principais recursos, pipeline de recuperação de 4 camadas, ancoragem de elementos e Sinergia Dual MCP.
📘 Referência Formal da API	Especificações completas, parâmetros e esquemas para todas as 15 ferramentas MCP consolidadas.
🔌 Guia de Integração Multi-IDE	Configurações passo a passo para Cursor, Claude Desktop, Antigravity, Windsurf, Zed, Roo Code e Regras de Agente.
💻 Referência de Comandos CLI	Guia completo para todos os 16 comandos de gerenciamento CLI, spec visual e snapshot.
⚙️ Guia de Configuração	Variáveis de ambiente completas do `.env`, limites e configuração de fallback de visão L4.
🔒 Criptografia de Armazenamento e Segurança	Detalhes de criptografia, privacidade de armazenamento local e garantias de mascaramento de PII.
🤝 Guia de Contribuição	Configuração de desenvolvimento, estrutura do código e diretrizes de envio.
🛡️ Política de Segurança	Relato de vulnerabilidades de segurança e divulgações de privacidade.
📜 Changelog	Registro cronológico de recursos, correções e atualizações de patch.

⚠️ Quando Não Usar Este Servidor

Embora o vision-memory-mcp seja projetado para cache de estado visual de frontend, testes de UI e fluxos de trabalho multimodais, ele pode não ser apropriado para:

Desenvolvimento Headless / Backend Puro: Ferramentas CLI não visuais, scripts de banco de dados ou microsserviços de backend puro sem renderização de UI. (Use state-memory-mcp standalone).
Streaming de Vídeo ao Vivo de Alta Taxa de Quadros: Ingestão contínua de vídeo ao vivo a 60 fps sem limites discretos de keyframe ou ação de teste.
Ambientes Embarcados de Memória Ultra Baixa (<512 MB de RAM): Executar embeddings neurais CLIP locais completos requer ~300 MB de RAM (use --skip-model-load para percepção leve apenas com dHash se a memória for limitada).

🧪 Testes

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

⚖️ Licença e Avisos Legais

Desenvolvido e mantido pela PuterVision. Lançado sob a Licença MIT.

Garantia de Armazenamento Local: Fornecido "como está", sem garantia. Capturas de tela, hashes perceptuais, embeddings vetoriais e grafos de transição são armazenados localmente sem criptografia no nível do aplicativo em .vision-memory-mcp/. Zero telemetria ou dados de análise são transmitidos.
Marcas Registradas e Não Afiliação: Nomes de produtos (Cursor, Claude Code, Gemini, Windsurf, VS Code, Sharp, LanceDB, ONNX, HuggingFace) são propriedade de seus respectivos proprietários e usados apenas para identificação de compatibilidade.