Engram: memoria persistente para agentes IA — guía paso a paso (2026)

¿Qué es Engram?

Engram es un sistema de memoria persistente para agentes de coding IA. Es un binario en Go, agent-agnostic, que guarda recuerdos de tus sesiones con agentes como Claude Code, OpenCode, Codex, Gemini CLI, Cursor, Windsurf, VS Code Copilot, Kiro, Kilocode, Qwen, Antigravity y Pi.

En lugar de que cada sesión con tu agente empiece desde cero, Engram permite que el agente guarde, busque y recupere contexto de trabajo anterior. La memoria se almacena en SQLite + FTS5 localmente, con un MCP server integrado, HTTP API, CLI y TUI.

¿Por qué necesitas memoria persistente?

Cuando usas un agente de coding, cada sesión nueva es como trabajar con un colega que se olvida todo lo que hiciste ayer. Tienes que re-explicar:

• La arquitectura del proyecto
• Decisiones técnicas importantes
• Por qué rechazaste cierto approach
• Convenciones del equipo
• Bugfixes y gotchas recientes

Engram soluciona esto guardando observaciones estructuradas (memorias) que el agente puede buscar automáticamente en sesiones futuras. Cada observación incluye:

• What: ¿Qué pasó?
• Why: ¿Por qué importa?
• Where: ¿En qué archivos o partes del proyecto?
• Learned: ¿Qué aprendimos?

Requisitos

• macOS, Linux o Windows
• No necesitas Node.js, Python ni Docker
• Un agente de IA compatible con MCP (Claude Code, OpenCode, Codex, Gemini CLI, Cursor, Windsurf, etc.)

Paso 1: Instalar Engram

macOS (Homebrew)

brew install gentleman-programming/tap/engram

Linux / Windows / Otros métodos

Ver la guía completa de instalación en el repo:

# Clonar y build desde source (Go requerido)
git clone https://github.com/Gentleman-Programming/engram.git
cd engram
go build -o engram ./cmd/engram
sudo mv engram /usr/local/bin/

O descargar el binario desde Releases.

Verificar instalación

engram version

Paso 2: Configurar Engram para tu agente

Engram incluye comandos de setup específicos para cada agente. El setup escribe los archivos de configuración MCP y plugins necesarios. Después, reinicia tu agente y listo.

Setup para Claude Code

engram setup claude

Esto configura el MCP server para Claude Code. Reinicia Claude Code y Engram estará disponible automáticamente como proceso stdio.

Setup para OpenCode

engram setup opencode

OpenCode requiere engram serve corriendo en segundo plano porque el plugin usa la HTTP API. El setup lo anota y el plugin intenta auto-startear el server.

Setup para otros agentes

engram setup codex        # OpenAI Codex CLI
engram setup gemini-cli   # Google Gemini CLI
engram setup cursor       # Cursor IDE
engram setup windsurf     # Windsurf IDE
engram setup vscode-copilot  # VS Code Copilot
engram setup kiro         # Kiro
engram setup kilocode     # Kilocode
engram setup qwen         # Qwen CLI
engram setup antigravity-cli # Antigravity CLI
engram setup pi           # Pi (Gentleman Programming agent)

Setup manual

engram setup

Para configuración avanzada o agentes custom, revisa docs/AGENT-SETUP.md.

Paso 3: Entender si necesitas engram serve

No siempre necesitas correr un server manualmente.

Agentes stdio-only (no requieren serve)

La mayoría de agentes lanzan engram mcp automáticamente como subprocess stdio cuando inician:

• Claude Code
• Gemini CLI
• Codex
• VS Code Copilot
• Cursor
• Windsurf

Para estos, no necesitas correr engram serve.

Agentes que sí requieren engram serve

Solo cuando un plugin usa la HTTP API para tracking de sesiones:

• OpenCode plugin
• Pi extension

Si el plugin no puede auto-startear el server, corre manualmente:

engram serve
# Puerto por defecto: 7437

Paso 4: Cómo funciona el flujo de memoria

El flujo básico con Engram es:

1. El agente completa trabajo significativo (bugfix, decisión de arquitectura, refactor)
2. El agente llama mem_save con título, tipo y campos What/Why/Where/Learned
3. Engram persiste en SQLite con índice FTS5 para búsqueda full-text
4. En la próxima sesión el agente busca memorias relevantes y recupera el contexto

Paso 5: Usar las 20 herramientas MCP

Engram expone 20 tools MCP que tu agente puede usar:

Tool	Qué hace
mem_save	Guardar una observación/memoria
mem_update	Actualizar una memoria existente
mem_delete	Eliminar una memoria
mem_suggest_topic_key	Sugerir clave de tópico
mem_search	Buscar memorias con FTS5
mem_context	Obtener contexto relevante para el proyecto
mem_timeline	Ver timeline de una observación
mem_get_observation	Leer una observación específica
mem_session_start	Iniciar tracking de sesión
mem_session_end	Finalizar tracking de sesión
mem_session_summary	Resumir sesión
mem_judge	Juzgar relación entre memorias
mem_compare	Comparar observaciones
mem_review	Revisar memorias
mem_save_prompt	Guardar prompts reutilizables
mem_stats	Estadísticas de memoria
mem_capture_passive	Captura pasiva de contexto
mem_merge_projects	Mergear proyectos
mem_current_project	Ver proyecto actual
mem_doctor	Diagnosticar estado de Engram

