ctxrs/ctx

Recherche d'Historique d'Agent ctx

Utilisez ctx chaque fois que vous devez référencer des sessions antérieures d'agents de codage. Ces transcriptions peuvent contenir des intentions utilisateur, des décisions, des chronologies de travail passées, des tentatives précédentes, et ce qui a fonctionné ou échoué.

Utilisez cette compétence dans deux modes :

• récupération avant le travail, lorsque des sessions précédentes peuvent contenir des décisions, commandes, échecs, ou citations qui affectent la tâche en cours ;
• rapports de recherche historique, lorsque l'utilisateur demande à un agent ou à un sous-agent en lecture seule de rechercher un sujet historique parmi les sessions d'agents locales précédentes.

Prérequis

• Exigez que la CLI ctx soit installée et configurée. Si elle est manquante et que l'installation d'outils est appropriée pour la tâche, installez-la avec :

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

• La première configuration peut prendre du temps pendant que ctx indexe les sessions passées. Si nécessaire, laissez-le tourner en arrière-plan ou dans tmux, ou attendez qu'il termine.

• Si ctx reste indisponible, dites que la recherche d'historique local est indisponible et n'inventez pas de résultats.

Flux de travail

1. Confirmez que ctx est prêt lorsque vous démarrez à partir d'un contexte froid :

   ctx status
   ctx sources
   

   Utilisez ctx status --format json ou ctx sources --format json uniquement lorsqu'un script a besoin de champs exacts.

2. Recherchez d'abord en langage naturel. Ajoutez des termes ou des filtres si nécessaire :

   ctx search "<requête>"
   ctx search "<requête>" --refresh off
   ctx search "<requête>" --provider codex
   ctx search "<requête>" --workspace <espace_de_travail>
   ctx search "<requête>" --file <chemin>
   ctx search "<requête>" --since 30d
   ctx search "<requête>" --term "<terme_connexe>" --term "<texte_d_erreur>"
   ctx search "<requête>" --session <ctx-session-id>
   ctx search "<requête>" --verbose
   

   Utilisez la sortie texte par défaut pour la lecture par l'agent. N'ajoutez pas --format json pour la recherche ou l'affichage sauf si vous le pipez dans jq ou un script, ou si vous avez besoin de champs exacts lisibles par machine. La sortie JSON est beaucoup plus volumineuse et peut rapidement consommer la fenêtre de contexte.

   Lorsque la requête demande un historique ou un rapport sur un sujet à travers plusieurs sessions, exécutez plusieurs requêtes ctx search avec différentes formulations et filtres pour trouver des sessions prometteuses. Utilisez ctx search "<requête>" --session <ctx-session-id> lorsqu'une session semble pertinente et que vous avez besoin de correspondances denses au niveau des événements de cette session.

   La recherche par défaut renvoie les sessions d'agents principaux afin que l'intention humaine et les décisions restent proéminentes. Utilisez --include-subagents lorsque les détails d'implémentation, les notes de révision de code, les sorties de test, ou les traces d'échec provenant de sessions de sous-agents sont susceptibles d'être importants.

   Utilisez --verbose lorsque vous avez besoin des identifiants complets ctx, des identifiants fournisseur, des citations, et des commandes de suivi copiables sans passer au JSON.

   Vous pouvez écrire une transcription de session dans un fichier temporaire, vérifier la taille du fichier, puis lire les parties pertinentes :

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

   Dans Codex, ctx exclut l'arbre de session active par défaut lorsque CODEX_THREAD_ID est disponible, afin que la requête en cours et les sous-agents ne dominent pas la recherche historique. Utilisez --include-current-session uniquement lorsque l'arbre de session active est la cible.

3. Inspectez les résultats pertinents avant de vous y fier :

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

4. Localisez le matériel original du fournisseur lorsque l'identité de la source ou les indices de reprise sont importants. provider_session_id est l'UUID de reprise Codex :

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

5. Écrivez une transcription des sessions pertinentes lorsque vous, l'humain, ou un autre agent avez besoin d'un fichier :

   ctx show session <ctx-session-id> --format markdown --out <chemin_de_sortie>
   

Quand la Recherche a Besoin d'Être Affinée

Variez la requête et utilisez les filtres de recherche avant de tirer des conclusions. Les suivis utiles incluent la recherche dense d'événements, la recherche limitée à une session, et les vérifications de localisation des sources :

