engram

What this skill does

# 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** | `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 |

### ❌ 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](https://github.com/steipete/mcporter) |
| **Engram** | Backend de memoria persistente | [Gentleman-Programming/engram](https://github.com/Gentleman-Programming/engram) |

### Instalar MCPorter

**macOS / Linux (Homebrew):**
```bash
brew 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):**
1. Descargar `mcporter-<version>.exe` desde [GitHub Releases](https://github.com/steipete/mcporter/releases)
2. Renombrar a `mcporter.exe`
3. Agregar al PATH del sistema

**Verificar:**
```bash
mcporter --version
```

### Instalar Engram

**macOS / Linux (Homebrew):**
```bash
brew install gentleman-programming/tap/engram
```

**Todas las plataformas (binario):**
1. Descargar desde [GitHub Releases](https://github.com/Gentleman-Programming/engram/releases)
2. **Windows**: Renombrar a `engram.exe` y agregar al PATH
3. **macOS/Linux**: `chmod +x engram && sudo mv engram /usr/local/bin/`

**Verificar:**
```bash
engram version
```

---

## Setup (Conectar MCPorter con Engram)

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
```

## 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

| 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 | `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 |

---

## Referencia de Herramientas (via MCPorter)

Todas las herramientas se llaman via MCPorter:

```bash
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`

```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 descubi