High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• src/parser.ts
• skill-packages/cxs/references/json-schema.md
• skill-packages/cxs/references/cli-surface.md
• skill-packages/cxs/references/progressive-workflow.md
• src/source-inventory.test.ts

cxs is a local-first, progressive retrieval CLI designed to index and search Codex session logs. Unlike real-time sync daemons or GUI applications, cxs operates as a retrieval engine that prioritizes manual incremental synchronization and a "find-then-read" workflow. It bridges the gap between raw local JSONL logs and structured, searchable data using a SQLite backend.

The system is architected around a multi-stage retrieval chain: session/message recall, followed by heuristic reranking, and finally progressive content reading. This design ensures that users or agents can locate specific historical context within vast amounts of local logs without loading unnecessary data into memory.

Sources: AGENTS.md:3-12, README.md:8-19

Core System Components

The architecture is divided into logical modules that handle CLI interaction, raw file parsing, data persistence, and query orchestration.

Component	Responsibility
CLI Surface (cli.ts)	Orchestrates commands (status, sync, find, etc.) and handles JSON/Text output.
Indexer (indexer.ts)	Manages the synchronization process and index updates.
Parser (parser.ts)	Processes Codex JSONL files, extracts metadata, and generates summaries for indexing.
DB Facade (db.ts)	Provides a SQLite interface; includes sub-modules for schema management and coverage tracking.
Query Facade (query.ts)	Orchestrates search, snippet generation, and session reading.
Selector Engine (selector.ts)	Handles path-based and date-based scoping rules for synchronization and queries.
Source Inventory	Scans raw session metadata to determine coverage and recommended actions.

Sources: AGENTS.md:38-48, skill-packages/cxs/references/cli-surface.md:1-10

Data Flow and Retrieval Lifecycle

The system follows a strict "progressive" lifecycle to ensure data freshness and retrieval accuracy.

Retrieval Workflow

1. Status & Coverage: The user/agent checks status to determine if the desired selector (e.g., a specific project path) is indexed and up-to-date.
2. Sync (Write Path): If coverage is missing or stale, sync --selector parses the raw JSONL files and populates the SQLite index.
3. Find/List (Recall): Search queries use Full-Text Search (FTS) across messages and session metadata.
4. Read (Projection): Once a session is identified, read-range or read-page projects a specific window of messages for consumption.

The diagram shows the transition from raw file scanning to structured search and granular reading.
Sources: AGENTS.md:14-25, README.md:10-15, skill-packages/cxs/references/progressive-workflow.md:3-15

Indexing and Parsing Logic

The parser.ts module is the gatekeeper for data entering the index. It transforms unstructured JSONL events into a structured ParsedSessionResult.

Key Parsing Features:

• Metadata Extraction: Captures session_uuid, cwd, and model from session_meta and turn_context events.
• Summary Generation: Builds summary_text by normalizing the first/latest user and assistant messages.
• Enrichment: Extracts compacted messages and reasoning_summary text for session-level recall.
• Filtering: Ignores internal Codex markers (e.g., "TRANSCRIPT START") to keep the index clean.

FTS Weighting

Session-level recall utilizes explicit field weighting in SQLite FTS to prioritize titles over reasoning:

• Title: 8.0
• Compact Text: 4.0
• Summary Text: 3.0
• Reasoning Summary: 1.2

Sources: src/parser.ts:14-80, AGENTS.md:21-25

Data Model (Schema)

cxs persists data in two primary tables, supplemented by virtual FTS tables for high-performance searching.

The ER diagram illustrates the relationship between session metadata, message sequences, and the coverage tracking system.
Sources: skill-packages/cxs/references/json-schema.md:113-170

Retrieval Implementation Details

The retrieval chain is designed to handle both specific message hits and general session-level context.

Search and Reranking

When a query is issued, the system performs a dual recall:

1. Message Recall: Searches messages_fts for specific dialogue matches.
2. Session Recall: Searches sessions_fts for hits in titles or generated summaries.
3. Heuristic Rerank: Results are ranked by relevance (default) or by time (--sort ended).

Progressive Reading

To avoid massive JSON overhead, content is read in slices:

• read-range: Anchors on a specific message sequence number (seq) or performs a sub-query within a session to find a specific context window.
• read-page: Provides a paginated view of a session (e.g., offset 0, limit 40).

Sources: AGENTS.md:14-23, skill-packages/cxs/references/progressive-workflow.md:40-60, README.md:145-160

Infrastructure and Environment

cxs respects standard Unix environment variables and directory structures for storage.

Configuration	Default Value / Path	Priority
Source Directory	~/.codex/sessions	Manual via Selectors
Data Directory	~/.local/state/cxs/	CXS_DATA_DIR > $XDG_STATE_HOME
Index File	index.sqlite	Inside Data Directory
Runtime	Node.js >= 22	Required

Sources: README.md:70-85, package.json:35-40

Conclusion

The high-level architecture of cxs emphasizes a pull-based, incremental indexing model. By separating the raw session inventory from the searchable SQLite index, and providing a progressive read interface, the system maintains high performance even with large volumes of local Codex logs. The integration of structural "Selectors" ensures that retrieval can be scoped accurately to specific projects or timeframes, which is critical for agentic workflows.

Sources: AGENTS.md:3-30, README.md:1-25