Engram - Memoria Persistente para Agentes IA

Engram te da memoria persistente entre sesiones. Recuerdas bugfixes, decisiones de arquitectura, patrones y descubrimientos de conversaciones previas.

⚠️ IMPORTANTE: Mecanismo de Activación

NO es automático como cron job → Requiere decisión ACTIVA del agente.

✅ Cuándo el agente LLAMA a Engram:

Momento	Herramienta	Razón
INICIO de sesión	INLINECODE0	Recuperar trabajo previo
Después de trabajo significativo

mem_save | Guardar descubrimientos | | Usuario dice "recuerda"/"recordar" | mem_search | Buscar en memoria | | Empezando trabajo similar | mem_search | Verificar si ya se hizo | | FIN de sesión | mem_session_summary | Preservar contexto | | Después de compactación de contexto | mem_context | Recuperar estado |

❌ Cuándo el agente NO llama a Engram:

• - Cada mensaje del usuario (ruido)
• Heartbeats (gasta tokens innecesariamente)
• Crons en background (no es el propósito)
• Tool calls triviales (no vale la pena guardarlo)

🤖 Decisión del Agente:

El agente evalúa el contexto y decide:

• - ¿Fue trabajo significativo? → Guardar
• ¿Aprendí algo importante? → Guardar
• ¿Cambio de configuración crítico? → Guardar
• ¿Fue trivial? → No guardar

NO esperes a que te pidan guardar → Decide proactivamente.

---

⚙️ Prerrequisitos

Este skill requiere dos binarios instalados:

Herramienta	Propósito	Repositorio
MCPorter	Cliente MCP para ejecutar herramientas	steipete/mcporter
Engram

Backend de memoria persistente | Gentleman-Programming/engram |

Instalar MCPorter

macOS / Linux (Homebrew):
CODEBLOCK0

Todas las plataformas (npm):
CODEBLOCK1

Windows (binario):

1. 1. Descargar mcporter-<version>.exe desde GitHub Releases
2. Renombrar a INLINECODE7
3. Agregar al PATH del sistema

Verificar:
CODEBLOCK2

Instalar Engram

macOS / Linux (Homebrew):
CODEBLOCK3

Todas las plataformas (binario):

1. 1. Descargar desde GitHub Releases
2. Windows: Renombrar a engram.exe y agregar al PATH
3. macOS/Linux: INLINECODE9

Verificar:

engram version

---

Setup (Conectar MCPorter con Engram)

Una vez instalados ambos binarios, registrar Engram como servidor MCP:

CODEBLOCK5

Resultado esperado:
CODEBLOCK6

Conceptos Core

• - Memoria curada por el agente: TÚ decides qué vale la pena recordar, no captura automática
• Revelación progresiva: Search → Timeline → Full observation (eficiente en tokens)
• Ciclo de vida de sesión: Contexto al inicio, guardados durante trabajo, resumen al final

---

🌐 Integración con Ecosistema OpenClaw

Ecosistema de Memoria Completo

CODEBLOCK7

Cuándo Usar Cada Sistema

Tipo de Información	Dónde Guardar	Por Qué
Info permanente del usuario	MEMORY.md	No cambia, referencia rápida
Notas del día

memory/YYYY-MM-DD.md | Contexto inmediato, raw | | Bugfix técnico | Engram | Búsqueda rápida, técnico | | Corrección del usuario | self-improving | Comportamiento futuro | | Decisión de arquitectura | Engram | Técnico, referenciable | | Preferencia de comunicación | MEMORY.md + self-improving | Ambos | | Proyecto activo | memory/YYYY-MM-DD.md | Contexto inmediato | | Patrón de código | Engram | Reutilizable |

Relación con Heartbeats

❌ NO llamar Engram desde heartbeats → Gasta tokens innecesariamente.

✅ Heartbeats son para:

• - Chequeos proactivos (emails, calendario, etc.)
• Tareas recurrentes
• Notificaciones

✅ Engram es para:

• - Memoria entre sesiones
• Contexto técnico
• Búsqueda de trabajo previo

Relación con self-improving

Pueden solaparse en tipo "learning":

• - self-improving: Preferencias de comportamiento del usuario
• Engram: Aprendizajes técnicos de código

Regla: Si es sobre cómo el usuario quiere que te comportes → self-improving. Si es técnico → Engram.

