¿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.
| Término | Qué significa |
|---|
| MCP (Model Context Protocol) | El protocolo estándar que permite a los agentes de IA usar herramientas externas. Dark Memory se conecta a tu agente vía MCP. |
| Agente | El asistente de IA con el que trabajas (Claude, opencode, Cursor, etc.). |
| Sesión | Un período de trabajo. Empiezas con session_start, terminas con session_close. |
| Spec | La promesa: "voy a hacer X con las tareas T1, T2, T3". |
| Artifact (artefacto) | Lo que el agente entrega: código, texto, imagen, lo que sea. |
| Drift (desviación) | Cuando lo entregado no cumple lo prometido. El juez lo detecta. |
| Vibe-loop | El ciclo completo: spec → trabajo → artifact → juez → (reintentar o aceptar). |
| Agent memory | El cuaderno personal del agente: notas, decisiones, observaciones, tareas pendientes. Persiste entre sesiones. |
| VLP (Vibe-Loop Protocol) | La máquina de estados que gobierna el ciclo del vibe-loop: idle → drafting_spec → spec_active → drift_judging → complete. |
| Constitución | Las reglas que el agente debe respetar. Define qué se considera "alineado" y qué no. |
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:
session_start · session_resume · session_heartbeat · session_status · session_close · session_recover · session_resurrect
Abrir, mantener viva, recuperar y cerrar sesiones de trabajo.
research_topic · research_recall · research_resume_thread
Buscar en la web y recordar investigaciones previas.
agent_bootstrap · agent_recommend_companions · agent_detect_environment
El servidor se documenta a sí mismo. El agente puede leer el manual completo sin docs externos.
vibe_spec · vibe_publish · pipeline_status · resolve_drift
Crear promesas, entregar artefactos, verificar drift, aceptar o rechazar.
Nuevo en v2.13.0: vibe_publish y vibe_spec ahora avanzan automáticamente la máquina de estados del VLP. El agente ya no necesita llamar vlp_handle_event manualmente después de cada entrega.
Contexto (4 tools)
artifact_context · spec_context · session_context · recall
Ver el estado de artefactos, specs, sesiones y cambios recientes.
agent_memory_save · agent_memory_list · agent_memory_recall · agent_memory_get · agent_memory_update · agent_memory_archive · agent_memory_delegate · agent_memory_entities · subagent_register · subagent_unregister
El cuaderno persistente. Guardar notas, decisiones, hallazgos, tareas. Buscar por texto (BM25). Delegar contexto a sub-agentes.
judge · consensus · judgment_history
Evaluar artefactos contra specs. Con rubricas G-Eval por tipo de trabajo (código, texto, imagen...). consensus(n=5) para decisiones de alto riesgo.
mindset_apply · delegate_intent
Componer system prompts para sub-agentes. Decidir si un trabajo se hace directo, se delega, o se rechaza.
active_policy · load_constitution
Consultar las reglas activas y la constitución del proyecto.
health_ping · memory_state · writes · anomalies
Monitorear salud del servidor, estado de la base de datos, auditoría de escrituras.
error_summary · error_list · error_get · error_resolve
Backlog de errores clasificados por dominio y severidad. Triage operador.
admin_migrate · admin_schema_status · admin_vacuum
Migraciones de schema, estado, limpieza de disco.
vlp_handle_event
Manejar manualmente la máquina de estados del vibe-loop (el agente normalmente no necesita llamarlo; las herramientas de vibe-loop auto-avanzan el estado desde v2.13.0).
embedder_setup_prompt
Consentimiento único para búsqueda híbrida vectorial.
Herramientas de investigación de seguridad. Solo disponibles con DARK_REDTEAM=armed.
Camino de aprendizaje
Dark Memory se aprende por capas. No necesitas entender todo para empezar.
Nivel 1 — Usar el cuaderno
El agente recuerda entre sesiones. Ideal para tu primer día.
"Guarda esto en dark-memory: 'El endpoint /api/users necesita rate limiting.'"
"¿Qué decisiones tomamos ayer sobre la base de datos?"
"Anota como tarea pendiente: escribir tests para el módulo de auth."
Herramientas que necesitas: session_start, agent_memory_save, agent_memory_recall, session_close.
Nivel 2 — Hacer vibe-loops
Verificar que lo que el agente entrega cumple lo que pediste.
"Voy a pedirte que crees una función de validación de emails.
Antes de empezar, crea un vibe_spec con las reglas: debe aceptar
emails con +, debe rechazar dominios sin TLD, debe ser O(1)."
[el agente trabaja]
"Entrega el código bajo la spec #X y pídele al juez que lo revise."
Herramientas que necesitas: las del nivel 1 + vibe_spec, vibe_publish, judge.
Nivel 3 — Delegar a sub-agentes
Para trabajos grandes, el agente principal divide y coordina.
"Este refactor involucra 4 módulos. Usa delegate_intent para decidir
si lo haces tú solo o divides el trabajo entre sub-agentes."
[el agente evalúa, decide delegar, compone mindsets, registra bindings]
"Cada sub-agente entrega su parte. Consolida y haz vibe_publish final."
Herramientas que necesitas: las del nivel 2 + delegate_intent, mindset_apply, agent_memory_delegate.
Nivel 4 — Contribuir a Dark Memory
Cuando entiendes el paradigma, puedes extenderlo. Agregar una herramienta, afinar las rúbricas de evaluación, mejorar el motor de búsqueda.
Buen primer PR: CONTRIBUTING.md tiene issues etiquetados good-first-issue. Tres sugerencias de entrada:
- Traducir errores y mensajes (i18n/l10n)
- Agregar un backend de búsqueda (Weaviate, Qdrant, pgvector)
- Escribir tests para un paquete con cobertura baja (
internal/recall/, internal/entity/)
Resolver problemas
"Mi agente no ve las herramientas de dark-memory"
- ¿El binario existe en la ruta que pusiste en la config? Verifícalo con
ls o dir.
- ¿Reiniciaste el agente después de cambiar la configuración MCP? Sin restart, no se recarga.
- En Windows, a veces el binario queda bloqueado. Cierra TODAS las terminales y vuelve a abrir.
"Dice 'session required' y no me deja hacer nada"
La mayoría de las herramientas necesitan una sesión activa. Pídele al agente:
"Inicia una sesión de dark-memory primero: operador [tu nombre], proyecto default."
"Guardé cosas pero ahora no las encuentro"
Las notas tienen alcance: por sesión, por proyecto, o por operador. Si cambiaste de proyecto sin darte cuenta, las notas están en el otro. Usa:
"Búscame en dark-memory todo lo que tengo anotado, sin filtrar por proyecto."
"Me sale un error de schema_version"
Si vienes de una versión vieja, la base de datos necesita migrar. Normalmente es automático al arrancar. Si falla:
./bin/dark-mem-cli migrate --status
./bin/dark-mem-cli migrate --apply
Arquitectura
Dark Memory corre como un proceso local. No hay servidor remoto, no hay telemetría, no hay costo.
Agente (Claude / opencode / Cursor)
│
│ MCP (JSON-RPC sobre stdin/stdout)
│
▼
dark-mem-mcp.exe ←── proceso local, 57+3 herramientas
│
│ SQL (database/sql)
│
▼
SQLite (archivo .db en tu disco) ←── o Postgres si configuras DARK_DRIVER=postgres
- Versión actual: v2.20.0
- Schema DB: v26 (error_events, vibe-loop state, agent_memory con BM25)
- Dependencias externas: ninguna en runtime. Solo Go stdlib + SQLite embebido.
- Tests: 29 suites de integración + 27 paquetes con test.
Contribuir
Dark Memory es open-source (MIT). Aceptamos contribuciones de todo nivel.
- Lee
CONTRIBUTING.md — las reglas de casa
- Busca issues con label
good-first-issue
- Toda contribución pasa por vibe-loop: spec → artifact → drift_judge → merge
Principios de diseño:
- Append-only: las migraciones de schema nunca se editan, solo se agregan
- Orden canónico: las herramientas tienen un orden fijo que no se renumera
- Best-effort: los componentes auxiliares (VLP, sweepers, telemetría) nunca bloquean la operación principal
- Sin hardcoding: una sola fuente de verdad para cada número, nombre y versión
