ctxrs/ctx 源码：https://github.com/ctxrs/ctx

ctx 是一个开源 CLI，用于快速本地搜索过去的编码代理会话。编码代理通常从零开始。它们可以检查当前仓库，但往往无法恢复早期工作中的讨论、决策、失败尝试、命令和测试结果。这些会话充满了有用的上下文：

• 来自你的决策、约束、意图和被否决的方案
• 之前代理的 bug 调查、重构、文件路径、命令、补丁和笔记

ctx 将这些日志索引到你机器上的 SQLite 中，然后为当前和未来的代理提供一个 CLI，用于在重复之前找到之前的讨论、命令或失败尝试。

安装与设置 ctx

curl -fsSL https://ctx.rs/install | sh

可选但建议用于代理会话：

npx skills add ctxrs/ctx

有关 Codex、Claude Code、Cursor 和原生 Agent Skills 中的市场/插件安装，请参阅 Agent Skill 安装。

比原始转录本搜索节省 50 倍以上的 Token

通过将代理历史结构化为会话、事件、元数据和索引字段，然后返回带有引用的匹配结果，代理可以比原始搜索用更少的 Token 访问有意义的历史。结果因查询和语料库而异，但原始搜索通常 Token 消耗巨大，实际上等同于没有可用历史。

工作原理

你过去的代理会话存储在本地提供者的历史文件中。ctx 发现支持的来源，导入真实的持久记录，并将标准化的会话、事件和触及文件元数据存储在针对检索优化的本地 SQLite 数据库中。

ctx 用 Rust 编写，并存储本地 SQLite 索引，因此搜索快速、可脚本化，且无需后台服务。索引默认是本地且私有的。转录本文本会被保留，不会隐藏本地路径或类似秘密的字符串，因此在将复制输出分享到机器之外之前，请审阅。

# 索引所有已有的本地代理会话
ctx setup

# 你的代理可以用自然语言搜索之前的工作
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 ID
# evt_01h... ses_01h... codex "migration expected the old cursor name" ...

# 打印旧转录本的匹配部分
ctx show event --window 3

# 或者打印原始会话的紧凑转录本
ctx show session

这些 ID 允许你当前的代理根据需求从之前的会话中恢复尽可能多的上下文。ctx 不会将你的提示、转录本或索引历史发送到云服务、调用模型 API、需要 API 密钥或写入你的源代码仓库。

安装的二进制文件还包含本地文档和 man 页面生成：

ctx docs search "upgrade"
ctx docs show cli-reference
ctx docs man --print

由官方安装程序管理的二进制文件支持带签名的自我升级：

ctx upgrade status
ctx upgrade check

源码构建和包管理器安装保持不受管理，不会自我升级。

有关完整流水线，请参阅 ctx 的工作原理。如需快速首次运行，请参阅 快速入门。

支持的代理历史记录

支持意味着 ctx 可以发现或读取该工具持久化的本地历史记录，并将其导入本地搜索索引。在你的机器上使用 ctx sources --json 查看当前哪些源是 importable（可导入）状态。

ctx 的对比

代理记忆工具通常保存紧凑的事实、摘要、向量或图节点。这些有助于稳定偏好，但在下一个代理需要知道某个决策的来源、哪个命令失败或原始对话中什么被否决时，它们提供的证据很薄弱。

Graphify 类工具回答了另一个问题：它们映射当前仓库：文件、符号、导入、文件夹和关系。ctx 搜索之前的代理会话，这些会话解释了当人和代理改变那个仓库时发生了什么。

ctx 将检索绑定到会话和事件，因此另一个代理可以在使用源之前检查它。了解更多关于 代理记忆、Graphify 式代码库图 以及 grep 或日志搜索 的信息。

探索文档