Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Sistema de memoria persistente para agentes IA. Usa mem_save después de bugfixes, decisiones, descubrimientos, cambios de config. Usa mem_search cuando el usuario menciona "remember"/"recordar" o al empezar trabajo que se solapa con sesiones previas. Usa mem_session_summary antes de terminar sesiones para preservar contexto.
| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-06 | ✗→✓ | ▲ Improved | — | — |
| case-11 | ✗→✓ | ▲ Improved | — | — |
| case-03 | ✗→✓ | ▲ Improved | — | — |
| case-10 | ✗→✓ | ▲ Improved | — | — |
| case-22 | ✗→✓ | ▲ Improved | — | — |
Engram te da memoria persistente entre sesiones. Recuerdas bugfixes, decisiones de arquitectura, patrones y descubrimientos de conversaciones previas.
NO es automático como cron job → Requiere decisión ACTIVA del agente.
| Momento | Herramienta | Razón | |---------|-------------|-------| | INICIO de sesión | mem_context | 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 |
El agente evalúa el contexto y decide:
NO esperes a que te pidan guardar → Decide proactivamente.
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 |
macOS / Linux (Homebrew):
bashbrew tap steipete/tap brew install steipete/tap/mcporter
Todas las plataformas (npm):
bash# Sin instalación (para probar) npx mcporter --version # Instalación global npm install -g mcporter
Windows (binario):
mcporter-<version>.exe desde GitHub Releasesmcporter.exeVerificar:
bashmcporter --version
macOS / Linux (Homebrew):
bashbrew install gentleman-programming/tap/engram
Todas las plataformas (binario):
engram.exe y agregar al PATHchmod +x engram && sudo mv engram /usr/local/bin/Verificar:
bashengram version
Una vez instalados ambos binarios, registrar Engram como servidor MCP:
bash# 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┌──────────────────────────────────────┐
│ 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 │
└──────────────────────────────────────┘| 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 |
❌ NO llamar Engram desde heartbeats → Gasta tokens innecesariamente.
✅ Heartbeats son para:
✅ Engram es para:
Pueden solaparse en tipo "learning":
Regla: Si es sobre cómo el usuario quiere que te comportes → self-improving. Si es técnico → Engram.
| Disparador | Herramienta | Propósito | |------------|-------------|-----------| | Empezando trabajo en un proyecto | mem_context | 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 |
Todas las herramientas se llaman via MCPorter:
bashmcporter 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.
Requerido: title, content Opcional: type, project, scope, topic_key
bash# 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]bash# 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.
bash# 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.
Requerido: content, project
bashmcporter 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]bashmcporter call engram.mem_timeline observation_id=42 before=5 after=5
Muestra qué pasó antes y después de una observación específica.
bashmcporter call engram.mem_get_observation id=42
Retorna contenido sin truncar de una observación específica.
bashmcporter call engram.mem_update id=42 content="Contenido actualizado..." mcporter call engram.mem_update id=42 title="Nuevo título"
bashmcporter call engram.mem_delete id=42 mcporter call engram.mem_delete id=42 hard_delete=true
Por defecto es soft-delete (puede recuperarse).
bashmcporter 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).
bashmcporter call engram.mem_save_prompt content="Usuario pidió implementar OAuth" project="mi-proyecto"
bashmcporter 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"
bashmcporter call engram.mem_stats
SIEMPRE llama mem_context al inicio de una sesión para recuperar contexto previo.Guarda memorias DESPUÉS de completar trabajo significativo. NO esperes a que te lo pidan.
Guarda cuando:
type: "bugfix"type: "decision" o type: "architecture"type: "discovery" o type: "pattern"type: "config"type: "learning"NO guardes:
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.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.| Herramienta | Frecuencia Ideal | Motivo | |-------------|------------------|--------| | mem_context | 1x (inicio sesión) | Recuperar contexto | | mem_save | 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 |
| Tipo | Proporción Ideal | Motivo | |------|------------------|--------| | bugfix | 20-30% | Errores comunes | | discovery | 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 |
bash# 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...'
bash# 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...'
bash# 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
bash# 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
bash# 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]
Verificar instalación:
bash# macOS / Linux which mcporter # Windows (PowerShell) where.exe mcporter
Solución:
| Plataforma | Comando | |------------|---------| | macOS/Linux (Homebrew) | brew install steipete/tap/mcporter | | Todas (npm) | npm install -g mcporter | | Windows (binario) | Descargar de GitHub Releases |
Verificar instalación:
bash# macOS / Linux which engram # Windows (PowerShell) where.exe engram
Solución:
| Plataforma | Comando | |------------|---------| | macOS/Linux (Homebrew) | brew install gentleman-programming/tap/engram | | Windows (binario) | Descargar de GitHub Releases |
Verificar versión:
bashengram version
MCPorter está instalado pero Engram no está registrado.
Solución:
bash# Registrar Engram como servidor MCP mcporter config add engram --stdio "engram mcp" # Verificar mcporter list engram
Verificar registro:
bashmcporter list engram
Si falla, registrar nuevamente:
bashmcporter config add engram --stdio "engram mcp" # Verificar tools disponibles (deben ser 13) mcporter list engram
No es error → Es normal la primera vez que se usa.
Solución: Empezar a usar el sistema:
bashmcporter call engram.mem_save title="Primera observación" content="..." mcporter call engram.mem_session_summary project="mi-proyecto" content="..."
bash# 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
Posibles causas:
project, type, scopebash# 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
Solución: Usar comillas simples para contenido multilínea:
bash# 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'
bash# ═══════════════════════════════════════════════════════ # 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.
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 truncarNo descargues todo. Profundiza cuando lo necesites.
Para temas que evolucionan en el tiempo (decisiones de arquitectura, features de larga duración):
bash# 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.
architecture/* — Arquitectura, diseño, ADR-like changesbug/* — Fixes, regresiones, errores, panicsdecision/* — Decisiones de proyectopattern/* — Patrones reutilizablesconfig/* — Cambios de configuracióndiscovery/* — Descubrimientoslearning/* — AprendizajesEnvuelve contenido sensible en tags <private> - se eliminan antes de guardar:
API key: <private>sk-abc123</private>
→ API key: [REDACTED]| Plataforma | Ruta | |------------|------| | macOS / Linux | ~/.engram/engram.db | | Windows | %USERPROFILE%\.engram\engram.db |
Override: Set ENGRAM_DATA_DIR environment variable para cambiar la ubicación.
bash# 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
Ver references/tools.md para documentación completa de las 13 herramientas MCP.
Engram puede alimentar proactividad del agente:
bash# 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
| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-04 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-05 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-02 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-01 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-06 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-11 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-03 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-10 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-22 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-09 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-17 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-14 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-21 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-15 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-08 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-07 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-20 | pass→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-12 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-13 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-16 | fail→fail | — | — | — | — | — | — | — | — | — | — | — | — |
case-18 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
case-19 | fail→pass | — | — | — | — | — | — | — | — | — | — | — | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 20 counted toward the lift figure. The other 2 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +55 percentage points is the difference between those two pass rates over the 20 comparable cases. 1 case got worse with the skill loaded, and it is included in that figure.
The per-case answers from this run were removed by the retention sweep, so the case table below shows the verdicts without the text either arm produced. The counts above were recorded at the time and are unaffected. Answers are now kept for 180 days.
Other measured skills in the registry, with their headline benchmark lift.