@putervision/state-memory-mcp

@putervision/state-memory-mcp es un servidor de Model Context Protocol (MCP) determinista y sin infraestructura que proporciona a los asistentes de codificación con IA (como Cursor, Claude Code, Gemini o Copilot) un grafo SQLite estructurado y persistente para el seguimiento del estado del flujo de trabajo: tareas, decisiones, artefactos, planes, bloqueadores y sus relaciones semánticas.

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

⚡ Inicio rápido e instalación

Requisitos previos: Node.js >= 18.18.0

# 1. Install globally
npm install -g @putervision/state-memory-mcp

# 2. Navigate to your project directory
cd your-project

# 3. Initialize state-memory-mcp
# Creates .state-memory-mcp/, updates .gitignore, registers project,
# and scaffolds IDE instructions and MCP configs for Cursor, Claude, VS Code, Windsurf, etc.
state-memory-mcp init

# Done! Restart your IDE or Agent Manager to activate.

Opciones alternativas

# Run directly via binary (after global install)
state-memory-mcp run

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

Related MCP server: AIVectorMemory

🌟 Aspectos destacados

• 🧠 Memoria de estado determinista: cero LLM en el bucle para operaciones de memoria; recorridos rápidos y deterministas del grafo SQLite.

• ⚡ 13 herramientas MCP consolidadas de nivel de producción: CRUD completo, vinculación de relaciones, comprobaciones de ciclos DAG, búsqueda FTS5, RAG TF-IDF, reversión del historial con viaje en el tiempo, desarrollo dirigido por especificaciones y validación con autocuración.

• 📉 Gestión eficiente del contexto: descarga el contexto a una base de datos SQLite local, lo que ayuda a reducir la sobrecarga de contexto del prompt y el uso de la ventana de contexto.

• 🚀 Reducción de latencia del 67 %–74 %: elimina los bucles de escaneo de archivos de varios pasos; los agentes recuperan tareas desbloqueadas y bloqueadores en milisegundos.

• 🤝 Pizarra multiagente: almacén de contexto compartido que permite a los subagentes paralelos publicar decisiones, tareas y actualizaciones de bloqueadores de forma segura.

• 🎨 Visualizador 3D interactivo: visualizador de grafos dirigidos por fuerza 3D WebGL en modo oscuro basado en navegador (state-memory-mcp view).

• 🔗 Sinergia de MCP dual: combínalo con @putervision/vision-memory-mcp para el caché de estado visual, el hash perceptivo y los paquetes criptográficos de evidencia multimodal.

• 🛡️ 100 % local y privado: arquitectura local-first; todo el estado permanece dentro de .state-memory-mcp/ en tu espacio de trabajo.

🛠️ Suite de herramientas MCP

@putervision/state-memory-mcp proporciona 13 herramientas MCP consolidadas de nivel de producción organizadas en 5 dominios principales del flujo de trabajo:

• Grafo y relaciones: manage_nodes (CRUD de nodos, búsqueda vectorial FTS5/TF-IDF, mutaciones atómicas por lotes, notas de observación), manage_edges (enlaces DAG tipados, vinculación de estado visual multimodal).

• Ejecución de tareas y cola de trabajo: manage_tasks (cola de dependencias topológicas, detección de bloqueadores, finalización de tareas con artefactos, poda automática), manage_sessions (atribución de agentes, seguimiento de turnos, arranque de contexto).

• Desarrollo dirigido por especificaciones (SDD): manage_specs (análisis de PRD/RFC, descomposición de requisitos en tareas, verificación en tiempo real de criterios de aceptación, puntuación de cumplimiento).

• Analítica, auditoría y diagnóstico: get_analytics (velocidad, burndown, ROI de tokens, carga cognitiva, ruta crítica), get_events (registro de eventos a prueba de manipulaciones SHA-256), run_diagnostics (validación de DAG, comprobaciones de salud, integridad de referencias AST).

• Datos, instantáneas y multiagente: manage_snapshots (puntos de control, deshacer con viaje en el tiempo), manage_database (copias de seguridad, auditorías de suma de comprobación, fusión de ramas VCS), manage_data (importación/exportación masiva, trayectorias de ML), query_graph (subgrafos, trazado de dependencias, SQL sin procesar), use_blackboard (tablero de temas asíncrono multiagente).

👉 Para las especificaciones completas de parámetros, los esquemas de retorno y las cargas útiles de ejemplo, consulta la Guía de referencia de herramientas y la Referencia formal de la API.

🚀 Arquitectura y ciclo de vida del grafo de estado

                      AI Agent Prompt / Task
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Agent Session Attribution       │ ──▶ manage_sessions(action: "start")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Context & Task Prioritization   │ ──▶ get_analytics(action: "summary")
               │                                 │ ──▶ manage_tasks(action: "next")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Deterministic Graph Mutation   │ ──▶ manage_nodes(action: "create"|"update")
               │  (Tasks, Decisions, Blockers)   │ ──▶ manage_edges(action: "add"|"link_visual")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Spec & Integrity Verification  │ ──▶ manage_specs(action: "compliance"|"verify")
               │                                 │ ──▶ run_diagnostics(action: "validate")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Persistent SQLite Storage      │ ──▶ .state-memory-mcp/graph.db (WAL mode)
               │  Append-Only Event Ledger       │ ──▶ SHA-256 Cryptographic Audit Chain
               └─────────────────────────────────┘

📚 Directorio de documentación

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

📖 Manual del agente: flujo de trabajo canónico en 5 pasos

Cuando un agente de IA autónomo entra en un repositorio con state-memory-mcp:

1. Orient & Bootstrap ──▶ manage_sessions(action: "start") + get_analytics(action: "summary")
2. Task Selection     ──▶ manage_tasks(action: "next") + manage_tasks(action: "find_blockers")
3. Trace Context      ──▶ query_graph(action: "trace") + manage_specs(action: "compliance")
4. Execute & Record   ──▶ manage_nodes(action: "create", type: "decision") + manage_edges(action: "link_visual")
5. Validate & Close   ──▶ run_diagnostics(action: "validate") + manage_tasks(action: "complete") + manage_sessions(action: "end")

🧪 Pruebas

# Run full unit, integration, and performance benchmark test suite across all 110 test files (406 tests)
npm run test

⚖️ Licencia y avisos legales

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

• Garantía de almacenamiento local: todos los datos del grafo, los registros de decisiones y los registros de eventos permanecen 100 % locales en tu espacio de trabajo. Nunca se transmite telemetría ni datos del proyecto.

• Marcas comerciales y no afiliación: los nombres de productos (Cursor, Claude Code, Gemini, Windsurf, VS Code, GitHub, SQLite) son propiedad de sus respectivos propietarios y se utilizan únicamente para identificar la compatibilidad.