🧠 Prism MCP — El Palacio Mental para Agentes de IA

Tu agente de IA olvida todo entre sesiones. Prism soluciona eso y, además, le enseña a pensar.

Prism v7.8 es una verdadera Arquitectura Cognitiva inspirada en la mecánica del cerebro humano. Más allá de la búsqueda vectorial plana, tu agente ahora forma principios a partir de la experiencia, sigue trenes de pensamiento causales y posee la autoconciencia necesaria para saber cuándo le falta información. Tus agentes no solo recuerdan; aprenden.

npx -y prism-mcp-server

Funciona con Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Gemini · Antigravity — cualquier cliente MCP.

https://github.com/dcostenco/prism-mcp/raw/main/docs/prism_mcp_demo.mp4

📖 Tabla de contenidos

• ¿Por qué Prism?

• Inicio rápido

• El momento mágico

• Guías de configuración

• Importación universal: Trae tu historial

• Qué hace diferente a Prism

• Arquitectura cognitiva (v7.8)

• Privacidad de datos y egreso

• Casos de uso

• Novedades

• Cómo se compara Prism

• Referencia de CLI

• Referencia de herramientas

• Variables de entorno

• Arquitectura

• Fundamentos científicos

• Hitos y hoja de ruta

• Preguntas frecuentes de solución de problemas

¿Por qué Prism?

Cada vez que inicias una nueva conversación con un asistente de programación de IA, empieza desde cero. Vuelves a explicar tu arquitectura, a describir tus decisiones, a listar tus tareas pendientes. Horas de contexto, perdidas.

Prism le da a tu agente un cerebro que persiste y, luego, le enseña a razonar. Guarda lo que importa al final de cada sesión. Cárgalo al instante en la siguiente. Pero Prism va mucho más allá del almacenamiento: consolida la experiencia bruta en principios duraderos, recorre cadenas causales para encontrar causas raíz y sabe cuándo decir "no lo sé".

📌 Terminología: A lo largo de este documento, "Prism" se refiere al servidor MCP y al motor de memoria cognitiva. "Palacio Mental" (Mind Palace) se refiere a la interfaz del panel visual en localhost:3000, tu ventana al cerebro del agente. Funcionan juntos; el panel es opcional.

Prism tiene tres pilares:

1. 🧠 Memoria cognitiva — Los recuerdos se clasifican como en un cerebro humano: el contexto accedido reciente y frecuentemente aparece primero, mientras que el contexto obsoleto se desvanece naturalmente mediante la decadencia de activación ACT-R. La experiencia bruta se consolida en principios semánticos a través del aprendizaje hebbiano. El resultado es una calidad de recuperación que ninguna búsqueda vectorial plana puede igualar. (Ver Arquitectura cognitiva y Fundamentos científicos.)

2. 🔗 Razonamiento de múltiples saltos — Cuando tu agente busca "Error X", Prism no solo encuentra registros que mencionan "Error X". La activación por propagación recorre el grafo causal y trae de vuelta "Solución alternativa Y", que está conectada a "Decisión de arquitectura Z": un tren de pensamiento literal. (Ver Arquitectura cognitiva.)

3. 🏭 Ejecución autónoma (Dark Factory) — Cuando estés listo, Prism puede ejecutar tareas de programación de principio a fin con una tubería de cierre ante fallos donde un evaluador adversarial detecta errores que el generador pasó por alto, antes de que veas el PR. (Ver Dark Factory.)

🚀 Inicio rápido

Requisitos previos

• Node.js v18+ (se recomienda v20 LTS; v23.x tiene un problema conocido con npx)

• Cualquier cliente compatible con MCP (Claude Desktop, Cursor, Windsurf, Cline, etc.)

• No se requieren claves API para las funciones principales (ver Matriz de capacidades)

Instalación

