dark-memory-mcp

╔════════════════════════════════════════════════════════════════════════════════════╗

║ ║ ║ ██████╗ ██████╗██████╗ ███╗ ███╗ ███╗ ███╗ ██████╗██████╗ ║ ║ ██╔═══██╗██╔════╝██╔══██╗████╗ ████║ ████╗ ████║██╔════╝██╔══██╗ ║ ║ ██║ ██║██║ ██║ ██║██╔████╔██║ ██╔████╔██║██║ ██████╔╝ ║ ║ ██║ ██║██║ ██║ ██║██║╚██╔╝██║ ██║╚██╔╝██║██║ ██╔═══╝ ║ ║ ▚██████╔╝╚██████╗██████╔╝██║ ╚═╝ ██║ ██║ ╚═╝ ██║╚██████╗██║ ║ ║ ╚═════╝ ╚═════╝╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝╚═╝ ║ ║ ║ ║ 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.33 — pre-release. 78 herramientas canónicas, schema 32,

MIT. Lo que funciona y lo que no está medido en

[`docs/v4-status.md`](docs/v4-status.md) — léelo antes de apostar

producción por esto. (Corte alpha.33: endpoint por credencial, juez LLM

operativo y clave en el keyring del SO; 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"] } } }

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.33", "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."

1. "Guarda: 'Estamos usando Postgres 16 con uuidv7 como PKs.'"
2. "¿Qué tenemos anotado sobre la base de datos?"
3. "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`](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`](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`](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

---

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."*

opitacode.com · github.com/Opita-Code · dark-research-mcp