ctxrs/ctx

Búsqueda en el Historial de Agentes ctx

Usa ctx siempre que necesites consultar sesiones anteriores de agentes de codificación. Esas transcripciones pueden contener la intención del usuario, decisiones, líneas de tiempo de trabajo previo, intentos pasados, y lo que funcionó o falló.

Usa esta habilidad en dos modos:

• recuperación antes del trabajo, cuando sesiones previas pueden contener decisiones, comandos, fallos o citas que afecten la tarea actual;
• informes de investigación histórica, cuando el usuario pide a un agente o subagente de solo lectura que investigue un tema histórico a través de sesiones locales previas de agentes.

Requisitos previos

• Es necesario que la CLI ctx esté instalada y configurada. Si no está presente e instalar herramientas es apropiado para la tarea, instálala con:

  curl -fsSL https://ctx.rs/install | sh
  

• La primera configuración puede llevar tiempo mientras ctx indexa las sesiones pasadas. Si es necesario, mantenla ejecutándose en segundo plano o en tmux, o espera a que termine.

• Si ctx no está disponible, indica que la búsqueda del historial local no está disponible y no inventes resultados.

Flujo de trabajo

1. Confirma que ctx está listo cuando empieces desde un contexto frío:

   ctx status
   ctx sources
   

   Usa ctx status --format json o ctx sources --format json solo cuando un script necesite campos exactos.

2. Busca primero con lenguaje natural. Añade términos o filtros cuando sea útil:

   ctx search "<consulta>"
   ctx search "<consulta>" --refresh off
   ctx search "<consulta>" --provider codex
   ctx search "<consulta>" --workspace <workspace>
   ctx search "<consulta>" --file <ruta>
   ctx search "<consulta>" --since 30d
   ctx search "<consulta>" --term "<término relacionado>" --term "<texto de error>"
   ctx search "<consulta>" --session <ctx-session-id>
   ctx search "<consulta>" --verbose
   

   Usa la salida de texto predeterminada para la lectura del agente. No agregues --format json para búsqueda o show a menos que lo estés canalizando a jq o un script, o necesites campos exactos legibles por máquina. La salida JSON es mucho más grande y puede consumir rápidamente la ventana de contexto.

   Cuando el prompt solicite un historial o informe de un tema a través de múltiples sesiones, ejecuta varias consultas ctx search con diferentes redacciones y filtros para encontrar sesiones prometedoras. Usa el ámbito ctx search "<consulta>" --session <ctx-session-id> cuando una sesión parezca relevante y necesites coincidencias densas a nivel de evento de esa sesión.

   La búsqueda predeterminada devuelve sesiones de agente principal para que la intención humana y las decisiones sigan siendo prominentes. Usa --include-subagents cuando es probable que los detalles de implementación, las notas de revisión de código, la salida de pruebas o los rastros de fallos de las sesiones de subagente importen.

   Usa --verbose cuando necesites IDs completos de ctx, IDs de proveedor, citas y comandos de seguimiento copiables sin cambiar a JSON.

   Puedes escribir la transcripción de una sesión en un archivo temporal, verificar el tamaño del archivo y luego leer las partes relevantes:

   ctx show session <ctx-session-id> --format markdown --out /tmp/ctx-session.md
   wc -c /tmp/ctx-session.md
   

   En Codex, ctx excluye el árbol de sesiones activas por defecto cuando CODEX_THREAD_ID está disponible, para que el prompt actual y los subagentes no dominen la recuperación histórica. Usa --include-current-session solo cuando el árbol de sesiones activas sea el objetivo.

3. Inspecciona los resultados relevantes antes de confiar en ellos:

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

4. Localiza el material original del proveedor cuando la identidad de la fuente o las pistas de reanudación importen. provider_session_id es el UUID de reanudación de Codex:

   ctx locate event <ctx-event-id>
   ctx locate session <ctx-session-id>
   

5. Escribe una transcripción de las sesiones relevantes cuando tú, el humano u otro agente necesite un archivo:

   ctx show session <ctx-session-id> --format markdown --out <ruta-de-salida>
   

Cuándo es necesario acotar la búsqueda

Varía la consulta y usa filtros de búsqueda antes de sacar conclusiones. Las acciones de seguimiento útiles incluyen búsqueda densa de eventos, búsqueda limitada a una sesión y comprobaciones de ubicación de la fuente:

