Progressive Retrieval Workflow
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Progressive Retrieval Workflow is the core operational methodology of the cxs CLI tool. It is designed to efficiently search and retrieve local Codex session logs by moving from high-level state inspection to granular content reading. Instead of performing bulk operations, the workflow emphasizes pinpointing candidate sessions first and then expanding context only as needed.
The primary chain of execution follows a fixed sequence: status -> ensure selector coverage -> find/list -> read-range/read-page. This approach ensures that the local SQLite index is consistent with raw session data before any content queries are executed, preventing "cold starts" or full transcript dumps that would be computationally expensive or provide excessive irrelevant information.
Sources: README.md:8-13, AGENTS.md:14-15, skill-packages/cxs/SKILL.md:46-47
Core Workflow Phases
The workflow is categorized into three distinct logical phases: Coverage Validation, Candidate Recall, and Granular Reading.
Phase 1: Coverage Validation (status & sync)
Before searching, the system must verify the "coverage" of the target session logs. The status command provides an inventory of raw sessions and the current state of the index. If the required data range (defined by a selector) is missing or stale, a sync operation is triggered.
status --selector: A read-only operation that reports the freshness and recommended actions for a specific scope.sync --selector: The only write operation in the system. It reconciles the SQLite index with raw JSONL source files within the defined selector scope.
Sources: AGENTS.md:16-19, skill-packages/cxs/references/cli-surface.md:12-25
Phase 2: Candidate Recall (find & list)
Once coverage is confirmed, the user identifies potential sessions. This phase focuses on "recall"—finding the right session UUID and a specific "match anchor" (sequence number).
find: Performs full-text search (FTS) across session titles, summaries, and message content. It returns ranked candidates with snippets.list: Used when the user has metadata constraints (like a specific project directory or date range) rather than keyword intent.
Sources: README.md:61-68, AGENTS.md:21-25, skill-packages/cxs/references/cli-surface.md:58-75
Phase 3: Granular Reading (read-range & read-page)
The final phase involves reading the actual dialogue context. The workflow mandates starting with a small window around a match and only expanding if necessary.
read-range: Displays a small message window (e.g., 4 messages before and 8 messages after) around a specific sequence number (--seq) or sub-query (--query).read-page: Used as a fallback to read larger chunks of a session via offset and limit.
Sources: skill-packages/cxs/references/progressive-workflow.md:7-14, skill-packages/cxs/references/cli-surface.md:77-90
Workflow Architecture
The following diagram illustrates the decision logic and data flow within the progressive retrieval system:
The diagram shows the mandatory check for coverage before proceeding to search, and the tiered reading approach.
Sources: skill-packages/cxs/references/progressive-workflow.md:3-17, skill-packages/cxs/SKILL.md:46-55
Selectors and Scope Constraints
Selectors are structural JSON objects used to constrain both indexing (sync) and retrieval (find/list). They ensure that the agent only operates on relevant subsets of the local history.
| Selector Kind | Description | Use Case |
|---|---|---|
all | Entire session root | Global history archaeology |
cwd | Matches a specific project path | "What did I do in this project?" |
date_range | From/To date constraints | "What happened last week?" |
cwd_date_range | Intersection of path and time | Pinpointing a specific work session |
Sources: README.md:73-83, skill-packages/cxs/references/cli-surface.md:32-38
Logic and Data Flow Sequence
The interaction between the user (or agent) and the various system components follows a synchronous sequence to ensure data integrity.
This sequence ensures that content answers always come from the index, while status acts as the bridge between raw storage and the indexed truth.
Sources: AGENTS.md:16-19, skill-packages/cxs/references/cli-surface.md:12-25, skill-packages/cxs/references/failure-cookbook.md:59-72
Implementation Invariants
For technical accuracy, several constraints must be maintained throughout the workflow:
- Single Write Entry:
syncis the only command that modifies the database. Sources: AGENTS.md:18 - Match Anchors: If a search hit is marked as
matchSource = "session", it lacks a specific message sequence; the workflow must pivot toread-pagerather than guessing a--seq. Sources: README.md:118-120 - Time vs. Relevance:
finddefaults to relevance. For "latest" queries, the--sort endedflag must be explicitly combined with--exclude-sessionto avoid self-hits from the current active session. Sources: skill-packages/cxs/references/progressive-workflow.md:16-18
Conclusion
The Progressive Retrieval Workflow provides a structured, multi-stage approach to local session archaeology. By enforcing a "coverage-first" policy through the status and sync commands, it guarantees that searches are performed against a fresh and relevant index, while the tiered read-range and read-page commands ensure that context is retrieved efficiently without overwhelming the user or system resources.