MemoryLake
Volver a todos los artículos
Tutorial13 de noviembre de 2026·12 min de lectura

¿Qué son los Claude Code Hooks? Cuáles pueden añadir contexto para Claude, por qué una sesión reanudada repite salidas antiguas y cuándo CLAUDE.md es la mejor opción (2026)

Escribiste un pequeño hook que le indica a Claude Code la rama actual y el último resultado de CI cada vez que envías un prompt. Funciona bien. Luego, reanudas la sesión de ayer con --continue, preguntas sobre la compilación, y Claude informa con total seguridad el estado de CI de ayer y un commit que ya ha sido reemplazado. El hook no falló. Claude Code simplemente repitió lo que dijo ayer.

La referencia de hooks de Anthropic describe exactamente esto: "Para eventos a mitad de sesión como PostToolUse o UserPromptSubmit, cuando reanudas con --continue o --resume, Claude Code repite el texto guardado en lugar de volver a ejecutar el hook para los turnos pasados, por lo que valores como marcas de tiempo o SHAs de commit quedan obsoletos".

Los hooks son una forma flexible de dar contexto a Claude Code, y también una fácil de malinterpretar. Esta guía cubre qué son los hooks, dónde se definen, qué eventos de hook pueden añadir contexto para Claude, dónde aterriza ese contexto, qué sucede con él al reanudar y tras la compactación, cómo los hooks dan forma al resumen de compactación y cuándo un archivo CLAUDE.md es el mejor lugar para la misma información.

Qué son los Claude Code hooks

Definición de Anthropic: "Los hooks son comandos de shell definidos por el usuario, endpoints HTTP, llamadas a herramientas MCP, prompts de LLM o subagentes que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code".

Se ejecutan en más lugares que la terminal. "Claude Code dispara los mismos eventos de hook dondequiera que se ejecute: sesiones en la terminal, extensiones de IDE, la aplicación de escritorio y sesiones en la nube".

Cada hook está vinculado a un evento. La referencia enumera docenas, desde SessionStart cuando una sesión comienza o se reanuda, hasta PreToolUse antes de que se ejecute una herramienta, pasando por PreCompact y PostCompact en torno a la compactación, hasta SessionEnd cuando una sesión termina.

Los hooks también pueden realizar tareas con efectos secundarios, como formatear archivos después de una edición, bloquear un comando arriesgado o enviar una notificación. Esta guía trata sobre el subconjunto que introduce texto en el contexto de Claude, porque ese texto se comporta como memoria, con sus propias reglas.

Dónde se definen los hooks

El lugar donde defines un hook establece su alcance. La referencia enumera las ubicaciones:

  • ~/.claude/settings.json para todos tus proyectos, local en tu máquina.
  • .claude/settings.json para un solo proyecto, y puede ser incluido en el repositorio.
  • .claude/settings.local.json para un solo proyecto, no compartido.
  • Configuración de políticas gestionadas para una organización, controlada por administradores.
  • hooks/hooks.json de un plugin mientras el plugin esté habilitado.
  • Frontmatter de una Skill o subagente mientras esa skill o subagente esté en uso.

Las entradas de los hooks se combinan en lugar de reemplazarse entre sí. "Las entradas de hooks se fusionan a través de los niveles de configuración en lugar de reemplazarse: las configuraciones de usuario, proyecto y locales añaden sus propios hooks sin eliminar los gestionados".

Vale la pena conocer un límite para el trabajo remoto: "Las sesiones en la nube no leen tu ~/.claude/settings.json local". Un hook en el que confías localmente no se ejecutará en una sesión en la nube a menos que esté definido en algún lugar que la sesión en la nube lea.

Para ver qué está configurado, escribe /hooks. Anthropic lo describe como "un explorador de solo lectura para tus hooks configurados" que etiqueta cada hook con su procedencia.

Qué hooks pueden añadir contexto para Claude

