Engram: memoria persistente para tus agentes de IA | Blog

Cada vez que abres una sesión nueva con Claude Code, Cursor o cualquier otro agente de IA, empiezas de cero. La decisión de arquitectura que tomaste ayer, el bug que tardaste dos horas en cazar, la convención de nombres que acordaste con tu equipo: todo desaparece al cerrar la terminal. El agente es brillante, pero tiene amnesia.

Engram resuelve exactamente ese problema: le da a tus agentes una memoria persistente que sobrevive entre sesiones, entre proyectos e incluso entre máquinas. En esta guía vemos qué es, cómo funciona por dentro y cómo instalarlo en local y en tu propia nube, paso a paso.

Qué es Engram

Engram es un proyecto open source (licencia MIT) creado por Gentleman Programming, escrito en Go y con más de 5.000 estrellas en GitHub. Su propuesta cabe en una frase: “un cerebro, local o en la nube, agnóstico del agente, un solo binario, cero dependencias”.

En la práctica, Engram guarda observaciones (decisiones de arquitectura, bugs resueltos con su causa raíz, convenciones, descubrimientos) en una base SQLite (una base de datos que cabe en un solo archivo de tu máquina) con búsqueda de texto completo (FTS5). Cuando el agente arranca una sesión nueva, recupera ese contexto y sigue trabajando como si nunca se hubiera ido.

El binario incluye todo lo que necesitas: un servidor MCP (Model Context Protocol, el estándar con el que los agentes de IA se conectan a herramientas externas), un CLI para interactuar directo desde la terminal, una TUI para navegar tus memorias y una API HTTP para integraciones. La base de datos vive en ~/.engram/engram.db y es la fuente de la verdad: todo funciona sin red y sin servicios externos.

Funciona con Claude Code, OpenCode, Gemini CLI, Codex, Cursor, Windsurf, VS Code y más. El agente recibe 20 herramientas MCP (mem_save, mem_search, mem_context, mem_session_summary, entre otras) y las usa solo: guarda decisiones cuando las tomas y busca contexto cuando lo necesita.

Instalación en local

Necesitas instalar el CLI en cada máquina donde trabajes con agentes. No hay servidor que levantar ni configuración extra: el agente lanza engram mcp como subproceso cuando lo necesita.

macOS y Linux

Con Homebrew:

brew install gentleman-programming/tap/engram

Para actualizar más adelante:

brew update && brew upgrade engram

Windows

Tienes dos opciones. La primera es descargar el binario precompilado engram_<version>_windows_amd64.zip desde la página de releases, extraer engram.exe en una carpeta como C:\Users\tu-usuario\bin\ y agregarla al PATH:

[Environment]::SetEnvironmentVariable(
  "Path",
  "$env:USERPROFILE\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"),
  "User"
)

La segunda, si tienes Go 1.24 o superior:

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

El binario queda en %USERPROFILE%\go\bin\; asegúrate de que esa carpeta esté en tu PATH. En ambos casos, abre una terminal nueva para que el cambio de PATH tenga efecto.

Verifica la instalación

engram --version
engram doctor

engram doctor es un diagnóstico de solo lectura que revisa que todo esté en orden. Si ambos comandos responden, ya estás listo.

Conecta Engram a tu agente

Para Claude Code, Engram se instala como plugin oficial:

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

Para el resto de agentes, un solo comando escribe la configuración MCP necesaria:

engram setup cursor           # Cursor
engram setup opencode         # OpenCode
engram setup gemini-cli       # Gemini CLI
engram setup codex            # Codex
engram setup windsurf         # Windsurf
engram setup vscode-copilot   # VS Code (Copilot)

Después del setup, reinicia el agente y listo. A partir de ahí, la memoria trabaja sola: el agente guarda y recupera contexto sin que tengas que pedirlo.

Algunos comandos útiles para explorar tu memoria desde la terminal:

