ctx：让编码代理的会话历史变成可搜索的本地资产

代理有 git 历史，却没有会话历史

编码代理在工作时会产生大量日志，包括消息、工具调用、决策过程。这些日志通常以 JSONL 或 SQLite 格式存放在 ~/.claude、~/.codex 这样的目录里。问题是这些文件是给机器读的，不是给人或代理读的。你想知道上次代理为什么选择了某个实现方案，或者某个错误之前是否已经尝试过修复，但面对一堆原始日志，你只能手动 grep，而且 grep 出来的结果缺乏结构。ctx 解决的就是这个问题：它把这些分散的、格式各异的日志转换成统一的、可搜索的本地记录。它面向的是使用编码代理的开发者，以及需要从历史会话中获取上下文的代理本身。

从 JSONL 到结构化索引：ctx 的数据流

ctx 的工作方式分为几步。首先，ctx setup 扫描本地目录，发现 Claude、Codex 等代理的历史文件。它读取这些文件，但不修改它们，只做只读转换。转换的结果是统一的记录，包含会话、消息、工具调用、会话之间的关系（比如父子会话、子代理、分叉），以及仓库活动。这些记录被存储并索引，索引更新是原子的，即每次更新完成前不会被读取，所以不会出现半构建状态。每个会话和事件都有一个稳定的 ctx ID，保留完整的原文内容和来源信息。之后，ctx search 用 BM25 算法做词汇匹配，ctx show 可以显示某个事件或整个会话，ctx locate 告诉你记录来自哪个源文件。这个流程的关键在于，它不要求代理进程内运行任何钩子，也不依赖代理的 API，纯粹从本地文件入手。

安装与基本命令：从 curl 到第一次搜索

安装很简单，macOS 和 Linux 上用 curl -fsSL https://ctx.rs/install | sh，Windows 上用 PowerShell 执行 irm https://ctx.rs/install.ps1 | iex。你也可以直接让你的代理去安装。装好后，第一步是 ctx setup，它会索引所有现有的本地代理会话。之后就能搜索了。最基本的用法是 ctx search "failed migration"，用自然语言描述你关心的问题。如果你记得某个文件，可以用 ctx search --file crates/foo/src/lib.rs 限定范围。多个关键词用 --term 叠加，比如 ctx search --term "failed migration" --term rollback。结果会返回匹配的会话、片段和 ctx ID，格式类似 evt_01h... ses_01h... codex "migration expected the old cursor name"。然后用 ctx show event <ctx-event-id> --window 3 打印事件附近的上下文。这些命令都基于本地索引，不依赖网络。

语义搜索：本地嵌入，无向量数据库

BM25 是默认的检索方式，适合关键词匹配，但遇到同义词或不同表述就失效了。比如你搜 "cursor rename"，但历史里写的是 "rename the pointer"，BM25 可能找不到。ctx 提供了语义搜索来解决这个问题。启用方式是 ctx semantic enable，然后 ctx semantic status 查看状态。语义搜索在本地计算嵌入，直接搜索这些嵌入，不需要运行独立的向量数据库。启用后，自动索引会启动或恢复一个守护进程，负责下载本地模型并构建语义投影。你可以加 --wait 参数等待就绪。这个设计的好处是隐私，所有计算都在本机。但代价是你需要为模型下载和守护进程占用资源买单。文档没有说明模型的大小或内存占用，如果你在资源受限的环境里，需要先自行评估。

ctx blame：从代码行回溯到代理会话

ctx pro 提供了一个独特的功能：ctx blame。它像 git blame 一样，但指向的是代理会话而不是提交。你可以对某个文件的行范围执行 ctx blame file src/checkout.ts --lines 118:146，它会找到产生这些行的代理会话，并给出提交哈希、会话 ID 和证据编号。然后 ctx show session <id> 就能打开原始会话记录，看到代理当时的决策和工具调用。也可以从提交或 PR 开始：ctx blame commit <sha> 或 ctx blame pr https://github.com/your-org/your-repo/pull/42。这个功能的价值在于，当代码里存在一个看似不合理的修改时，你能找回当初代理为什么这么写的上下文。但有一个明确的限制：如果代码不是本机会话产生的，比如队友的代理在另一台机器上工作，ctx 会明确说它无法证明归属。这意味着 ctx blame 只适用于个人本地工作流，团队协作时它只能覆盖你自己的部分。

本地优先的代价：索引维护与隐私边界

ctx 强调所有操作都在本地，代码和历史从不离开你的机器。这既是优点也是限制。优点是隐私有保障，敏感代码不会被发送到外部服务。限制是索引需要维护。自动索引默认开启，它会持续监视历史源文件的变化，每次更新都保证原子性。但这意味着你需要一个常驻进程，尤其是在启用语义搜索后，守护进程要加载模型。文档没有说明索引的性能开销，也没有给出索引体积的估算。如果你的代理历史文件非常大，比如数千个会话，索引构建时间可能很长，而且磁盘占用会翻倍（原始日志加索引）。另一个问题是，ctx 依赖代理历史文件的格式。如果某个代理改变了日志格式，ctx 可能需要更新才能识别。目前它支持 Claude 和 Codex，但其他代理没有提及。

与 agent memory 的根本区别

ctx 明确将自己与常见的 agent memory 区分开。agent memory 通常会把历史压缩成事实或摘要，这些摘要会过时，或者丢失细节。ctx 不做压缩，它保留完整的原始转录内容，只是建立索引。这意味着代理搜索到的不是二手总结，而是原始记录。这个设计决策有实际后果：搜索结果的 token 消耗比原始搜索少 50 倍（文档声称），因为返回的是结构化的、带引用的匹配项，而不是大段原始文本。但完整保留也意味着你仍然需要面对原始日志的噪音。ctx 用 BM25 排名来缓解，但如果你搜索的关键词太宽泛，结果可能仍然很多。相比之下，agent memory 的摘要虽然可能丢失细节，但更简洁。ctx 的取舍是保真度优先，适合需要精确回溯的场景，比如审计或理解复杂决策。

编辑结论

重度使用编码代理、经常需要回顾之前会话的开发者应该尝试 ctx，尤其是那些已经积累了大量 JSONL 或 SQLite 日志的人。它能把原本不可读的日志变成可检索的记录，减少重复劳动。不适合那些代理使用频率极低、或者完全依赖云端托管会话的用户，因为 ctx 只处理本地文件。在采用前，先确认你的代理历史确实存储在本地且路径可被 ctx setup 发现，然后运行 ctx search 测试一个具体错误信息，看看返回结果是否包含足够上下文。如果依赖 ctx blame 的溯源能力，要清楚它只能证明本地会话产生的代码，无法证明队友代理的提交。最后，注意 ctx pro 是付费功能，免费试用两周，但核心搜索和索引是开源的，可以先只用免费部分。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes