🌱 Empieza aquí · Guardián de Cap de Memoria

Esta semilla mantiene en cintura el archivo de memoria de tu asistente: ese archivo donde va guardando lo que no quiere olvidar entre conversaciones. Con el tiempo ese archivo se infla, tu asistente lo relee entero cada vez y empieza a gastar de más y a perder el hilo. Este guardián lo vigila y, apenas se pasa de la raya, lanza un aviso imposible de ignorar para que tu asistente lo pode.

Para instalarla

Abre esta carpeta con Claude Code o Cowork y dile a tu asistente:

"Siembra esta semilla 🌱"

Con eso basta de tu parte. Tu asistente hace todo lo técnico y al final te dice cómo comprobar que quedó funcionando. Vas a ver algunas palabras en inglés en la pantalla; ni caso, él te guía.

¿Otras formas de pedírselo? "instala esta semilla", "pon a funcionar el guardián de memoria", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Instala este hook (gancho de automatización) del evento SessionEnd (fin de sesión). Sigue estos pasos y no inventes rutas: usa $HOME siempre.

1. Copia el script del kernel (el corazón de la semilla)

Copia kernel/memory-cap-validator.sh a la carpeta de hooks del usuario y dale permiso de ejecución.

Claude Code / Cowork (macOS o Linux):

mkdir -p "$HOME/.claude/hooks"
cp kernel/memory-cap-validator.sh "$HOME/.claude/hooks/memory-cap-validator.sh"
chmod +x "$HOME/.claude/hooks/memory-cap-validator.sh"

Windows (Git Bash / WSL): misma ruta ~/.claude/hooks/. El script usa bash, wc y awk, que vienen con Git Bash o WSL. Si el usuario corre Claude Code nativo en Windows sin bash, avísale que este hook necesita un entorno con bash disponible.

2. Registra el hook en `settings.json`

Abre $HOME/.claude/settings.json (créalo si no existe) y agrega esta entrada dentro de hooks.SessionEnd. Si ya hay hooks de SessionEnd, suma este objeto al arreglo hooks existente en lugar de reemplazarlo:

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash $HOME/.claude/hooks/memory-cap-validator.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. (Opcional) Ajusta límites o ruta

Los valores por defecto son: 180 líneas · 25 KB · máximo 5 entradas de más de 200 caracteres. El script autodetecta el archivo de memoria en $HOME/.claude/memory/MEMORY.md y, si no existe, cae al patrón por proyecto $HOME/.claude/projects/*/memory/MEMORY.md.

Si el usuario quiere otros valores o apuntar a otro archivo, hay dos caminos:

Editar los valores por defecto en la parte superior de memory-cap-validator.sh (lo más simple para alguien no técnico: solo cambias el número).
Exportar variables de entorno antes de que corra el hook. Estas son todas las que entiende el script, con su significado:
- MEMORY_FILE — ruta absoluta al archivo de memoria (si la fijas, desactiva la autodetección).
- MEMORY_MAX_LINES — tope de líneas (por defecto 180).
- MEMORY_MAX_KB — tope de tamaño en KB (por defecto 25).
- MEMORY_MAX_ENTRY_CHARS — una entrada de lista más larga que esto cuenta como "inflada" (por defecto 200).
- MEMORY_MAX_BLOAT_ENTRIES — cuántas entradas infladas se toleran antes de avisar (por defecto 5).
- MEMORY_CAP_OVERRIDE — ruta del archivo de override (permiso de excepción de una sola sesión); por defecto $HOME/.claude/.memory-cap-override.

4. Verificación post-siembra (obligatoria)

Corre esta prueba para confirmar que el guardián se dispara de verdad. Crea un archivo de memoria de prueba que rebase el límite de líneas y ejecuta el hook apuntándolo ahí:

printf 'línea %s\n' $(seq 1 200) > /tmp/memoria-prueba.md
MEMORY_FILE=/tmp/memoria-prueba.md bash "$HOME/.claude/hooks/memory-cap-validator.sh"; echo "EXIT=$?"

Salida esperada (un bloque de aviso terminado en EXIT=2):

⚠️ Aviso de higiene de memoria · memory-cap-validator
   Archivo de memoria: /tmp/memoria-prueba.md
   Supera los límites de disciplina:
   - LÍNEAS=200 (límite 180)
   ...
EXIT=2

Si sale EXIT=2, el guardián está vivo y avisando. Ahora comprueba el caso feliz (archivo dentro de límites → deja pasar):

printf 'línea %s\n' $(seq 1 10) > /tmp/memoria-prueba.md
MEMORY_FILE=/tmp/memoria-prueba.md bash "$HOME/.claude/hooks/memory-cap-validator.sh"; echo "EXIT=$?"
rm -f /tmp/memoria-prueba.md

Salida esperada: sin avisos y EXIT=0.

Por último, confirma que el hook quedó registrado en settings.json:

grep -q 'memory-cap-validator' "$HOME/.claude/settings.json" && echo 'REGISTRADO'

Salida esperada: REGISTRADO.

Cuando las tres pruebas den lo esperado, avísale al usuario que ya quedó y explícale en una línea qué gana con esto.

¿Cómo sé que funcionó?

A partir de ahora, cuando cierres una sesión de trabajo, si tu archivo de memoria creció de más, aparecerá un aviso imposible de ignorar y tu asistente te pedirá podarlo. No tienes que hacer nada especial: si algún día ves ese aviso, solo pídele a tu asistente que "resuma la memoria" para la próxima sesión y listo. Si esa vez prefieres no podar, él sabe cómo darte un permiso de una sola sesión.

Tu memoria se mantiene liviana, tu asistente arranca más rápido y con la cabeza más clara. Eso es todo. 🌱