Engram — Memoria persistente para agentes IA

⚠️ Verificar versiones antes de usar — la versión de Engram documentada aquí puede estar desactualizada. Consultar brew info gentleman-programming/tap/engram o el repositorio oficial para la versión más reciente. Ver politicas-core.

Engram es un sistema de memoria persistente para agentes de IA. Funciona como un binario Go único con SQLite + FTS5, expuesto vía servidor MCP (Model Context Protocol) — el mecanismo por el que Claude Code se conecta a herramientas externas. Permite que Claude (u otro agente) recuerde decisiones, bugs, convenciones y descubrimientos entre sesiones.

Referencia oficial: https://github.com/Gentleman-Programming/engram

Estado en Wiedii

Engram está instalado globalmente en el equipo del desarrollador vía Homebrew. El plugin de Claude Code ya viene vendorizado como dependencia de wiedii-dev (ver claude-wiedii-plugin y plugins-empresariales-distribucion-configuracion) — se auto-instala al hacer /plugin install wiedii-dev@claude-wiedii-plugins, sin pasos adicionales. Lo único que cada dev instala manualmente es el binario, por Homebrew. El tap es de terceros, así que Homebrew 6.0+ exige confiarlo explícitamente antes de instalar (ver gestion-herramientas-brew-mise):

brew tap gentleman-programming/tap
brew trust --formula gentleman-programming/tap/engram
brew install engram

Si usas Engram fuera del ecosistema de plugins de Wiedii (sin wiedii-dev instalado), el método genérico upstream es claude plugin marketplace add Gentleman-Programming/engram seguido de claude plugin install engram — normalmente no aplica dentro de Wiedii.

No se reinstala por proyecto. La instalación global es suficiente para que las herramientas MCP (mem_save, mem_search, mem_context, etc.) estén disponibles en cualquier sesión de trabajo.

Cómo funciona el aislamiento por proyecto

Engram no usa archivos de configuración por proyecto para el aislamiento. El aislamiento se logra mediante el parámetro project en cada herramienta MCP. La herramienta mem_current_project detecta automáticamente el nombre del proyecto desde el directorio de trabajo (basado en el nombre del repositorio git).

~/Docker/wietoo          → proyecto: "wietoo"
~/Docker/wiedii-configs  → proyecto: "wiedii-configs"
~/Docker/wiedii-dev-onboarding → proyecto: "wiedii-dev-onboarding"

No se necesita ningún archivo de configuración adicional en cada repo para que funcione el aislamiento.

Estándar Wiedii: CLAUDE.md

Cada repositorio Wiedii debe incluir un bloque ## Memoria (Engram) en su CLAUDE.md. Este bloque instruye al agente sobre cuándo y cómo usar Engram, y es crítico para sobrevivir compactaciones de contexto.

Bloque estándar a incluir en todos los CLAUDE.md de Wiedii:

## Memoria (Engram)

Engram provee memoria persistente entre sesiones de IA. Está instalado globalmente como plugin de Claude Code. El proyecto se detecta automáticamente desde el directorio de trabajo.

- Guarda proactivamente decisiones, bugs corregidos, convenciones y descubrimientos — no esperes a que te lo pidan.
- Después de cualquier compactación o reinicio de contexto, llama `mem_context` para recuperar el estado de la sesión antes de continuar.
- Al terminar la sesión, llama `mem_session_summary` con: Goal, Discoveries, Accomplished, Next Steps, Relevant Files.

Este bloque ya está incluido en _scaffold-onboarding/CLAUDE.md y debe replicarse en cada nuevo repo.

Qué guardar (tipos de observación)

Tipo	Cuándo usarlo
bug	Bug corregido, incluir causa raíz
decision	Decisión de arquitectura o tecnología
architecture	Estructura de sistemas, patrones
convention	Convención de nomenclatura, estilo, flujo
discovery	Hallazgo no obvio, gotcha, edge case
policy	Política de equipo o restricción operacional

Herramientas MCP principales

Herramienta	Cuándo usarla
mem_save	Inmediatamente después de cualquier decisión, bug fix, convención o descubrimiento
mem_search	Al iniciar trabajo que pudo hacerse antes, o cuando el usuario menciona algo sin contexto
mem_context	Al inicio de sesión o después de una compactación
mem_session_summary	Obligatorio antes de terminar cualquier sesión no trivial
mem_current_project	Para verificar qué proyecto se detectó automáticamente

Git Sync (opcional — memoria compartida entre devs)

Engram puede sincronizar memorias entre máquinas usando el repositorio git del proyecto. Los chunks comprimidos se almacenan en .engram/ y se commitean como cualquier otro archivo.

# Exportar memorias nuevas como chunk comprimido
engram sync

# Commitear
git add .engram/ && git commit -m "chore: sync engram memories"

# En otra máquina: importar chunks
engram sync --import

# Ver estado de sincronización
engram sync --status

Por defecto, el .gitignore del scaffold incluye .engram/ comentado. Si el equipo quiere compartir memorias, se descomenta esa línea (para ignorarlo) o simplemente se deja sin ignorar y se commitea.

Recomendación para Wiedii: activar Git Sync en repos de larga duración donde varios devs trabajan con Claude. No necesario en repos de onboarding o experimentales.

TUI — Interfaz de terminal

Para explorar las memorias guardadas de forma visual:

engram tui

Navegación: j/k (vim), Enter para entrar, / para buscar, Esc para volver.

Exportar a Obsidian (beta)

Engram puede exportar memorias como un grafo de conocimiento en Obsidian:

engram obsidian-export

Esta función está en beta. Consultar la documentación oficial antes de usarla en producción.

Actualizar Engram

brew upgrade gentleman-programming/tap/engram

# Después de actualizar, reiniciar Claude Code para recargar el MCP subprocess
engram setup claude-code

Notas de seguridad

• La base de datos local está en ~/.engram/engram.db — no cifrada.
• Nunca guardar en Engram: tokens, contraseñas, claves privadas, o cualquier secreto. Solo contexto técnico y decisiones.
• Los chunks de Git Sync no contienen secretos si se sigue esta regla.