trovex

trovex

trovex：为编码 Agent 提供一份权威文档，令 Token 用量减少约 60%。

你的编码 Agent（Claude Code、Cursor、Windsurf、Zed，以及任何 MCP 客户端）每次会话都会重新阅读代码仓库， 试图弄清楚哪个 .md 文件是最新的，然后凭猜测作答。每次会话、每个 Agent、每位队友都会为此付出代价。

trovex 会为代码仓库中的 Markdown 编制索引，并提供一个 MCP 工具。你的 Agent 提出问题； trovex 会返回能回答问题的唯一最新文档，并提供 path:line 指针和新鲜度标记（权威 / 过时 / 重复）， 只提供能回答问题的章节，而不是整个文件。Agent 也可以通过一个共享入口写回它们学到的内容， 这样每个 Agent 和队友读取的都是同一份事实来源，而不是各自重新推导。

查找文档时 Token 用量减少约 60%；这是在我们自己的代码仓库中、任务成功率相同的情况下测得的（实际效果因你的代码仓库而异）。在本地运行：向量存储在 SQLite 中，通过 ONNX 生成嵌入，无需云服务或 API 密钥。

你将安装什么

30 秒了解可信度，因为是否采用的决定是在 README 上做出的，而不是在目录列表页：

• 一方开发，开源。 由背后的团队 tsukumo 构建并在生产环境中运行。AGPL-3.0-or-later。
• 本地优先，数据不会离开你的设备。 向量存储在 SQLite 中，通过 ONNX 生成嵌入。无需云服务、API 密钥，也无需联网即可回答查询。
• 写入受限，无 Shell。 六个 MCP 工具：三个只读工具（trovex、trovex_read、trovex_search），以及三个只会修改 trovex 自身文档存储的工具（trovex_write、trovex_tag、trovex_delete）。不会执行 Shell，也不会写入你的源文件。
• 约 60% 的节省可复现。 在我们自己的代码仓库中，以相同任务成功率测得（中位数 69%，各代码仓库约为 41–81%，n=26，由大模型评判）；trovex search 会显示你的节省情况。完整方法见 trovex.dev/measure。

快速开始

trovex 处于公开测试版，可在 PyPI 获取。无需克隆；uv tool install 会将 trovex 添加到你的 PATH 中：

uv tool install trovex   # one-time, no clone
trovex setup             # wire into Claude Code (skill + hooks + MCP); idempotent

trovex index /path/to/your/repo        # index your markdown (~1 min)
trovex search "how do we roll back a deploy?"   # ask, prints the tokens it saved
trovex serve                           # wire into your agent: MCP at /mcp, dashboard at /savings

没有 uv？一行命令即可安装：curl -LsSf https://astral.sh/uv/install.sh | sh （或运行 brew install uv）。

通过 search 步骤，你可以快速了解它的作用：它会返回唯一的权威文档， 并显示相较于阅读前几个候选文档节省了多少 Token。通过 MCP 将 trovex 接入 Agent 后，相同的数据会累积到节省情况面板 http://localhost:8765/savings 中。

暂时不想安装任何东西？uvx trovex search "..." 会在临时环境中运行一次命令，无需安装。

接入你的 Agent

trovex 是一个 MCP 服务。运行 trovex serve 后，将客户端指向 http://localhost:8765/mcp。 各客户端（Claude Code、Cursor、Windsurf、Cline、Zed、Roo）的设置说明见 trovex.dev/for。

Claude Code，一条命令即可。 trovex setup 会一步安装 Claude Code 技能、 Active-Memory 钩子并注册 MCP 服务（可重复运行，且安全）：

trovex setup

之后重启 Claude Code，以便加载技能和钩子。想手动接入 MCP 服务，而不安装其他内容？ 运行 trovex setup --no-skill --no-hooks，或：

claude mcp add --transport http trovex http://localhost:8765/mcp

Cursor 用户只需点击一次（先运行 trovex serve）： 将 trovex 添加到 Cursor

工作原理

trovex 会将代码库中的 Markdown 转换为一个可查询的权威存储，然后为每个 Agent 提供唯一一篇能回答问题的当前文档，而不是一堆需要排序的候选文档。

flowchart LR
  A["Your repo<br/>.md files"] -->|trovex index| B["Chunk + parse"]
  B --> C["Embed locally<br/>ONNX · bge-small"]
  C --> D[("sqlite-vec<br/>vector store")]
  Q["Agent question"] -->|MCP| E["Route + rerank"]
  D --> E
  E --> F["One canonical doc<br/>path:line + freshness"]
  F --> G["Agent answers from<br/>the current doc"]

