capn-hook es una herramienta de línea de comandos pensada para coding agents como Claude Code y Codex, que sufren un problema recurrente: cada nueva sesión empiezan de cero y vuelven a pagar el coste de descubrir dónde vive cada cosa dentro de un repositorio. capn-hook resuelve eso con una memoria local y persistente que el agente consulta antes de buscar y en la que guarda los hallazgos costosos de obtener.
El flujo se reduce a tres comandos. Con capn ask el agente formula una pregunta en lenguaje natural; si hay una coincidencia, recibe en JSONL los archivos que ya responden a esa duda, ahorrándose la búsqueda. Si no la hay, sale con un código 1 y el agente explora. Tras un descubrimiento difícil, capn chart guarda la pregunta junto con los archivos que la responden y, opcionalmente, notas adicionales como rangos de líneas o advertencias. Cuando alguno de esos archivos cambia o desaparece, la entrada se elimina automáticamente: cada archivo se huella con sha256 al guardarlo y, antes de cada consulta, se eliminan las entradas obsoletas. Los comandos son chart y unchart, nunca update: una respuesta o sigue siendo válida o deja de servir.
La integración es mínima. capn init instala un hook de SessionStart que inyecta al inicio de cada sesión un breve contrato ("antes de buscar, pregunta a capn; tras un hallazgo difícil, guárdalo"). El modelo lo lee y decide cuándo usarlo, sin middleware ni comportamiento forzado. El índice se apoya en QMD, con búsqueda semántica híbrida por defecto o BM25 puro con --no-embedding, y corre en proceso dentro del propio proyecto, sin daemon ni servidor. Todo vive bajo .capn/, que capn init añade al .gitignore para mantener la memoria local y descartable.
El repositorio incluye una evaluación sobre 60 preguntas reales en cinco bases de código en producción (Dub, Polar, PostHog, Twenty y Documenso): un agente con capn consumió un 77 % menos de tokens que uno que partía de cero, acertando todas las respuestas en ambos casos, y la sesión se amortiza a partir de unas 1,6 reutilizaciones. La licencia es MIT.