No todos los hooks pueden hablar con Claude. Los que pueden, utilizan un campo llamado additionalContext. Anthropic explica: "El campo additionalContext pasa una cadena desde tu hook hacia la ventana de contexto de Claude".

El lugar donde aparece ese texto depende del evento:

  • SessionStart y SubagentStart: "al inicio de la conversación, antes del primer prompt".
  • UserPromptSubmit y UserPromptExpansion: "junto al prompt enviado".
  • PreToolUse, PostToolUse, PostToolUseFailure y PostToolBatch: "junto al resultado de la herramienta".
  • Stop y SubagentStop: al final del turno, para que Claude pueda actuar sobre el feedback.
  • PostModelSwitch: "con la siguiente solicitud después del cambio".

Para UserPromptSubmit, la salida simple también funciona. La referencia describe dos canales, stdout simple y additionalContext, y dice: "Ninguno de los canales produce una entrada de transcripción visible".

Esa es la parte que sorprende a la gente. Claude Code envuelve el texto en un recordatorio del sistema: "Claude lee el recordatorio en la siguiente solicitud al modelo, pero no aparece como un mensaje de chat en la interfaz". Claude lo ve, y el chat no lo muestra.

Si quieres ver qué añadieron los hooks, la vista de transcripción muestra más de la sesión que el chat. Lo cubrimos en nuestra guía sobre qué muestra la vista de transcripción en Claude Code.

Cuánto contexto puede añadir un hook

Hay un límite de tamaño. "Si un valor supera los 10,000 caracteres, Claude Code escribe el texto en un archivo en el directorio de la sesión y le pasa a Claude la ruta del archivo con una vista previa de hasta los primeros 2,000 caracteres en su lugar. Claude puede leer el archivo, pero Claude Code no le pide que lo haga".

Por lo tanto, un hook que vuelca un informe largo no pone todo el informe frente a Claude. Pone una vista previa y una ruta, y si Claude abre el archivo depende de Claude.

Cuando varios hooks se disparan en el mismo evento, todos cuentan. "Cuando varios hooks devuelven additionalContext para el mismo evento, Claude recibe todos los valores".

Cómo escribir el contexto que añade un hook

Anthropic da consejos específicos sobre la redacción: "Escribe el texto como declaraciones de hechos en lugar de instrucciones imperativas del sistema".

La razón es la seguridad. El texto que suena como un comando desde fuera de la conversación puede parecer una inyección de prompts. Anthropic advierte que tal enfoque "puede activar las defensas de inyección de prompts de Claude, lo que hace que Claude te muestre el texto a ti en lugar de tratarlo como contexto".

Los ejemplos que da se leen como hechos simples: "El objetivo de despliegue es producción" o "Este repositorio usa bun test". También enumera los tipos de información para los que los hooks son útiles:

  • Estado del entorno: la rama actual, el objetivo de despliegue o flags de características.
  • Reglas condicionales del proyecto: qué comando de prueba se aplica al archivo recién editado, qué directorios son de solo lectura en un worktree.
  • Datos externos: issues abiertos, resultados recientes de CI, contenido de un servicio interno.

Lo que estos tienen en común es que cambian. Esa es la razón para usar un hook en lugar de un archivo.

Por qué una sesión reanudada repite la salida de hooks antiguos

Aquí está el comportamiento de la introducción, en detalle. "Claude Code guarda el texto inyectado en la transcripción de la sesión".

Cuando vuelves a una sesión, los turnos pasados no se vuelven a ejecutar. "Para eventos a mitad de sesión como PostToolUse o UserPromptSubmit, cuando reanudas con --continue o --resume, Claude Code repite el texto guardado en lugar de volver a ejecutar el hook para los turnos pasados, por lo que valores como marcas de tiempo o SHAs de commit quedan obsoletos".

En la práctica, Claude ve lo que tus hooks dijeron en ese momento. Si un hook informó un estado de CI, una rama o una lista de issues ayer, eso es lo que hay en el historial de la conversación reanudada, junto a los turnos donde se disparó.