engram tui                    # interfaz visual en la terminal
engram search "auth"          # busca en todas tus memorias
engram context mi-proyecto    # contexto reciente de un proyecto
engram stats                  # estadísticas de tu memoria

Engram Cloud: la misma memoria en todas tus máquinas

Hasta aquí, tu memoria vive en una sola máquina. Engram Cloud es la capa opcional de replicación: un servidor que tú mismo hospedas y contra el que cada máquina sincroniza sus memorias por proyecto.

Hay tres ideas clave que debes entender antes de desplegarlo:

El SQLite local sigue siendo la fuente de la verdad. La nube replica, no migra. Si borras el servidor, no pierdes nada: cada máquina conserva su copia completa.
La sincronización es siempre por proyecto. No existe un --all: está bloqueado a propósito para que nada se suba por accidente.
Tres puertas independientes deben pasar antes de que un proyecto sincronice: el enrolamiento local, el token de autenticación y la allowlist del servidor.

Este diseño de triple validación hace que sea prácticamente imposible filtrar memoria de un proyecto que no decidiste compartir de forma explícita.

La arquitectura en el servidor

El despliegue de referencia usa un VPS con Dokploy (que incluye Traefik como reverse proxy con TLS automático), el contenedor oficial de Engram y una base PostgreSQL interna:

Antes de empezar necesitas: un VPS con Dokploy funcionando, un dominio propio y un registro DNS tipo A apuntando engram.tudominio.com a la IP del servidor.

Importante: el repositorio incluye un docker-compose.cloud.yml en la raíz que es solo para desarrollo: desactiva la autenticación y usa una contraseña fija. Nunca lo despliegues en un servidor público. Usa el compose de esta guía.

Genera los secretos

Necesitas cinco secretos distintos. Usa openssl rand -hex y no otro generador: la contraseña de Postgres va incrustada en una URL de conexión, y caracteres como @, : o / la rompen. La salida hexadecimal es segura por definición.

openssl rand -hex 24   # POSTGRES_PASSWORD
openssl rand -hex 32   # ENGRAM_CLOUD_TOKEN
openssl rand -hex 32   # ENGRAM_CLOUD_ADMIN
openssl rand -hex 32   # ENGRAM_JWT_SECRET
openssl rand -hex 32   # ENGRAM_CLOUD_TOKEN_PEPPER

El Docker Compose

En Dokploy, crea un proyecto, dentro un servicio de tipo Compose con proveedor “Raw”, y pega esto:

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: engram
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: engram_cloud
    volumes:
      - engram-cloud-pg:/var/lib/postgresql/data
    networks:
      - default
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U engram -d engram_cloud"]
      interval: 10s
      timeout: 5s
      retries: 10

  cloud:
    image: ghcr.io/gentleman-programming/engram:latest
    command: cloud serve
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    env_file: .env
    expose:
      - "18080"
    networks:
      - default
      - dokploy-network

volumes:
  engram-cloud-pg:

networks:
  dokploy-network:
    external: true

Tres líneas de este archivo son críticas y quitarlas reproduce fallos reales:

env_file: .env en el servicio cloud: Dokploy no inyecta las variables de entorno en el contenedor automáticamente; sin esta línea, la app arranca sin configuración y muere con cloud auth token is required.
dokploy-network en cloud: es la red externa por la que Traefik enruta; sin ella, el dominio devuelve 404 para siempre.
default en cloud: es la red interna del compose donde resuelve el hostname postgres; sin ella, la app no llega a la base de datos y entra en crash loop.

Fíjate también que postgres queda solo en la red interna (nunca expuesto a Traefik) y que se usa expose en vez de ports: nada se publica en el host, Traefik es el único punto de entrada.

Las variables de entorno

En la pestaña Environment del servicio, con tus valores generados:

POSTGRES_PASSWORD=<hex-24>
ENGRAM_DATABASE_URL=postgres://engram:<mismo-hex-24>@postgres:5432/engram_cloud
ENGRAM_CLOUD_TOKEN=<hex-32>
ENGRAM_CLOUD_ADMIN=<hex-32>
ENGRAM_JWT_SECRET=<hex-32>
ENGRAM_CLOUD_TOKEN_PEPPER=<hex-32>
ENGRAM_CLOUD_ALLOWED_PROJECTS=proyecto-a,proyecto-b
ENGRAM_CLOUD_HOST=0.0.0.0
ENGRAM_PORT=18080

Dos reglas: POSTGRES_PASSWORD aparece dos veces (sola y dentro de la URL) y ambas deben ser idénticas; y ENGRAM_CLOUD_ALLOWED_PROJECTS es la allowlist de proyectos que pueden sincronizar: cada vez que agregues un proyecto nuevo, edita la lista y redespliega.

Dominio y verificación

En la pestaña Domains del servicio: host engram.tudominio.com, servicio cloud, puerto 18080, HTTPS con Let’s Encrypt. Despliega y verifica:

curl -s https://engram.tudominio.com/health

Debe responder 200. Ten en cuenta que la raíz / devuelve 404 page not found y eso es normal: Engram Cloud es un servidor de API sin ruta raíz. No pierdas tiempo depurando el 404: usa siempre /health.

Configura cada máquina cliente

Tres pasos por máquina. Primero, apunta el CLI a tu servidor:

engram cloud config --server https://engram.tudominio.com

Segundo, define el token (el valor de ENGRAM_CLOUD_TOKEN del servidor). En Windows:

setx ENGRAM_CLOUD_TOKEN "<token>"
$env:ENGRAM_CLOUD_TOKEN = "<token>"

En macOS o Linux:

echo 'export ENGRAM_CLOUD_TOKEN="<token>"' >> ~/.zshrc
source ~/.zshrc

Ojo con un detalle en Windows: setx solo afecta a terminales nuevas, y las herramientas que ya estaban corriendo (incluido tu agente) conservan el entorno viejo hasta que las reinicies.

Tercero, enrola el proyecto y haz la primera sincronización:

engram cloud enroll proyecto-a
engram sync --cloud --project proyecto-a

El flujo de trabajo diario

Un solo comando cubre todo, porque la sincronización es bidireccional: en una sola ejecución sube tus mutaciones locales y baja las remotas.

# antes de empezar: baja lo que otras máquinas subieron
engram sync --cloud --project proyecto-a

# trabaja normal: el agente guarda todo en tu SQLite local, sin red

# al terminar: publica tu sesión para el resto de tus máquinas
engram sync --cloud --project proyecto-a

Si olvidas sincronizar, no pierdes nada: tus cambios existen en local y se replican en la siguiente sincronización. Para revisar el estado sin tocar nada:

engram cloud status
engram sync --cloud --status --project proyecto-a

Suma a otro miembro del equipo

Todo lo anterior funciona igual de bien para un equipo: Engram Cloud no distingue entre “tu otra máquina” y “la máquina de un compañero”. Mismo servidor, mismo proyecto, memoria compartida. El onboarding tiene una parte en el servidor y otra en la máquina del nuevo integrante.

En el servidor (tú, una sola vez)

Verifica que el proyecto compartido esté en ENGRAM_CLOUD_ALLOWED_PROJECTS; si ya lo agregaste para tus propias máquinas, no hay nada más que hacer. Y comparte con tu compañero dos datos por un canal seguro (un gestor de contraseñas, nunca un chat en texto plano): la URL del servidor y el valor de ENGRAM_CLOUD_TOKEN.

En la máquina del nuevo integrante

Los cuatro pasos, en orden:

# 1. Instala el CLI (brew en macOS/Linux; binario o go install en Windows)
brew install gentleman-programming/tap/engram

