Initial commit - Engram wiki docs

01-setup-maquina-nueva.md

@@ -0,0 +1,122 @@
+# Engram — Setup en máquina nueva
+
+Guía para instalar Engram en un equipo nuevo y recuperar toda la memoria del cloud.
+
+---
+
+## 1. Descargar el binario
+
+Ve a:
+```
+https://github.com/Gentleman-Programming/engram/releases/latest
+```
+
+Descarga `engram_1.15.2_windows_amd64.zip` y extrae `engram.exe` en:
+```
+C:\Users\TuUsuario\bin\
+```
+
+---
+
+## 2. Añadir al PATH
+
+Abre PowerShell y ejecuta (solo una vez):
+
+```powershell
+[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
+```
+
+Cierra y abre PowerShell de nuevo. Verifica:
+
+```powershell
+engram version
+```
+
+---
+
+## 3. Apuntar al servidor cloud
+
+```powershell
+engram cloud config --server https://engram.v-encore-lab.com
+```
+
+---
+
+## 4. Enrollar el proyecto
+
+```powershell
+engram cloud enroll planificacion_proyectos
+```
+
+---
+
+## 5. Descargar memorias del cloud
+
+```powershell
+engram sync --cloud --project planificacion_proyectos --import
+```
+
+Esto descarga toda la memoria almacenada en el VPS a la máquina nueva.
+
+---
+
+## 6. Configurar OpenCode
+
+```powershell
+engram setup opencode
+```
+
+---
+
+## 7. Arrancar el servidor HTTP
+
+```powershell
+engram serve
+```
+
+Déjalo corriendo en una terminal aparte.
+
+---
+
+## 8. Arranque automático con Windows
+
+1. Pulsa `Win + R` y escribe:
+```
+shell:startup
+```
+
+2. Crea un archivo `engram.bat` con este contenido:
+```bat
+@echo off
+start /min engram serve
+```
+
+A partir de ahora `engram serve` arranca solo cada vez que inicias Windows.
+
+---
+
+## 9. Verificar que todo funciona
+
+Abre OpenCode en tu proyecto y escribe:
+```
+mem_context
+```
+
+Si responde con información de sesión, todo está funcionando correctamente.
+
+---
+
+## Sync manual en cualquier momento
+
+```powershell
+cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN_AQUI && engram sync --cloud --project nombre_proyecto"
+```
+
+---
+
+## Notas
+
+- El cloud está en `https://engram.v-encore-lab.com`
+- El dashboard está en `https://engram.v-encore-lab.com/dashboard/`
+- La base de datos local está en `C:\Users\TuUsuario\.engram\engram.db`
+- El autosync se ejecuta cada ~5 minutos automáticamente

02-nuevo-proyecto-cloud.md

@@ -0,0 +1,53 @@
+# Engram — Añadir nuevo proyecto al cloud
+
+Pasos para registrar un nuevo proyecto en Engram Cloud.
+
+---
+
+## 1. En el VPS — Permitir el proyecto
+
+Edita el docker-compose:
+
+```bash
+nano /opt/engram/docker-compose.cloud.yml
+```
+
+Añade el nuevo proyecto a la variable `ENGRAM_CLOUD_ALLOWED_PROJECTS`:
+
+```yaml
+ENGRAM_CLOUD_ALLOWED_PROJECTS: smoke-project,planificacion_proyectos,gestion-talleres-2000,NOMBRE_NUEVO_PROYECTO
+```
+
+Reinicia el contenedor para aplicar los cambios:
+
+```bash
+docker compose -f docker-compose.cloud.yml up -d --force-recreate cloud
+```
+
+---
+
+## 2. En tu PC — Enrollar y sincronizar
+
+```powershell
+engram cloud enroll NOMBRE_NUEVO_PROYECTO
+cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram sync --cloud --project NOMBRE_NUEVO_PROYECTO"
+```
+
+---
+
+## Notas
+
+- El nombre del proyecto se normaliza automáticamente a minúsculas con guiones bajos. Por ejemplo `PLANIFICACION_PROYECTOS` → `planificacion_proyectos`
+- Cada proyecto tiene su propia memoria aislada en el cloud
+- El dashboard muestra todos los proyectos en `https://engram.v-encore-lab.com/dashboard/`
+
+## Si el sync falla por mutaciones legacy
+
+```powershell
+C:\Users\juanm\Downloads\sqlite3.exe C:\Users\juanm\.engram\engram.db "DELETE FROM sync_mutations WHERE entity = 'relation' AND project = 'NOMBRE_PROYECTO';"
+```
+
+Luego vuelve a hacer sync:
+```powershell
+cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram sync --cloud --project NOMBRE_NUEVO_PROYECTO"
+```

03-seguridad-cloud.md