Agrégalo a la configuración de tu cliente MCP (claude_desktop_config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

⚠️ Windows / Shells restringidas: Si tu cliente MCP se queja de que no se encuentra npx, usa la ruta absoluta a tu binario de node (ej. C:\Program Files\nodejs\npx.cmd).

Eso es todo. Reinicia tu cliente. Todas las herramientas están disponibles. El Panel del Palacio Mental (la interfaz visual para el cerebro de tu agente) se inicia automáticamente en http://localhost:3000. No necesitas mantener una pestaña abierta; el panel se ejecuta en segundo plano y las herramientas MCP funcionan con o sin él.

🔮 Consejo profesional: Una vez instalado, abre http://localhost:3000 en tu navegador para ver el Panel del Palacio Mental, una hermosa interfaz en tiempo real del cerebro de tu agente. Explora el Grafo de Conocimiento, los indicadores de salud de intención y el Libro de Sesiones.

🔄 Actualización de Prism: npx -y almacena el paquete en caché localmente. Para forzar una actualización a la última versión, reinicia tu cliente MCP; npx -y buscará la versión más reciente automáticamente. Si te quedas atascado en una versión antigua, ejecuta npx clear-npx-cache (o npm cache clean --force) antes de reiniciar.

Agrega PRISM_DASHBOARD_PORT al bloque de entorno de tu configuración MCP:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"],
      "env": { "PRISM_DASHBOARD_PORT": "3001" }
    }
  }
}

Luego abre http://localhost:3001 en su lugar.

Matriz de capacidades

🔑 El Palacio Mental principal funciona 100% sin conexión sin claves API. Las claves de la nube desbloquean funciones de inteligencia. Ver Variables de entorno.

💰 Nota sobre el costo de la API: GOOGLE_API_KEY (Gemini) tiene un nivel gratuito generoso que cubre la mayoría de los usos individuales. BRAVE_API_KEY ofrece 2000 búsquedas gratuitas al mes. FIRECRAWL_API_KEY tiene un plan gratuito con 500 créditos. Para el desarrollo típico en solitario, espera $0/mes en los niveles gratuitos. Solo los equipos de alto volumen o el uso intensivo de tuberías autónomas incurrirán en costos significativos.

✨ El momento mágico

Sesión 1 (lunes por la noche):

You: "Analyze this auth architecture and plan the OAuth migration."
Agent: *deep analysis, decisions, TODO list*
Agent: session_save_ledger → session_save_handoff ✅

Sesión 2 (martes por la mañana: nueva conversación, nueva ventana de contexto):

Agent: session_load_context → "Welcome back! Yesterday we decided to use PKCE
       flow with refresh tokens. 3 TODOs remain: migrate the user table,
       update the middleware, and write integration tests."
You: "Pick up where we left off."

Tu agente recuerda todo. No hay que volver a subir archivos. No hay que volver a explicar decisiones.

📖 Guías de configuración

Agrégalo a claude_desktop_config.json:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

Agrégalo a .cursor/mcp.json (proyecto) o ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

Agrégalo a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