四个核心理念：

• 权威，而非完整。 每个问题都应该有一篇能够回答它的文档。trovex 会将每篇文档标记为权威 / 过时 / 重复，这样检索就能优先选择仍然有效的那篇：过时文档与当前文档对查询的相似度完全相同，因此仅凭相似度无法区分它们。
• 先路由，再提供相关章节。 查询会返回指向唯一一篇文档的 path:line，并只提供回答问题的章节，而不是整个文件，也不是 Agent 原本要自行阅读和排序的 top-k 候选文档。弥合这一差距，正是节省 token 的关键。
• 默认在本地运行。 索引、嵌入（ONNX、bge-small-en-v1.5）和向量搜索（sqlite-vec）都在你的机器上运行。没有云服务、没有 API 密钥，也不需要网络调用来回答查询。
• 共享写回路径。 Agent 只需将学到的内容存储一次（trovex_write）到 trovex 自己的存储中；其他所有 Agent 和队友都可以读取这些内容（trovex_read），而不必重新推导。

让所有 Agent 使用同一事实来源的读写循环：

sequenceDiagram
  participant A as Agent
  participant T as trovex (MCP)
  participant S as Store (sqlite-vec)
  A->>T: trovex("how do we roll back a deploy?")
  T->>S: route + rerank candidates
  S-->>T: one canonical doc
  T-->>A: path:line + section + freshness
  A->>T: trovex_write("rollback runbook: …")
  T->>S: upsert (dedupes near-copies)
  Note over S: the next agent reads it back via trovex_read

在自己的代码库中验证

约 60% 的节省是可以实际运行验证的主张，不是让你盲目信任的数字。只需运行两个命令：

trovex bench /path/to/your/repo          # token-accounting model, instant, no LLM, no key
trovex bench /path/to/your/repo --eval   # full answer+judge A/B at equal task-success (needs OPENAI_API_KEY)

bench 报告的是分布（中位数 + 离散程度），而非最佳情况：比较路由到的单篇权威文档与未获辅助的 Agent 会读取的 top-k 候选文档的读取成本。--eval 更进一步：两种方案都会作答，由大模型评判，只有两者都回答正确时才计入节省。完整方法和我们的数据见 trovex.dev/measure。

已经通过 md-guard hook 运行 trovex？trovex measure 会根据 hook 的基线日志，比较你实际的 .md token 消耗变化。

开发说明：声明评测框架

上文的 bench --eval 会逐个查询回答“trovex 是否仍能得出正确答案”，并比较两种方案。trovex eval-harness（src/trovex/eval_harness.py）是这一思路的发布门禁版本：使用带版本控制的 cases.jsonl 数据集，评估检索质量（hit@k/MRR/recall@k，免费），并提供加权评分标准（correctness35/autonomy25/actionability20/safety10/concision10，盲评——评审者不会看到生成答案所用的配置），还支持 $ 预算上限和断点续跑。

make eval                                                          # retrieval-only, no key, CI-safe
uv run trovex eval-harness . --gate --budget-usd 1.0 --resume run.jsonl   # full rubric pass, needs OPENAI_API_KEY

--retrieval-only（make eval 运行的模式）绝不会调用大模型——它只根据 benchmarks/token-savings/eval-baseline.json 中的 hit@1 进行门禁评估。完整的评分标准评测需要密钥，因此需要手动运行或通过 CI 密钥控制运行，不属于 make test 的一部分。随附的 cases.jsonl（47 个案例）和 eval-baseline.json 阈值都在 benchmarks/token-savings/ 中进行版本控制——在实际运行一次并有意将数据填入之前，基线只是占位值（运行时绝不会自动覆盖该文件）。

MCP 工具

• trovex(q)：将问题路由到正确的本地 .md 文件，并返回带有新鲜度标记的 path:line 指针，而不是一堆需要排序的文件。
• trovex_write(content, kind?, doc_id?, tags?, section?) / trovex_read(query | doc_id, section?)： 由 trovex 内部托管的文档。Agent 只需存储一次记录（事件、决策、“实际有效的方法”）；其他所有 Agent 和另一位开发者都可以将其作为内容读回（也可以只读取一个章节），而不必重新推导。传入 section= 给 trovex_write，即可就地更新某个标题下的章节，而无需替换整个文档。
• trovex_search(query, k?, tags?)：通过标签筛选，在存储中检索段落；当你需要最匹配的内容块，而非一篇规范文档时使用。
• trovex_tag(...) / trovex_delete(...)：为已存储的文档添加标签或软删除；删除会将文档归档，以便恢复，而非彻底抹除。两者只会操作 trovex 存储，绝不会触碰你的文件。

