← Volver al listado de tecnologías ← Índice de Engram

TUI, Dashboard y CLI Avanzada

27 de abril de 2026 Por: Artiko

engramtuiclidashboardobsidianbubbletea

La interfaz terminal (TUI)

Engram incluye una interfaz de terminal interactiva construida con Bubbletea — la librería de TUI en Go de Charm — con el tema visual Catppuccin Mocha. Es la forma más cómoda de explorar, buscar y gestionar memorias sin tener que recordar sintaxis de comandos.

Para iniciarla:

engram tui

Pantallas de la TUI

La TUI tiene cuatro pantallas principales navegables con las teclas de vim:

Dashboard principal — Vista de resumen con estadísticas del proyecto actual, sesiones recientes y un gráfico de actividad. Muestra cuántas memorias has acumulado por tipo y la sesión más reciente.

Browser de observaciones — Lista completa de memorias con filtros por tipo y proyecto. Cada entrada muestra el título, tipo, fecha de creación y un extracto del contenido.

Browser de sesiones — Historial de sesiones con fecha, resumen y estado (activa/completada). Permite explorar qué se trabajó en cada sesión histórica.

Vista de detalle — Al seleccionar una observación, muestra el contenido completo en un panel con scroll.

Navegación

Tecla	Acción
`j` / `k`	Mover arriba/abajo
`Enter`	Entrar al detalle / abrir
`/`	Activar búsqueda
`Esc`	Volver atrás
`q`	Salir de la TUI
`Tab`	Cambiar entre pantallas

La búsqueda con / usa el mismo motor FTS5 que mem_search, así que admite las mismas consultas de texto completo.

Cuándo usar la TUI vs la CLI

La TUI es ideal para:

Exploración casual de memorias acumuladas
Revisar qué se trabajó en sesiones anteriores
Buscar memorias de forma interactiva cuando no recuerdas el término exacto
Auditar el contenido antes de hacer un backup o sync

La CLI es mejor para:

Scripting y automatización
Integración con otros comandos via pipe
Cuando sabes exactamente qué buscar

Referencia completa de la CLI

La CLI de Engram tiene esta estructura de comandos:

Comandos principales

engram version              # Mostrar versión instalada
engram stats                # Estadísticas de memoria del proyecto actual
engram search <query>       # Búsqueda FTS5 en la terminal
engram save <título> <msg>  # Guardar una memoria directamente
engram context [proyecto]   # Contexto reciente del proyecto
engram timeline <obs_id>    # Contexto cronológico alrededor de una observación
engram tui                  # Iniciar la interfaz terminal

Comandos de servidor

engram serve [puerto]       # Iniciar servidor HTTP (default: 7437)
engram mcp [--tools=PERFIL] # Iniciar servidor MCP stdio

Exportar e importar

engram export [archivo]              # Exportar todas las memorias a JSON
engram export --project X [archivo] # Exportar solo el proyecto X
engram import <archivo>              # Importar desde JSON
engram obsidian-export               # Exportar a Obsidian vault (beta)

Sincronización

engram sync                    # Exportar nuevas memorias como chunk
engram sync --import           # Importar chunks nuevos
engram sync --status           # Ver estado de sincronización
engram sync --cloud --project X  # Sync cloud del proyecto X

Gestión de proyectos

engram projects list           # Listar todos los proyectos con memorias
engram projects consolidate    # Consolidar nombres similares
engram projects prune          # Eliminar proyectos sin observaciones

Configuración de agentes

engram setup claude-code       # Instalar integración para Claude Code
engram setup opencode          # Instalar integración para OpenCode
engram setup gemini-cli        # Instalar integración para Gemini CLI
engram setup codex             # Instalar integración para Codex

Cloud

engram cloud status                             # Estado actual de la configuración cloud
engram cloud config --server <url>              # Configurar URL del servidor cloud
engram cloud enroll <proyecto>                  # Inscribir proyecto para cloud sync
engram cloud serve                              # Iniciar servidor cloud (requiere PostgreSQL)
engram cloud upgrade doctor --project X        # Diagnóstico de upgrade (solo lectura)
engram cloud upgrade repair --project X --dry-run  # Planear reparaciones
engram cloud upgrade repair --project X --apply    # Aplicar reparaciones
engram cloud upgrade bootstrap --project X     # Bootstrap inicial reanudable
engram cloud upgrade status --project X        # Estado del upgrade
engram cloud upgrade rollback --project X      # Revertir a snapshot pre-upgrade

Engram como servicio systemd

Para que el servidor HTTP de Engram esté siempre disponible (útil si tienes integraciones programáticas o scripts que lo consultan), puedes configurarlo como servicio systemd en Linux:

Crea /etc/systemd/system/engram.service:

[Unit]
Description=Engram Memory Server
After=network.target

[Service]
Type=simple
User=tu-usuario
ExecStart=/usr/local/bin/engram serve
Restart=on-failure
RestartSec=5s
Environment=ENGRAM_DATA_DIR=/home/tu-usuario/.engram
Environment=ENGRAM_PORT=7437

[Install]
WantedBy=multi-user.target

Activar y habilitar:

sudo systemctl daemon-reload
sudo systemctl enable engram
sudo systemctl start engram
sudo systemctl status engram

