ctx: Local Search for Coding Agent History

ctx enables agents to recover past context from local session logs

Coding agents typically start each session from a blank slate. While they can inspect a current repository, they often lack the way to recover the specific discussions, rejected approaches, and failed commands from previous sessions. ctx solves this by indexing local agent history files into a local SQLite database, providing a CLI that current and future agents can use to find prior work and avoid repeating mistakes.

Token-efficient retrieval vs. raw transcript search

Searching agent history via raw transcripts is often token-heavy, making it impractical for large histories. ctx is designed to be up to 50x more token-efficient than raw search by structuring history into sessions, events, and metadata.

Instead of feeding a massive transcript into a model's context window, ctx returns ranked cited matches. This allows agents to access meaningful history with significantly fewer tokens. For example, the project documentation cites a case where a ctx search required 917 tokens compared to 45,734 tokens for a raw transcript search.

Technical architecture and privacy

Written in Rust, ctx operates as a local-first tool that does not require a background service. It discovers supported local provider history files, imports them, and stores normalized metadata in a local SQLite index optimized for retrieval.

Key privacy and security characteristics include:

Local and Private: The index is stored locally by default.
No Cloud Dependency: ctx does not send prompts, transcripts, or history to cloud services, nor does it require API keys.
No Repository Pollution: The tool does not write data into the user's source repositories.
Data Preservation: Transcript text is preserved exactly as is, including local paths and secrets, meaning users should review output before sharing it externally.

Supported agent harnesses

ctx can discover and import history from several popular agent harnesses. Users can verify which sources are currently importable on their specific machine using the command ctx sources --json.

Supported agents include:

Claude Code
Cursor
Codex
Pi
OpenCode
Antigravity / Gemini CLI
Factory AI Droid
Copilot CLI

CLI usage and integration

ctx provides a comprehensive CLI for managing and searching history. Key commands include:

ctx setup: Indexes all existing local agent sessions.
ctx search "query": Searches prior work using natural language.
ctx search --file <path>: Searches sessions or events that touched a specific file.
ctx show event <id>: Prints the matching part of an old transcript with a configurable window.
ctx show session <id>: Prints a compact transcript of the original session.
ctx sql: Allows read-only SQL inspection of the local index data.

For deeper integration, ctx can be added as an "Agent Skill" via npx skills add ctxrs/ctx, allowing agents to call the search tool directly during a task.

Comparison with other memory tools

ctx differs from other common AI memory approaches:

Vs. Memory Tools: While some tools save compact facts or vectors, ctx preserves the original session and event context, providing evidence of why a decision was made or what specifically failed.
Vs. Codebase Graphs: Tools like Graphify map the current state of the repository (symbols and imports). ctx instead maps the process of how the repository reached its current state through agent interactions.
Vs. Grep/Log Search: While users can manually grep logs, ctx provides a structured, ranked, and token-efficient way to retrieve specific events.

Community insights and counterpoints

Discussion around the tool highlights both its utility and potential overlaps with existing workflows. Some users noted that certain agents, such as Claude Code, already possess internal tools to rebuild edit history or can be directed to grep through their own session files (e.g., in ~/.claude).

Other community members suggested improvements, such as building an index on top of data without requiring ingestion into a database, or raising concerns about how the tool prevents agents from trusting stale or outdated history. The author of ctx also noted that the project's development revealed a need for a standardized specification for agent transcripts and logs, similar to the ACP for runtime events.