Sobrevivir a la compactación

Cuando Claude Code compacta una conversación larga, el resumen conserva la idea general y pierde los detalles. La recuperación post-compactación devuelve esos detalles: justo después de cada compactación, un hook vuelve a inyectar en el contexto del modelo las memorias más recientes de tu proyecto en ContextForge y sus tareas pendientes. Disponible desde contextforge-mcp 0.12.0. Solo para Claude Code.

El problema

Las sesiones largas llenan la ventana de contexto. Claude Code compacta la conversación, ya sea cuando ejecutas /compact o automáticamente cuando se queda sin espacio. El resumen que conserva es bueno con la visión general y malo con los detalles. Lo que suele perderse es justo lo que necesitas a continuación:

Las decisiones que tomaste hace una hora y los motivos detrás de ellas.
Qué tareas se terminaron, cuáles siguen pendientes y qué se acordó como siguiente paso.
Las correcciones que le diste al agente y que ahora olvida en silencio.

El agente no sabe qué perdió. Tras la compactación sigue trabajando a partir del resumen como si nada hubiera pasado, así que la desviación solo se nota cuando vuelve a preguntar algo ya resuelto o deshace una decisión.

Cómo funciona

Dos piezas: un hook de Claude Code y un subcomando de la CLI.

1. El hook que instala `init`

npx contextforge-mcp init ahora añade un hook SessionStart con el matcher compact al archivo .claude/settings.json de tu proyecto. Claude Code lo ejecuta justo después de cada compactación y añade la salida estándar del comando al contexto del modelo.

# .claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "npx -y contextforge-mcp recall" }
        ]
      }
    ]
  }
}

init se fusiona con un settings.json existente sin tocar otras claves ni otros hooks, y es idempotente: si lo vuelves a ejecutar imprime "already present". Cursor no recibe nada aquí, porque no tiene hooks.

2. El subcomando `recall`

contextforge-mcp recall resuelve tu clave API (desde CONTEXTFORGE_API_KEY; si no, desde la entrada del servidor contextforge en ~/.claude.json; si no, desde el .mcp.json del proyecto), lee el proyecto vinculado desde el archivo .contextforge en la raíz del repositorio, obtiene las 10 memorias más recientes del proyecto en todos sus espacios y hasta 5 tareas pendientes, e imprime un bloque de texto plano como este:

# salida de npx contextforge-mcp recall

## ContextForge: context restored after compaction

Recent memories:
- [Decisions] Keep Supabase magic links, drop password login — Decided after the support thread on 2026-09-22. Password reset emails were the top ticket…
- [API] Rate limit is 60 requests per minute per key — Enforced in the edge function. Return 429 with a Retry-After header, never a 500…

Pending tasks:
- [f8drg2] Ship the billing webhook retry (high, due 2026-09-30)
- [k2m9xa] Write the 0.12.0 release notes (medium, due 2026-10-02)

For anything older or more specific, call memory_query before answering.

Nunca bloquea una sesión. Sin clave, sin proyecto vinculado, con un error de red o al superar el tiempo límite de 8 segundos, no imprime nada y sale con código 0. Una ejecución normal tarda unos 4 segundos.

Usuarios nuevos

Nada extra. Ejecuta init en el proyecto, como en el paso "Inicializa tu proyecto" de la guía de inicio, y el hook se instala junto con todo lo demás:

cd ~/your-project
npx contextforge-mcp init

Usuarios existentes

Dos pasos: obtén la 0.12.0 y vuelve a ejecutar init una vez por proyecto.

1. Actualiza el paquete

Si lo instalaste globalmente, actualízalo. Si solo has usado npx, recibirás la 0.12.0 en el próximo arranque. En cualquier caso, comprueba la versión, porque una instalación global antigua se impone sobre npx:

npm update -g contextforge-mcp
npx contextforge-mcp --version   # expect 0.12.0 or newer

2. Vuelve a ejecutar init en cada proyecto

Solo añade el hook que falta. Tu CLAUDE.md, tus otros hooks y el resto de claves de settings quedan tal como están.

cd ~/your-project
npx contextforge-mcp init

¿Prefieres hacerlo a mano? Pega el grupo hooks.SessionStart del fragmento de arriba en el .claude/settings.json de tu proyecto. Si ya tienes un array SessionStart, añade el grupo dentro en lugar de reemplazarlo.

Comprueba que funciona

Desde la carpeta del proyecto, ejecuta el subcomando directamente. Deberías ver el bloque de arriba con tus propias memorias y tareas. Una salida vacía significa que no hay clave o que el proyecto no está vinculado.
Después, en Claude Code, ejecuta /compact y pregunta "what context did you just receive?". El agente debería repetir las memorias y tareas del bloque.

cd ~/your-project
npx contextforge-mcp recall

Requisitos y límites

Solo Claude Code. El hook vive en .claude/settings.json. Cursor no tiene hooks, así que ahí no se instala nada.
Un proyecto vinculado. El proyecto necesita un archivo .contextforge en la raíz del repositorio. Consulta Vinculación de proyectos.
Solo vuelve a inyectar lo que guardaste. El bloque contiene las 10 memorias más recientes y hasta 5 tareas pendientes de ContextForge. No puede decirte qué descartó el resumen de la compactación, porque nunca ve la conversación.
Así que guarda las decisiones sobre la marcha. Pídele al agente que "guarde dónde estamos y qué sigue" antes de un tramo largo de trabajo. Lo que está en ContextForge vuelve; lo que solo estaba en el chat, no.

Solución de problemas

El hook se ejecuta pero no inyecta nada

Un export CONTEXTFORGE_API_KEY=... antiguo en el rc de tu shell tiene prioridad sobre ~/.claude.json. Si esa clave está caducada, el hook no imprime nada y no avisa. Elimina el export o sustituye la clave, y vuelve a ejecutar npx contextforge-mcp recall para confirmarlo.

El hook ejecuta una versión vieja

Una instalación global antigua hace que npx -y contextforge-mcp ejecute la versión vieja, que no tiene el subcomando recall. Compruébalo y actualízala:

which contextforge-mcp
npm update -g contextforge-mcp
npx contextforge-mcp --version

Salida vacía, la clave es correcta

El proyecto no está vinculado. Debe existir un archivo .contextforge en la raíz del repositorio. Pídele al agente que "vincule el proyecto" (usa cf_tools) y vuelve a ejecutar recall.