← Volver al listado de tecnologías ← Índice de Engram

Introducción a Engram

27 de abril de 2026 Por: Artiko

engrammemoriamcpiaagentes

El problema: los agentes de IA tienen amnesia

Trabajas con Claude Code durante horas. Descubres que la API de pagos tiene una limitación de reintentos de 3 segundos que causa fallos intermitentes en producción. Pasas 45 minutos debuggeando, encuentras la solución exacta, y documentas el workaround en tu código. La sesión termina.

La siguiente semana, abres una nueva sesión con Claude Code para continuar el trabajo. El agente no recuerda nada. La limitación de la API, el debugging de 45 minutos, el workaround específico — todo se fue. Empiezas de cero.

Este es el problema fundamental de todos los agentes de IA actuales: el contexto muere con la sesión. Cada conversación nueva es un lienzo en blanco. El agente no sabe qué decisiones arquitectónicas tomaste el mes pasado, no recuerda qué bugs resolviste, no conoce las convenciones específicas de tu proyecto.

La solución: memoria persistente agnóstica al agente

Engram resuelve este problema con un enfoque minimalista y pragmático. En lugar de reinventar cómo los agentes funcionan, agrega una capa de persistencia que cualquier agente compatible con MCP (Model Context Protocol) puede usar.

La arquitectura es deliberadamente simple:

Agente de IA (Claude Code / OpenCode / Gemini CLI / ...)
    ↓ MCP stdio transport
Engram (binario Go único, ~15MB)
    ↓
SQLite + FTS5 (~/.engram/engram.db)

Un binario. Una base de datos. Cero dependencias de runtime.

No necesitas Node.js, Python, Docker ni ningún servicio externo para que Engram funcione. Es un ejecutable standalone que se comporta como infraestructura silenciosa: se instala una vez y desaparece del radar.

¿Qué es exactamente Engram?

Engram es una herramienta de línea de comandos escrita en Go que expone cuatro interfaces simultáneas:

CLI directa — Puedes interactuar con tus memorias desde la terminal sin ningún agente:

engram search "api de pagos"
engram save "Bug crítico" "La API de pagos tiene retry delay de 3s"
engram stats

Servidor MCP — Expone 17 herramientas que los agentes de IA pueden llamar via stdio:

engram mcp  # servidor MCP stdio para agentes

API HTTP REST — Para integraciones programáticas en el puerto 7437:

engram serve  # inicia el servidor HTTP local

TUI interactiva — Una interfaz de terminal para explorar, buscar y gestionar memorias visualmente:

engram tui  # interfaz tipo Catppuccin Mocha con vim keys

El modelo mental correcto

Engram sigue la filosofía de que el agente decide qué vale la pena recordar, no un sistema de captura automática. Esto es una decisión de diseño deliberada: la captura automática de todo produciría ruido masivo e inutilizaría la búsqueda.

El flujo es el siguiente:

sequenceDiagram
    participant A as Agente IA
    participant E as Engram
    participant DB as SQLite + FTS5

    A->>E: Completa trabajo significativo
    A->>E: mem_save(título, tipo, contenido)
    E->>DB: Persiste con índice FTS5
    
    Note over A,DB: Fin de sesión — contexto destruido

    A->>E: Nueva sesión inicia
    A->>E: mem_context() — solicita contexto previo
    E->>DB: Recupera memorias recientes del proyecto
    DB->>A: Contexto relevante inyectado automáticamente

El agente trabaja, completa algo importante (un bugfix, una decisión de arquitectura, un patrón descubierto), y llama mem_save con un resumen estructurado. En la siguiente sesión, el agente llama mem_context y recupera ese contexto. La amnesia se rompe.

¿Por qué un binario Go con SQLite?

La elección tecnológica de Engram es intencionalmente pragmática. Algunos sistemas de memoria para agentes dependen de bases de datos vectoriales, servicios cloud, o runtimes pesados como Node.js. Engram tomó el camino opuesto:

Go compila a un binario estático sin dependencias de runtime. Una vez instalado, no hay nada que “actualizar” o “gestionar”. El binario funciona igual en macOS, Linux y Windows.

SQLite con FTS5 es una de las tecnologías más battle-tested del mundo. FTS5 (Full Text Search 5) permite búsqueda de texto completo sobre millones de memorias sin configuración adicional. WAL mode habilita lecturas concurrentes sin bloqueos.

Sin captura automática evita el problema de “demasiado ruido”. Otros sistemas intentan capturar todo el historial de conversación y terminan con bases de datos ruidosas donde encontrar información relevante es difícil. Engram confía en el agente para decidir qué importa.

Los 17 tipos de herramientas MCP

Engram expone exactamente 17 herramientas MCP organizadas en categorías funcionales:

Categoría	Herramientas
Guardar y actualizar	`mem_save`, `mem_update`, `mem_delete`, `mem_suggest_topic_key`
Buscar y recuperar	`mem_search`, `mem_context`, `mem_timeline`, `mem_get_observation`
Ciclo de sesión	`mem_session_start`, `mem_session_end`, `mem_session_summary`
Conflictos	`mem_judge`
Utilidades	`mem_save_prompt`, `mem_stats`, `mem_capture_passive`, `mem_merge_projects`, `mem_current_project`

Estas herramientas cubren todo el ciclo de vida de una memoria: desde crearla hasta buscarla, actualizarla, y gestionar la sesión en la que fue creada.

Casos de uso reales

Engram brilla en situaciones donde el contexto acumulado tiene valor duradero:

Decisiones arquitectónicas — Guardas por qué elegiste Event Sourcing para el módulo de pagos. Tres meses después, cuando un nuevo desarrollador pregunta “¿por qué no usamos CQRS simple?”, el agente puede recuperar el razonamiento completo sin que nadie tenga que buscarlo en PRs o Slack.

Bugs y workarounds específicos — La limitación del retry de 3 segundos de la API externa, el bug de la librería de PDF que aparece con caracteres especiales, la query SQL que se optimizó con un índice específico. Todos estos viven en Engram y están disponibles en futuras sesiones.

Patrones del proyecto — Convenciones de nomenclatura, patrones de testing, configuraciones de linting que el equipo acordó. El agente las conoce desde el primer mensaje de cada sesión.

Contexto entre máquinas — Con Git Sync (capítulo 6), las memorias viajan contigo entre tu laptop de trabajo y tu equipo personal.

Comparación con alternativas

Característica	Engram	claude-mem	Solución manual (CLAUDE.md)
Agnóstico al agente	✅ Cualquier MCP	❌ Solo Claude	✅ Depende del agente
Búsqueda FTS5	✅	❌ Texto plano	❌
Ciclo de sesión	✅ start/end/summary	❌	❌
Dependencias	Ninguna	Node.js	Ninguna
TUI	✅	❌	❌
Git sync	✅	❌	✅ Manual
Cloud opcional	✅	❌	❌

La ventaja más importante de Engram es que funciona con cualquier agente MCP-compatible. Si cambias de Claude Code a OpenCode mañana, tus memorias te siguen. Si usas Gemini CLI en paralelo, comparte la misma base de datos.

La filosofía de infraestructura invisible

El mantra de Engram está bien resumido en su documentación oficial:

“Engram es infraestructura. Como una buena base de datos, se configura una vez y se olvida. Si estás pensando en Engram mientras trabajas, algo salió mal. Debería ser invisible.”

Esta filosofía guía todas las decisiones de diseño: cero configuración manual de qué guardar, instalación de un solo comando, integración silenciosa con el agente, y recuperación automática del contexto al inicio de cada sesión.

En los próximos capítulos veremos cómo instalar Engram, configurarlo con cada agente popular, y entender el protocolo de memoria que hace que todo esto funcione de manera confiable.