ctx 是什么?

ctx 是一款 Apache-2.0 开源命令行工具,读取本机已有的编码代理会话记录,把消息、工具调用、会话关系和仓库活动整理成可检索索引。它还提供 ctx blame,把文件行、提交或 PR 追溯到原始代理会话,并给出可回看的记录引用。

⭐ 759 Stars 🍴 44 Forks Rust Apache-2.0 作者: ctxrs
来源:github.com/ctxrs/ctx 查看 GitHub 仓库 → 📘 使用教程 →

为什么值得关注

编码代理用得越多,本机就越容易积累分散在 JSONL 或 SQLite 中的历史记录。ctx 把这些记录转成统一索引,并在 v1.6.1 加入 Devin CLI 本地历史发现与导入,覆盖的代理来源继续扩大。

来源:github.com/ctxrs/ctx (1) · github.com/ctxrs/ctx/releases/tag/v1.6.1 (2)

核心功能

词法与本地语义检索

默认用 BM25 搜索历史消息和工具调用;语义检索需显式启用,嵌入在本地计算,词法索引在模型准备期间仍可使用。

来源:github.com/ctxrs/ctx
可引用的原始记录

search 返回会话与事件 ID,show 可读取命中片段或完整会话,locate 用来确认原始来源。

来源:github.com/ctxrs/ctx
代码变更追溯

ctx blame 可从文件、行号、提交或 PR 追溯产生变更的代理会话;本机没有相应会话时会明确说明无法证明归属。

来源:github.com/ctxrs/ctx/blob/main/docs/blame.md
多代理历史适配

官方列表覆盖 Codex、Claude Code、Cursor、OpenCode、Gemini CLI、Devin 等多种本地历史格式,并理解父会话、子代理和分叉关系。

来源:github.com/ctxrs/ctx

技术架构

ctx setup 先发现本机代理历史源,再把不同格式转换成会话、消息、工具调用、关系和仓库活动等统一记录。并行扫描器把记录直接写入 Tantivy 索引,避免先导入关系型数据库;自动索引默认开启,并以完成后的新索引原子可见。语义搜索在本机下载模型并建立投影,不要求模型 API key。

来源:github.com/ctxrs/ctx (1) · ctx.rs/concepts/how-it-works (2)

项目知识图谱