ctx search "<variante de consulta>" --events --refresh off
ctx search "<consulta>" --session <ctx-session-id> --refresh off
ctx search "<consulta>" --include-subagents --refresh off
ctx show event <ctx-event-id> --window 5
ctx show session <ctx-session-id>
ctx locate event <ctx-event-id>
ctx locate session <ctx-session-id>

Las ventanas de resultados de búsqueda tienen límites. No afirmes recuentos exactos de todo el corpus ni una auditoría completa a partir del número de resultados devueltos. Si la conclusión solicitada no puede respaldarse con la evidencia de búsqueda, show y localización, indica esa limitación e informa la evidencia más sólida recuperada.

Para consultas avanzadas o enumeración determinista completa de eventos, usa ctx list events. Lee la documentación completa de filtros, rangos, cursores y salida antes de usarlo:

ctx docs show event-queries

Informes de investigación histórica

Cuando se te pida investigar un tema histórico, mantente en modo de solo lectura a menos que el usuario también solicite ediciones. El agente escribe el informe; ctx solo recupera material de la fuente local.

1. Reformula el tema, el alcance y la extensión deseada si el prompt es ambiguo. Por defecto, prefiere informes concisos; usa un informe más extenso cuando el usuario solicite cronología, alternativas o evidencia detallada.

2. Ejecuta varias búsquedas dirigidas. Varía los términos de consulta entre la redacción del usuario, los nombres de archivos o módulos, el texto de error, los comandos, los nombres de rama y los términos de decisión. Empieza con ctx search "<tema>", luego amplía con --term o acota con --workspace, --provider, --file, --since o --session <ctx-session-id>. Usa --include-subagents cuando es probable que las revisiones, los intentos de implementación, la salida de las pruebas o los rastros de fallos se encuentren en sesiones delegadas. Añade --refresh off cuando el informe no deba actualizar el índice local de ctx.

3. Inspecciona las fuentes relevantes antes de sacar conclusiones. Prefiere ctx show event para un resultado más las interacciones cercanas, y ctx show session cuando el arco completo de la sesión importe:

   ctx show event <ctx-event-id> --window 5
   ctx show session <ctx-session-id>
   

   Usa el modo completo o de registro solo cuando la salida predeterminada omita la evidencia necesaria.

4. Compara la evidencia entre sesiones. Anota acuerdos, conflictos, resultados obsoletos y lagunas donde las búsquedas no encontraron evidencia.

5. Produce el informe como síntesis del agente con citas.

Forma del informe conciso:

• respuesta o hallazgo;
• IDs de ctx de respaldo más sólidos;
• salvedades o lagunas importantes;
• paso opcional de búsqueda o verificación adicional.

Forma del informe extenso:

• pregunta y alcance;
• método de búsqueda, incluyendo las consultas y filtros clave;
• hallazgos o cronología;
• tabla de evidencia con proveedor, ID de sesión de ctx, ID de evento de ctx cuando esté disponible, y por qué cada fuente es importante;
• conflictos, lagunas y seguimiento sugerido.

Reglas de citación

• Cita el material de ctx cuando afecte a tu respuesta o implementación.
• Incluye el proveedor, el ID de sesión de ctx, el ID de evento de ctx cuando esté disponible, el ID de sesión del proveedor cuando esté disponible.
• Si sintetizas a partir de múltiples fragmentos, etiqueta la conclusión como tu síntesis y cita los fragmentos de respaldo.
• Si un evento o sesión citada está ausente de la generación Principal actual, indícalo y considera si un ctx import explícito es apropiado.

Reglas de seguridad

• Prefiere la salida de texto para la lectura del agente. Usa JSON solo para scripts, jq o extracción exacta de campos, y mantén las salidas JSON pequeñas.
• No digas que ctx infirió una decisión a menos que el texto citado establezca explícitamente esa decisión.
• No afirmes que ctx escribió un análisis de modelo.
• No pegues transcripciones sin procesar, cargas JSON grandes, secretos, tokens o rutas privadas en un informe visible para el usuario. Resume la evidencia revisada y cita solo fragmentos cortos necesarios para respaldar una afirmación.
• Trata ~/.ctx, las rutas de las transcripciones del proveedor y la salida JSON como historial local privado a menos que el usuario solicite explícitamente compartir los extractos revisados.