人类可在渲染后的阅读器中通过 /doc/{id} 阅读由 trovex 托管的文档。若要让 Agent 通过 trovex_write 而非磁盘来处理 .md 写入，请安装 PreToolUse 钩子 deploy/hooks/trovex-md-guard.sh，并在 .trovexignore 中设置例外。

对比

• 与 CLAUDE.md / AGENTS.md 相比：一个会过时、无法将问题路由到正确文档的静态文件，与多篇保持规范并按查询提供的文档。 更多。
• 与 repomix / files-to-prompt 相比：将整个仓库打包到上下文窗口中，与检索单个答案。 更多。
• 与向量数据库 / 纯 RAG 相比：一堆已排序、没有新鲜度信号的候选内容块，与带有明确标记的一篇最新文档。 更多。

关于约 60% 这一数字的推理已写在基准测试方法中。

技术栈

• Python 3.11 + uv
• FastAPI（MCP HTTP + 服务端渲染的 HTML UI）
• fastembed（本地嵌入，底层使用 ONNX）
• sqlite-vec（SQLite 中的向量搜索）
• Jinja2 + HTMX（UI，无需构建步骤）

嵌入：默认本地运行，也可使用自选模型

trovex 开箱即用地使用 BAAI/bge-small-en-v1.5（ONNX，384-d）进行本地嵌入。 无需 API 密钥，任何数据都不会离开你的计算机。你可以换用任何嵌入模型：

• 其他本地模型： 设置 TROVEX_EMBED_MODEL=<fastembed model>；如果不是内置模型，还需设置 TROVEX_EMBED_DIM=<its dimension>。
• 兼容 OpenAI 的端点（包括 Ollama、LM Studio、vLLM 等本地服务）：设置 TROVEX_EMBED_PROVIDER=openai、TROVEX_EMBED_MODEL=<model>、 TROVEX_OPENAI_BASE_URL=http://localhost:11434/v1、TROVEX_EMBED_DIM=<dim>。 指向 localhost 即可完全在本地运行；指向 OpenAI（text-embedding-3-large）则可获得更强的检索能力，代价是将每个内容块发送到 OpenAI 的 API。

更换模型会改变向量维度，因此切换模型时需要重新建立索引。

公测

trovex 目前处于公测阶段。安装并在你的仓库中运行它；如果它为你节省了 Token，给一个 GitHub 星标就能帮助其他开发者发现它。欢迎提交问题和 PR。

有疑问，或想与其他运行 Agent 的人交流心得？加入 Discord 社区： tsukumo.ch/discord。

安全

trovex 以本地为先，且为单租户：它在你的机器上运行，为你的文档建立索引，并为你的 Agent 提供服务。写入操作受 X-TROVEX-Write-Token 请求头保护，默认采用失败关闭策略：未配置令牌时，trovex 会在首次运行时自动生成一个实例专属令牌，并将其持久化到 <data_dir>/.write_token（权限设为 600），因此暴露在网络中的实例不会接受匿名写入。设置 TROVEX_WRITE_TOKEN 可在多台机器间共享同一个令牌；设置 TROVEX_ALLOW_UNAUTH_WRITES=1 则可在可信的本地主机上有意启用开放写入。信任模型、安全加固措施以及漏洞报告方式详见 SECURITY.md。

许可证

trovex 根据 GNU AGPL-3.0-or-later 许可发布（参见 LICENSE）。你可以自由地自行托管和修改它；如果你将修改后的版本作为网络服务运行，AGPL 要求你公开所做的修改。

套件组成

trovex 是由 tsukumo 构建的、用于在生产环境中运行 AI 编码 Agent 的四部分开源套件中的上下文层：

• trovex，上下文：每次查询都向 Agent 提供唯一权威的文档，而不是反复读取仓库（每次查找可减少约 60% 的令牌用量；测量方法见 trovex.dev/measure）。
• wrai.th，编排：运行并协调一组 Agent。
• yoru，可观测性：记录每个 Agent 实际执行内容的会话凭证。
• dokan，确定性执行：将 Agent 已确定且可重复的工作作为脚本在干净的容器中运行，不让模型参与执行。

与团队协作？

trovex 可免费自行运行。如果你的团队正大规模部署编码 Agent，并希望获得实操指导，或想在无需承担 AGPL 著佐权义务的情况下私下嵌入并托管修改版 trovex，我们提供相关咨询服务。

联系 trovex 背后的团队 tsukumo。