Dark Memory MCP

╔════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                    ║
║         ██████╗  ██████╗██████╗ ███╗   ███╗      ███╗   ███╗ ██████╗██████╗        ║
║        ██╔═══██╗██╔════╝██╔══██╗████╗ ████║      ████╗ ████║██╔════╝██╔══██╗       ║
║        ██║   ██║██║     ██║  ██║██╔████╔██║      ██╔████╔██║██║     ██████╔╝       ║
║        ██║   ██║██║     ██║  ██║██║╚██╔╝██║      ██║╚██╔╝██║██║     ██╔═══╝        ║
║        ╚██████╔╝╚██████╗██████╔╝██║ ╚═╝ ██║      ██║ ╚═╝ ██║╚██████╗██║            ║
║         ╚═════╝  ╚═════╝╚═════╝ ╚═╝     ╚═╝      ╚═╝     ╚═╝ ╚═════╝╚═╝            ║
║                                                                                    ║
║                     MEMORIA PERSISTENTE PARA AGENTES DE IA                         ║
║                                                                                    ║
║     El cuaderno que tu agente no olvida. Sesión tras sesión, proyecto tras         ║
║     proyecto. Con verificación automática de que lo entregado cumple lo pedido.    ║
║                                                                                    ║
╚════════════════════════════════════════════════════════════════════════════════════╝

¿Qué es esto?

Imagina que trabajas con un asistente de IA. Le pides tareas, te entrega resultados. Es brillante, pero tiene un defecto: cuando cierras la conversación, lo olvida todo. Al día siguiente tienes que volver a explicarle quién eres, qué proyecto llevas, qué decisiones tomaste ayer, qué intentaste y no funcionó.

Dark Memory es el cuaderno de ese asistente. Un archivo que vive en tu computadora y al que tu agente puede escribir y consultar cuando quiera, desde cualquier sesión.

¿Cómo se conecta?

Tu agente (Claude, opencode, Cursor, etc.) se comunica con Dark Memory a través del protocolo MCP (Model Context Protocol) — un estándar abierto para que las IAs usen herramientas externas. Dark Memory aparece como un conjunto de herramientas que el agente puede invocar:

Tú le hablas al agente  →  El agente usa dark_memory_*  →  Dark Memory guarda/recupera

Tú no interactúas directamente con Dark Memory. Es tu agente quien lo usa, como quien consulta un cuaderno de notas.

¿Para quién es?

Para cualquiera que use agentes de IA para trabajo serio: desarrollo de software, investigación, diseño, escritura, análisis de datos. Si tu agente hace más que conversación casual, Dark Memory le da memoria.

El problema que resuelve

Sin Dark Memory

Lunes:   "Vamos a refactorizar el módulo de autenticación."
         El agente trabaja. Tomas 5 decisiones de arquitectura.
         Cierras la sesión.

Martes:  "Continuemos con el refactor."
         El agente: "¿Qué refactor? ¿Qué módulo? ¿Quién eres?"
         Tienes que explicarle TODO otra vez. 20 minutos perdidos.

Con Dark Memory

Lunes:   "Vamos a refactorizar el módulo de autenticación."
         El agente anota en Dark Memory: proyecto, decisión #1, decisión #2, ...
         Todo queda guardado en tu disco duro.

