Caches UI screenshots locally using perceptual hashing and vector search so AI coding assistants can recall visual states without repeated vision LLM calls.
Also known as putervision/vision-memory-mcp, vision-memory-mcp, @putervision/vision-memory-mcp
- Stars
- 42
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.4.2
- Last commit
- Oct 8, 2026
- License
- —
What is Vision Memory MCP?
Vision Memory caches UI screenshots locally using perceptual hashing and vector search so AI coding assistants can recall visual states without repeated vision LLM calls.
Summary generated from the project's README
About Vision Memory MCP server
Developers using AI coding assistants like Cursor, Claude Code, or Gemini can use this tool to cache UI screenshots locally and reduce expensive vision LLM API calls. By utilizing perceptual hashing and local CLIP embeddings, the server allows an AI to recall previous visual states through a multi-tier retrieval pipeline. This local-first approach ensures privacy by storing data in a local LanceDB vector store with zero cloud telemetry.
Users can set up the environment by running an init command in their project root to scaffold necessary directories and configuration files. The server provides 15 core tools for tasks such as semantic search, element grounding, and video ingestion. It supports ingesting WebM or MP4 recordings to create searchable keyframe timelines and transition graphs. For environments with limited resources, a skip-model-load flag allows the server to run without heavy CLIP model downloads.
What you can do with it
- 1Reduce vision token costsAn AI assistant can retrieve cached descriptions of a UI layout instead of making a new vision LLM request.
- 2Automate UI interactionA developer can ask an AI to find the exact CSS selector or coordinates for a specific button on the screen.
- 3Verify design consistencyYou can register a design mockup as a baseline to check if current UI changes cause visual regressions.
- 4Analyze test recordingsIngest end-to-end test videos to turn screen captures into a searchable timeline of visual states.
Written from the project's README. Every use case is checked against a quote from it.
How to install Vision Memory MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Vision Memory MCP in Claude Code
$ claude mcp add vision-memory-mcp -- npx -y @putervision/vision-memory-mcpInstall Vision Memory MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "npx",
"args": [
"-y",
"@putervision/vision-memory-mcp"
]
}
}
}Install Vision Memory MCP in VS Code
.vscode/mcp.json
{
"servers": {
"vision-memory-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@putervision/vision-memory-mcp"
]
}
}
}Install Vision Memory MCP in VS Code CLI
$ code --add-mcp '{"name":"vision-memory-mcp","type":"stdio","command":"npx","args":["-y","@putervision/vision-memory-mcp"]}'Install Vision Memory MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "npx",
"args": [
"-y",
"@putervision/vision-memory-mcp"
]
}
}
}Install Vision Memory MCP in Codex
$ codex mcp add vision-memory-mcp -- npx -y @putervision/vision-memory-mcpInstall Vision Memory MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.vision-memory-mcp] command = "npx" args = ["-y", "@putervision/vision-memory-mcp"]
Install Vision Memory MCP in Gemini CLI
$ gemini mcp add -s user vision-memory-mcp npx -- -y @putervision/vision-memory-mcpInstall Vision Memory MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"vision-memory-mcp": {
"command": "npx",
"args": [
"-y",
"@putervision/vision-memory-mcp"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableputervision/vision-memory-mcp is public and reachablegithub.com/putervision/vision-memory-mcp ↗Pass
- Package names this repository as its source@putervision/vision-memory-mcp names putervision/vision-memory-mcp as sourcenpmjs.com/package/@putervision/vision-memory-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @putervision/vision-memory-mcpnpmjs.com/package/@putervision/vision-memory-mcp/v/1.4.2#pro ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-08github.com/putervision/vision-memory-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @putervision/vision-memory-mcpPass
- No critical advisory in the package or its dependencies114 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@putervision/vision-memory-mcp
@putervision/vision-memory-mcp is a zero-infrastructure, local-first Model Context Protocol (MCP) server and CLI tool that provides AI coding assistants (such as Cursor, Claude Code, Gemini, or Copilot) with visual state caching using perceptual hashing, local CLIP embeddings, and transition graphs to eliminate repetitive vision LLM calls.
🌐 Official Documentation & Website: visionmemorymcp.com
⚡ Quick Start & Installation
Prerequisites: Node.js >= 18.18.0
1. Installation
# Global installation via npm
npm install -g @putervision/vision-memory-mcp
2. Workspace Initialization
Run init in your project root to scaffold database directories, .gitignore, .env, and IDE rules:
vision-memory-mcp init --yes
3. Basic MCP Client Setup
Add to your MCP client config (e.g. .cursor/mcp.json or .vscode/mcp.json):
{
"mcpServers": {
"vision-memory-mcp": {
"command": "vision-memory-mcp",
"args": ["run"]
}
}
}
Alternative Options & CLI Usage Examples
# 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
🌟 Key Highlights
- 👁️ Perceptual Visual Caching & Compact Slices: Sub-5ms L1/L2 dHash zero-token fast-path layout recognition and sub-1KB
compact_sliceexport for Pentad System 1 StatePack assembly. - 🎬 WebM & MP4 Video Ingestion: Digest E2E test recordings & screen captures into searchable keyframe visual states & state transition graphs.
- ⚡ 15 Core MCP Tools: High-coherence consolidated toolset covering perception, video memory, evidence packs, trajectory comparison, semantic retrieval, element grounding, visual SDD, snapshots, and unified context & metrics.
- 🔗 Dual-MCP Synergy & Immutable Evidence Packs: Deeply bridges
@putervision/state-memory-mcptask DAGs with visual state memory, generating cryptographically hashable evidence packs for compliance and audit trails. - 📉 Reduced Token Overhead: Caches UI states locally using dHash, local CLIP vector search, and accessibility trees to maximize vision token savings.
- 🚀 Sub-5ms Fast-Path Latency: Eliminates repetitive vision LLM API calls and avoids visual hallucination loops.
- 🎯 Element Grounding & Action Target Prediction: Maps screen elements to CSS selectors and coordinates for deterministic UI interaction.
- 🎨 Visual Spec-Driven Development (Visual SDD): Register design mockups or screenshots as perceptual baseline contracts to verify visual regression.
- 🛡️ 100% Local-First Privacy: Local LanceDB vector store, local CLIP model, zero cloud telemetry, and PII redaction guarantees.
🛠️ MCP Tool Suite
@putervision/vision-memory-mcp provides 15 production-grade consolidated MCP tools structured across 4 core visual perception & automation domains:
- Perception & Semantic Search:
analyze_screenshot(L1/L2 perceptual dHash & AX tree parsing, single/batch),recall_memory(text & image semantic vector search),get_session_context(aggregated cache hit metrics, recent states, and sub-1KBcompact_sliceexport). - Element Grounding & Navigation:
predict_next_action(deterministic CSS selectors & bounding coordinates),record_outcome(UI action transitions & visual blockers),get_navigation_paths(BFS shortest-path planner),wait_for_visual_state(polling for target UI state). - Video Trajectories & Evidence Packs:
manage_video(WebM/MP4 keyframe ingestion, timeline search),compare_states(visual layout diffs & video trajectory comparison),create_evidence_pack(cryptographic audit proof linking video keyframes to state-memory DAGs),export_trajectories(multimodal fine-tuning datasets). - Snapshots & Visual SDD:
manage_visual_spec(mockup baseline contracts & regression checks),manage_snapshot(checkpoints, export, restore),undo_visual_mutation(revert state ingestion),forget_state(privacy & PII purging).
👉 For complete parameter specifications, return schemas, and example payloads, see the Formal API Reference and Features & Architecture Guide.
🚀 Architecture At a Glance
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
└──────────────┬───────────────┘
📚 Documentation Directory
Explore dedicated guides and deep dives in the docs/ directory:
| Guide | Description |
|---|---|
| 🏗️ Architecture & Codebase Distillation | High-signal architectural overview, 4-tier pipeline, module inventory, and design decisions. |
| 🚀 Features & Architecture | Key features, 4-tier retrieval pipeline, element grounding, and Dual MCP Synergy. |
| 📘 Formal API Reference | Complete specifications, parameters, and schemas for all 15 consolidated MCP tools. |
| 🔌 Multi-IDE Integration Guide | Step-by-step configs for Cursor, Claude Desktop, Antigravity, Windsurf, Zed, Roo Code & Agent Rules. |
| 💻 CLI Commands Reference | Full guide for all 16 CLI management, visual spec, and snapshot commands. |
| ⚙️ Configuration Guide | Complete .env environment variables, thresholds, and L4 vision fallback setup. |
| 🔒 Storage Encryption & Security | Encryption details, local storage privacy, and PII masking guarantees. |
| 🤝 Contributing Guide | Development setup, codebase structure, and submission guidelines. |
| 🛡️ Security Policy | Security vulnerability reporting and privacy disclosures. |
| 📜 Changelog | Chronological record of release features, fixes, and patch updates. |
⚠️ When Not to Use This Server
While vision-memory-mcp is designed for visual frontend state caching, UI testing, and multimodal workflows, it may not be appropriate for:
- Headless / Pure Backend Development: Non-visual CLI tools, database scripts, or pure backend microservices with no UI rendering. (Use
state-memory-mcpstandalone instead). - High-Framerate Live Video Streaming: Continuous 60 fps live video ingest without discrete keyframe or test action boundaries.
- Ultra Low-Memory Embedded Environments (<512 MB RAM): Running full local CLIP neural embeddings requires ~300 MB RAM (use
--skip-model-loadfor lightweight dHash-only perception if memory is constrained).
🧪 Testing
# Run full unit and integration test suite across all 72 test files (312 tests)
npm run test
⚖️ License & Disclaimers
Developed and maintained by PuterVision. Released under the MIT License.
- Local Storage Guarantee: Provided "as is" without warranty. Screenshots, perceptual hashes, vector embeddings, and transition graphs are stored locally unencrypted at the application level in
.vision-memory-mcp/. Zero telemetry or analytics data is ever transmitted. - Trademarks & Non-Affiliation: Product names (Cursor, Claude Code, Gemini, Windsurf, VS Code, Sharp, LanceDB, ONNX, HuggingFace) are property of their respective owners and used solely for compatibility identification.
Vision Memory MCP questions
How do I add Vision Memory MCP to Claude Code?
Run claude mcp add vision-memory-mcp -- npx -y @putervision/vision-memory-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Vision Memory MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I install vision-memory-mcp?
Install it globally with npm and then run the init command in your project root to scaffold the workspace.
Does it send my screenshots to the cloud?
No. It uses a local LanceDB vector store and local CLIP model with zero cloud telemetry.
Can it run offline without downloading models?
Yes, the run command accepts a --skip-model-load flag for air-gapped or offline environments using dHash-only perception.
What MCP tools does it expose?
It provides 15 consolidated tools covering screenshot analysis, semantic recall, element grounding, video ingestion, evidence packs, snapshots, and visual spec checks.
What Node.js version is required?
Node.js 18.18.0 or newer is required.