ctx: Local Search for Coding Agent History

ctx: Local Search for Coding Agent History

ctx enables agents to recover past context from local history

Coding agents typically begin each session without memory of previous interactions. While they can inspect a repository's current state, they often lack access to the previous discussions, rejected approaches, and failed commands that led to the current codebase. ctx solves this by indexing local agent history files into a local SQLite database, allowing current and future agents to retrieve specific prior events and decisions using a CLI.

Token-efficient retrieval vs. raw transcript search

Searching through raw transcripts is often prohibitively expensive in terms of token usage. 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 an entire transcript into a model's context window, ctx returns ranked, cited matches. This prevents the "token-heavy" nature of raw search from rendering history unusable for the agent.

Technical architecture and privacy

Written in Rust, ctx operates as a local-first tool that requires no background services or API keys. It functions through a specific pipeline:

  1. Discovery: ctx identifies supported local provider history files on the machine.
  2. Import: It imports persisted records and normalizes session, event, and touched-file metadata.
  3. Storage: Data is stored in a local SQLite index optimized for retrieval.

To maintain privacy, the index remains local and private by default. The tool does not send prompts, transcripts, or history to cloud services. However, because transcript text is preserved (including local paths and potential secrets), users are cautioned to review output before sharing it outside their machine.

Supported agents and integration

ctx can discover and import history from a wide range of agent harnesses, including:

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

Users can integrate ctx as an "Agent Skill" via npx skills add ctxrs/ctx or through specific plugin installs for tools like Cursor and Claude Code, enabling the agents themselves to call the search CLI.

Comparison to other memory tools

ctx differs from typical agent memory tools and codebase mapping tools in its focus on the "why" behind the code:

  • Agent Memory Tools: Often save compact facts or vectors, which lack the evidence needed to understand why a specific decision was made or why a command failed.
  • Codebase Graphs (e.g., Graphify): Map the current state of files and symbols but do not capture the historical process of how the repository changed.
  • Grep/Log Search: While possible, ctx provides a structured, indexed approach that is more efficient than manual grep-ing of log files.

Community perspectives and discussion

While the utility of a structured search tool is clear, some users on Hacker News noted that certain agents already possess the ability to search their own history.

"I often tell Claude Code to look at previous sessions in ~/.claude and it’s happy to jq/grep its way through them with no special tool."

Other contributors highlighted the need for a standardized format for agent transcripts and logs to simplify the creation of such tools across different providers. The author of ctx, luca-ctx, noted that building the tool made it the obvious that a standard specification for agent transcripts is necessary.

Sources