ctx search "<variante de requête>" --events --refresh off
ctx search "<requête>" --session <ctx-session-id> --refresh off
ctx search "<requête>" --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>

Les fenêtres de résultats de recherche sont limitées. Ne prétendez pas avoir des comptages exacts sur l'ensemble du corpus ou un audit complet à partir du nombre de résultats retournés. Si la conclusion demandée ne peut pas être étayée par des preuves de recherche, d'affichage et de localisation, indiquez cette limite et rapportez les preuves les plus solides récupérées à la place.

Pour des requêtes avancées ou une énumération déterministe complète des événements, utilisez ctx list events. Lisez la documentation complète sur les filtres, plages, curseurs et sorties avant utilisation :

ctx docs show event-queries

Rapports de Recherche Historique

Lorsqu'on vous demande de rechercher un sujet historique, restez en lecture seule sauf si l'utilisateur demande également des modifications. L'agent rédige le rapport ; ctx récupère uniquement le matériel source local.

1. Reformulez le sujet, la portée et la longueur souhaitée si la requête est ambiguë. Préférez des rapports concis par défaut ; utilisez un rapport plus long lorsque l'utilisateur demande une chronologie, des alternatives ou des preuves détaillées.

2. Effectuez plusieurs recherches ciblées. Variez les termes de requête entre la formulation de l'utilisateur, les noms de fichiers ou de modules, le texte d'erreur, les commandes, les noms de branches et les termes de décision. Commencez par ctx search "<sujet>", puis élargissez avec --term ou affinez avec --workspace, --provider, --file, --since, ou --session <ctx-session-id>. Utilisez --include-subagents lorsque les révisions, les tentatives d'implémentation, les sorties de test ou les traces d'échec sont susceptibles de se trouver dans des sessions déléguées. Ajoutez --refresh off lorsque le rapport ne doit pas mettre à jour l'index ctx local.

3. Inspectez les sources ciblées avant de tirer des conclusions. Préférez ctx show event pour un résultat plus les échanges voisins, et ctx show session lorsque l'arc complet de la session est important :

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

   Utilisez le mode complet ou log uniquement lorsque la sortie par défaut omet des preuves nécessaires.

4. Comparez les preuves entre les sessions. Notez les accords, les conflits, les résultats obsolètes et les lacunes où les recherches n'ont pas trouvé de preuves.

5. Produisez le rapport sous forme de synthèse d'agent avec citations.

Format de rapport concis :

• réponse ou constatation ;
• identifiants ctx les plus solides pour étayer ;
• mises en garde ou lacunes importantes ;
• étape facultative de recherche ou de vérification supplémentaire.

Format de rapport long :

• question et portée ;
• méthode de recherche, y compris les requêtes et filtres clés ;
• constatations ou chronologie ;
• tableau des preuves avec fournisseur, identifiant de session ctx, identifiant d'événement ctx lorsqu'il est disponible, et pourquoi chaque source est importante ;
• conflits, lacunes et suivi suggéré.

Règles de Citation

• Citez le matériel ctx lorsqu'il affecte votre réponse ou votre implémentation.
• Incluez le fournisseur, l'identifiant de session ctx, l'identifiant d'événement ctx lorsqu'il est disponible, et l'identifiant de session fournisseur lorsqu'il est disponible.
• Si vous synthétisez plusieurs extraits, étiquetez la conclusion comme votre synthèse et citez les extraits justificatifs.
• Si un événement ou une session cité est absent de la génération Core actuelle, dites-le et considérez si un ctx import explicite est approprié.

Règles de Sécurité

• Préférez la sortie texte pour la lecture par l'agent. Utilisez JSON uniquement pour les scripts, jq, ou l'extraction exacte de champs, et gardez les sorties JSON petites.
• Ne dites pas que ctx a déduit une décision à moins que le texte cité n'énonce explicitement cette décision.
• Ne dites pas que ctx a rédigé une analyse de modèle.
• Ne collez pas de transcriptions brutes, de gros blocs JSON, de secrets, de jetons ou de chemins privés dans un rapport destiné à l'utilisateur. Résumez les preuves examinées et citez uniquement de courts extraits nécessaires pour étayer une affirmation.
• Considérez ~/.ctx, les chemins de transcriptions fournisseur et la sortie JSON comme un historique local privé, sauf si l'utilisateur demande explicitement de partager des extraits examinés.