# 2. Conecta su agente (Claude Code como ejemplo)
claude plugin marketplace add Gentleman-Programming/engram
claude plugin install engram

# 3. Apunta el CLI al servidor del equipo
engram cloud config --server https://engram.tudominio.com

# 4. Enrola el proyecto y haz la primera sincronización
engram cloud enroll proyecto-a
engram sync --cloud --project proyecto-a

Entre el paso 3 y el 4, el token va como variable de entorno. En Windows:

setx ENGRAM_CLOUD_TOKEN "<token-del-equipo>"
$env:ENGRAM_CLOUD_TOKEN = "<token-del-equipo>"

En macOS o Linux:

echo 'export ENGRAM_CLOUD_TOKEN="<token-del-equipo>"' >> ~/.zshrc
source ~/.zshrc

Esa primera sincronización descarga el historial completo del proyecto: tu compañero arranca con toda la memoria acumulada del equipo (decisiones, bugs resueltos, convenciones) desde el primer minuto. A partir de ahí, su flujo diario es el mismo que el tuyo: sincronizar al empezar y al terminar.

Tres detalles que importan en equipo:

El nombre del proyecto debe coincidir exactamente en todas las máquinas. La sincronización es por nombre de proyecto: si tú usas proyecto-a y tu compañero enrola proyectoA, cada uno alimenta una memoria distinta y nunca se fusionan.
El token compartido da acceso de lectura y escritura a todos los proyectos de la allowlist. Compártelo solo con el equipo, y si alguien se va, rótalo: genera uno nuevo con openssl rand -hex 32, actualiza la variable en el servidor, redespliega y avisa al resto.
Existen cuentas y tokens gestionados por usuario (vía engram cloud bootstrap admin y el dashboard) para un control más fino de quién accede a qué proyecto. Para un equipo pequeño, el token compartido es el camino simple y suficiente.

Errores comunes y su solución

blocked_unenrolled: el proyecto no está enrolado en esa máquina. Es la puerta local: agregarlo a la allowlist del servidor no ayuda. Ejecuta engram cloud enroll <proyecto>.
401 unauthorized: missing authorization header: el token no está en el shell que ejecuta la sincronización. Abre una terminal nueva o define la variable en la sesión actual.
Crash loop con cannot parse "postgres://...": la contraseña de Postgres tiene caracteres no válidos para una URL. Genera una nueva con openssl rand -hex 24 y actualízala tanto en la base como en las variables.
El dominio devuelve 404 en todas las rutas: revisa que el contenedor no esté en crash loop y que el servicio cloud esté conectado a dokploy-network.
404 solo en la raíz /: no es un error, la API no tiene ruta raíz. Verifica con /health.

Cierra el círculo

Con esto tienes memoria persistente en local en menos de cinco minutos, y si trabajas desde varias máquinas, tu propia nube de sincronización sin depender de ningún servicio de terceros: tus memorias, tu servidor, tus reglas.

Para profundizar, el punto de partida es el repositorio oficial: github.com/Gentleman-Programming/engram. Ahí encontrarás la documentación de instalación, la guía de Engram Cloud y las releases con los binarios para cada plataforma.

Y si lo pruebas, cuéntanos en la comunidad cómo te fue: ver cómo otros builders estructuran la memoria de sus agentes es de las mejores formas de mejorar la tuya.

Sigue al creador de Engram

Engram existe gracias a Alan Buscaglia, más conocido como Gentleman Programming, y a toda la comunidad open source que colabora en el repositorio con código, issues y feedback. Esta guía solo documenta ese trabajo: todo el mérito de la herramienta es de ellos.

Si Engram te resulta útil, la mejor manera de agradecerlo es darle una estrella al repositorio y seguir su contenido, donde comparte arquitectura, buenas prácticas y desarrollo con IA de forma clara y sin humo:

YouTube: youtube.com/@gentlemanprogramming
LinkedIn: linkedin.com/in/alanbuscaglia