ctx 本地代理历史搜索
为编码代理检索本机上的历史会话、决策与失败记录。
这个 Agent 能做什么，适合哪些场景？
ctx 是一个开源 Rust CLI，用于快速搜索本机保存的编码代理会话历史。它发现受支持代理的本地历史文件，导入真实持久化记录，并将会话、事件和受影响文件的元数据规范化存入本地 SQLite 索引。当前或后续代理可通过命令行检索排序后的匹配结果、片段和 ctx ID，再回看原始事件或会话上下文。它不需要后台服务、模型 API 或 API 密钥，默认在本地私有运行。适合希望避免重复排查、并需要核验过去决策和命令结果的开发工作流。
运行 ctx setup 会索引已存在的本地代理会话。ctx search "failed migration" 可按自然语言查询历史，ctx search --file crates/foo/src/lib.rs 可按触及的文件筛选，ctx search --term "failed migration" --term rollback --term "cursor rename" 可组合多个术语。它返回匹配的会话、片段和 ctx ID；随后可用 ctx show event <ctx-event-id> --window 3 查看事件附近的原始记录，或用 ctx show session <ctx-session-id> 输出紧凑会话记录。ctx sql "SELECT provider, COUNT(*) AS sessions FROM ctx_sessions GROUP BY provider" 提供对本地索引的只读 SQL 查询；已安装二进制还提供 ctx docs、ctx docs man --print ctx、ctx upgrade status 和 ctx upgrade check。
- 使用 Codex 排查迁移失败的开发者，在再次修改前搜索过去失败的命令、讨论和回滚方案。
- 维护长期 Rust 或多工作树项目的工程师，按文件路径检索此前哪些代理会话曾触及某个实现文件。
- 接手同一仓库的团队成员，需要通过 ctx ID 回看此前代理为何拒绝某种重构方案。
- 同时使用 Claude Code、Cursor、Pi 或 GitHub Copilot CLI 的开发者，希望将可导入的本地会话统一检索。
- 需要对本机代理历史做脚本化盘点的开发者，使用只读 SQL 按 provider 统计已索引会话。
这个 Agent 有哪些优点和局限？
- 保留会话与事件的可追溯关联：搜索结果可通过 ctx ID 回到原始事件或完整会话，而不只是摘要。
- 将多种代理的本地历史规范化为 SQLite 索引，并支持自然语言、文件路径、多术语和只读 SQL 查询。
- 无后台服务、无模型 API 调用、无 API 密钥要求，搜索可在本机脚本化执行。
- README 明确列出大量受支持的代理历史来源，并提供 Codex、Claude Code 和 Cursor 的技能安装路径。
- 价值取决于本机是否已有可发现、可导入的代理历史；应先用 `ctx sources --json` 核实来源状态。
- 索引会保留转录文本，不会隐藏本地路径或看似机密的字符串；对外分享输出前需要人工审查。
- 它检索的是过去会话，不是当前代码库的符号、导入关系或目录图谱工具。
- 官方签名自升级只适用于安装器管理的二进制；源码构建和包管理器安装不会自行升级。
如何安装或部署这个 Agent？
macOS、Linux 和 FreeBSD：curl -fsSL https://ctx.rs/install | sh。Windows PowerShell：irm https://ctx.rs/install.ps1 | iex。安装后运行 ctx setup 初始化并索引发现到的本地历史。README 未要求 API 密钥或云端凭据；官方安装程序会通过网络下载二进制，而已安装后的搜索使用本地 SQLite 索引。
如何使用这个 Agent？
首次执行：ctx setup。随后例如执行 ctx search "failed migration" 搜索历史，或执行 ctx search --file crates/foo/src/lib.rs 按文件搜索。结果中的 ctx ID 可用于 ctx show event <ctx-event-id> --window 3 或 ctx show session <ctx-session-id>，以检查原始上下文。用 ctx sources --json 查看本机当前哪些历史来源可导入。
这个 Agent 与同类方案有什么区别？
与保存紧凑事实、摘要、向量或图节点的代理记忆工具相比，ctx 面向需要追溯原始决策、失败命令和被拒绝方案的会话证据。与 Graphify 风格的代码库图谱工具相比，它搜索的是解释代码变更过程的既有代理会话，而不是映射当前仓库的文件、符号和关系。README 也将其与 grep 或日志搜索作比较，强调结构化、排序并带引用的检索。