Engram

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:

❌ 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:

Instalar MCPorter

macOS / Linux (Homebrew):

brew tap steipete/tap
brew install steipete/tap/mcporter

Todas las plataformas (npm):

# Sin instalación (para probar)
npx mcporter --version

# Instalación global
npm install -g mcporter

Windows (binario):

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

Verificar:

mcporter --version

Instalar Engram

macOS / Linux (Homebrew):

brew install gentleman-programming/tap/engram

Todas las plataformas (binario):

1. Descargar desde GitHub Releases
2. Windows: Renombrar a engram.exe y agregar al PATH
3. macOS/Linux: chmod +x engram && sudo mv engram /usr/local/bin/

Verificar:

engram version

Setup (Conectar MCPorter con Engram)

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

# Registrar servidor MCP de Engram
mcporter config add engram --stdio "engram mcp"

# Verificar conexión (debe mostrar 13 herramientas)
mcporter list engram

Resultado esperado:

engram - Sistema de memoria persistente para agentes IA
  13 tools · HTTP/stdio

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

┌──────────────────────────────────────┐
│      MEMORY.md (Estático/Permanente) │
│  - Info del usuario (no cambia)      │
│  - Reglas de seguridad (permanentes) │
│  - Directrices (permanentes)         │
└──────────────────────────────────────┘
              ↓ complementa
┌──────────────────────────────────────┐
│   memory/YYYY-MM-DD.md (Diario/Raw)  │
│  - Notas del día                     │
│  - Proyectos trabajados              │
│  - Contexto inmediato                │
│  - Se archiva automáticamente        │
└──────────────────────────────────────┘
              ↓ complementa
┌──────────────────────────────────────┐
│      Engram (Memoria Técnica)        │
│  - Bugfixes                          │
│  - Decisiones de código              │
│  - Patrones descubiertos             │
│  - Configuraciones técnicas          │
│  - Búsqueda rápida                   │
└──────────────────────────────────────┘
              ↓ complementa
┌──────────────────────────────────────┐
│  self-improving (Comportamiento)     │
│  - Correcciones del usuario          │
│  - Preferencias aprendidas           │
│  - Patrones de comportamiento        │
│  - Sistema HOT/WARM/COLD             │
└──────────────────────────────────────┘

Cuándo Usar Cada Sistema

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

Referencia de Herramientas (via MCPorter)

Todas las herramientas se llaman via MCPorter:

mcporter call engram.<nombre_herramienta> [parámetros]

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, topic_key

# Ejemplo - Bugfix
mcporter call engram.mem_save \
  title="Error N+1 en lista de usuarios" \
  type="bugfix" \
  project="mi-proyecto" \
  content='**Qué**: Agregué eager loading en query UserList
**Por qué**: Degradación de rendimiento con 100+ usuarios
**Dónde**: src/services/users.ts
**Aprendido**: ORM requiere Preload() explícito para asociaciones'

# Ejemplo - Decisión de arquitectura
mcporter call engram.mem_save \
  title="Sistema de backups automatizado" \
  type="config" \
  project="mi-proyecto" \
  content='**Qué**: Cron de backups diarios configurado
**Por qué**: Evitar pérdida de datos críticos
**Dónde**: scripts/backup.sh, crontab
**Aprendido**: Verificar permisos antes de automatizar'

# Ejemplo - Patrón descubierto
mcporter call engram.mem_save \
  title="Patrón: Validar inputs en boundary" \
  type="discovery" \
  project="mi-proyecto" \
  content='**Qué**: Validar inputs en capa HTTP, no en services
