dark-memory-mcp

<div align="center">

```
╔════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                    ║
║   ██████╗  ██████╗██████╗ ███╗   ███╗      ███╗   ███╗ ██████╗██████╗              ║
║  ██╔═══██╗██╔════╝██╔══██╗████╗ ████║      ████╗ ████║██╔════╝██╔══██╗             ║
║  ██║   ██║██║     ██║  ██║██╔████╔██║      ██╔████╔██║██║     ██████╔╝             ║
║  ██║   ██║██║     ██║  ██║██║╚██╔╝██║      ██║╚██╔╝██║██║     ██╔═══╝              ║
║  ╚██████╔╝╚██████╗██████╔╝██║ ╚═╝ ██║      ██║ ╚═╝ ██║╚██████╗██║                  ║
║   ╚═════╝  ╚═════╝╚═════╝ ╚═╝     ╚═╝      ╚═╝     ╚═╝ ╚═════╝╚═╝                  ║
║                                                                                    ║
║                              OPITA CODE DARK MEMORY MCP                            ║
║                                                                                    ║
║        Persistent Memory • Vibe-Loop Engine • Agent Governance • MCP               ║
║                                                                                    ║
╚════════════════════════════════════════════════════════════════════════════════════╝
```

**El cuaderno persistente del agente: para que nunca pierdas el hilo de lo que estás haciendo.**

