Memoria Persistente con Engram (MCP)

Engram

Los asistentes de IA (como Claude Code, Gemini CLI o Codex) son herramientas increiblemente potentes para el desarrollo y el aprendizaje, pero sufren de “amnesia”: cada vez que abres una nueva sesion, empiezan desde cero y olvidan las decisiones de arquitectura, los bugfixes y los aprendizajes previos.

Engram es un servidor basado en el Model Context Protocol (MCP) que resuelve este problema. A diferencia de otras soluciones, Engram es un unico binario en Go sin dependencias externas (no necesita Node.js, Python ni Docker). Almacena las memorias en una base de datos SQLite con busqueda de texto completo (FTS5) y expone su funcionalidad a traves de CLI, una API HTTP, un servidor MCP y una interfaz de terminal (TUI). Le da a tu IA un “cerebro” persistente compatible con Claude Code, OpenCode, Gemini CLI, Codex, VS Code Copilot, Cursor, Windsurf y cualquier otro agente que soporte MCP.

Requisitos Previos

1. Un cliente de IA compatible con MCP (ej. Claude Code, Gemini CLI, Cursor, Codex, etc.).
2. Sin dependencias de runtime. Engram es un unico binario; no necesitas Node.js, Python ni Docker.
3. Go 1.24+ unicamente si vas a compilarlo desde el codigo fuente.

El almacenamiento por defecto es una base de datos SQLite en ~/.engram/engram.db.

Instalacion

Nix (flake) — recomendada

Si usas Nix, la forma mas comoda es a traves del flake engram-nix, que empaqueta Engram y se auto-actualiza a diario (un GitHub Action corre nix-update y bumpea a la ultima release sola). No tienes que tocar versiones ni hashes a mano.

Probarlo sin instalar nada:

nix run github:yfloress/engram-nix -- --version

Instalarlo en tu perfil:

nix profile install github:yfloress/engram-nix

O agregarlo como input a tu propio flake (ej. tus dotfiles):

{
  inputs.engram-nix.url = "github:yfloress/engram-nix";

  outputs = { self, nixpkgs, engram-nix }: {
    # agregalo donde lo necesites, ej.:
    #   engram-nix.packages.${system}.default
  };
}

Para actualizar: tu nix flake update + rebuild de siempre.

macOS / Linux (Homebrew)

La forma mas sencilla en macOS (y Linux con Homebrew):

brew install gentleman-programming/tap/engram

# Para actualizar mas adelante
brew update && brew upgrade engram

Desde el codigo fuente (cualquier plataforma)

Requiere Go 1.24+:

git clone https://github.com/Gentleman-Programming/engram.git
cd engram
go install ./cmd/engram

Con sello de version (opcional):

go install -ldflags="-X main.version=local-$(git describe --tags --always)" ./cmd/engram

Windows

Opcion A - Go Install:

go install github.com/Gentleman-Programming/engram/cmd/engram@latest

Opcion B - Compilar desde el codigo fuente:

git clone https://github.com/Gentleman-Programming/engram.git
cd engram
go install ./cmd/engram

Opcion C - Binario precompilado: descarga el .zip correspondiente desde las Releases de GitHub y extrae el ejecutable en una carpeta que este en tu PATH.

En Windows asegurate de que engram.exe quede dentro del PATH del sistema.

Binarios precompilados (todas las plataformas)

Descargables desde las Releases de GitHub:

Conectando tu Cliente de IA

El principio es siempre el mismo: indicarle al cliente que ejecute el servidor MCP de Engram. El subcomando que arranca el servidor MCP (transporte stdio) es:

engram mcp [--tools=PROFILE] [--project NOMBRE]

En todas las configuraciones se usa "engram" como nombre del servidor. La deteccion de proyecto se hace con el flag --project=nombre o la variable de entorno ENGRAM_PROJECT.

Para Claude Code (CLI)

La forma recomendada es a traves del marketplace de plugins:

claude plugin marketplace add Gentleman-Programming/engram
claude plugin install engram

Alternativa via el propio Engram:

engram setup claude-code

O bien, configuracion MCP manual anadiendo el bloque a ~/.claude/settings.json (global) o al .claude/settings.json del proyecto:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Para Gemini CLI

Setup automatico recomendado (configura el MCP, escribe el Memory Protocol en ~/.gemini/system.md y se asegura de que cargue):

