╔════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ ██████╗██████╗ ███╗ ███╗ ███╗ ███╗ ██████╗██████╗ ║
║ ██╔═══██╗██╔════╝██╔══██╗████╗ ████║ ████╗ ████║██╔════╝██╔══██╗ ║
║ ██║ ██║██║ ██║ ██║██╔████╔██║ ██╔████╔██║██║ ██████╔╝ ║
║ ██║ ██║██║ ██║ ██║██║╚██╔╝██║ ██║╚██╔╝██║██║ ██╔═══╝ ║
║ ▚██████╔╝╚██████╗██████╔╝██║ ╚═╝ ██║ ██║ ╚═╝ ██║╚██████╗██║ ║
║ ╚═════╝ ╚═════╝╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝╚═╝ ║
║ ║
║ MEMORIA PERSISTENTE PARA AGENTES DE IA ║
║ ║
╚════════════════════════════════════════════════════════════════════════════════════╝
Dark Memory convierte a tu agente de un amnésico en un colega que recuerda.
Es un cuaderno que vive en tu disco. Tu agente escribe en él y lo consulta entre sesiones, con verificación automática de que lo que entregó cumple lo que le pediste. Sin servidor remoto, sin telemetría, sin costo.
Qué es · Quickstart · Las 78 herramientas · Vibe-cases · Ayuda · Estado real · Contribuir
STATUS: v4-alpha.32 — pre-release. 78 herramientas canónicas, schema 32, MIT. Lo que funciona y lo que no está medido en
docs/v4-status.md— léelo antes de apostar producción por esto. (Corte alpha.32: tag → HEAD, CI publica npm + registry.)
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"]
}
}
}
| Agente | Dónde pegarlo |
|---|---|
| opencode | opencode.jsonc → mcp.dark-memory |
| Claude Code | .claude.json |
| Claude Desktop | claude_desktop_config.json |
| Cursor | .cursor/mcp.json |
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
| Término | Qué es |
|---|---|
| MCP | El protocolo estándar con el que tu agente usa herramientas externas. |
| Sesión | Un tramo de trabajo. session_start … session_close. |
| Spec | La promesa: "voy a hacer X con las tareas T1, T2, T3". |
| Artifact | Lo entregado: código, texto, imagen, lo que sea. |
| Drift | Cuando lo entregado no cumple lo prometido. El juez lo detecta. |
| Vibe-loop | El ciclo: spec → trabajo → artifact → juez → reintentar o aceptar. |
| Agent memory | El cuaderno persistente del agente. Sobrevive a las sesiones. |
| Vibe-case | C1–C8. El tipo de artefacto; decide la rúbrica del juez. |
Catálogo completo: docs/tools.md.
Si algo falla
| Síntoma | Causa probable |
|---|---|
| "Mi agente no ve las herramientas" | Falta reiniciar el agente tras cambiar la config. En Windows el binario puede quedar bloqueado: cierra todas las terminales. |
| "Dice 'session required'" | Casi todas las herramientas necesitan sesión activa. Inicia una primero. |
| "Guardé cosas y no las encuentro" | Las notas tienen alcance: por sesión, proyecto u operador. Cambiaste de proyecto sin darte cuenta. |
| "Error de schema_version" | Vienes de una versión vieja; la DB necesita migrar. ./bin/dark-mem-cli migrate --apply |
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 endocs/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.
CONTRIBUTING.md— las reglas de casa- §10 Keeping published claims honest — la regla que este proyecto aprendió por las malas
- 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
Construido con ❤️ desde Neiva, Huila, Colombia por Opita Code.
"No construimos software para que se vea bonito en una presentación. Lo construimos para que trabaje contigo todos los días."