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

Git Sync y Nube

27 de abril de 2026 Por: Artiko

engramgit-syncclouddockerpostgresqlsincronizacion

El modelo local-primero

Engram es local-first por diseño. Tu ~/.engram/engram.db es la fuente de verdad. Cualquier mecanismo de sincronización — ya sea Git Sync o la integración cloud — es replicación opcional sobre esa fuente local.

Esta arquitectura tiene ventajas importantes:

Funciona sin conexión a internet
No hay latencia de red en operaciones de lectura/escritura
El agente nunca falla por problemas de conectividad
La privacidad de las memorias queda bajo tu control

Dicho esto, hay dos escenarios comunes donde la sincronización es valiosa:

Múltiples máquinas — tu laptop de trabajo y tu equipo personal deben compartir el mismo conocimiento
Equipo de desarrolladores — compartir memorias del proyecto entre miembros del equipo

Git Sync: compartir memorias sin servicios externos

Git Sync es el mecanismo de sincronización built-in de Engram que no requiere ninguna infraestructura adicional. Usa el repositorio Git del proyecto para transportar memorias en formato comprimido.

El mecanismo funciona con chunks comprimidos. Engram serializa memorias nuevas, las comprime, y las almacena en un directorio .engram/ dentro del repositorio. Estos chunks tienen una propiedad importante: nunca causan conflictos de merge porque cada push genera un chunk con ID único.

La fuente de verdad siempre es la SQLite local. Los chunks son solo el mecanismo de transporte.

Workflow de Git Sync

En la máquina A (exportar nuevas memorias):

engram sync
# Exporta nuevas memorias como chunk comprimido en .engram/
git add .engram/
git commit -m "sync: engram memories session 2026-04-27"
git push

En la máquina B (importar los chunks nuevos):

git pull
engram sync --import
# Importa los chunks nuevos desde .engram/ a la base de datos local

Ver el estado de sincronización:

engram sync --status
# Output:
# Last sync: 2026-04-27 10:30 UTC
# Local chunks: 12
# Unimported chunks: 3
# Database: ~/.engram/engram.db (2.1 MB)

¿Qué se sincroniza?

Git Sync sincroniza las observaciones (memorias guardadas con mem_save o sus equivalentes). Los registros de sesión y los prompts capturados son locales por defecto.

La granularidad es por proyecto: cuando ejecutas engram sync, sincroniza todas las memorias del proyecto detectado en el directorio actual. Esto significa que en un monorepo con múltiples proyectos, debes ejecutar engram sync desde el directorio de cada proyecto por separado.

Privacidad de Git Sync

El directorio .engram/ puede contener información sensible sobre tu codebase (decisiones de arquitectura, bugs encontrados, rutas de archivos). Considera si quieres incluirlo en el repositorio público o solo en repositorios privados.

Si el repo es público pero quieres sincronizar memorias:

Usa .gitignore para excluir .engram/ del repo público
Crea un repo privado separado solo para las memorias
Usa la integración cloud con un servidor privado

La integración cloud: sincronización avanzada (opcional)

La integración cloud de Engram es completamente opcional. Agrega sincronización en tiempo real, un dashboard web para explorar memorias, y acceso multi-usuario. Usa PostgreSQL como backend y expone una API HTTP separada de la local.

Importante: La cloud de Engram siempre es replicación del SQLite local. Nunca reemplaza la fuente de verdad local. Operaciones de cloud bloqueadas en producción (como --all) son intencionalmente conservadoras.

Opción A: Smoke test local con Docker Compose

La forma más rápida de probar la integración cloud es con el Docker Compose incluido:

# Levantar el backend cloud localmente
docker compose -f docker-compose.cloud.yml up -d

# Configurar el cliente local para apuntar al servidor local
engram cloud config --server http://127.0.0.1:18080

# Inscribir un proyecto para cloud sync
engram cloud enroll smoke-project

# Diagnosticar antes de sincronizar
engram cloud upgrade doctor --project smoke-project

# Reparar si hay issues detectados
engram cloud upgrade repair --project smoke-project --dry-run
engram cloud upgrade repair --project smoke-project --apply

# Bootstrap inicial (enrollar + push + verificar)
engram cloud upgrade bootstrap --project smoke-project

# Sincronizar
engram sync --cloud --project smoke-project

# Ver estado
engram sync --cloud --status --project smoke-project

El Docker Compose de smoke test usa modo inseguro (ENGRAM_CLOUD_INSECURE_NO_AUTH=1) para facilitar el desarrollo local. No lo uses en producción con datos reales.

Variables de entorno del servidor cloud

Para un despliegue de producción del servidor cloud:

Variable	Requerida	Descripción
`ENGRAM_DATABASE_URL`	Sí	DSN de PostgreSQL
`ENGRAM_CLOUD_TOKEN`	Sí (modo auth)	Token de autenticación Bearer
`ENGRAM_JWT_SECRET`	Sí (modo auth)	Secreto JWT, mínimo 32 bytes, no default
`ENGRAM_CLOUD_ALLOWED_PROJECTS`	Sí	Lista CSV de proyectos permitidos
`ENGRAM_PORT`	No	Puerto (default: 8080)
`ENGRAM_CLOUD_HOST`	No	Bind host (default: 127.0.0.1, usar 0.0.0.0 en containers)
`ENGRAM_CLOUD_ADMIN`	No	Token de admin para dashboard /admin
`ENGRAM_CLOUD_INSECURE_NO_AUTH`	No	Solo para desarrollo local

Ejemplo de despliegue con autenticación:

ENGRAM_DATABASE_URL="postgres://engram:password@db:5432/engram_cloud?sslmode=disable" \
ENGRAM_JWT_SECRET="$(openssl rand -base64 32)" \
ENGRAM_CLOUD_TOKEN="tu-token-secreto-aqui" \
ENGRAM_CLOUD_ALLOWED_PROJECTS="proyecto-alpha,proyecto-beta" \
engram cloud serve

El ciclo de upgrade cloud

Si actualizas Engram mientras tienes proyectos enrollados en cloud, hay un proceso de upgrade determinístico para asegurar que el esquema local y el cloud estén sincronizados:

flowchart LR
    D[doctor --dry-run] --> R[repair --dry-run]
    R --> RA[repair --apply]
    RA --> B[bootstrap --resume]
    B --> S[sync --cloud]
    S --> ST[upgrade status]

# 1. Diagnóstico (solo lectura, sin mutaciones)
engram cloud upgrade doctor --project mi-proyecto

# 2. Planear reparaciones (sin aplicar)
engram cloud upgrade repair --project mi-proyecto --dry-run

# 3. Aplicar reparaciones
engram cloud upgrade repair --project mi-proyecto --apply

# 4. Bootstrap (enrollar + push + verificar, reanudable)
engram cloud upgrade bootstrap --project mi-proyecto --resume

# 5. Verificar estado final
engram cloud upgrade status --project mi-proyecto

Este proceso es determinístico y seguro: cada paso solo avanza si el anterior fue exitoso. Si algo falla a mitad del camino, --resume permite continuar desde donde quedó.

El dashboard web

Cuando el servidor cloud está corriendo, el dashboard está disponible en http://tu-servidor/dashboard. Incluye:

Overview — estadísticas generales de memorias y sesiones
Browser — explorador de observaciones, sesiones y prompts
Projects — vista por proyecto con sus observaciones
Contributors — vista por colaborador
Admin — gestión de proyectos y usuarios (requiere ENGRAM_CLOUD_ADMIN)

El dashboard usa HTMX para updates parciales sin recargas completas, y Go templates para el rendering server-side. En modo autenticado, accedes via /dashboard/login con tu token, que genera una cookie HTTP-only para la sesión del navegador.

Autosync: sincronización automática

Puedes configurar sincronización automática usando la variable ENGRAM_CLOUD_SYNC=1:

ENGRAM_CLOUD_SYNC=1 engram sync --status --project mi-proyecto

Para una sincronización verdaderamente automática, puedes configurar un cron job o un hook de Git:

Cron job (sync cada hora):

# crontab -e
0 * * * * cd /ruta/al/proyecto && engram sync 2>/dev/null

Git post-commit hook para Git Sync:

# .git/hooks/post-commit
#!/bin/bash
engram sync 2>/dev/null
git add .engram/ 2>/dev/null
# Si hay chunks nuevos, agrégatelos al próximo commit

Exportar e importar memorias

Independientemente del mecanismo de sync, Engram permite exportar todas las memorias a JSON e importarlas en otro sistema:

# Exportar todas las memorias
engram export backup-completo.json

# Exportar solo un proyecto específico
engram export --project mi-proyecto backup-proyecto.json

# Importar
engram import backup-completo.json

El formato JSON es autocontenido y portable. Es el mecanismo ideal para:

Migrar a una nueva máquina sin Git
Hacer backups manuales antes de actualizaciones
Compartir memorias con alguien que no tiene acceso al repo
Exportar a Obsidian (via engram obsidian-export, actualmente en beta)

Consideraciones de privacidad y seguridad

Las memorias de Engram pueden contener información sensible sobre tu codebase: decisiones de arquitectura, bugs encontrados, rutas de archivos, nombres de variables, credenciales mencionadas en bugs, etc.

Recomendaciones:

No commitees .engram/ en repos públicos sin revisar el contenido primero
Usa repos privados para Git Sync si el proyecto es privado
Configura ENGRAM_CLOUD_TOKEN en producción (nunca uses modo inseguro con datos reales)
Revisa periódicamente tus memorias con engram tui para eliminar información sensible que ya no es relevante
Soft-delete (mem_delete) vs hard-delete (mem_delete hard=true) — usa hard-delete para información verdaderamente sensible que no debe poder recuperarse

En el último capítulo del tutorial veremos la TUI interactiva, el dashboard, y los comandos avanzados de la CLI que completan el ecosistema de Engram.