ctx review Native history search, citations and incremental imports
Testing ctx 2.4.1 with artificial Claude Code and Codex transcripts: cross-provider search, exact readback, stable IDs, manual refresh and partial-rejection outcomes.
AgentIndex · Published 2026-11-07 · Updated 2026-11-07
ctx searches existing coding-agent histories and retrieves their recorded content. The practical question is whether a search hit leads back to inspectable evidence, how new records become visible and what an import error means. We tested the native Claude Code and Codex workflow with the published binary.
Version 2.4.1 completed native imports, cross-provider lexical search, event/session readback, stable IDs on repeat import and appended-record refresh. Two boundaries mattered: an explicitly unrefreshed search did not see a new append, and an import with usable records plus one malformed line returned exit zero while reporting partial rejection in JSON.
A fixed release and independent storage
On November 7, 2026, we downloaded the macOS ARM64 release asset for 2.4.1. SHA-256 3876f1c197ac2a6dc74ae0020a4aa3a38dd3cf055c857142d9e4fddcfbd8593d matched the digest returned by GitHub's release-asset API. Source inspection used tag v2.4.1, commit 33ba4645b620fd89d138c6db1fabf33096a0ee16. Execution used macOS 26.6.2. Release
We did not scan personal Claude or Codex directories. Our three artificial sessions used native JSONL formats: two Claude sessions and one Codex session, covering migration rollback and unrelated layout work. A dedicated CTX_DATA_ROOT persisted manual indexing and disabled automatic source discovery. Analytics, upgrades and semantic search were off. Imports named exact artificial roots and skipped Blame.
The fixture and raw results retain eighteen command calls. The release binary and actual local index performed retrieval; no simulated response or model output replaced them.
| Exercise | Observed behavior |
|---|---|
| Native Claude/Codex import | Both providers became searchable |
| Migration/rollback query | Relevant sessions from both providers returned |
| Provider/workspace filtering | Selected results stayed within the tested scope |
| Event and session retrieval | Expected content and Chinese text preserved |
locate event | Returned Core source identity and provider metadata |
| Repeated identical import | Selected hit stayed singular with stable event/session IDs |
| Append then refresh | Invisible with refresh off; found after explicit incremental import |
| One malformed JSON line | Usable content remained searchable; one rejection reported with exit zero |
The small corpus establishes no real-history recall rate, Chinese retrieval-quality score or token-savings ratio.
Native formats require correct roots and identities
ctx is not simply a full-text reader for arbitrary JSON. The tested native source required a directory root, and the Claude filename had to agree with the record's session identity. Unsupported shapes were rejected. We corrected our artificial preparation before the final run rather than relaxing these checks. Claude path implementation
On macOS, /tmp aliases /private/tmp. The runner resolves canonical paths so an alias-related rejection is not misreported as transcript parsing failure.
Manual indexing also does not mean imports perform no worker activity. Explicit imports use finite Core workers to publish results; continuous automatic tracking is disabled. We persisted the setting in the independent root so child processes had the same configuration. Configuration implementation
Follow hits into their recorded content
A unique-term hit included session and event IDs, a snippet and citations. We passed its event ID to show event with a surrounding window, then retrieved the session by ID. Both preserved expected content, including Chinese text.
A broader query returned Claude and Codex sessions; a provider filter restricted it to Codex. The unrelated layout session did not enter the tested migration scope. These are selected filtering checks, not coverage of every provider or subagent relationship.
Identity is different from a physical source location. Our locate event response supplied a Core source ID, native session ID and source format, without the original JSONL path. We therefore do not claim arbitrary hits can jump directly to a physical file and line. Search contracts
Refresh controls visibility
Importing identical inputs again left the selected result singular and retained its IDs. Input hashes also confirmed that import and retrieval had not rewritten our source files.
We appended a new Claude message. Searching with --refresh off found no new marker. After an explicit incremental import, another CLI process found it. This validates the tested publication boundary, not automatic watching or an assumption that every search discovers new data.
An existing snapshot can be useful for fast inspection. Fresh-record workflows need an explicit import or appropriate refresh policy. Automation should understand both what a result contains and how current its index is.
Partial acceptance requires inspecting the response
Adding a malformed JSON line to otherwise usable history preserved searchable valid content. The import returned completed_with_rejections, a rejection count of one and a diagnostic with line information, while exiting zero.
That is a partial-success outcome. It should neither be called complete ingestion nor generalized into a tool-wide failure. A pipeline that cares about rejected records needs to inspect outcome and rejection counts, not process status alone.
Our artificial transcript also contained an explicitly fake token-shaped string. Event readback preserved it. Original-text retrieval is not automatic redaction. No real credential, remote sharing or external semantic executor participated.
Adoption decision
ctx merits a controlled trial when prior coding sessions contain decisions and failed approaches worth recovering. Start with a representative copy, identify native roots, choose index freshness and verify the search-to-show chain while handling partial rejection.
We did not test semantic models, every provider, Blame attribution, graph indexing, Sift, persistent daemon operation, hosted sharing or other operating systems. We did not reproduce README speed or token ratios. For editing a curated knowledge base rather than searching prior sessions, see the OpenKnowledge review. For measurable web-performance reports, see the WebPerf Snippets review.