trovex vs CLAUDE.md / AGENTS.md
A static instructions file is the right tool for a few stable rules. Here's where it stops scaling — and what trovex does instead.
CLAUDE.md and AGENTS.md are one static markdown file your agent loads in full every session. They're great for a short, stable set of project rules. They go stale, don't scale past a handful of topics, and can't route a question to the right doc or section. trovex indexes many docs and serves the single current one that answers a query — a path:line pointer with a freshness marker — for about 60% fewer tokens per lookup. The two work well together: keep a small CLAUDE.md, let trovex carry the corpus.
What are CLAUDE.md and AGENTS.md?
They are convention files an AI coding agent reads at the start of a session — CLAUDE.md for Claude Code, AGENTS.md as the cross-tool equivalent picked up by editors like Cursor and others. You write your project's rules and context into one markdown file, and the agent loads the whole thing into its context window. For a tight, rarely-changing set of instructions — build commands, code style, "always run the tests" — that's a clean, zero-infrastructure fit.
Where does a single static file stop working?
When your real knowledge outgrows one file. A static blob has three structural limits:
- It goes stale. The file is a copy. When the underlying runbook, ADR, or README changes, the blob doesn't, and nothing flags the drift. Your agent reads confident, outdated instructions.
- It doesn't scale. One file is loaded whole, so every topic you add costs tokens on every session for every agent — whether or not the question needed it.
- It can't route. There's no "which doc answers this?" step. The agent gets the same fixed text for every query and still has to go reread the repo to find specifics.
How is trovex different?
trovex indexes your repo's markdown and answers a query with the one canonical doc that addresses it, down to the section — not a fixed blob, and not a pile of files to sift. Each result carries a freshness marker (canonical / stale / duplicate), so the stale and duplicate copies never reach the agent's context. An agent that learns something writes it back through one shared point, so every other agent and teammate reads the same source of truth. Cost scales with the question, not the size of your docs.
| Capability | CLAUDE.md / AGENTS.md | trovex |
|---|---|---|
| Setup | Write one file ✓ zero infra | One local process, ~1-minute install |
| Routes a query to the right doc | — fixed text for every query | ✓ one canonical answer per query |
| Freshness signal | — no staleness signal | ✓ canonical / stale / duplicate |
| Section-level reads | — whole file, every time | ✓ serves the section that answers |
| Scales to many docs | — one blob, loaded whole | ✓ cost scales with the question |
| Shared write-back (SSOT) | — hand-edited | ✓ agents record once, all read it |
| Tokens per lookup | Full file each session | ~60% fewer vs rereading the top stale files |
| Runs locally, no keys | ✓ | ✓ SQLite + ONNX, no cloud |
When is CLAUDE.md the right choice?
When your context fits in a page and rarely changes. A small project, a fixed set of conventions, a solo repo with three docs — a static file is simpler and you should use it. trovex earns its place when knowledge lives across many markdown files that drift, when several agents or teammates need the same current answer, or when you're paying tokens to reread the repo every session to figure out which doc is canonical. Most teams end up with both: a short CLAUDE.md for rules, trovex for the corpus.
FAQ
What is the difference between trovex and CLAUDE.md?
CLAUDE.md is one static markdown file your agent loads in full every session. trovex indexes many docs and serves the single current one that answers a given query, with a freshness marker, instead of loading everything up front. CLAUDE.md is a fixed blob; trovex routes a question to the right doc and section.
Should I replace my CLAUDE.md with trovex?
Not necessarily. Keep a short CLAUDE.md or AGENTS.md for a handful of stable, always-relevant rules (build commands, conventions). Add trovex when your real knowledge lives across many markdown files that go stale and don't fit in one blob. They work well together.
Does CLAUDE.md scale to a large set of docs?
Not well. A single file has to be loaded whole, so every topic you add costs tokens on every session, and it can't route a question to the right doc or signal which copy is current. trovex serves one canonical answer per query, so cost scales with the question, not the size of the corpus.
Give your agents one current answer per query.
Point trovex at your repo. Your agents stop rereading it in about a minute.
trovex is in private beta — request access and we'll bring you in.
Open source. No cloud, no API keys. Your docs never leave your machine.