SessionStart es la excepción. Anthropic dice que los hooks de SessionStart se ejecutan de nuevo al reanudar, con el campo source establecido en resume, o en fork si añadiste --fork-session, "para que puedan refrescar su contexto".

Por lo tanto, si quieres valores frescos en una sesión reanudada, un hook de SessionStart con un matcher de resume es el lugar documentado para ellos. Los valores antiguos siguen en el historial, por lo que ayuda que el nuevo texto indique qué es lo actual.

Qué sucede con el contexto del hook al compactar

La compactación resume las partes anteriores de una conversación para liberar espacio. La guía de hooks de Anthropic es directa sobre el riesgo: "Esto puede hacer que se pierdan detalles importantes".

El texto del hook reside en el historial de la conversación, que es lo que la compactación resume. Los hooks te dan dos formas de gestionar esto.

Re-inyectar después de la compactación. SessionStart tiene un matcher compact, que se dispara después de una compactación automática o manual. La recomendación de la guía: "Usa un hook de SessionStart con un matcher compact para re-inyectar contexto crítico después de cada compactación".

Dar forma al resumen mismo. PreCompact se ejecuta antes de la compactación, y su salida tiene un papel especial. "Cuando un hook PreCompact sale con código 0 y no bloquea, Claude Code usa su stdout como instrucciones para el resumen de compactación". Se aplica el mismo límite de 10,000 caracteres, y la salida más larga se corta en el límite.

PreCompact también puede bloquear la compactación, con diferentes resultados según el momento. Si la compactación se activó de forma proactiva, bloquearla significa que la conversación continúa sin compactar. Si se activó para recuperarse de un error de límite de contexto, "el error subyacente sale a la superficie y la solicitud actual falla".

PostCompact recibe el resumen que se generó, en un campo llamado compact_summary, lo cual es útil para registrar o actualizar notas fuera de Claude Code. La referencia lo enumera sin control de decisión, para efectos secundarios como el registro.

Los matchers de SessionStart

Dado que SessionStart es la forma principal en que los hooks refrescan el contexto, vale la pena conocer sus matchers. La referencia enumera cinco:

  • startup para una nueva sesión.
  • resume para --resume, --continue o /resume.
  • clear para /clear.
  • compact para compactación automática o manual.
  • fork para una nueva sesión bifurcada de una existente.

También hay un detalle de tiempo. Al inicio y después de /clear, los hooks de SessionStart se ejecutan en segundo plano para que puedas escribir de inmediato, pero "la primera respuesta de Claude aún espera a que los hooks terminen, para que su contexto llegue a Claude". La referencia también dice que si ejecutas /clear o cambias de conversación mientras los hooks en segundo plano aún se están ejecutando, nada de lo que devuelvan se aplica a la sesión.

Cuándo CLAUDE.md es la mejor opción

Anthropic responde a esto directamente en la referencia: "Para instrucciones que nunca cambian, prefiere CLAUDE.md. Se carga sin ejecutar un script y es el lugar estándar para las convenciones estáticas del proyecto".

La sección de SessionStart dice lo mismo: "Para contexto estático que no requiere un script, usa CLAUDE.md en su lugar".

Una prueba simple: si el texto fuera el mismo cada vez que se ejecuta el hook, pertenece a CLAUDE.md. Si depende del momento, como la rama, la hora o la última compilación, un hook es la herramienta adecuada.

CLAUDE.md tiene su propio comportamiento en torno a la compactación. La referencia menciona un motivo de carga InstructionsLoaded de compact, que se dispara cuando los archivos de instrucciones se vuelven a cargar después de una compactación. Si has estado poniendo reglas estáticas en un hook para que sobrevivan a la compactación, CLAUDE.md es el hogar documentado para ellas. Para comprobar cómo se cargan tus archivos CLAUDE.md y qué coste tienen, consulta nuestra guía sobre qué comprueba /doctor en Claude Code.

Desactivar los hooks