Agrégalo a tu config.json de Continue o a la configuración MCP de Cline:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"],
      "env": {
        "PRISM_STORAGE": "local",
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

Claude Code detecta naturalmente las herramientas MCP agregándolas a tu .clauderules del espacio de trabajo. Simplemente agrega:

Always start the conversation by calling `mcp__prism-mcp__session_load_context(project='my-project', level='deep')`.
When wrapping up, always call `mcp__prism-mcp__session_save_ledger` and `mcp__prism-mcp__session_save_handoff`.

Nota de formato: Claude envuelve automáticamente las herramientas MCP con guiones bajos dobles (mcp__prism-mcp__...), mientras que la mayoría de los otros clientes usan guiones bajos simples (mcp_prism-mcp_...). El backend de Prism maneja ambos formatos de forma nativa y sin problemas.

Alternativa CLI: Si las herramientas MCP no están disponibles o estás creando scripts alrededor de Claude Code:

# Load context before a session
prism load my-project --level deep

# Machine-readable JSON for parsing in scripts
prism load my-project --level deep --json

Consulta la Guía de configuración de Gemini para conocer la arquitectura de prompts de tres capas probada para garantizar una carga automática de sesión confiable.

Antigravity no expone las herramientas MCP al modelo. Usa la CLI prism load como respaldo:

# From a shell or run_command tool
prism load my-project --level standard --json

# Or via the wrapper script
bash ~/.gemini/antigravity/scratch/prism_session_loader.sh my-project

La CLI utiliza la misma capa de almacenamiento que la herramienta MCP (SQLite o Supabase).

⚠️ CRÍTICO (v9.2.2): Prevención de cerebro dividido Si tu servidor MCP está configurado con PRISM_STORAGE=local pero también se establecen las credenciales de Supabase, la CLI puede leer desde el backend incorrecto (Supabase) mientras el servidor escribe en SQLite. Esto causa tareas pendientes obsoletas y un estado divergente. Pasa siempre --storage local explícitamente cuando uses la CLI en un entorno de modo local:

prism load my-project --storage local --json

El contenedor prism_session_loader.sh maneja esto automáticamente desde la v9.2.2.

Usa la CLI prism load para acceder al contexto de la sesión desde cualquier entorno de shell:

# Quick check — human-readable
prism load my-project

# Parse JSON in scripts
CONTEXT=$(prism load my-project --level quick --json)
SUMMARY=$(echo "$CONTEXT" | jq -r '.handoff[0].last_summary')
VERSION=$(echo "$CONTEXT" | jq -r '.handoff[0].version')
echo "Project at v$VERSION: $SUMMARY"

# Explicit storage backend (v9.2.2 — prevents split-brain)
prism load my-project --storage local --json
prism load my-project --storage supabase --json

# Role-scoped loading
prism load my-project --role qa --json

# Use in CI/CD to verify context exists before deploying
if ! prism load my-project --level quick --json | jq -e '.handoff[0].version' > /dev/null 2>&1; then
  echo "No Prism context found — skipping context-aware deploy"
fi

📦 Instalación: npm install -g prism-mcp-server hace que la CLI prism esté disponible globalmente. Para compilaciones locales: node /path/to/prism/dist/cli.js load.

Para sincronizar la memoria entre máquinas o equipos:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"],
      "env": {
        "PRISM_STORAGE": "supabase",
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_KEY": "your-supabase-anon-or-service-key"
      }
    }
  }
}

Migraciones de esquema

Prism aplica automáticamente su esquema en la primera conexión; no se requiere ningún paso manual. Si necesitas aplicar o volver a aplicar migraciones manualmente (ej. para un proyecto nuevo o después de una actualización de versión), ejecuta los archivos SQL en supabase/migrations/ en orden numérico a través del Editor SQL de Supabase o la CLI:

# Via CLI (requires supabase CLI + project linked)
supabase db push

# Or apply a single migration via the Supabase dashboard SQL Editor
# Paste the contents of supabase/migrations/0NN_*.sql and click Run

Migraciones clave:

• 020_* — Esquema central (libro mayor, transferencia, FTS, TTL, CRDT)

• 033_memory_links.sql — Grafo de memoria asociativa (MemoryLinks) — requerido para session_backfill_links

Clave anónima vs. clave de rol de servicio: La clave anónima funciona para uso personal (se aplican las políticas RLS de Supabase). Usa la clave de rol de servicio para implementaciones de equipo donde varios usuarios comparten el mismo proyecto de Supabase; omite RLS y permite que Prism gestione todas las filas independientemente del contexto de autenticación. Nunca expongas la clave de rol de servicio en el lado del cliente.

git clone https://github.com/dcostenco/prism-mcp.git
cd prism-mcp && npm install && npm run build

Luego agrégalo a tu configuración MCP:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "node",
      "args": ["/path/to/prism-mcp/dist/server.js"],
      "env": {
        "BRAVE_API_KEY": "your-key",
        "GOOGLE_API_KEY": "your-gemini-key"
      }
    }
  }
}

Prism se puede implementar de forma nativa en plataformas en la nube como Render para que la memoria de tu agente esté siempre en línea y accesible en diferentes máquinas o equipos.

1. Haz un fork de este repositorio.

2. En el Panel de Render, crea un nuevo Servicio Web que apunte a tu repositorio.

3. En el asistente de configuración, selecciona Docker como tiempo de ejecución.

4. Establece la ruta del Dockerfile en Dockerfile.smithery.

5. Conecta tu cliente MCP local a tu nuevo endpoint en la nube usando el transporte sse:

{
  "mcpServers": {
    "prism-mcp-cloud": {
      "command": "npx",
      "args": ["-y", "supergateway", "--url", "https://your-prism-app.onrender.com/sse"]
    }
  }
}

Nota: El Dockerfile.smithery utiliza una compilación optimizada de varias etapas que compila Types