Trove / Get started
Engine quickstart
Index a repository with the trove CLI, check its status, ask a first cited question, run a layered query, and capture a memory from the shell.
On this page
This page assumes you have built the engine and put trove on your PATH, as described in Installation. From inside the Trove clone you can replace trove with cargo run -p trove-cli --.
The examples below index the Trove repository itself at the current main branch. Your numbers will differ.
First principles
The steps follow what depends on what. Everything that reads code (status, query, ask, ship) reads the index in .trove/, so indexing comes first. Reading comes next, because it changes nothing and shows whether the index is useful. Writing memory comes last, because trove remember writes into a trove that has to exist already. The engine never creates one on its own, because where your knowledge lives, in the repository or in your home folder, is your choice.
1. Index a repository
cd /path/to/repo
trove index
The command walks the repository, writes .trove/ at its root and prints a one-line report:
Indexed 134 files, 1372 symbols, 134 modules, 3 subsystems (0 stale rebuilt)
Add .trove/ to your .gitignore. The Trove repository ignores it, and the plugin’s index skill says not to commit it unless you want the index checked in.
Run index, status and query from the repository root, or pass --repo /path/to/repo. They use the current directory as the repository.
2. Check the status
trove status
Trove v0.2.0
Repo: /path/to/repo
Indexed: 2026-10-25T03:48:26.940491+00:00
Counts: 1372 symbols, 134 modules, 3 subsystems
If there is no index yet, it prints No index found. Run: trove index. Add --json to get the manifest as JavaScript Object Notation (JSON).
3. Ask a question
trove ask ranks everything Trove can see (troves, repository Markdown, the code index and installed tools) and prints the best hits with a citation each:
trove ask --no-tools "how does the retrieval budget work"
1 doc VISION.md:90 Retrieval Pipeline
Every retrieval should ask: do I need more detail? If no, stop.
3 symbol crates/trove-retrieve/tests/eval.rs:141 retrieval_eval_baseline
fn retrieval_eval_baseline() {
5 symbol crates/trove-core/src/hierarchy.rs:29 default_token_budget
pub fn default_token_budget(self) -> usize {
-- 12 of 31 matches | ~357/1500 tokens | offline retrieval; add --provider for a written answer
The output above is trimmed. Each hit shows its rank, its source kind, a path:line citation and the line that matched. The footer shows how many hits fit the token budget (1,500 by default). --no-tools leaves the installed tool catalog out; without it, the first run builds the catalog. See Asking questions.
4. Query the layers
trove query assembles orientation context top-down, from the architecture summary to subsystems, modules and symbols:
trove query "retrieval pipeline budget"
# Query: retrieval pipeline budget
Estimated tokens: 893 / 200000 (stopped early: false)
## L4 Architecture Memory [summary] architecture:root
Trove-indexed repository with 1372 symbols across 3 subsystems. ...
_confidence: synthesized from index | path: indexer -> architecture_
Each item shows its memory level, compression tier, object id, content, and why it was retrieved. Set a smaller budget, or ask for JSON:
trove query "auth middleware" --budget 20000
trove query "auth middleware" --json
See Retrieval levels for how the budget is spent.
5. Capture a memory
trove remember writes one entry into the repository’s project trove, or into your personal trove when the repository has none. It needs an existing trove: create one with /trove:init in Claude Code, or run bash /path/to/trove/plugins/trove/scripts/trove.sh init from your repository.
echo "Bulk inserts must run inside one transaction." \
| trove remember "WAL gotcha: bulk inserts" --type gotcha --tags db,postgres
Remembered 'WAL gotcha: bulk inserts' -> .claude/trove/memory/entries/wal-gotcha-bulk-inserts.md (memory)
The next trove ask finds it. See Project troves for how entries are routed and rendered.
6. Optional: bring trove entries into the layered query
trove query reads only .trove/. To include your trove entries in its results, import them as historical memory:
trove import-historical
trove ask does not need this step; it reads the trove folders directly.
Next steps
- Indexing a repository explains what is parsed and what lands in
.trove/. - Asking questions covers sources, ranking, budgets and the optional written answer.
- CLI reference lists every subcommand and flag.