[![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Go 1.25+](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white)](go.mod)
[![MCP tools](https://img.shields.io/badge/MCP-38%20canonical%20tools-blueviolet)](#las-38-herramientas)
[![Schema](https://img.shields.io/badge/schema-v20-success)](#la-base-de-datos)
[![Tests](https://img.shields.io/badge/tests-27%20suites%20verdes-brightgreen)](#tests)
[![Install](https://img.shields.io/badge/install-npx%20%40opita--code%2Fdark--memory--mcp-cc3534)](docs/npm-install.md)
[![MCPB](https://img.shields.io/badge/MCPB%20bundle%20for%20Claude%20Desktop-cc3534)](docs/mcpb-install.md)
[![Backends](https://img.shields.io/badge/backends-sqlite%20%7C%20postgres-blue)](#la-base-de-datos)

[¿Qué es dark-memory?](#que-es-dark-memory) · [¿Qué es vibe-loop?](#que-es-vibe-loop) · [Cómo se conectan](#como-se-conectan) · [Quickstart en 5 minutos](#quickstart-en-5-minutos) · [Hacer un vibe-loop paso a paso](#hacer-un-vibe-loop-paso-a-paso) · [Cuando algo no funciona](#cuando-algo-no-funciona) · [Para los curiosos técnicos](#para-los-curiosos-tecnicos)

</div>

---

## ¿Qué es dark-memory?

Imagina que tu agente IA es un asistente brillante que trabaja contigo todos los días.
Cada día le pides algo nuevo: refactorizar una función, escribir un test, diseñar
un workflow, recordar por qué tomaste una decisión la semana pasada.

**El problema es que el agente olvida.** Cuando cierras la sesión, todo se va.
Al día siguiente le tienes que volver a explicar quién eres, qué proyecto estás
haciendo, qué decisiones tomaste, qué cosas ya intentaste.

**dark-memory es el cuaderno donde el agente anota todo lo importante.**

Cuando el agente aprende algo nuevo, lo escribe. Cuando toma una decisión, registra
por qué. Cuando descubre que algo no funcionó, lo apunta para no repetirlo.
Cuando le preguntas "¿qué decidimos la semana pasada?", lo busca.

Es un **cuaderno persistente** (no se borra al cerrar) que vive en tu propia
computadora y al que tu agente puede acceder cuando quiera, desde cualquier sesión
de trabajo.

### Tres cosas concretas que hace por ti

1. **Recuerda entre sesiones.** Anota el contexto de tu proyecto una vez;
   recuérdalo siempre. Cuando vuelvas mañana, el agente sabe quién eres,
   qué proyecto tienes, en qué punto vas, qué decisiones tomaste.

2. **Te ayuda a hacer vibe-loop.** Cuando le pides algo al agente, dark-memory
   guarda la promesa ("voy a hacer X") y luego verifica que lo que entregó
   realmente cumpla esa promesa. Si no cumple, te avisa. (Más sobre esto abajo.)

3. **Lleva un registro de auditoría.** Cada cambio que el agente hace en su
   cuaderno queda firmado con quién lo hizo, cuándo, y por qué. Si algo
   sale mal, puedes revisar qué pasó.

### ¿Qué NO es dark-memory?

- **No es una base de datos para tu aplicación.** Es un cuaderno del agente,
  no un almacén de datos de negocio. Para eso usa Postgres normal.
- **No es un modelo de IA.** No piensa, no escribe código, no toma decisiones.
  Solo guarda y recupera lo que el agente ya pensó.
- **No es un servicio en la nube.** Todo vive en tu computadora. No hay
  servidor remoto, no hay telemetría, no hay costos recurrentes.

---

## ¿Qué es vibe-loop?

Vibe-loop es una forma de trabajar con tu agente que cierra el círculo entre
**lo que le pediste** y **lo que entregó**.

El flujo normal con un agente es así:

> Tú: "Hazme una función que valide emails."
> Agente: "Aquí está." [te da código]
> Tú: [lo pruebas] "Funciona, gracias."

Pero ¿qué pasa cuando el código entregado **no cumple lo que pediste**?

> Tú: "Hazme una función que valide emails."
> Agente: "Aquí está." [te da una función que solo valida emails de gmail]
> Tú: "Pero esto no valida emails de yahoo..."
> Agente: "Tienes razón, lo arreglo." [te da otra versión]
> Tú: "Ahora tampoco maneja emails con +..."
> Agente: "..." [iteración sin fin]

El problema: **el agente nunca se da cuenta solo de que se desvió**. Tú tienes
que estar revisando cada entrega. Se pierde mucho tiempo.

**Vibe-loop cierra ese círculo:**

```
   Le dices al agente QUÉ quieres (la promesa/spec)
            ↓
   El agente entrega algo (el artefacto)
            ↓
   Un juez automático revisa: ¿lo entregado cumple lo prometido?
            ↓
   Si cumple → "OK, seguimos"
   Si NO cumple → el agente re-intenta con la crítica del juez
            ↓
   Si después de varios intentos NO cumple → te pregunta a ti
```

La promesa (spec) y la crítica del juez (drift) se quedan guardadas en
dark-memory. Mañana puedes revisar: "¿qué le pedí, qué entregó, qué dijo
el juez?"

Es como tener un manager de calidad revisando cada entrega del agente,
pero automático y persistente.

---

## ¿Cómo se conectan?

dark-memory es el **cuaderno donde el vibe-loop escribe**.

| Pieza del vibe-loop | Qué hace | Cómo lo guarda dark-memory |
|---|---|---|
| La promesa | "Voy a hacer X, Y, Z" | Lo guarda como **spec** |
| El artefacto | El código/texto/imagen que entregó el agente | Lo guarda como **artifact** |
| El juicio | "¿Cumple lo prometido? Sí/No/Parcial" | Lo guarda como **drift_log** |
| Tu decisión final | "Acepto / Rechazo" | Lo guarda como **resolve_drift** |
| El cuaderno | Tus notas, observaciones, decisiones, links | Lo guarda como **agent_memory** |

Cuando el agente está trabajando y necesita recordar algo, mira su cuaderno
(consulta `dark_memory_recall`). Cuando termina y entrega algo, escribe
en el cuaderno qué hizo y por qué. Es un loop cerrado.

---

## Quickstart en 5 minutos

### 1. Verifica que tienes lo necesario

```
- Node.js 18+ (https://nodejs.org/) — solo si vas a usar el wrapper npm
- Go 1.25+ (https://go.dev/dl/) — solo si vas a compilar desde source
```

### 2. Conéctalo a tu agente (opencode, Claude Code, Cursor, etc.)

**Opción A — vía npm wrapper (recomendado para vibe-coders, desde v2.5.0):**

Pega esto en tu config de MCP host:

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

Eso es todo. `npx` descarga el wrapper + el binario para tu OS la primera vez; las
siguientes veces usa caché. No hay build, no hay SHA-256 manual, no hay
`go install`. Funciona idéntico en macOS, Linux y Windows.

Detalles por host (Claude Code, Claude Desktop, opencode, Cursor) en
[`docs/npm-install.md`](docs/npm-install.md).

**Opción B — descarga directa del binario (legacy, aún soportado):**

Ve a [Releases](https://github.com/Opita-Code/dark-memory-mcp/releases),
descarga el `.exe` / ELF / Mach-O de tu OS, verifica el SHA-256, y apunta
tu MCP host al path absoluto:

```jsonc
{
  "mcp": {
    "dark-memory": {
      "type": "local",
      "command": ["C:/ruta/a/dark-mem-mcp.exe"],
      "enabled": true
    }
  }
}
```

(en Mac/Linux sería sin `.exe`).

### 3. Verifica que arrancó bien

Si usaste el wrapper npm, abre tu agente y pídele que llame a
`dark_memory_health_ping`. Deberías ver un JSON con
`schema_version: 20` (o superior) y `driver: sqlite`.

Si compilaste desde source:

```bash
./bin/dark-mem-inspect --json
```

### 4. Pídele a tu agente que use el cuaderno

> *"Inicia una sesión de dark-memory para mí, soy Nico y estoy trabajando
> en el proyecto darkmem."*

El agente debería llamar a `dark_memory_session_start`. Si no, recuérdale
que tiene una herramienta MCP disponible.

### ¿Quieres compilarlo tú mismo?

```bash
git clone https://github.com/Opita-Code/dark-memory-mcp.git
cd dark-memory-mcp

# Esto crea los tres binarios que necesitas
go build -o bin/dark-mem-mcp   ./cmd/dark-mem-mcp
go build -o bin/dark-mem-cli   ./cmd/dark-mem-cli
go build -o bin/dark-mem-inspect ./cmd/dark-mem-inspect
```

Útil si quieres contribuir, hacer un fork, o auditar el binario antes
de correrlo.

---

## Las 39 herramientas

dark-memory expone 39 acciones que tu agente puede invocar. Todas empiezan
con el prefijo `dark_memory_`. Están agrupadas en 13 oficios:

### 🧭 Empezar y cerrar sesión (PROJECT + SESSION — 5 tools)

| Herramienta | Cuándo se usa |
|---|---|
| `dark_memory_project_create` | Una vez: para crear un proyecto nuevo (como "crear un workspace") |
| `dark_memory_session_start` | Al comenzar a trabajar: abre tu sesión del día |
| `dark_memory_session_resume` | Si cerraste mal y quieres retomar |
| `dark_memory_session_status` | "¿En qué punto vamos?" |
| `dark_memory_session_close` | Al terminar: cierra la sesión limpio |

### 🔍 Investigar (RESEARCH — 3 tools)

| Herramienta | Cuándo se usa |
|---|---|
| `dark_memory_research_topic` | "Investiga X y dame un resumen" |
| `dark_memory_research_recall` | "¿Qué investigué antes sobre X?"