---

Cuándo Usar Cada Herramienta

Disparador	Herramienta	Propósito
Empezando trabajo en un proyecto	INLINECODE10	Cargar contexto de sesión previa
Después de arreglar un bug

mem_save | Documentar qué/por qué/dónde/aprendido |
| Tomando decisión de arquitectura | mem_save | Registrar decisión + razonamiento |
| Descubriendo un patrón o gotcha | mem_save | Capturar para referencia futura |
| Usuario dice "remember"/"recordar" | mem_search | Encontrar memorias relevantes |
| Empezando trabajo que se solapa | mem_search | Verificar si ya se hizo antes |
| Terminando una sesión | mem_session_summary | Preservar contexto de sesión |
| Después de compactación de contexto | mem_context | Recuperar estado de sesión |

---

Referencia de Herramientas (via MCPorter)

Todas las herramientas se llaman via MCPorter:

CODEBLOCK8

Parámetro default: Si no especificas project, Engram intenta detectar el directorio actual del proyecto. Si no puede, usa default.

Herramientas Core

mem_save - Guardar una observación

Requerido: title, content
Opcional: type, project, scope, INLINECODE25

CODEBLOCK9

Tipos: decision, bugfix, pattern, config, discovery, learning, INLINECODE32

Formato de contenido (recomendado):
CODEBLOCK10

mem_search - Búsqueda de texto completo

CODEBLOCK11

Retorna resultados compactos con IDs de observación para drill-down.

mem_context - Obtener contexto de sesión reciente

CODEBLOCK12

Llama esto al INICIO de una sesión para recuperar lo que pasó antes.

memsessionsummary - Guardar resumen de fin de sesión

Requerido: content, INLINECODE34

CODEBLOCK13

Formato de contenido requerido:
CODEBLOCK14

Herramientas Secundarias

mem_timeline - Contexto cronológico

CODEBLOCK15

Muestra qué pasó antes y después de una observación específica.

memgetobservation - Obtener contenido completo

CODEBLOCK16

Retorna contenido sin truncar de una observación específica.

mem_update - Actualizar observación existente

CODEBLOCK17

mem_delete - Eliminar observación

CODEBLOCK18

Por defecto es soft-delete (puede recuperarse).

memsuggesttopic_key - Obtener topic key estable

CODEBLOCK19

Úsalo para temas que evolucionan (mismo topic_key = actualiza observación existente).

memsaveprompt - Guardar prompt del usuario

CODEBLOCK20

memsessionstart / memsessionend - Ciclo de vida de sesión

CODEBLOCK21

mem_stats - Estadísticas de memoria

CODEBLOCK22

---

🔄 Protocolo de Memoria

1. Inicio de Sesión

CODEBLOCK23

2. Durante el Trabajo - Guarda Proactivamente

Guarda memorias DESPUÉS de completar trabajo significativo. NO esperes a que te lo pidan.

Guarda cuando:

• - Arreglaste un bug → INLINECODE35
• Tomaste decisión de arquitectura → type: "decision" o INLINECODE37
• Descubriste un patrón o gotcha → type: "discovery" o INLINECODE39
• Cambiaste configuración → INLINECODE40
• Aprendiste algo no obvio → INLINECODE41

NO guardes:

• - Cada tool call (ruido)
• Cambios triviales
• Información fácil de encontrar en código

3. Fin de Sesión - Resumen Obligatorio

CODEBLOCK24

4. Después de Compactación de Contexto

CODEBLOCK25

---

📊 Métricas de Uso Saludable

Rango Ideal por Sesión

Herramienta	Frecuencia Ideal	Motivo
INLINECODE42	1x (inicio sesión)	Recuperar contexto
INLINECODE43

2-5x (después trabajo significativo) | Guardar descubrimientos | | mem_search | 0-3x (cuando se necesita) | Verificar trabajo previo | | mem_session_summary | 1x (fin sesión) | Preservar contexto |

Alertas de Uso Excesivo

• - >10 memsave por sesión → Guardando demasiado ruido
• 0 memsave en 5 sesiones → Probablemente olvidando cosas importantes
• >50 observaciones en 1 semana → Considerar limpieza

Proporción Saludable de Tipos