engram setup gemini-cli

Configuracion manual en ~/.gemini/settings.json (Windows: %APPDATA%\gemini\settings.json):

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Para OpenCode

Setup completo recomendado (instala el plugin, registra el MCP con --tools=agent y agrega indicadores de estado):

engram setup opencode

Configuracion manual (solo MCP) en opencode.json:

{
  "mcp": {
    "engram": {
      "type": "local",
      "command": ["engram", "mcp"],
      "enabled": true
    }
  }
}

Para Codex

Setup recomendado (configura el MCP y escribe el Memory Protocol en ~/.codex/engram-instructions.md):

engram setup codex

Configuracion manual en ~/.codex/config.toml:

model_instructions_file = "~/.codex/engram-instructions.md"
experimental_compact_prompt_file = "~/.codex/engram-compact-prompt.md"

[mcp_servers.engram]
command = "engram"
args = ["mcp"]

Para Cursor

Anade a .cursor/mcp.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Memory Protocol: crea .cursor/rules/engram.mdc con el contenido del protocolo (soporta formato .mdc desde la version 0.43+).

Para Windsurf

Anade a ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Memory Protocol: agrega las instrucciones al archivo .windsurfrules.

Para VS Code (Copilot / extension de Claude Code)

Configuracion de workspace recomendada en .vscode/mcp.json:

{
  "servers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

One-liner por CLI:

code --add-mcp "{\"name\":\"engram\",\"command\":\"engram\",\"args\":[\"mcp\"]}"

En entornos VS Code, WSL o CI conviene fijar el proyecto explicitamente con "args": ["mcp", "--project=mi-proyecto"].

Memory Protocol (recuperacion tras compactacion)

Para que la memoria sobreviva a un reset de contexto o a una compactacion, anade a las instrucciones del sistema de tu agente algo como:

“Tienes acceso a la memoria persistente de Engram via herramientas MCP. Guarda proactivamente despues de trabajo significativo. Tras cualquier compactacion o reset de contexto, llama a mem_context para recuperar el estado de la sesion antes de continuar.”

Los comandos engram setup ... escriben este protocolo automaticamente para cada agente.

Uso Basico (CLI)

Engram tambien funciona como herramienta de linea de comandos independiente:

# Buscar memorias
engram search <consulta>

# Guardar una memoria
engram save <titulo> <mensaje>

# Lanzar el dashboard TUI
engram tui

# Levantar la API HTTP (puerto 7437 por defecto)
engram serve [puerto]

# Exportar / importar memorias
engram export [archivo]
engram import <archivo>

# Sincronizacion con Git
engram sync
engram sync --import

# Ver estadisticas
engram stats

# Diagnostico
engram doctor

Sincronizar memorias entre maquinas (engram sync)

engram sync te permite compartir tu memoria entre varias maquinas (o con tu equipo) versionandola junto a tu codigo en git. Funciona exportando las memorias nuevas como chunks comprimidos dentro de una carpeta .engram/ en tu proyecto: cada sync crea un chunk nuevo (nunca modifica los viejos) y actualiza un manifest.json pequeno y sin conflictos de merge. La base local .engram/engram.db queda gitignoreada.

Maquina A (exportar y publicar):

engram sync                    # exporta lo nuevo a .engram/chunks/
git add .engram                # commitea manifest + chunks
git commit -m "engram: sync"
git push

Maquina B (traer las memorias):

git pull
engram sync --import           # importa los chunks que aun no tenes (idempotente)

En los syncs siguientes repetis el mismo flujo: engram sync solo agrega lo nuevo.

engram sync --status           # compara chunks locales vs remotos
engram sync --project NAME     # exporta solo un proyecto
engram sync --all              # exporta todos los proyectos

Alternativa: engram sync --cloud --project NOMBRE usa replicacion via servidor cloud (opcional) en vez de git. Ver la seccion Cloud.

Variables de Entorno

Cloud (opcional)

La SQLite local sigue siendo la fuente de verdad; el cloud es solo replicacion opt-in.

docker compose -f docker-compose.cloud.yml up -d
engram cloud config --server http://127.0.0.1:18080
engram cloud enroll smoke-project
engram sync --cloud --project smoke-project

Documentacion adicional

• Guia completa de instalacion
• Configuracion por agente
• Referencia completa (DOCS.md)