mastermind-setup

# Mastermind Setup Procedures for setting up and maintaining the Mastermind personal agent system — a private GitHub repo that serves as the agent's second brain (skills, notes, memory, config, scripts). ## Cuándo usar - Se configura un nuevo entorno de Hermes Agent para Ntizar - Necesitas sincronizar skills desde el repositorio Mastermind al sistema local - El SOUL.md se corrompió o truncó y necesita recuperación - Se necesitan configurar cron jobs de sincronización automática ## Cuándo NO usar - Configurar un usuario diferente de Ntizar → el repo y las rutas son específicas - Solo necesitas instalar un skill individual → usa `skill_manage(action='create')` directamente - El sistema ya está configurado y funcionando → no reconfigurar sin necesidad ## Identity El nombre del agente es **Mastermind**, no "Hermes Agent". Hermes es el framework subyacente; Mastermind es el nombre que David (Ntizar) le dio a su sistema de agente personal. Al presentarte o referirte a ti mismo, usa "Mastermind". - **Framework:** Hermes Agent (el motor subyacente) - **Nombre:** Mastermind (el agente personal) - **Usuario:** David Antizar (Ntizar) Esta es la identidad preferida del usuario. Siempre presentarse como Mastermind. ## Setup ### 1. Install GitHub CLI ```bash curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg 2>/dev/null echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null apt-get update -qq && apt-get install -y -qq gh ``` ### 2. Authenticate with GitHub ```bash # Read token from .env token=$(grep GITHUB_TOKEN /hermes-home/.env 2>/dev/null | cut -d= -f2-) # ⚠️ PITFALL: gh auth login fails when GITHUB_TOKEN env var is set # Clear it first: GITHUB_TOKEN="" echo "$token" | gh auth login --with-token ``` ### 3. Clone the repo ```bash cd /root/workspace git clone https://github.com/Ntizar/mastermind.git ``` ### 4. Configure Hermes to use it as a skills source In `/hermes-home/config.yaml`: ```yaml skills: external_dirs: - /root/workspace/Mastermind/mastermind ``` Then `/reset` (new session) for Hermes to detect the new skills. ### 5. Copy skills to local directory ```bash mkdir -p /hermes-home/skills/mastermind cp /root/workspace/Mastermind/mastermind/*.md /hermes-home/skills/mastermind/ ``` Create a `SKILL.md` umbrella in `/hermes-home/skills/mastermind/SKILL.md` listing the individual skills. ### 6. Actualizar SOUL.md Configurar `/hermes-home/SOUL.md` con: identidad del agente, reglas, sistema de conocimiento en 3 capas, estructura del repo, modelo de subagentes, stack actual y lista de skills. ### 8. Arrancar ChromaDB local (skills vector search) ChromaDB corre en localhost:8000 para búsqueda semántica de skills. Debe arrancar tras cada reinicio de la VM: ```bash # Arranque manual bash /hermes-home/scripts/start-chromadb.sh # Verificar curl http://localhost:8000/api/v1/version # → "1.5.9" ``` **Script de arranque:** El script `start-chromadb.sh` está en el skill `chromadb-skills-vector-search`: ```bash skill_view(name='chromadb-skills-vector-search', file_path='scripts/start-chromadb.sh') # O directamente: bash /hermes-home/skills/chromadb-skills-vector-search/scripts/start-chromadb.sh ``` **Datos persistentes:** `/hermes-home/chromadb-data/` **Pitfall:** ChromaDB NO arranca automáticamente al reiniciar la VM. Si el agente nota que las consultas semánticas fallan, debe ejecutar `start-chromadb.sh` o reportarlo. Ver skill `chromadb-skills-vector-search` para detalles completos de indexación y consulta. Create a cron job that runs daily: ```bash # Schedule: 0 9 * * * (daily at 09:00 UTC) # Prompt: cd /root/workspace/Mastermind && git pull origin main cp /root/workspace/Mastermind/mastermind/*.md /hermes-home/skills/mastermind/ gh auth status || re-authenticate from /hermes-home/.env ``` See `scripts/mastermind-autoconfig.sh` for the ready-to-use sync script (includes SOUL.md size guard). See `scripts/restore-soul.sh` for SOUL.md sync check and recovery. See `scripts/backup-hermes-memory.sh` for manual backup of memory to repo. See `references/backup-hermes-complete.md` for the complete backup procedure (vulnerability assessment → copy → commit → auto-sync cron). See `references/backup-pitfalls-2026-06-22.md` for backup pitfalls: double nesting with cp, duplicate commits, .hub/quarantine exclusion, skill-learning.log gitignore. See `references/backup-rsync-fallback.md` for rsync fallback: Python shutil-based implementation when rsync binary is not available on the VM. See `references/backup-cp-nesting.md` for the complete `cp -r` / `cp -a` double-nesting pitfall and safe copy patterns. ## Estructura del Repositorio ``` Mastermind/ ├── README.md ← Visión general del sistema ├── ARCHITECTURE.md ← Documentación técnica (capas, flujos) ├── mastermind/ ← Skills CORE del sistema │ ├── SKILL.md ← Índice umbrella de skills propios │ ├── SOUL.md ← Plantilla de identidad │ └── (skills .md individuales) ├── learning/ ← Sistema de aprendizaje autónomo │ ├── MEGA-PLAN-LECTURA-ESCRITURA.md ← Plan maestro del curso │ ├── README.md ← Cómo funciona el sistema │ ├── sesiones/ ← HTMLs de lecciones generadas │ └── indices/ ← Índices temáticos (autores, vocab...) ├── improvement/ ← Mejora continua de Mastermind │ ├── skills-desapavechadas.md ← Skills que no uso y debería │ ├── skills-nuevas-proyecto.md ← Skills que debería crear │ └── INDEX.md ← Índice unificado de mejoras ├── skills/ ← Skills de referencia (hub externo) │ └── INDEX.md ← Catálogo completo ├── config/ │ └── skill-priority.json ← Prioridad HIGH/MEDIUM/LOW ├── scripts/ ← Automatizaciones │ ├── mastermind-autoconfig.sh ← Autoconfiguración diaria │ ├── generate-skill-index.sh ← Generador de índice │ └── (otros scripts) ├── memory/ ← Respaldo de memoria ├── notes/ ← Notas de sesiones │ └── _template.md ← Template con frontmatter YAML └── .deploy/ ← Deploy configs (nginx, Docker) ``` ## Reglas 1. **Nunca borrar del repositorio** — solo crear nuevos archivos o modificar archivos que creaste 2. **Formato de notas:** `YYYY-MM-DD-titulo.md` en `notes/` 3. **Skills:** cada skill tiene su propio archivo en `mastermind/` 4. **Commit tras aprender:** lecciones importantes → commit al repositorio 5. **Sin secretos en notas/commits/chat** 6. **SOUL.md es la fuente de verdad** para la identidad del agente — mantenerlo sincronizado con el repo ## Backup automático de Hermes al repo (MANTENER ACTUALIZADO) Este es el procedimiento estándar de backup completo al repo Mastermind. Ejecutar cuando se pida o como cron. ### Pasos 1. **Verificar que el destino existe:** ```bash test -d /root/workspace/Mastermind/hermes-home/ || mkdir -p /root/workspace/Mastermind/hermes-home/ ``` 2. **Copiar archivos/carpetas (rsync o fallback):** ```bash # OPCIÓN A: rsync (si está disponible) rsync -av /hermes-home/skills/ /root/workspace/Mastermind/hermes-home/skills/ rsync -av /hermes-home/memories/ /root/workspace/Mastermind/hermes-home/memories/ rsync -av /hermes-home/notes/ /root/workspace/Mastermind/hermes-home/notes/ rsync -av /hermes-home/scripts/ /root/workspace/Mastermind/hermes-home/scripts/ # OPCIÓN B: rm -rf + cp -a (cuando rsync no está disponible — confirmado 2026-06-29) rm -rf /root/workspace/Mastermind/hermes-home/skills/ cp -a /hermes-home/skills/ /root/workspace/Mastermind/hermes-home/skills/ rm -rf /root/workspace/Mastermind/hermes-home/memories/ cp -a /hermes-home/memories/ /root/workspace/Mastermind/hermes-home/memories/ rm -rf /root/workspace/Mastermind/hermes-home/notes/ cp -a /hermes-home/notes/ /root/workspace/Mastermind/hermes-home/notes/ rm -rf /root/workspace/Mastermind/hermes-home/scripts/ cp -a /hermes-home/scripts/ /root/workspace/Mastermind/hermes-home/scripts/ cp /hermes-home/config.yaml /root/workspace/Mastermind/hermes-home/config.yaml ``` > **Por qué rsync y no `cp -r`:** `cp -r /hermes-home/memories/ /dest/hermes-home/memories/` cuando el destino ya existe produce `/dest/hermes-home/memories/memories/`. `rsync -av` no tiene este problema. Si rsync no está, usar `rm -rf` + `cp -a` como fallback confirmado. 3. **Verificar que no hay nesting:** ```bash find /root/workspace/Mastermind/hermes-home/ -mindepth 2 -maxdepth 2 -type d | while read dir; do parent=$(basename "$(dirname "$dir")") child=$(basename "$dir") if [ "$parent" = "$child" ]; then echo "NESTED: $dir" fi done ``` Si hay nesting, aplicar el fix cascading (ver pitfall 2026-06-28). 4. **Contar archivos copiados:** ```bash find /root/workspace/Mastermind/hermes-home/skills -type f | wc -l ``` 5. **git add, commit, push:** ```bash cd /root/workspace/Mastermind git add -A git commit -m "Backup semanal: $(date +%Y-%m-%d)" git push origin HEAD:master ``` ### Pitfalls críticos del backup - **DOBLE NESTING con `cp -r` (recurrente):** `cp -r /hermes-home/memories/ /dest/hermes-home/memories/` cuando `/dest/hermes-home/memories/` ya existe produce `/dest/hermes-home/memories/memories/`. **SOLUCIÓN OBLIGATORIA:** usar `rsync -av` en lugar de `cp -r`. Siempre. - **Cascading nesting en skills:** Cuando el nesting raíz se corrige (`skills/skills/` → `skills/`), CADA categoría top-level puede tener el mismo patrón: `ai-patterns/ai-patterns/`, `creative/creative/`, `stem/stem/` — 70+ directorios. **Fix:** loop sistemático `find . -mindepth 2 -maxdepth 2 -type d | while read dir; do parent=$(basename "$(dirname "$dir")"); child=$(basename "$dir"); if [ "$parent" = "$child" ]; then mv "$dir"/* "$dir"/.* . 2>/dev/null; rm -rf "$dir"; fi; done`. - **skill-learning.log:** puede no existir (gitignore, puede haber sido eliminado). No fallar si no está. - **Comparación de skills:** usar `find -name 'SKILL.md'` en ambos lados, EXCLUYENDO `.hub/`. El repo puede tener más skills que Hermes (skills propios del sistema, STEM, etc.). No es problema. - **`.hub/quarantine/` no va al backup.** Contiene installs fallidas. - **`.lock` files:** los archivos `.lock` de memories (MEMORY.md.lock, USER.md.lock) van al backup pero son inertes. Limpiarlos con `find -name '*.lock' -delete` antes de commit si se quiere repos limpio. - **`.hub/` en conteo:** no incluir `.hub/` al comparar conteos de SKILL.md. - **`rsync --delete` es destructivo:** solo usar si se quiere espejo exacto. Para backup incremental seguro, usar `rsync -av` SIN `--delete`. - **Hermes no detecta external_dirs mid-session** — reiniciar sesión (`/reset`) tras cambiar `config.yaml` - **SKILL.md requerido** — archivos `.md` individuales no se detectan sin un `SKILL.md` umbrella - **gh auth falla con GITHUB_TOKEN set** — limpiar primero: `GITHUB_TOKEN="" echo "$token" | gh auth login --with-token` - **SOUL.md debe actualizarse** — instalar skills no es suficiente; la identidad debe estar en SOUL.md - **SOUL.md puede truncarse** — puede reducirse a ~48 bytes. **Detección:** `wc -c /hermes-home/SOUL.md` — si <1000, está corrupto. **Recuperación:** `cp /root/workspace/Mastermind/mastermind/SOUL.md /hermes-home/SOUL.md` - **Hermes memory drifts from repo** — el cron NO hace backup de memoria. Usar `scripts/backup-hermes-memory.sh` manualmente. - **SOUL.md size guard (ACTUALIZADO 2026-06-03)** — `mastermind-autoconfig.sh` usa lógica de 3 vías: (1) si local < 1000 bytes → SIEMPRE restaurar desde repo (truncado), (2) si repo > local → restaurar, (3) si local > repo y local > 1000 → subir al repo. El guard anterior solo comparaba `repo > local`, lo que permitía corrupción parcial silenciosa. - **Config drift silencioso** — `tts.edge.voice` y `display.language` pueden perderse tras updates de Hermes o reconfiguraciones. **Verificar periódicamente:** `grep "voice:" /hermes-home/config.yaml | head -1` debe mostrar `es-ES-AlvaroNeural`, y `grep "language:" /hermes-home/config.yaml` debe mostrar `es` en sección display. Si están en inglés → el agente responde en inglés y TTS suena raro. - **Hermes path quirk** — algunos deployments usan `/hermes-home/` en vez de `~/.hermes/`. Verificar `$HERMES_HOME`. - **No crear skills con write_file manual** — usar `skill_manage(action='create')`. - **Duplicate workspace clones** — solo una copia de Mastermind repo en `/root/workspace/Mastermind/`. - **gh CLI no instalado** — `git push` funciona sin `gh`. - **ChromaDB no sobrevive a reinicios** — la VM de NaN puede reiniciarse. ChromaDB no tiene systemd unit. Si el agente detecta que `curl localhost:8000/api/v1/version` falla, debe ejecutar `bash /hermes-home/scripts/start-chromadb.sh` para re-arrancarlo. Los datos persisten en `/hermes-home/chromadb-data/`. - **Debian Node.js stub crashes** — `/usr/bin/node` es un stub que crashea. Usar nvm o shebang directo al path nvm. ## Patrón de Sincronización Bidireccional ## Orquestación de Cron Jobs (Multi-Sesión con Plan Maestro) Cuando el usuario pide generar un proyecto grande que requiere múltiples sesiones/entregas (curso de 10 sesiones, serie de informes, batch de archivos), usar este patrón. ### Pasos 1. **Crear MEGA-PLAN.md** en el directorio de trabajo - Estructura general del proyecto - Diseño visual unificado (paleta, CDN, estilo) - Contenido detallado por sesión/archivo - Requisitos técnicos - Checklist de calidad 2. **Crear archivo principal** (INDEX.html, README, etc.) con navegación entre entregas 3. **Crear cron jobs** con: - `deliver: origin` (entregar al chat actual) - Schedule espaciado (cada 12h o 24h para no saturar) - `repeat: once` (ejecutar una sola vez) - Cada cron con prompt autocontenido que referencie el MEGA-PLAN.md - Nombre descriptivo: `NombreProyecto SNN — Descripción` 4. **Verificar que los crons se crearon** con `cronjob action=list` ### Reglas - El MEGA-PLAN.md es la fuente de verdad: TODOS los crons lo referencian - Cada cron debe ser autocontenido (no depende del contexto del chat) - Espaciar crons para evitar saturación de tokens - Límite de líneas por archivo para evitar truncamiento ### Pitfalls - NO crear crons en bucle infinito (`repeat: forever`) para proyectos de una sola vez - NO usar `openrouter` como provider en crons de Mastermind (401 error) — usar `qwen3.6` vía `custom` - NO olvidar que los crons corren en sesión aislada: el prompt debe ser completamente autocontenido