Paso 6: Guardar memorias manualmente con la CLI

Incluso si tu agente no guarda automáticamente, tú puedes guardar observaciones desde la terminal:

Guardar una observación

engram save "Usar Clean Architecture" \
  "Separar el proyecto en entities, use cases y adapters." \
  --type architecture \
  --project mi-proyecto

Buscar memorias

engram search "clean architecture"

Ver contexto del proyecto

engram context mi-proyecto

Ver estadísticas

engram stats

Ver timeline de una observación

engram timeline <obs_id>

Eliminar una observación

engram delete <obs_id>

Paso 7: Explorar memorias con la Terminal UI

Engram incluye una interfaz de terminal con tema Catppuccin Mocha:

engram tui

Controles:

• j/k: navegar arriba/abajo
• Enter: entrar a detalle
• c: copiar contenido al clipboard (OSC 52)
• /: buscar
• Esc: volver atrás

Paso 8: Sincronizar memorias entre máquinas con Git

Engram usa chunks comprimidos para compartir memorias sin conflictos de merge ni archivos enormes. La base de datos SQLite local sigue siendo la fuente de verdad.

Exportar nuevas memorias

engram sync

Commit del chunk

git add .engram/
git commit -m "sync engram memories"

En otra máquina: importar chunks

engram sync --import

Ver estado de sync

engram sync --status

Paso 9: Integración con Pi (Gentleman Programming)

Engram tiene un paquete first-class para Pi llamado gentle-engram:

engram setup pi

Esto le da a Pi memoria persistente de proyecto, recuperación por compaction y memoria compartida con otros agents MCP a través del mismo brain local (o cloud) de Engram.

Paso 10: Cloud Integration (opt-in)

La integración cloud es opt-in replication. Tu base de datos local sigue siendo la fuente de verdad. El cloud solo replica.

Variables de entorno cloud

ENGRAM_CLOUD_TOKEN=tu-token
ENGRAM_CLOUD_SERVER=https://tu-servidor-cloud
ENGRAM_CLOUD_AUTOSYNC=1  # Autosync activado

Comandos cloud

engram cloud enroll mi-proyecto
engram cloud status
engram sync --cloud --project mi-proyecto

Guía completa de cloud → docs/engram-cloud/quickstart.md

Paso 11: Diagnosticar problemas

engram doctor

Este comando revisa el estado de Engram y reporta problemas comunes.

Variables de entorno importantes

Variable	Default	Descripción
ENGRAM_DATA_DIR	~/.engram	Directorio de datos de Engram
ENGRAM_PORT	7437	Puerto de engram serve
ENGRAM_URL	http://127.0.0.1:<ENGRAM_PORT>	URL del server
ENGRAM_HTTP_TOKEN	—	Token para Authorization: Bearer
ENGRAM_TIMEZONE	America/New_York	Zona horaria
ENGRAM_BIN	—	Ruta al binario de engram

Flujo de trabajo recomendado

1. Al iniciar un proyecto: corre engram setup [tu-agente]
2. Durante la sesión: deja que el agente use mem_save para decisiones importantes
3. Al finalizar: opcionalmente corre engram sync y commitea .engram/
4. En la próxima sesión: el agente automáticamente recupera contexto relevante
5. Cada semana: revisa engram tui para limpiar memorias obsoletas

Engram vs otros sistemas de memoria

Aspecto	Engram	Memoria nativa del agente	Notion/Obsidian manual
Automático	Sí (agente guarda via MCP)	Limitado	No
Local-first	Sí (SQLite)	Depende	No (cloud)
Multi-agent	Sí	No	Manual
Git sync	Sí (chunks comprimidos)	No	Posible
Búsqueda	FTS5 integrado	Variable	FTS de cada app
Agent-agnostic	Sí	No	No

Consejos prácticos

• No guardes todo: guarda decisiones, arquitectura, patrones, bugfixes y gotchas. El código ya está en git
• Usa tópicos consistentes: --type architecture, --type decision, --type bugfix
• Commitea .engram/ regularmente: así tu equipo comparte memoria contextual
• Combina con CLAUDE.md: Claude Code lee CLAUDE.md + Engram para contexto completo
• Revisa conflictos: en beta hay features para detectar memorias que se contradicen

Conclusión

Engram es la pieza que faltaba en el ecosistema de agentes de coding: una memoria persistente, local-first y agent-agnostic. Con un binario en Go, SQLite + FTS5, MCP server y CLI/TUI, es trivial de instalar y usar.

Si pasas horas re-explicando contexto a Claude Code, Cursor o Codex, Engram te devuelve ese tiempo. La memoria del proyecto deja de vivir en prompts temporales y pasa a ser un activo estructurado, versionable y compartible.