ctx 中文教程：把旧代理会话变成可追溯的本地搜索库
ctx 搜索 Codex、Claude Code、Cursor、OpenCode 等编码代理留在本机的历史。它和“让模型记住几条事实”不同：搜索结果可以回到原始消息、工具调用和完整会话。最新正式版是 v1.6.1。
1. 安装前决定升级方式
macOS 和 Linux 的官方入口是远程安装脚本，Windows 使用 PowerShell 脚本。生产工作站不应盲跑远程脚本：先在浏览器查看脚本，确认发布来源与安装目录，再执行。
# macOS / Linux：先检查 https://ctx.rs/install 的内容
curl -fsSL https://ctx.rs/install | sh
# 安装后确认命令
ctx --version
ctx --help托管安装默认启用自动升级。需要固定变更窗口时，可按官方 CLI 文档执行 ctx upgrade disable，或把 CTX_UPGRADE_AUTO 设为 off；GitHub Release、Homebrew、mise 与源码安装属于非托管路径。
2. 发现来源，不要先假定它找到了什么
ctx setup
ctx status
ctx sourcessetup 会发现本机已存在的历史并建立索引。官方称它只读取原历史，不改写来源文件。执行后仍要看 status 和来源列表，确认扫描范围里没有不该被当前账户索引的目录。
3. 从词法搜索跑通命中与证据链
# 用明确的错误、文件名或决策词搜索
ctx search "failed migration"
ctx search --file crates/foo/src/lib.rs
ctx search --term "failed migration" --term rollback
# 用结果中的 ID 回看原始记录
ctx show event <ctx-event-id> --window 3
ctx show session <ctx-session-id>默认是 BM25 词法排序。查询包含原错误、命令或文件名时，结果通常比泛泛的自然语言问题更容易核对。show 才是证据回看步骤，不要只根据搜索摘要下结论。
4. 用 ctx blame 追溯代码来源
ctx blame file src/checkout.ts --lines 118:146
ctx blame commit <sha>
ctx blame pr https://github.com/your-org/your-repo/pull/42ctx blame 把 Git 对象与已索引会话联系起来，并引用原始转录或工具调用。若变更来自队友的机器，或者旧会话已丢失，它会说明无法证明归属。这个结果不能用来断言“没有代理参与”。
5. 什么时候开启语义搜索
ctx semantic enable
ctx semantic status语义搜索适合“意思相近但措辞不同”的查询。它会在本地获取嵌入模型并建立语义投影；准备期间词法搜索仍可使用。磁盘有限、数据边界尚未审查，或者明确关键词已经够用时，可以不启用。
6. 和 Mem0 怎么选
| 问题 | ctx | Mem0 |
|---|---|---|
| 输入 | 原始编码代理会话、工具调用和本地 Git | 对话或应用事件中提取的记忆 |
| 主要用途 | 查“当时做了什么”，并回到原记录 | 让应用跨会话保存用户事实和偏好 |
| 证据形态 | 事件、会话与 blame 引用 | 提取并更新后的记忆 |
相比官方 Mem0 这类应用记忆层，ctx 直接保留并检索原始代理记录。需要审计旧代理工作时，ctx 更贴近问题；需要给产品构建长期用户记忆时，Mem0 的数据模型更合适。
7. v1.6.1 更新与边界
v1.6.1 于 2026-09-22 发布，新增 Devin CLI 标准本地历史导入，覆盖主会话、压缩历史、关联子代理和工具活动；托管 Devin 历史与未关联后台线程不在范围内。它还改善磁盘空间不足后的恢复和守护进程诊断，并移除了已退役商业产品页面。
验证边界：未验证二进制签名、自动升级、索引速度、磁盘占用、代理格式兼容、语义相关性和 blame 命中率。官方的性能图表来自项目方测试，不能直接当作你的机器的保证。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
近期变化与关注原因
编码代理用得越多，本机就越容易积累分散在 JSONL 或 SQLite 中的历史记录。ctx 把这些记录转成统一索引，并在 v1.6.1 加入 Devin CLI 本地历史发现与导入，覆盖的代理来源继续扩大。
适合谁用
适合找回旧会话里的报错、决策和失败方案，审计某段代码由哪次代理会话产生，或让新会话引用过去的原始记录。它不能替代 Git 的代码差异、团队知识库或长期规则管理；队友生成但未同步到本机的代理历史也无法被证明。
采用建议
如果你已经积累了大量本地编码代理会话，ctx 值得先用词法检索做小范围试跑。先检查来源目录和本地索引权限，再决定是否开启自动索引、语义模型与自动升级。把它当作原始历史检索和审计工具，而不是自动脱敏的团队知识库。
原教程未展开的系统信息
核心功能
词法与本地语义检索
默认用 BM25 搜索历史消息和工具调用；语义检索需显式启用，嵌入在本地计算，词法索引在模型准备期间仍可使用。
可引用的原始记录
search 返回会话与事件 ID，show 可读取命中片段或完整会话，locate 用来确认原始来源。
代码变更追溯
ctx blame 可从文件、行号、提交或 PR 追溯产生变更的代理会话；本机没有相应会话时会明确说明无法证明归属。
架构与数据流
ctx setup 先发现本机代理历史源，再把不同格式转换成会话、消息、工具调用、关系和仓库活动等统一记录。并行扫描器把记录直接写入 Tantivy 索引，避免先导入关系型数据库；自动索引默认开启，并以完成后的新索引原子可见。语义搜索在本机下载模型并建立投影，不要求模型 API key。
技术栈和运行条件
语言
Rust
框架
Tantivy 本地搜索索引，Apache-2.0
关键依赖
- Tantivy
- rusqlite（读取基于 SQLite 的代理历史）
- 本地嵌入模型（仅在启用 semantic 后获取）
运行环境
macOS、Linux 和 Windows 有预编译安装路径；源码构建还需要 Rust、Bazel、C/C++ 工具链，Windows 原生构建需要 MSVC 与 Windows SDK
常见问题
ctx 会把 Codex 或 Claude Code 的会话上传到云端吗？
官方 README 称索引、搜索和语义嵌入在本地完成，不调用模型 API，也不需要 API key。不过转录文本会原样保存在本地索引中，导出或粘贴结果前仍要检查敏感信息。
ctx setup 会改写原来的代理历史文件吗？
官方说明 setup 会发现并读取已有来源，不修改原文件；它把标准化记录写入自己的本地存储和索引。首次使用前仍应确认扫描到的来源目录符合预期。
为什么 ctx blame 找不到某次代码变更对应的会话？
blame 只能基于本机已索引的 Git 与代理历史建立证据。若提交来自队友、原会话被清理、仓库路径不匹配或历史尚未导入，ctx 会无法证明归属；这不是代码没有经过代理的证明。
ctx 的语义搜索必须开启吗？
不必须。默认 BM25 词法搜索可直接使用。只有同一概念经常用不同措辞、且能接受模型下载与额外索引成本时，才需要执行 ctx semantic enable。