ctxrs/ctx

ctx 是一个开源的 CLI 工具，用于在你的历史 coding agent 会话中进行快速本地搜索。 Coding agent 通常是从零开始的。它们可以检查当前的代码仓库，但往往无法恢复之前工作中的讨论、决策、失败的尝试、命令和测试结果。 这些会话中充满了有用的上下文： - 你的决策、限制、意图和被否决的方案 - 之前 agent 进行的 bug 调查、重构、文件路径、命令、补丁和笔记 ctx 会将这些日志索引到你机器上的 SQLite 中，然后为当前和未来的 agent 提供一个 CLI，以便在它们重复操作之前找到先前的讨论、命令或失败的尝试。 ## 安装和配置 ctx ``` curl -fsSL https://ctx.rs/install | sh ``` 可选，但建议用于 agent 会话： ``` npx skills add ctxrs/ctx ``` 如需在 Codex、Claude Code、Cursor 和原始 Agent Skills 中进行 marketplace/plugin 安装，请参阅 [Agent Skill 安装](docs/agent-skill-install.md)。 ## token 效率比原始记录搜索高 50 倍 通过将 agent 历史结构化为会话、事件、元数据和索引字段，然后返回带有引用的排序匹配结果，agent 能够以比原始搜索少得多的 token 访问有意义的历史记录。结果因查询和语料库而异，但原始搜索通常消耗大量 token，以至于效果等同于没有可用的历史记录。 ## 工作原理 你过去的 agent 会话存储在本地提供商的历史文件中。ctx 会发现受支持的来源，导入真实的持久化记录，并将规范化的会话、事件和被修改文件的元数据存储在专为检索优化的本地 SQLite 数据库中。 ctx 使用 Rust 编写并存储本地 SQLite 索引，因此搜索速度快、可脚本化，且不需要后台服务。 该索引默认是本地且私有的。文本记录会被完整保留，而不会隐藏本地路径或类似密钥的字符串，因此在将复制的输出共享到本机之外之前，请先进行审查。 ``` # 索引所有现有的本地 agent 会话 ctx setup # 你的 agent 可以使用自然语言搜索先前的工作 ctx search "failed migration" # 搜索涉及某个文件的会话/事件 ctx search --file crates/foo/src/lib.rs # 或者搜索多个术语 ctx search --term "failed migration" --term rollback --term "cursor rename" # 高级：使用只读 SQL 检查精确的本地索引数据 ctx sql "SELECT provider, COUNT(*) AS sessions FROM ctx_sessions GROUP BY provider" # 结果包括匹配的会话、片段和 ctx IDs # evt_01h... ses_01h... codex "migration expected the old cursor name" ... # 打印旧 transcript 的匹配部分 ctx show event --window 3 # 或者打印原始会话的精简 transcript ctx show session ``` 这些 ID 让你当前的 agent 能够根据需要从之前的会话中恢复尽可能多的上下文。 ctx 不会将你的 prompt、记录或索引的历史发送到云服务，不调用模型 API，不需要 API 密钥，也不会写入你的源代码仓库。 安装的二进制文件还包含本地文档和 man-page 生成功能： ``` ctx docs search "upgrade" ctx docs show cli-reference ctx docs man --print ctx ``` 官方安装程序管理的二进制文件支持签名的自我升级： ``` ctx upgrade status ctx upgrade check ``` 源码构建和包管理器安装的版本保持非托管状态，不会自我升级。 有关完整的流水线，请参阅 [ctx 的工作原理](https://ctx.rs/concepts/how-it-works)。有关快速首次运行，请参阅[快速入门](https://ctx.rs/first-search)。 ## 受支持的 agent 历史记录 支持意味着 ctx 能够发现或读取该工具持久化的本地历史记录，并将其导入到本地搜索索引中。在你的机器上使用 `ctx sources --json` 查看当前哪些来源是 `importable` 的。 | Agent 工具 | 支持情况 | | --- | --- | | Claude Code | 受支持 | | Codex | 受支持 | | Cursor | 受支持 | | Pi | 受支持 | | OpenCode | 受支持 | | Antigravity / Gemini CLI | 受支持 | | Factory AI Droid | 受支持 | | Copilot CLI | 受支持 | ## ctx 的对比 Agent 记忆工具通常保存紧凑的事实、摘要、向量或图节点。这些有助于维持稳定的偏好，但当下一个 agent 需要知道某个决策的来源、哪个命令失败或在原始对话中拒绝了什么时，这些信息的参考价值很弱。 Graphify 类工具回答的是不同的问题。它们映射当前的代码仓库：文件、符号、导入、文件夹和关系。而 ctx 搜索的是先前的 agent 会话，这些会话解释了在人和 agent 更改该代码库时发生了什么。 ctx 将检索与会话和事件绑定，因此另一个 agent 可以在使用源之前对其进行检查。阅读更多关于[agent 记忆](https://ctx.rs/comparisons/agent-memory)、[Graphify 类代码库图](https://ctx.rs/comparisons/codebase-graphs)以及[grep 或日志搜索](https://ctx.rs/comparisons/grep-log-search)的内容。 ## 探索文档 | 页面 | 涵盖内容 | | --- | --- | | [安装](https://ctx.rs/getting-started/install) | 安装 ctx，初始化本地存储，并索引发现的本地历史记录。 | | [快速入门](https://ctx.rs/first-search) | 搜索本地历史，检查事件，打开会话，并使用 JSON 输出。 | | [安装 ctx skill](https://ctx.rs/skill) | 使用开放的 skills 安装程序安装 agent 历史搜索 skill。 | | [Agent 插件安装](docs/agent-skill-install.md) | 通过 Codex、Claude Code、Cursor 或原始 skill 文件夹安装 ctx skill。 | | [SDK](docs/sdks.md) | 从 TypeScript、Python、Rust、Go、JVM、Swift 或 .NET 代码中使用 ctx agent 历史搜索。 | | [自定义历史插件](docs/history-source-plugins.md) | 为 ctx 原生不支持的 agent 格式构建高级本地适配器。 | | [Cursor](https://ctx.rs/agents/cursor) | 导入 Cursor agent 记录，并要求 Cursor 在编辑之前引用检索到的本地历史记录。 | | [工作原理](https://ctx.rs/concepts/how-it-works) | 了解发现、导入、SQLite 存储、搜索刷新和带引用的检索。 | | [受支持的 agent](https://ctx.rs/concepts/supported-agents) | 查看 ctx 如今能够发现、导入和搜索哪些 agent 历史记录。 | | [CLI 参考](https://ctx.rs/reference/cli) | 查看设置、状态、来源、导入、显示、定位、搜索、SQL、MCP 和 doctor。 |

标签：AI编程助手, Rust, SOC Prime, SQLite, 可视化界面, 开发工具, 文档结构分析, 日志审计, 本地搜索, 网络流量审计, 逆向工具, 通知系统