dark-memory-mcp

╔════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                    ║
║         ██████╗  ██████╗██████╗ ███╗   ███╗      ███╗   ███╗ ██████╗██████╗        ║
║        ██╔═══██╗██╔════╝██╔══██╗████╗ ████║      ████╗ ████║██╔════╝██╔══██╗       ║
║        ██║   ██║██║     ██║  ██║██╔████╔██║      ██╔████╔██║██║     ██████╔╝       ║
║        ██║   ██║██║     ██║  ██║██║╚██╔╝██║      ██║╚██╔╝██║██║     ██╔═══╝        ║
║        ▚██████╔╝╚██████╗██████╔╝██║ ╚═╝ ██║      ██║ ╚═╝ ██║╚██████╗██║            ║
║         ╚═════╝  ╚═════╝╚═════╝ ╚═╝     ╚═╝      ╚═╝     ╚═╝ ╚═════╝╚═╝            ║
║                                                                                    ║
║                     MEMORIA PERSISTENTE PARA AGENTES DE IA                         ║
║                                                                                    ║
╚════════════════════════════════════════════════════════════════════════════════════╝

El problema que resuelve

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: proyecto, decisión #1, decisión #2...
         Todo queda en tu disco.

Martes:  Abres sesión. El agente recibe:
           - Proyecto: dark-memory-mcp
           - Decisiones del lunes: 5 (la #3: "RS256, no HS256")
           - Pendientes: 2
         "OK, ayer elegimos RS256, terminemos los tests."
         0 minutos de re-explicación.

Tú no interactúas con Dark Memory. Lo usa tu agente (Claude, opencode, Cursor) por MCP, como quien consulta un cuaderno de notas.

El vibe-loop

Cierra el círculo entre lo que pediste y lo que entregaron.

Sin supervisión:
  Tú:    "Crea una API que devuelva productos filtrados por categoría."
  Agente: [200 líneas]
  Tú:    "También devuelve los borrados..."
  Agente: "Cierto." [150 líneas más]
  Tú:    "No tiene paginación."
  Agente: "..."  ← iteración sin fin

Con vibe-loop:
  1. CREAS LA PROMESA (spec)      → dark_memory_vibe_spec
  2. EL AGENTE TRABAJA
  3. ENTREGA EL ARTEFACTO         → dark_memory_vibe_publish
  4. EL JUEZ COMPARA entrega vs promesa:
        "aligned"        → cumple, adelante        ✅
        "drift_detected" → se desvió, reintenta    🔄
        "needs_human"    → no está seguro, te pregunta 🤔
  5. CIERRE — queda registrado qué pediste, qué entregaron, qué dijo el juez

No eres tú revisando cada línea. Es el juez evaluando cada entrega contra la promesa original, y el agente corrige solo.

Quickstart

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

// Agrega esto a la config MCP de tu agente
{
  "mcpServers": {
    "dark-memory": {
      "command": "npx",
      "args": ["-y", "@opitacode/dark-memory-mcp"]
    }
  }
}

npx descarga el binario de tu sistema la primera vez. No compilas nada.

Verificar que funciona

> "Llama a dark_memory_health_ping y dime qué responde."

{
  "server": { "version": "4.0.0-alpha.32", "name": "dark-memory-mcp" },
  "db": { "live": true, "schema_version": 32 },
  "registry": { "canonical_tools": 78 }
}

78 es el registro medido en vivo. server.version es el stamp de build (tag publicado o pseudo-versión local); la forma que importa es la de arriba: vivo + schema + conteo.

server.version refleja el stamp de build: si compilaste sin -ldflags verás dev en vez de una versión. Eso no es un error.

Primeros pasos

1. "Inicia sesión en dark-memory. Operador: [tu nombre]. Proyecto: mi-proyecto."
2. "Guarda: 'Estamos usando Postgres 16 con uuidv7 como PKs.'"
3. "¿Qué tenemos anotado sobre la base de datos?"
4. "Cierra la sesión."

Desde source: go build -o bin/dark-mem-mcp ./cmd/dark-mem-mcp Más detalle por host: docs/npm-install.md.

Elige tu nivel

Nivel 1 — el cuaderno. El agente recuerda entre sesiones. Para el primer día. session_start, agent_memory_save, agent_memory_recall, session_close.

Nivel 2 — los vibe-loops. Verifica que lo entregado cumple lo pedido. vibe_spec para prometer, vibe_publish para entregar, pipeline_status para el veredicto, resolve_drift para aceptar o rechazar.

Nivel 3 — delegar. Para trabajos grandes: delegate_intent decide si se hace directo o entre sub-agentes, mindset_apply compone sus prompts.

Nivel 4 — extender. Agregar herramientas, afinar rúbricas, mejorar búsqueda. Empieza por CONTRIBUTING.md → good first issues.

Conceptos que verás en el código

Catálogo completo: docs/tools.md.

Si algo falla

Lo que todavía no hace

Honesto, porque un README que sólo vende no sirve para decidir:

• Pre-release. 78 herramientas canónicas medidas en el registro (+3 extras armadas por variable de entorno = 81). La superficie crece por release y la fija el freeze test — el delta desde alpha.31 es +5 (vibe_compile + namespace OAUTH con 4). Detalle por namespace en docs/v4-status.md §1.
• Phase 21 en 2 de 9 primitivas. El motor de vibe-loop es una biblioteca verificada con el cableado empezado, no un producto terminado. Las 7 primitivas restantes cambian comportamiento y necesitan instrument → measure → decide → flip.
• Postgres sin probar en anger. 58 métodos devuelven notImpl (0 en SQLite). El path de producción es SQLite.
• Sin consumidores externos todavía. Lo usa el autor a diario desde 2026-10-08.

Todo esto medido, con fecha y origen, en docs/v4-status.md. internal/tools/v4_status_consistency_test.go falla el build si ese documento se contradice con el código que corre, así que no puede pudrirse en silencio.

Cómo funciona por dentro

Tu agente (Claude / opencode / Cursor)
    │  MCP (JSON-RPC sobre stdin/stdout)
    ▼
dark-mem-mcp.exe  ←── proceso local, 78+3 herramientas
    │  SQL
    ▼
SQLite (archivo .db en tu disco)   ←── o Postgres con DARK_DRIVER=postgres

• Schema DB: 32, entero en schema_migrations.version. 66 tablas en la instancia viva, contando sombras de FTS5.
• Dependencias externas: ninguna en runtime. Go stdlib + SQLite embebido.
• Tests: el número autoritativo es el de CI, no el de este README. Un número copiado en un README es exactamente lo que este proyecto dejó de hacer.

Contribuir

MIT. Aceptamos contribuciones de todo nivel.

1. CONTRIBUTING.md — las reglas de casa
2. §10 Keeping published claims honest — la regla que este proyecto aprendió por las malas
3. Toda contribución pasa por vibe-loop: spec → artifact → drift_judge → merge

Principios de diseño:

• Append-only: las migraciones nunca se editan, solo se agregan
• Orden canónico: las herramientas tienen un orden fijo que no se renumera
• Best-effort: VLP, sweepers y telemetría nunca bloquean la operación principal
• Sin hardcoding: una sola fuente de verdad para cada número, nombre y versión