Martes:  Abres sesión. Dark Memory le devuelve al agente:
           - Proyecto: dark-memory-mcp
           - Decisiones del lunes: 5 (la #3 dice "usar RS256 en vez de HS256")
           - Tareas pendientes: 2 ("escribir tests de integración", "actualizar docs")
         El agente: "OK, ayer decidimos RS256, terminemos los tests."
         0 minutos de re-explicación.

Dark Memory convierte a tu agente de un amnésico en un colega que recuerda.

El vibe-loop: un paradigma nuevo

El vibe-loop es una forma de trabajar con agentes que cierra el círculo entre lo que pediste y lo que entregaron. Es la práctica central que Dark Memory habilita.

El problema del agente sin supervisión

Tú:    "Crea una API que devuelva productos filtrados por categoría."
Agente: [escribe 200 líneas de código]
Tú:    "Esto devuelve productos borrados también..."
Agente: "Cierto, lo arreglo." [otras 150 líneas]
Tú:    "Ahora no tiene paginación..."
Agente: "..." [iteración sin fin]

El agente nunca sabe por sí solo si se desvió de lo pedido. Tú haces de control de calidad manual.

Cómo lo resuelve el vibe-loop

1. CREAS LA PROMESA (spec)
   "Voy a construir X, con estas tareas: T1, T2, T3."
   → dark_memory_vibe_spec

2. EL AGENTE TRABAJA
   Escribe código, investiga, diseña. Guarda hallazgos en el cuaderno.

3. ENTREGA EL ARTEFACTO (artifact)
   "Aquí está lo que hice, bajo la promesa #42."
   → dark_memory_vibe_publish

4. EL JUEZ REVISA AUTOMÁTICAMENTE (drift_judge)
   Compara lo entregado contra lo prometido:
   - "aligned"     → Cumple. Adelante. ✅
   - "drift_detected" → Se desvió. El agente ve la crítica y reintenta. 🔄
   - "needs_human" → El juez no está seguro. Te consulta a ti. 🤔

5. CIERRE
   Todo queda registrado: qué pediste, qué entregaron, qué dijo el juez.

El juez es automático. No eres tú revisando cada línea; es Dark Memory evaluando cada entrega contra la promesa original. El agente recibe retroalimentación inmediata y corrige solo, sin que tú intervengas en cada iteración.

Es como tener un revisor de código automático que nunca se cansa y nunca olvida lo que se pidió.

Conceptos clave

Estos términos aparecen en el código, las herramientas y la documentación. Tenerlos claros desde el principio ahorra fricción.

Quickstart

Necesitas Node.js 18+ (para el wrapper npm) o Go 1.25+ (para compilar desde source).

Opción A — npm wrapper (recomendado)

Agrega esto a la configuración MCP de tu agente:

{
  "mcpServers": {
    "dark-memory": {
      "command": "npx",
      "args": ["-y", "@opitacode/dark-memory-mcp"]
    }
  }
}

npx descarga el binario correcto para tu sistema operativo la primera vez. Las siguientes usan caché. No necesitas compilar nada.

• opencode: pega el bloque en opencode.jsonc → mcp.dark-memory
• Claude Code: pega en .claude.json o /Users/tu/.claude.json
• Claude Desktop: pega en claude_desktop_config.json
• Cursor: pega en .cursor/mcp.json

Detalles por host en docs/npm-install.md.

Opción B — descargar el binario

Ve a Releases, descarga el binario para tu sistema y apunta tu MCP host a la ruta absoluta.

Opción C — compilar desde source

git clone https://github.com/Opita-Code/dark-memory-mcp.git
cd dark-memory-mcp
go build -o bin/dark-mem-mcp ./cmd/dark-mem-mcp

Verificar que funciona

Una vez configurado, dile a tu agente:

"Llama a dark_memory_health_ping y dime qué responde."

Debe mostrar algo como:

{
  "server": { "version": "2.20.0", "name": "dark-memory-mcp" },
  "db": { "live": true, "schema_version": 26 },
  "registry": { "canonical_tools": 57 }
}

Primeros pasos

1. "Inicia una sesión de dark-memory. Operador: [tu nombre]. Proyecto: mi-proyecto."
   → El agente llama a dark_memory_session_start

2. "Guarda esto en el cuaderno: 'Estamos usando Postgres 16 con uuidv7 como PKs.'"
   → El agente llama a dark_memory_agent_memory_save

3. "¿Qué tenemos anotado sobre la base de datos?"
   → El agente llama a dark_memory_agent_memory_recall

4. "Cierra la sesión."
   → El agente llama a dark_memory_session_close

Las 57 herramientas

Dark Memory expone 57 herramientas (más 3 extras en modo investigación). El agente las invoca con el prefijo dark_memory_. Están agrupadas por 17 oficios:

Sesión (7 tools)

session_start · session_resume · session_heartbeat · session_status · session_close · session_recover · session_resurrect