@@ -0,0 +1,149 @@
+# Engram Cloud — Configuración de Seguridad
+
+Guía completa para securizar Engram Cloud en el VPS.
+
+---
+
+## Configuración actual
+
+- **Servidor:** `https://engram.v-encore-lab.com`
+- **Dashboard:** `https://engram.v-encore-lab.com/dashboard/`
+- **Token:** `e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b`
+- **Modo:** enterprise con autenticación JWT activa
+- **Proyectos permitidos:** `smoke-project`, `planificacion_proyectos`, `gestion-talleres-2000`
+
+---
+
+## Docker Compose del VPS
+
+Ubicación: `/opt/engram/docker-compose.cloud.yml`
+
+```yaml
+services:
+  postgres:
+    restart: always
+    image: postgres:16-alpine
+    container_name: engram-cloud-postgres
+    environment:
+      POSTGRES_USER: engram
+      POSTGRES_PASSWORD: engram_dev
+      POSTGRES_DB: engram_cloud
+    ports:
+      - "127.0.0.1:5433:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U engram -d engram_cloud"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    volumes:
+      - engram-cloud-pg:/var/lib/postgresql/data
+  cloud:
+    restart: always
+    build:
+      context: .
+      dockerfile: docker/cloud/Dockerfile
+    container_name: engram-cloud
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      ENGRAM_DATABASE_URL: postgres://engram:engram_dev@postgres:5432/engram_cloud?sslmode=disable
+      ENGRAM_JWT_SECRET: "e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b"
+      ENGRAM_CLOUD_TOKEN: "e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b"
+      ENGRAM_CLOUD_ALLOWED_PROJECTS: smoke-project,planificacion_proyectos,gestion-talleres-2000
+      ENGRAM_CLOUD_HOST: 0.0.0.0
+      ENGRAM_PORT: "18080"
+    ports:
+      - "127.0.0.1:18080:18080"
+    command: ["cloud", "serve"]
+volumes:
+  engram-cloud-pg:
+```
+
+---
+
+## Si el VPS se cae o necesitas reinstalar
+
+### 1. Clonar el repo y arrancar
+
+```bash
+cd /opt
+sudo git clone https://github.com/Gentleman-Programming/engram
+cd /opt/engram
+```
+
+Sobreescribe el docker-compose con la configuración segura:
+
+```bash
+cat > /opt/engram/docker-compose.cloud.yml << 'EOF'
+# pega aquí el contenido del bloque de arriba
+EOF
+```
+
+Arranca:
+
+```bash
+docker compose -f docker-compose.cloud.yml up -d
+```
+
+### 2. Conectar a la red de Nginx Proxy Manager
+
+```bash
+docker network connect nginx-proxy-manager_default engram-cloud
+```
+
+---
+
+## Si necesitas regenerar el token
+
+En el VPS genera uno nuevo:
+
+```bash
+openssl rand -hex 32
+```
+
+Actualiza `ENGRAM_JWT_SECRET` y `ENGRAM_CLOUD_TOKEN` en el docker-compose y reinicia:
+
+```bash
+docker compose -f docker-compose.cloud.yml up -d --force-recreate cloud
+```
+
+---
+
+## Acceso al dashboard
+
+- URL: `https://engram.v-encore-lab.com/dashboard/`
+- Campo **Cloud Token:** pega el `ENGRAM_CLOUD_TOKEN`
+- Sin el token nadie puede acceder a los datos
+
+---
+
+## Verificar que el servidor está seguro
+
+```bash
+docker logs engram-cloud --tail 10
+```
+
+✅ Correcto — debe mostrar solo:
+```
+Starting Engram cloud server on port 18080
+[engram-cloud] listening on 0.0.0.0:18080
+```
+
+❌ Inseguro — si aparece esta línea hay que eliminarla del docker-compose:
+```
+warning: ENGRAM_CLOUD_INSECURE_NO_AUTH=1 disables cloud API authentication
+```
+
+---
+
+## Nginx Proxy Manager — Configuración del proxy host
+
+| Campo | Valor |
+|---|---|
+| Domain | `engram.v-encore-lab.com` |
+| Scheme | `http` |
+| Forward Hostname | `engram-cloud` |
+| Forward Port | `18080` |
+| SSL | Let's Encrypt |
+| Force SSL | |

README.md

@@ -0,0 +1,58 @@
+# Engram Wiki
+
+Documentación de configuración, instalación y gestión de Engram.
+
+---
+
+## Índice
+
+1. **[01-setup-maquina-nueva.md](01-setup-maquina-nueva.md)** — Instalar Engram en un PC nuevo
+2. **[02-nuevo-proyecto-cloud.md](02-nuevo-proyecto-cloud.md)** — Añadir proyectos al cloud
+3. **[03-seguridad-cloud.md](03-seguridad-cloud.md)** — Configuración de seguridad VPS
+
+---
+
+## Proyectos sincronizados
+
+- `planificacion_proyectos`
+- `gestion-talleres-2000`
+
+---
+
+## Tokens
+
+- **Cloud Token:** `e5ace1caed605543642c1032ef9e24f803f092b4ef9863cc068a8eceaa01445b`
+- **Gitea Token:** `187130f38d937b03f19e1aea1afccb9e3e3ec01d`
+
+---
+
+## URLs
+
+- **Gitea:** `https://git.v-encore-lab.com/`
+- **Engram Cloud:** `https://engram.v-encore-lab.com`
+- **Dashboard:** `https://engram.v-encore-lab.com/dashboard/`
+
+---
+
+## Comandos útiles
+
+```powershell
+# Ver estado
+cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram cloud status"
+
+# Sincronizar
+cmd /c "set ENGRAM_CLOUD_TOKEN=TOKEN && engram sync --cloud --project NOMBRE_PROYECTO"
+
+# Buscar memorias
+engram search "texto a buscar"
+
+# Ver contexto
+mem_context
+```
+
+---
+
+## SQLite (para solves legacy)
+
+- Ubicación: `C:\Users\juanm\Downloads\sqlite3.exe`
+- DB: `C:\Users\juanm\.engram\engram.db`