知识图谱:项目核心节点(中心)+ 核心功能(内环六边形)+ 关键技术依赖(外环 chip) Tantivy rusqlite(读取基于 SQLite 的代理历史)rusqlite(读取… 本地嵌入模型(仅在启用 semantic 后获取)本地嵌入模型(仅… 词法与本地语义检索 可引用的原始记录 代码变更追溯 多代理历史适配 ctx 项目本体 核心功能 关键依赖

技术栈

语言Rust框架Tantivy 本地搜索索引,Apache-2.0
Tantivyrusqlite(读取基于 SQLite 的代理历史)本地嵌入模型(仅在启用 semantic 后获取)
macOS、Linux 和 Windows 有预编译安装路径;源码构建还需要 Rust、Bazel、C/C++ 工具链,Windows 原生构建需要 MSVC 与 Windows SDK
来源:github.com/ctxrs/ctx (1) · github.com/ctxrs/ctx/blob/main/docs/unmanaged-installs.md (2)

快速上手

在 macOS/Linux 可运行官方安装脚本,Windows 使用 PowerShell 安装脚本;安装后执行 ctx setup,再用 ctx status 检查来源与索引,最后以 ctx search、ctx show 跑通一条检索链。语义检索单独执行 ctx semantic enable,不要在尚未确认本地磁盘和隐私边界时直接启用。
来源:github.com/ctxrs/ctx (1) · ctx.rs/first-search (2)

使用场景

适合找回旧会话里的报错、决策和失败方案,审计某段代码由哪次代理会话产生,或让新会话引用过去的原始记录。它不能替代 Git 的代码差异、团队知识库或长期规则管理;队友生成但未同步到本机的代理历史也无法被证明。

来源:github.com/ctxrs/ctx

优势与局限

优势

  • 索引、词法搜索、语义嵌入和 blame 均可在本地完成
  • 保留原始会话与工具调用,可从结果回到证据
  • 覆盖多种编码代理,并理解父子会话关系
  • 词法检索无需模型或 API key

局限

  • 索引保存完整转录文本,不会自动脱敏,复制或分享输出前必须检查秘密和个人信息
  • 只能搜索当前机器可读取的历史,不能证明缺失的队友会话
  • 语义检索首次需要下载本地模型并建立索引,占用磁盘和计算资源
  • 托管安装默认自动升级;需要固定变更窗口时要关闭自动升级或使用非托管安装
  • 官方性能图表来自项目自己的语料与环境,不能直接外推到所有机器
来源:github.com/ctxrs/ctx (1) · ctx.rs/reference/cli (2)

最新版本

最新正式版 v1.6.1 于 2026-09-22 发布。它新增 Devin CLI 标准本地历史发现与导入,覆盖主会话、压缩历史、关联子代理和工具活动;托管 Devin 历史与未关联后台线程不在范围内。该版本还改进磁盘空间不足时的恢复、守护进程诊断,并从网站和文档移除已退役商业产品页面。

来源:github.com/ctxrs/ctx/releases/tag/v1.6.1

实测与证据

status: official_docs_checked_not_installed  |  checked_at: 2026-09-23  |  environment: 核对官方 README、v1.6.1 Release、安装与 CLI 文档;没有运行远程安装脚本,也没有读取本机代理历史  |  limitations: 未验证安装脚本内容、二进制签名、自动升级、索引速度、语义模型下载、磁盘占用、任何具体代理格式或 ctx blame 的真实命中率  |  observed_output: 最新正式 Release 为 v1.6.1,发布于 2026-09-22;README 给出 macOS/Linux 与 Windows 安装入口;v1.6.1 新增 Devin CLI 标准本地历史导入,并移除已退役商业产品页面

来源:github.com/ctxrs/ctx/releases/tag/v1.6.1 (1) · github.com/ctxrs/ctx (2)

同类项目对比

相比 Mem0,ctx 面向编码代理的原始本地历史和 Git 变更归因,搜索结果可以回到完整会话与工具调用;Mem0 是面向 AI 应用的记忆层,会从对话中提取、保存并检索可用记忆。需要保留原始证据和追溯代码来源时选 ctx;需要让应用跨会话维护用户偏好或事实时,Mem0 的抽取式记忆模型更直接。两者可以并用。

来源:github.com/ctxrs/ctx (1) · github.com/mem0ai/mem0 (2)

总结评价

如果你已经积累了大量本地编码代理会话,ctx 值得先用词法检索做小范围试跑。先检查来源目录和本地索引权限,再决定是否开启自动索引、语义模型与自动升级。把它当作原始历史检索和审计工具,而不是自动脱敏的团队知识库。

来源:github.com/ctxrs/ctx (1) · ctx.rs/first-search (2)

常见问题

ctx 会把 Codex 或 Claude Code 的会话上传到云端吗?

官方 README 称索引、搜索和语义嵌入在本地完成,不调用模型 API,也不需要 API key。不过转录文本会原样保存在本地索引中,导出或粘贴结果前仍要检查敏感信息。

ctx setup 会改写原来的代理历史文件吗?

官方说明 setup 会发现并读取已有来源,不修改原文件;它把标准化记录写入自己的本地存储和索引。首次使用前仍应确认扫描到的来源目录符合预期。

为什么 ctx blame 找不到某次代码变更对应的会话?

blame 只能基于本机已索引的 Git 与代理历史建立证据。若提交来自队友、原会话被清理、仓库路径不匹配或历史尚未导入,ctx 会无法证明归属;这不是代码没有经过代理的证明。

ctx 的语义搜索必须开启吗?

不必须。默认 BM25 词法搜索可直接使用。只有同一概念经常用不同措辞、且能接受模型下载与额外索引成本时,才需要执行 ctx semantic enable。

资料与核验范围
本文依据项目公开资料整理。版本、安装命令和功能边界可能随上游更新,请以所列来源和项目当前版本为准。 资料核对时间: 2026-09-23 10:52.

参考材料:README、GitHub API、依赖文件