Para eliminar un hook, borra su entrada del archivo de configuración. Para desactivar todos los hooks temporalmente, la referencia describe un ajuste disableAllHooks, que sigue la precedencia de configuración. Los administradores tienen una versión más fuerte: con allowManagedHooksOnly en la configuración gestionada, se bloquean los hooks de usuario, proyecto, locales y de plugins.

Si el contexto de un hook parece haber desaparecido, comprueba esos dos ajustes antes de depurar el script.

Lo que la gente intenta primero

Confiar en los valores de una sesión reanudada. La salida de los hooks a mitad de sesión se repite desde la transcripción, por lo que las marcas de tiempo y los SHAs de commit pueden estar obsoletos.

Buscar la salida del hook en el chat. El contexto añadido no aparece como un mensaje de chat.

Poner reglas estáticas en un hook. Anthropic recomienda CLAUDE.md para instrucciones que nunca cambian.

Escribir el texto del hook como comandos. El lenguaje imperativo puede activar las defensas contra inyección de prompts.

Devolver un informe largo. Por encima de 10,000 caracteres, Claude recibe una vista previa y una ruta de archivo.

Esperar hooks locales en sesiones en la nube. Las sesiones en la nube no leen tu configuración de usuario local.

La solución: Dar a Claude contexto actual sin restos obsoletos

Paso 1: Mover las reglas estáticas a CLAUDE.md

Si un hook siempre dice lo mismo, pon ese texto en CLAUDE.md en su lugar.

Paso 2: Refrescar al reanudar y después de la compactación

Usa SessionStart con los matchers resume y compact para los valores que cambian.

Paso 3: Escribir hechos, mantenerlos cortos

Redacta la salida del hook como declaraciones de hechos, etiqueta lo que es actual y mantente por debajo de los 10,000 caracteres.

Paso 4: Escribir las razones

Guarda las decisiones detrás de tus convenciones, como por qué un directorio es de solo lectura o por qué un comando de prueba difiere, en algún lugar que no se regenere en cada sesión.

Configurando esto en MemoryLake

Los hooks son buenos para el tiempo presente: en qué rama estás, qué dice CI ahora mismo. CLAUDE.md es bueno para convenciones fijas. Ninguno está diseñado para las decisiones que cambian lentamente y necesitan llegar a más de una herramienta, como por qué el equipo eligió un orden de migración o qué enfoque ya fue descartado.

MemoryLake es una capa de memoria para ese tipo de contexto de proyecto, como decisiones, restricciones y convenciones, mantenidos en un solo lugar que tú controlas y disponibles para los asistentes que conectes, como ChatGPT, Claude Code y Codex.

Tú mismo escribes las entradas, con tus propias palabras. No se lee nada, ni se escribe ni se borra de tus hooks, tus archivos de configuración, tus archivos CLAUDE.md, tus transcripciones de sesión, tus resúmenes de compactación o el almacén de cualquier proveedor. Los hooks, la compactación y la reanudación funcionan de la manera que Anthropic describe.

Paso 1: Crear una clave API

Inicia sesión y genera una clave desde el panel de control. Guárdala fuera de tus repositorios y fuera de los scripts de hooks, como cualquier otra credencial.

La consola de MemoryLake mostrando la pantalla de claves API, donde se crea y copia una nueva clave para usar en un agente
La consola de MemoryLake mostrando la pantalla de claves API, donde se crea y copia una nueva clave para usar en un agente

Paso 2: Sube tus primeras memorias

Empieza con lo que escribiste en el Paso 4 de la solución: las razones detrás de tus convenciones y las decisiones que tus hooks asumen. Una decisión por entrada.

El espacio de trabajo de MemoryLake con los primeros documentos subidos, enumerando cada archivo a medida que se convierte en memoria buscable
El espacio de trabajo de MemoryLake con los primeros documentos subidos, enumerando cada archivo a medida que se convierte en memoria buscable

Paso 3: Conecta tu IA y agentes

Conecta Claude Code y cualquier otro asistente que utilices. Los hooks siguen suministrando el estado actual, y el razonamiento está disponible junto a él.

