memory-mcp

Memoria persistente, buscable y versionada para agentes de IA — respaldada por Valkey (compatible con Redis), expuesta como un servidor MCP a través de HTTP.

Funciona con cualquier agente compatible con MCP: Claude Code, Cursor, VS Code y otros.

Qué hace

• Almacena entradas de memoria con nombre, etiquetas, tipos y ámbitos de proyecto

• Búsqueda por intersección de etiquetas, filtrado por tipo/proyecto y búsqueda por subcadena

• Seguimiento de aciertos (las entradas accedidas con más frecuencia suben a la parte superior)

• Historial completo de versiones con reversión

• Punto final de métricas de Prometheus

• Autenticación opcional mediante token bearer

Inicio rápido

cp .env.example .env
# Optional: set MEMORY_MCP_AUTH_TOKEN in .env (see Auth section)
docker compose up -d

Esto descarga la imagen precompilada de GHCR. El servidor MCP ya está disponible en http://127.0.0.1:3106/mcp.

Para compilar localmente en su lugar:

docker compose build
docker compose up -d

Uso de un Redis o Valkey existente

Por defecto, docker compose up -d inicia un contenedor de Valkey incluido. Para conectarse a una instancia existente de Redis o Valkey, configure VALKEY_URL e inicie solo el servicio memory-mcp:

# .env
VALKEY_URL=redis://your-host:6379

docker compose up -d memory-mcp

Cualquier servidor compatible con Redis (Redis 6+, Valkey, KeyDB, Upstash a través de rediss://, etc.) funciona. El servidor utiliza solo estructuras de datos básicas: hashes, listas y conjuntos.

Configuración del agente

Copie AGENTS.md de este repositorio en la raíz de su proyecto. Indica a su agente cómo utilizar las herramientas de memoria, qué almacenar y cuándo.

Luego, registre el servidor MCP con su cliente de agente:

Claude Code

# Without auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp

# With auth
claude mcp add memory --transport http http://127.0.0.1:3106/mcp \
  --header "Authorization: Bearer your-token"

O añádalo manualmente a ~/.claude.json:

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Cursor

Añada a ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto):

{
  "mcpServers": {
    "memory": {
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

VS Code (GitHub Copilot, extensión MCP)

Añada a .vscode/mcp.json en su proyecto:

{
  "servers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:3106/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

Omita la línea headers / Authorization en cualquier configuración si no está utilizando autenticación.

Configuración

Copie .env.example a .env y edítelo según sea necesario.

Autenticación

Por defecto, el servidor se ejecuta sin autenticación. Esto es seguro cuando se vincula a loopback (127.0.0.1) y se accede solo desde la máquina local.

Para habilitar la autenticación:

# Generate a token
openssl rand -hex 32

# Add to .env
MEMORY_MCP_AUTH_TOKEN=your-generated-token

docker compose up -d

Todas las solicitudes a POST /mcp deben incluir entonces:

Authorization: Bearer <token>

GET /health y GET /metrics siempre están sin autenticación.

Herramientas disponibles

Tipos de memoria

pattern, decision, reference, feedback, incident, project, entity, state

Puntos finales

Modelo de datos

Cada entrada se almacena como un hash de Redis en mem:<id>:

El historial de versiones se almacena en una lista de Redis en memver:<id> (de la más nueva a la más antigua, limitada a MAX_VERSIONS_PER_ENTRY).

Los índices de etiquetas, tipos y proyectos son conjuntos de Redis (tag:<nombre>, type:<nombre>, project:<nombre>).

Licencia

MIT