Trove / Reference
.trove directory format
Every file and folder the Trove engine writes under .trove/, and the fields of the manifest, memory objects, symbols, the dependency graph and the ship output.
On this page
The engine stores everything as pretty-printed JavaScript Object Notation (JSON) under .trove/ at the repository root.
First principles
Almost everything in .trove/ is derived: the index and the imported entries can be rebuilt from the source code and the troves at any time, and so can the ship/ output. That is why it is kept out of Git, and why deleting it is a safe way to start clean. The exceptions are execution.json and patches.json, which hold what trove record and trove patch logged; copy them first if you want to keep them. Your own knowledge lives elsewhere, in .claude/trove/ and ~/.claude/trove/, which are never rebuilt.
Each object is its own small JSON file so a reader can load one level without parsing the whole index, and so you can inspect any object with a text editor or jq.
Layout
.trove/
├── manifest.json # written by index
├── symbols.json # all symbols, written by index
├── graph.json # dependency graph, written by index
├── symbols/ # one memory object per symbol (L1)
├── modules/ # one memory object per file (L2)
├── subsystems/ # one memory object per subsystem (L3)
├── architecture/ # architecture_root.json (L4)
├── historical/ # imported trove entries (L5), from import-historical
├── repository/ # repository_index.json (L6), from import-historical
├── execution.json # from trove record
├── patches.json # from trove patch
└── ship/ # default output of trove ship
File names inside the object folders are the object id with every character other than letters, digits, - and _ replaced by _, plus .json. For example module:PRD.md is stored as modules/module_PRD_md.json.
manifest.json
{
"version": "0.2.0",
"repo_root": "/absolute/path/to/repo",
"indexed_at": "2026-10-25T03:48:26.940491+00:00",
"symbol_count": 1372,
"module_count": 134,
"subsystem_count": 3
}
version is the engine’s version, 0.2.0 for both the release and the current main branch. trove status prints this file, and trove ship and trove.sh context check for it to decide whether an index exists.
Memory objects
Every file in the object folders is one memory object with these fields:
id: for examplemodule:src/lib.rs,subsystem:crates,architecture:root,historical:<slug>,repository:index, or a symbol id.kind:symbol,module,subsystem,architecture,historicalorrepository.path: file path, subsystem name, or repository name.text:raw,summary,ultra_summary,keywordsandembedding(always null).dependencies,symbols: related ids and paths.hash: a Secure Hash Algorithm 256 (SHA-256) hex digest.updated_at: a timestamp in Coordinated Universal Time (UTC).importance,risk: numbers between 0 and 1.confidence:score,reason,retrieval_path,distance,last_verified, or null.git_commit: always null in the current code.
symbols.json
An array of symbols:
id:path:kind:name:line.name,kind,path,start_line,end_line.signature: first line of the node for functions, methods and structs, otherwise null.owner,dependencies,references: not filled in the current code.complexity: count of branch keywords plus one per ten lines.hash: SHA-256 of the file content.
graph.json
nodes:id,path,kind. Onefilenode per file with symbols, and one node per symbol with the symbol kind.edges:from,to,kind. Edges have kindimport, from a file path to the resolved import.
execution.json and patches.json
See record and patch in the CLI reference for their shape. trove ship reads the latest 30 patches into its decisions document.
ship/
The default output folder of trove ship, with a .trove-ship file that lists the files ship owns there. In the default folder format it holds README.md, overview.md, architecture.md, setup.md, conventions.md, decisions.md, gotchas.md, REDACTION_REPORT.md and redaction-report.json. See Handoff docs with trove ship.
Housekeeping
- The indexer skips
.trove/when it walks the repository. - Re-indexing overwrites objects with the same id but does not delete objects for files that no longer exist. To start clean, delete
.trove/and runtrove index. index,status,query,import-historical,recordandpatchcreate.trove/in the folder they treat as the repository, even when they only read. A stray empty.trove/in a subdirectory comes from running one of them there without--repo.- Keep
.trove/out of Git unless you want the index checked in.