La pantalla de integraciones de MemoryLake enumerando los clientes de IA y frameworks de agentes que pueden conectarse a la capa de memoria
La pantalla de integraciones de MemoryLake enumerando los clientes de IA y frameworks de agentes que pueden conectarse a la capa de memoria

Qué cambia esto en la práctica

La primera diferencia es una división más limpia. Los hooks llevan lo que cambia minuto a minuto, CLAUDE.md lleva las convenciones fijas, y las decisiones que se mueven más lentamente tienen su propio lugar.

La segunda es un contexto menos obsoleto. Las decisiones no se quedan congeladas en una transcripción en el momento en que se disparó un hook.

La tercera es la continuidad entre herramientas. Codex u otro asistente que trabaje en el mismo repositorio puede usar las mismas decisiones sin su propia configuración de hooks.

Mejores prácticas para los hooks de Claude Code

Usa hooks para lo que cambia. Ramas, compilaciones y listas de issues, no reglas fijas.

Pon las reglas fijas en CLAUDE.md. Se carga sin ejecutar un script.

Refresca al reanudar. Solo SessionStart se vuelve a ejecutar cuando reanudas.

Planifica para la compactación. Usa un matcher compact para re-inyectar lo que importa, o PreCompact para guiar el resumen.

Escribe hechos, no comandos. Evita que el texto del hook parezca una inyección.

Mantente por debajo del límite de tamaño. La salida larga se convierte en una ruta de archivo y una vista previa.

Consulta /hooks cuando falte algo. Muestra de dónde proviene cada hook.

Conclusión

Los hooks de Claude Code se ejecutan automáticamente en puntos del ciclo de vida de una sesión, y varios de ellos pueden añadir contexto para Claude a través de additionalContext: SessionStart, SubagentStart, UserPromptSubmit, los eventos de herramientas, Stop y PostModelSwitch, entre otros. Ese texto llega a Claude como un recordatorio del sistema y no aparece como un mensaje de chat.

Claude Code guarda el texto del hook en la transcripción y lo repite al reanudar para los turnos pasados, por lo que los valores pueden quedar obsoletos, y solo SessionStart se ejecuta de nuevo. Usa los matchers de SessionStart y PreCompact para gestionar el contexto a través de la reanudación y la compactación, mantén las reglas estáticas en CLAUDE.md y guarda las decisiones detrás de tu configuración en algún lugar que no se regenere en cada sesión.

Preguntas frecuentes

¿Qué son los hooks en Claude Code?

Comandos de shell definidos por el usuario, endpoints HTTP, llamadas a herramientas MCP, prompts de LLM o subagentes que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code.

¿Puede un hook añadir contexto para Claude?

Sí. Varios eventos, incluyendo SessionStart, UserPromptSubmit y los eventos de herramientas, pueden devolver additionalContext, que Claude lee como un recordatorio del sistema.

¿Por qué Claude ve la salida de un hook antiguo después de reanudar?

Claude Code guarda el texto inyectado en la transcripción y lo repite para los turnos pasados en lugar de volver a ejecutar el hook, por lo que valores como marcas de tiempo y SHAs de commit pueden estar obsoletos.

¿Se vuelven a ejecutar los hooks cuando reanudo una sesión?

Los hooks de SessionStart se vuelven a ejecutar al reanudar. Los hooks de mitad de sesión para turnos pasados se repiten, no se vuelven a ejecutar.

¿Cómo mantengo el contexto después de la compactación?

Usa un hook de SessionStart con un matcher compact para re-inyectarlo, o un hook PreCompact para dar instrucciones para el resumen de compactación.

¿Debería usar un hook o CLAUDE.md?

Anthropic recomienda CLAUDE.md para instrucciones que nunca cambian. Usa hooks para el contexto que cambia, como la rama actual o los resultados de CI.

¿Por qué mi hook no se ejecuta en sesiones en la nube?

Las sesiones en la nube no leen tu ~/.claude/settings.json local.