Trove / Guides
Personal trove
The personal trove's layout, the Markdown and JSON entry format every trove shares, how a trove is chosen, and what is worth saving or skipping.
On this page
The personal trove is a folder of plain files at ~/.claude/trove/ that follows you across every project. The plugin, the trove binary and you can all read and write it, and you can edit it by hand. The entry format on this page is shared by every trove, including the sections of a project trove.
First principles
Every Claude Code session normally starts from zero. What you taught an agent yesterday is gone unless it is written somewhere the next session reads.
Writing it down only helps if reading it is cheap. So each fact gets its own small file, and one index line per fact goes into INDEX.md. The index is what loads every session: an agent sees every title for the price of one short file, and opens a full entry only when it matters. One fact per file also means an entry can be corrected or deleted without touching the others, and a new machine gets the same knowledge by copying one folder.
Layout
~/.claude/trove/
├── INDEX.md # one line per entry, newest first
└── entries/
├── use-pgx-not-orm.md
├── service-ports.json
└── staging-db-mirror.md
A project trove uses the same entry format, with one INDEX.md and entries/ folder per section.
Which trove is used
- Personal,
~/.claude/trove/: one trove for all your work. - Project,
<repo>/.claude/trove/: lives in the repository, split into sections and committed to share with a team.
Writers pick one. The remember and recall skills, trove.sh and trove remember use the project trove when <repo>/.claude/trove/INDEX.md exists, otherwise the personal trove. For trove.sh, <repo> is the Git top level; for trove remember, it is --repo, or else the nearest folder, starting from the current one, that holds .trove/ or .git.
Readers see both. The SessionStart hook loads the project trove and then the personal trove when both exist, and trove ask searches both.
One fact, one file
Each entry is a single file in entries/. Pick the format by the shape of the content, and prefer Markdown when in doubt. trove remember always writes Markdown.
Markdown, for prose
Decisions, gotchas, conventions and short narrative notes.
---
title: Use pgx + sqlc, not a heavy ORM, in Go services
slug: use-pgx-not-orm
type: decision
created: 2026-06-13
tags: [go, postgres, data-layer]
---
We standardised on pgx for the driver and sqlc to generate
type-safe query code from plain SQL. GORM was rejected for
hiding query cost behind reflection.
**Why it matters:** reach for this on any new Go service.
**Related:** [[deploy-single-binary]]
[[slug]] links to another entry. A slug that does not exist yet is fine.
JSON, for structured data
JavaScript Object Notation (JSON) entries hold mappings, lists of records, configuration snapshots, endpoint tables and schemas. The payload goes under data, and summary is the one-line hook.
{
"title": "Local service ports",
"slug": "service-ports",
"type": "reference",
"created": "2026-06-14",
"tags": ["infra", "ports"],
"summary": "which service runs on which port",
"data": {
"web": 8000,
"trove-ui": 8010,
"partners": 8011
}
}
Entry types
convention, decision, gotcha, preference, reference, project, snippet and context. In a project trove the type picks the section: convention and preference go to conventions/, context to context/, and the rest to memory/.
INDEX.md
One bullet per entry, newest first, below the <!-- entries below --> marker. The file extension tells readers which format the entry uses.
# Trove Index
<!-- entries below -->
- [Use pgx + sqlc, not a heavy ORM](entries/use-pgx-not-orm.md) - Go data-layer decision
- [Local service ports](entries/service-ports.json) - infra reference (JSON)
- [Staging DB mirrors prod nightly](entries/staging-db-mirror.md) - gotcha, do not seed
The index does most of the work:
- It is what loads every session. The SessionStart hook prints
INDEX.md, one compact line per entry, so Claude knows what exists without loading every file. - It keeps recall cheap. Claude scans the index, then opens only the entries that matter.
- It is your map. It is readable and you can prune it by hand.
- The one-line hooks make entries findable. Write each one to match the words someone would search with.
trove rememberuses the first line of the body, cut to 100 characters.
Creating it
/trove:init --user in Claude Code, or /trove:init outside a Git repository. From a shell:
bash /path/to/trove/plugins/trove/scripts/trove.sh init --user
Both create ~/.claude/trove/INDEX.md and entries/, and never overwrite existing files.
What to save
- Decisions and their rationale.
- Gotchas and footguns.
- Conventions and preferences an agent should follow.
- External references such as web addresses, dashboards and tickets.
- Constraints that are not obvious from the code.
What to skip
- Secrets and credentials. A project trove is committed to Git, and
trove askcan send excerpts to a provider (with secrets redacted).trove rememberand therememberskill refuse entries that look like secrets. - Transient task state that only matters to one conversation.
- Facts that are easy to re-derive from the code, Git history or existing docs.
If asked to remember one of these, the remember skill captures what was non-obvious about it instead.
Keeping it honest
- The
rememberskill updates an existing entry instead of writing a near-duplicate, and deletes entries that have become wrong.trove rememberrefuses an existing slug unless you pass--update. - The
recallskill flags entries that conflict or look stale, such as an oldcreateddate or a reference to a file that no longer exists.