Tipo	Proporción Ideal	Motivo
INLINECODE46	20-30%	Errores comunes
INLINECODE47

20-30% | Aprendizajes clave | | decision | 15-25% | Decisiones importantes | | pattern | 10-20% | Patrones reutilizables | | config | 10-15% | Cambios de configuración | | architecture | 5-10% | Decisiones estructurales |

---

🚫 Anti-Patrones (Qué NO Hacer)

❌ NO Guardar Todo

CODEBLOCK26

❌ NO Usar como Sistema de Logging

CODEBLOCK27

❌ NO Duplicar Información de MEMORY.md

CODEBLOCK28

❌ NO Llamar desde Heartbeats

CODEBLOCK29

❌ NO Guardar Información Sensible sin Redacción

CODEBLOCK30

---

🔧 Troubleshooting

Error: "mcporter: command not found"

Verificar instalación:

CODEBLOCK31

Solución:

Plataforma	Comando
macOS/Linux (Homebrew)	INLINECODE52
Todas (npm)

npm install -g mcporter |
| Windows (binario) | Descargar de GitHub Releases |

Error: "engram: command not found"

Verificar instalación:

CODEBLOCK32

Solución:

Plataforma	Comando
macOS/Linux (Homebrew)	INLINECODE54
Windows (binario)

Descargar de GitHub Releases |

Verificar versión:
CODEBLOCK33

Error: "No MCP servers configured" o "server 'engram' not found"

MCPorter está instalado pero Engram no está registrado.

Solución:
CODEBLOCK34

Error: "MCPorter not configured"

Verificar registro:
CODEBLOCK35

Si falla, registrar nuevamente:
CODEBLOCK36

Error: "No previous session memories found"

No es error → Es normal la primera vez que se usa.

Solución: Empezar a usar el sistema:
CODEBLOCK37

Memoria Muy Grande (>1000 observaciones)

CODEBLOCK38

Búsqueda No Encuentra Resultados

Posibles causas:

1. 1. Typo en query → Verificar ortografía
2. Muy específico → Usar términos más generales
3. No existe → Guardar la información primero
4. Filtro incorrecto → Verificar project, type, INLINECODE57

CODEBLOCK39

Error: "Content too long"

Solución: Usar comillas simples para contenido multilínea:

CODEBLOCK40

---

📝 Ejemplo: Flujo Completo de Sesión Real

Escenario: Usuario pide implementar autenticación

CODEBLOCK41

Próxima sesión: mem_context recuperará automáticamente todo este contexto.

---

🔄 Patrón de Revelación Progresiva

Recuperación de memoria eficiente en tokens:

CODEBLOCK42

No descargues todo. Profundiza cuando lo necesites.

---

🔑 Topic Keys (Temas que Evolucionan)

Para temas que evolucionan en el tiempo (decisiones de arquitectura, features de larga duración):

CODEBLOCK43

Mismo topic_key + project + scope = actualiza observación existente en lugar de crear nueva.

Familias de Topic Keys

• - architecture/* — Arquitectura, diseño, ADR-like changes
• INLINECODE63 — Fixes, regresiones, errores, panics
• INLINECODE64 — Decisiones de proyecto
• INLINECODE65 — Patrones reutilizables
• INLINECODE66 — Cambios de configuración
• INLINECODE67 — Descubrimientos
• INLINECODE68 — Aprendizajes

---

🔐 Privacidad

Envuelve contenido sensible en tags <private> - se eliminan antes de guardar:

CODEBLOCK44

---

📁 Ubicación de Datos

Plataforma	Ruta
macOS / Linux	INLINECODE70
Windows

%USERPROFILE%\.engram\engram.db |

Override: Set ENGRAM_DATA_DIR environment variable para cambiar la ubicación.

---

📖 Referencia Rápida

CODEBLOCK45

---

📚 Referencia Completa de Herramientas

Ver references/tools.md para documentación completa de las 13 herramientas MCP.

---

🚀 Sinergia Proactiva

Engram puede alimentar proactividad del agente:

Patrón de Uso

1. 1. Engram: Almacena patrones de comportamiento del usuario
2. Proactive-agent: Usa esos patrones para anticipar necesidades
3. Feedback loop: Nuevas observaciones mejoran proactividad

Ejemplo Concreto

CODEBLOCK46

---

Versión del skill: 1.0