{ "markdown": "

\n \"trovex:\n

\n\n\n\n# trovex\n\n**trovex: one canonical doc for your coding agents, ~60% fewer tokens.**\n\n

\n \"Join\n

\n\nYour coding agents (Claude Code, Cursor, Windsurf, Zed, any MCP client) reread the repo\nevery session to work out which `.md` is current, then answer from a guess. You pay for\nthat on every session, every agent, every teammate.\n\ntrovex indexes your repo's markdown and exposes one MCP tool. Your agent asks a question;\ntrovex returns the single current doc that answers it as a `path:line` pointer with a\nfreshness marker (canonical / stale / duplicate), and serves just the section that answers\ninstead of the whole file. Agents also write what they learn back through one shared point,\nso every agent and teammate reads the same source of truth instead of re-deriving it.\n\nAbout **60% fewer tokens** on doc lookups, measured at equal task-success on our own repo (it varies by yours). Runs locally: vectors in\nSQLite, embeddings via ONNX, no cloud or API keys.\n\n## What you're installing\n\nA 30-second trust check, since the decision happens on the README, not the directory listing:\n\n- **First-party, open source.** Built and run in production by [tsukumo](https://tsukumo.ch), the team behind it. AGPL-3.0-or-later.\n- **Local-first, nothing leaves your machine.** Vectors in SQLite, embeddings via ONNX. No cloud, no API keys, no network call to answer a query.\n- **Confined writes, no shell.** Six MCP tools: three read-only (`trovex`, `trovex_read`, `trovex_search`) and three that mutate only trovex's own doc store (`trovex_write`, `trovex_tag`, `trovex_delete`). No shell execution, no writes to your source files.\n- **The ~60% is reproducible.** Measured at equal task-success on our own repo (median 69%, ~41–81% by repo, n=26, LLM-judged); `trovex search` prints the savings on yours. Full method at [trovex.dev/measure](https://trovex.dev/measure).\n\n## Quick start\n\ntrovex is in public beta, on PyPI. No clone needed; `uv tool install` puts `trovex`\non your PATH:\n\n```bash\nuv tool install trovex # one-time, no clone\ntrovex setup # wire into Claude Code (skill + hooks + MCP); idempotent\n\ntrovex index /path/to/your/repo # index your markdown (~1 min)\ntrovex search \"how do we roll back a deploy?\" # ask, prints the tokens it saved\ntrovex serve # wire into your agent: MCP at /mcp, dashboard at /savings\n```\n\nDon't have `uv`? It's a one-line install: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n(or `brew install uv`).\n\nThe `search` step is the fast way to see the point: it returns the one canonical doc and\nprints how many tokens that saved versus reading the top few candidates. Once trovex is\nwired into your agent over MCP, the same numbers accumulate on the savings dashboard at\n`http://localhost:8765/savings`.\n\n> Prefer not to install anything yet? `uvx trovex search \"...\"` runs a single command in a\n> throwaway environment, no install.\n\n## Wire it into your agent\n\ntrovex is an MCP server. Point your client at `http://localhost:8765/mcp` after `trovex serve`.\nPer-client setup (Claude Code, Cursor, Windsurf, Cline, Zed, Roo) is at\n[trovex.dev/for](https://trovex.dev/for/).\n\n**Claude Code, one command.** `trovex setup` installs the Claude Code skill, the\nActive-Memory hooks, and registers the MCP server in one step (idempotent, safe to\nre-run):\n\n```bash\ntrovex setup\n```\n\nRestart Claude Code afterwards so it loads the skill + hooks. Prefer to wire just the\nMCP server by hand? `trovex setup --no-skill --no-hooks`, or:\n\n```bash\nclaude mcp add --transport http trovex http://localhost:8765/mcp\n```\n\nFor **Cursor**, one click (after `trovex serve`):\n[**Add trovex to Cursor**](cursor://anysphere.cursor-deeplink/mcp/install?name=trovex&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0Ojg3NjUvbWNwIn0=)\n\n## How it works\n\ntrovex turns your repo's markdown into one queryable, canonical store, then serves each\nagent the single current doc that answers a question, not a pile of candidates to rank.\n\n```mermaid\nflowchart LR\n A[\"Your repo
.md files\"] -->|trovex index| B[\"Chunk + parse\"]\n B --> C[\"Embed locally
ONNX · bge-small\"]\n C --> D[(\"sqlite-vec
vector store\")]\n Q[\"Agent question\"] -->|MCP| E[\"Route + rerank\"]\n D --> E\n E --> F[\"One canonical doc
path:line + freshness\"]\n F --> G[\"Agent answers from
the current doc\"]\n```\n\nFour ideas do the work:\n\n- **Canonical, not complete.** For each question there should be one doc that answers it.\n trovex marks every doc canonical / stale / duplicate, so retrieval can prefer the one\n that's still true: a stale doc is exactly as similar to a query as the current one, so\n similarity alone can't tell them apart.\n- **Route, then serve the section.** A query returns a `path:line` pointer to the one doc\n and just the section that answers, not the whole file, and not the top-k pile your agent\n would otherwise read and rank itself. Closing that gap is where the tokens are saved.\n- **Local by default.** Indexing, embeddings (ONNX, `bge-small-en-v1.5`) and vector search\n (sqlite-vec) all run on your machine. No cloud, no API key, no network call to answer a query.\n- **A shared write-back path.** Agents store what they learn once (`trovex_write`) in\n trovex's own store; every other agent and teammate reads it back (`trovex_read`) instead\n of re-deriving it.\n\nThe read-and-write loop that keeps every agent on the same source of truth:\n\n```mermaid\nsequenceDiagram\n participant A as Agent\n participant T as trovex (MCP)\n participant S as Store (sqlite-vec)\n A->>T: trovex(\"how do we roll back a deploy?\")\n T->>S: route + rerank candidates\n S-->>T: one canonical doc\n T-->>A: path:line + section + freshness\n A->>T: trovex_write(\"rollback runbook: …\")\n T->>S: upsert (dedupes near-copies)\n Note over S: the next agent reads it back via trovex_read\n```\n\n## Prove it on your own repo\n\nThe ~60% is a claim you can run, not a number to take on faith. Two commands:\n\n```bash\ntrovex bench /path/to/your/repo # token-accounting model, instant, no LLM, no key\ntrovex bench /path/to/your/repo --eval # full answer+judge A/B at equal task-success (needs OPENAI_API_KEY)\n```\n\n`bench` reports the distribution (median + spread), not a best case: the cost of reading the\none routed canonical doc versus the top-k candidates an unaided agent would read. `--eval`\ngoes further: both arms answer, an LLM judges, and a saving counts only when both answer\ncorrectly. Full method and our own numbers are at [trovex.dev/measure](https://trovex.dev/measure).\n\nAlready running trovex through the md-guard hook? `trovex measure` compares your real `.md`\ntoken consumption before and after, from the hook's baseline log.\n\n### Dev notes: the claims eval harness\n\n`bench --eval` above answers \"does trovex still get the right answer\" per-query, one arm vs\nthe other. `trovex eval-harness` (`src/trovex/eval_harness.py`) is the release-gate version of\nthat idea: a versioned `cases.jsonl` set, retrieval quality (hit@k/MRR/recall@k, free) plus a\nweighted rubric score (correctness35/autonomy25/actionability20/safety10/concision10, blind —\nthe judge never sees which config produced an answer), a `$` budget cap, and resumability.\n\n```bash\nmake eval # retrieval-only, no key, CI-safe\nuv run trovex eval-harness . --gate --budget-usd 1.0 --resume run.jsonl # full rubric pass, needs OPENAI_API_KEY\n```\n\n`--retrieval-only` (what `make eval` runs) never calls an LLM — it gates purely on hit@1\nagainst `benchmarks/token-savings/eval-baseline.json`. The full rubric pass needs a key, so\nit's a manual/CI-secret-gated run, not part of `make test`. The bundled `cases.jsonl` (47\ncases) and `eval-baseline.json` thresholds are versioned in `benchmarks/token-savings/` — the\nbaseline is a placeholder until it's been run once for real and the numbers copied in\ndeliberately (the file is never auto-overwritten by a run).\n\n## MCP tools\n\n- `trovex(q)`: route a question to the right on-disk `.md` and get back `path:line` pointers\n with freshness markers, not a pile of files to rank.\n- `trovex_write(content, kind?, doc_id?, tags?, section?)` / `trovex_read(query | doc_id, section?)`:\n docs owned *inside* trovex. An agent stores a record (an incident, a decision, \"what\n actually worked\") once; every other agent and a second dev read it back as content\n (optionally just one section) instead of re-deriving it. Pass `section=` to `trovex_write`\n to patch one heading's section in place instead of replacing the whole doc.\n- `trovex_search(query, k?, tags?)`: passage-level retrieval across the store with tag\n filters, for when you want the top matching chunks rather than one canonical doc.\n- `trovex_tag(...)` / `trovex_delete(...)`: tag or soft-delete a stored doc; delete is a\n recoverable archive, not a hard wipe. Both touch only the trovex store, never your files.\n\nHumans read trovex-owned docs at `/doc/{id}` in the rendered reader. To make agents route\n`.md` writes through `trovex_write` instead of the disk, install the PreToolUse hook\n`deploy/hooks/trovex-md-guard.sh` and carve out exceptions in `.trovexignore`.\n\n## How it compares\n\n- vs `CLAUDE.md` / `AGENTS.md`: one static file that goes stale and can't route a question\n to the right doc, vs many docs kept canonical and served per query. [More](https://trovex.dev/vs/claude-md/).\n- vs `repomix` / files-to-prompt: pack the whole repo into the window vs retrieve the one\n answer. [More](https://trovex.dev/vs/repomix/).\n- vs a vector DB / plain RAG: a ranked pile of candidate chunks with no freshness signal vs\n one current doc with an explicit marker. [More](https://trovex.dev/vs/vector-db-rag/).\n\nThe reasoning behind the ~60% number is written up in\n[the benchmark methodology](https://trovex.dev/measure).\n\n## Stack\n\n- Python 3.11 + uv\n- FastAPI (MCP HTTP + server-rendered HTML UI)\n- fastembed (local embeddings, ONNX under the hood)\n- sqlite-vec (vector search in SQLite)\n- Jinja2 + HTMX (UI, no build step)\n\n## Embeddings: local by default, bring your own\n\ntrovex embeds locally out of the box with `BAAI/bge-small-en-v1.5` (ONNX, 384-d).\nNo API key, nothing leaves your machine. You can swap in any embedder:\n\n- **Another local model:** `TROVEX_EMBED_MODEL=` plus\n `TROVEX_EMBED_DIM=` if it's not a built-in.\n- **An OpenAI-compatible endpoint** (incl. a local server like Ollama, LM Studio,\n vLLM): `TROVEX_EMBED_PROVIDER=openai`, `TROVEX_EMBED_MODEL=`,\n `TROVEX_OPENAI_BASE_URL=http://localhost:11434/v1`, `TROVEX_EMBED_DIM=`.\n Point it at `localhost` and you stay fully local; point it at OpenAI\n (`text-embedding-3-large`) for stronger retrieval at the cost of sending each\n chunk to OpenAI's API.\n\nChanging the model changes the vector dimension, so switching requires a reindex.\n\n## Public beta\n\ntrovex is in public beta. Install it, run it on your repo, and if it saves you tokens a\n[GitHub star](https://github.com/TsukumoHQ/trovex) helps other devs find it. Issues and\nPRs welcome.\n\nQuestions, or comparing notes with other people running agents? Join the community on Discord:\n[tsukumo.ch/discord](https://tsukumo.ch/discord?utm_source=github&utm_medium=readme&utm_campaign=discord&utm_content=community).\n\n## Security\n\ntrovex is **local-first and single-tenant**: it runs on your machine, indexes your docs, and\nserves your agents. Mutations are gated behind the `X-TROVEX-Write-Token` header, and the\ndefault is **fail-closed**: with no token configured, trovex auto-generates a per-instance\ntoken on first run and persists it to `/.write_token` (chmod 600), so a\nnetwork-exposed instance does not accept anonymous writes. Set `TROVEX_WRITE_TOKEN` to share\none token across machines, or `TROVEX_ALLOW_UNAUTH_WRITES=1` to deliberately run with open\nwrites on a trusted localhost. The trust model, what's hardened, and how to report a\nvulnerability are documented in [`SECURITY.md`](SECURITY.md).\n\n## License\n\ntrovex is licensed under the **GNU AGPL-3.0-or-later** (see [`LICENSE`](LICENSE)). You can\nself-host and modify it freely; if you run a modified version as a network service, AGPL\nrequires you to share your changes.\n\n## Part of the suite\n\ntrovex is the **context** layer of a four-part open-source suite for running AI coding agents in production, built by [tsukumo](https://tsukumo.ch):\n\n- **trovex**, context: serve agents the one canonical doc per query instead of rereading the repo (~60% fewer tokens per lookup; method at [trovex.dev/measure](https://trovex.dev/measure)).\n- **[wrai.th](https://github.com/TsukumoHQ/WRAI.TH)**, orchestration: run and coordinate a fleet of agents.\n- **[yoru](https://yoru.sh)**, observability: session receipts of what each agent actually did.\n- **[dokan](https://github.com/TsukumoHQ/dokan)**, deterministic execution: run the agent's settled, repeatable work as scripts in clean containers, no model in the loop.\n\n## Working with a team?\n\ntrovex is free to run yourself. If your team is rolling out coding agents at scale and wants\nhands-on help doing it well, or to embed and host a modified trovex privately without the\nAGPL's copyleft obligations, that's what the consulting is for.\n[Reach out](https://tsukumo.ch/go/consulting?s=readme) to tsukumo, the team behind trovex.\n", "bytes": 13830, "sha": "a6b2bf7e83eb11f7891927c89a8e97c1c64b057ffaa1f4dc1c8b502a30800202", "repo_slug": "tsukumohq/trovex", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_tsukumohq_trovex_cf784fb0/readme" }