Skip to content
Trove

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
  1. First principles
  2. Layout
  3. Which trove is used
  4. One fact, one file
  5. Markdown, for prose
  6. JSON, for structured data
  7. Entry types
  8. INDEX.md
  9. Creating it
  10. What to save
  11. What to skip
  12. Keeping it honest

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 remember uses 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 ask can send excerpts to a provider (with secrets redacted). trove remember and the remember skill 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 remember skill updates an existing entry instead of writing a near-duplicate, and deletes entries that have become wrong. trove remember refuses an existing slug unless you pass --update.
  • The recall skill flags entries that conflict or look stale, such as an old created date or a reference to a file that no longer exists.