**Por qué**: Evita contaminar lógica de negocio
**Dónde**: src/routes/*.ts
**Aprendido**: Early validation reduce cognitive load'

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

Formato de contenido (recomendado):

**Qué**: [descripción concisa]
**Por qué**: [razonamiento/contexto]
**Dónde**: [archivos afectados: ruta/al/archivo.ts, otro.go]
**Aprendido**: [gotchas, edge cases - opcional]

mem_search - Búsqueda de texto completo

# Búsqueda básica
mcporter call engram.mem_search query="middleware auth"

# Filtrada por proyecto
mcporter call engram.mem_search query="N+1" project="mi-proyecto"

# Filtrada por tipo
mcporter call engram.mem_search query="error" type="bugfix"

# Limitar resultados
mcporter call engram.mem_search query="JWT" limit=5

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

mem_context - Obtener contexto de sesión reciente

# Obtener contexto reciente del proyecto
mcporter call engram.mem_context project="mi-proyecto"

# Más observaciones
mcporter call engram.mem_context project="mi-proyecto" limit=30

# Scope personal
mcporter call engram.mem_context scope="personal"

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

mem_session_summary - Guardar resumen de fin de sesión

Requerido: content, project

mcporter call engram.mem_session_summary \
  project="mi-proyecto" \
  content='## Objetivo
Implementar autenticación JWT y corregir bugs de rendimiento

## Instrucciones
El usuario prefiere español para explicaciones

## Descubrimientos
- ORM requiere Preload() explícito para associations
- Validación debe ir en boundary layer
- Refresh tokens deben rotarse por seguridad

## Logrado
- ✅ JWT implementado con refresh tokens
- ✅ Query N+1 corregido (100x más rápido)
- ✅ Middlewares de autenticación agregados
- 🔲 Tests de integración pendientes
- 🔲 Documentación API pendiente

## Archivos Relevantes
- src/auth/jwt.ts — Generación y validación de tokens
- src/middleware/auth.ts — Middleware de autenticación
- src/services/users.ts — Queries optimizadas
- src/routes/*.ts — Validación de inputs en boundary'

Formato de contenido requerido:

## Objetivo
[Una frase: qué se construyó/trabajó en esta sesión]

## Instrucciones
[Preferencias de usuario descubiertas - opcional]

## Descubrimientos
- [Hallazgo técnico 1]
- [Hallazgo técnico 2]

## Logrado
- ✅ [Tarea completada 1 — con detalles clave]
- ✅ [Tarea completada 2 — mencionar archivos cambiados]
- 🔲 [Identificado pero no hecho — para próxima sesión]

## Archivos Relevantes
- ruta/al/archivo.ts — [qué hace o qué cambió]
- ruta/a/otro.go — [rol en la arquitectura]

Herramientas Secundarias

mem_timeline - Contexto cronológico

mcporter call engram.mem_timeline observation_id=42 before=5 after=5

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

mem_get_observation - Obtener contenido completo

mcporter call engram.mem_get_observation id=42

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

mem_update - Actualizar observación existente

mcporter call engram.mem_update id=42 content="Contenido actualizado..."
mcporter call engram.mem_update id=42 title="Nuevo título"

mem_delete - Eliminar observación

mcporter call engram.mem_delete id=42
mcporter call engram.mem_delete id=42 hard_delete=true

Por defecto es soft-delete (puede recuperarse).

mem_suggest_topic_key - Obtener topic key estable

mcporter call engram.mem_suggest_topic_key type="architecture" title="Auth architecture"
# Retorna: architecture/auth-architecture

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

mem_save_prompt - Guardar prompt del usuario

mcporter call engram.mem_save_prompt content="Usuario pidió implementar OAuth" project="mi-proyecto"

mem_session_start / mem_session_end - Ciclo de vida de sesión

mcporter call engram.mem_session_start id="session-123" project="mi-proyecto"
mcporter call engram.mem_session_end id="session-123" summary="Completada implementación auth"

mem_stats - Estadísticas de memoria

mcporter call engram.mem_stats

🔄 Protocolo de Memoria

1. Inicio de Sesión

SIEMPRE llama mem_context al inicio de una sesión para recuperar contexto previo.

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 → type: "bugfix"
• Tomaste decisión de arquitectura → type: "decision" o type: "architecture"
• Descubriste un patrón o gotcha → type: "discovery" o type: "pattern"
• Cambiaste configuración → type: "config"
• Aprendiste algo no obvio → type: "learning"

NO guardes:

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

3. Fin de Sesión - Resumen Obligatorio

ANTES de terminar una sesión, SIEMPRE llama mem_session_summary.
Esto NO es opcional. Si lo saltas, la próxima sesión empieza a ciegas.

4. Después de Compactación de Contexto

Si el contexto se compacta/resetea, INMEDIATAMENTE llama mem_context para recuperar estado.
Luego llama mem_session_summary con el contenido compactado antes de continuar.

📊 Métricas de Uso Saludable

Rango Ideal por Sesión

Alertas de Uso Excesivo

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

Proporción Saludable de Tipos

🚫 Anti-Patrones (Qué NO Hacer)

❌ NO Guardar Todo

# MAL: Guardar trivialidades
mcporter call engram.mem_save title="Usuario dijo hola" content="Usuario dijo hola"

# BIEN: Solo trabajo significativo
mcporter call engram.mem_save \
  title="Error N+1 corregido" \
  type="bugfix" \
  content='**Qué**: Agregué eager loading...'

❌ NO Usar como Sistema de Logging

# MAL: Guardar cada tool call
mcporter call engram.mem_save title="Llamé read tool" content="Leí archivo X"

# BIEN: Guardar descubrimientos
mcporter call engram.mem_save \
  title="Problema de seguridad encontrado" \
  type="discovery" \
  content='**Qué**: SQL injection en login...'

❌ NO Duplicar Información de MEMORY.md

# MAL: Duplicar info del usuario
mcporter call engram.mem_save title="Info del usuario" content="CEO de empresa..."

# BIEN: MEMORY.md ya tiene eso, Engram es para cosas TÉCNICAS
# Solo guardar si es contexto técnico específico de una sesión

❌ NO Llamar desde Heartbeats

# MAL: Gasta tokens innecesariamente
# En heartbeat cron:
mcporter call engram.mem_context  # ← NO

# BIEN: Solo en sesión interactiva
# Heartbeats son para chequeos proactivos, no memoria

❌ NO Guardar Información Sensible sin Redacción

# MAL: API key expuesta
mcporter call engram.mem_save title="Config API" content="Key: sk-abc123..."

# BIEN: Usar tags <private>
mcporter call engram.mem_save \
  title="Config API" \
  content='API key: <private>sk-abc123</private>'
# → API key: [REDACTED]

🔧 Troubleshooting

Error: "mcporter: command not found"

Verificar instalación:

# macOS / Linux
which mcporter

# Windows (PowerShell)
where.exe mcporter

Solución:

Error: "engram: command not found"

Verificar instalación:

# macOS / Linux
which engram

# Windows (PowerShell)
where.exe engram

Solución:

Verificar versión:

engram version

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

MCPorter está instalado pero Engram no está registrado.

Solución:

# Registrar Engram como servidor MCP
mcporter config add engram --stdio "engram mcp"

# Verificar
mcporter list engram

Error: "MCPorter not configured"

Verificar registro:

mcporter list engram

Si falla, registrar nuevamente:

mcporter config add engram --stdio "engram mcp"

# Verificar tools disponibles (deben ser 13)
mcporter list engram

Error: "No previous session memories found"

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

Solución: Empezar a usar el sistema:

mcporter call engram.mem_save title="Primera observación" content="..."
mcporter call engram.mem_session_summary project="mi-proyecto" content="..."

Memoria Muy Grande (>1000 observaciones)

# Ver estadísticas
mcporter call engram.mem_stats

# Buscar observaciones viejas
mcporter call engram.mem_search query="..." limit=20

# Limpiar observaciones específicas
mcporter call engram.mem_delete id=XX hard_delete=true

# Recomendación: Mantener <500 observaciones activas

Búsqueda No Encuentra Resultados

Posibles causas:

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, scope

# Debug: Búsqueda amplia
mcporter call engram.mem_search query="auth" limit=10

# Debug: Ver todo el proyecto
mcporter call engram.mem_context project="mi-proyecto" limit=50

Error: "Content too long"

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

# MAL (falla con newlines)
mcporter call engram.mem_save title="..." content="Línea 1
Línea 2"

# BIEN (comillas simples)
mcporter call engram.mem_save title="..." content='Línea 1
Línea 2
Línea 3'

📝 Ejemplo: Flujo Completo de Sesión Real

Escenario: Usuario pide implementar autenticación

# ═══════════════════════════════════════════════════════
# 1. INICIO DE SESIÓN - Recuperar contexto previo
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_context project="mi-proyecto"
# → Veo que ayer trabajamos en el módulo de usuarios
# → Veo que se identificó un problema de seguridad
# → Sé que falta implementar JWT

# ═══════════════════════════════════════════════════════
# 2. TRABAJO - Después de implementar JWT
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_save \
  title="JWT implementado correctamente" \
  type="config" \
  project="mi-proyecto" \
  content='**Qué**: Autenticación JWT agregada al API
**Por qué**: Sessions no escalan en múltiples instancias
**Dónde**: src/auth/jwt.ts, src/middleware/auth.ts
**Aprendido**: Refresh tokens deben rotarse'

# ═══════════════════════════════════════════════════════
# 3. TRABAJO - Después de corregir bug de N+1
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_save \
  title="Query N+1 corregido en lista de usuarios" \
  type="bugfix" \
  project="mi-proyecto" \
  content='**Qué**: Agregué eager loading en UserList
**Por qué**: Degradación de rendimiento con 100+ usuarios
**Dónde**: src/services/users.ts
**Aprendido**: ORM requiere Preload() explícito'

# ═══════════════════════════════════════════════════════
# 4. TRABAJO - Después de descubrir patrón
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_save \
  title="Patrón: Validar inputs en boundary" \
  type="pattern" \
  project="mi-proyecto" \
  content='**Qué**: Validar inputs en capa HTTP, no en services
**Por qué**: Evita contaminar lógica de negocio
**Dónde**: src/routes/*.ts
**Aprendido**: Early validation reduce cognitive load'

# ═══════════════════════════════════════════════════════
# 5. FIN DE SESIÓN - Guardar resumen completo
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_session_summary \
  project="mi-proyecto" \
  content='## Objetivo
Implementar autenticación JWT y corregir bugs de rendimiento

## Instrucciones
El usuario prefiere español para explicaciones

## Descubrimientos
- ORM requiere Preload() explícito para associations
- Validación debe ir en boundary layer
- Refresh tokens deben rotarse por seguridad

## Logrado
- ✅ JWT implementado con refresh tokens
- ✅ Query N+1 corregido (100x más rápido)
- ✅ Middlewares de autenticación agregados
- 🔲 Tests de integración pendientes
- 🔲 Documentación API pendiente

## Archivos Relevantes
- src/auth/jwt.ts — Generación y validación de tokens
- src/middleware/auth.ts — Middleware de autenticación
- src/services/users.ts — Queries optimizadas
- src/routes/*.ts — Validación de inputs en boundary'

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:

1. mem_search "auth middleware" → resultados compactos con IDs (~100 tokens c/u)
2. mem_timeline observation_id=42 → qué pasó antes/después
3. mem_get_observation id=42 → contenido completo sin truncar

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):

# Obtener topic key estable
mcporter call engram.mem_suggest_topic_key type="architecture" title="Auth architecture"
# → architecture/auth-architecture

# Guardar con topic_key (hace upsert a observación existente)
mcporter call engram.mem_save \
  title="Decisión arquitectura auth" \
  type="architecture" \
  topic_key="architecture/auth-architecture" \
  project="mi-proyecto" \
  content="..."

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
• bug/* — Fixes, regresiones, errores, panics
• decision/* — Decisiones de proyecto
• pattern/* — Patrones reutilizables
• config/* — Cambios de configuración
• discovery/* — Descubrimientos
• learning/* — Aprendizajes

🔐 Privacidad

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

API key: <private>sk-abc123</private>
→ API key: [REDACTED]

📁 Ubicación de Datos

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

📖 Referencia Rápida

# Iniciar sesión
mcporter call engram.mem_context project="mi-proyecto"

# Guardar bugfix
mcporter call engram.mem_save title="..." type="bugfix" content='...'

# Buscar
mcporter call engram.mem_search query="..."

# Terminar sesión
mcporter call engram.mem_session_summary project="mi-proyecto" content='...'

# Ver estadísticas
mcporter call engram.mem_stats

📚 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. 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

# Después de 3 sesiones donde el usuario pide lo mismo:
mcporter call engram.mem_save \
  title="Patrón: Usuario pide status al iniciar sesión" \
  type="pattern" \
  project="mi-proyecto" \
  content='**Qué**: Al iniciar sesión pregunta "qué hay pendiente"
**Por qué**: Quiere overview antes de empezar a trabajar
**Dónde**: Sesiones consecutivas
**Aprendido**: Preparar resumen automático al inicio'

# Proactive-agent puede usar esto:
# → Generar resumen de pendientes al inicio de sesión

Versión del skill: 1.0