Con el servicio corriendo, el servidor HTTP está disponible permanentemente en http://localhost:7437 y los agentes MCP pueden conectarse via engram mcp sin necesidad de que el servidor HTTP esté explícitamente iniciado (el MCP usa stdio, no HTTP).

Exportación a Obsidian (beta)

Engram tiene integración experimental con Obsidian, el gestor de knowledge graph basado en Markdown:

engram obsidian-export

Por defecto, exporta las memorias al directorio configurado de Obsidian. Cada observación se convierte en una nota Markdown con frontmatter y links entre notas relacionadas (basados en proyecto y tipo).

La exportación a Obsidian está en beta, lo que significa que el formato puede cambiar entre versiones. Es útil para:

Revisar memorias en un contexto visual de knowledge graph
Compartir conocimiento con miembros del equipo que no usan Engram directamente
Crear documentación del proyecto a partir de las memorias acumuladas

Operaciones de mantenimiento

Limpiar sesiones antiguas

Las sesiones se acumulan con el tiempo. Para limpiar sesiones huérfanas (sin observaciones) o muy antiguas:

engram projects prune  # elimina proyectos sin observaciones

Para una limpieza más quirúrgica, usa la API HTTP:

# Ver sesiones recientes
curl "http://localhost:7437/sessions/recent?limit=50"

# Eliminar una sesión específica (si no tiene observaciones)
curl -X DELETE "http://localhost:7437/sessions/session-id-aqui"

Consolidar proyectos fragmentados

Si el mismo proyecto tiene memorias bajo varios nombres (por ejemplo, mi-proyecto, mi-proyecto-main, Mi Proyecto):

# Ver todos los proyectos
engram projects list

# Consolidar automáticamente (busca nombres similares)
engram projects consolidate

# O consolidar manualmente via API
curl -X POST "http://localhost:7437/projects/migrate" \
  -H "Content-Type: application/json" \
  -d '{"old_project": "mi-proyecto-main", "new_project": "mi-proyecto"}'

Backup antes de actualizaciones

Antes de actualizar Engram a una versión mayor, haz un backup:

engram export engram-backup-$(date +%Y%m%d-%H%M).json

Si algo sale mal después de la actualización, puedes restaurar:

engram import engram-backup-20260427-1030.json

Configuración avanzada de perfiles MCP

El servidor MCP de Engram soporta perfiles de herramientas para exposición selectiva:

# Todas las herramientas (17)
engram mcp

# Perfil agente (12 herramientas, omite admin)
engram mcp --tools=agent

# Ver qué herramientas están disponibles en un perfil
engram mcp --list-tools

Usa el perfil agent para agentes de producción. Reserva el perfil completo para scripts de administración.

El plugin de Claude Code: detalles internos

Si instalaste Engram via el plugin de Claude Code, la integración incluye estos componentes:

Hooks de sesión:

session-start — llama mem_current_project y mem_context al inicio
session-stop — llama mem_session_summary y mem_session_end al cerrar
post-compaction — recupera contexto de Engram después de que Claude Code compacta el contexto
subagent-stop — maneja el fin de sub-agentes en modo multi-agente

Skill “memory”: El plugin instala un skill en ~/.claude/skills/memory/SKILL.md que Claude puede invocar con /memory para ver instrucciones explícitas sobre cuándo y cómo usar Engram.

Permisos en settings.json: El setup agrega automáticamente las herramientas de Engram al allowlist de permisos para que Claude Code no pida confirmación cada vez que guarda o busca una memoria:

{
  "permissions": {
    "allow": [
      "mcp__engram__mem_save",
      "mcp__engram__mem_search",
      "mcp__engram__mem_context",
      "mcp__engram__mem_session_start",
      "mcp__engram__mem_session_end",
      "mcp__engram__mem_session_summary",
      "mcp__engram__mem_current_project"
    ]
  }
}

Si en algún momento las herramientas dejan de funcionar después de una actualización, ejecuta engram setup claude-code de nuevo para regenerar y reparar la configuración.

Resumen: el ecosistema completo de Engram

graph TD
    AG[Agentes de IA<br/>Claude Code / OpenCode / Gemini / ...] -->|MCP stdio| MCP[engram mcp]
    MCP --> DB[(SQLite + FTS5<br/>~/.engram/engram.db)]
    CLI[engram CLI] --> DB
    TUI[engram tui] --> DB
    HTTP[engram serve<br/>:7437] --> DB
    DB -->|sync| GIT[.engram/ chunks<br/>Git Sync]
    DB -->|replicación| CLOUD[Cloud Server<br/>PostgreSQL + Dashboard]
    DB -->|export| JSON[JSON backup]
    DB -->|export| OBS[Obsidian vault]

Engram es un sistema completo que crece con tu proyecto. Cada sesión añade conocimiento. Cada búsqueda recupera contexto. Cada sync protege el trabajo. Y todo desde un único binario sin dependencias.

La inversión para instalarlo es de 5 minutos. El retorno es acumulativo: cada semana que trabajas con tu agente, el conocimiento que Engram preserva hace que las siguientes sesiones sean más efectivas.

Con esto completamos el tutorial de Engram. Los próximos pasos naturales son:

Instalar Engram y configurar tu agente principal (capítulo 2 y 3)
Trabajar normalmente y dejar que el protocolo de memoria haga su trabajo (capítulo 4)
Después de unas semanas, explorar la TUI para ver el conocimiento acumulado (este capítulo)