Source: https://velofy.co/trove/project-trove/ [Trove](https://velofy.co/trove/) / Guides # Project troves How a project trove splits memory into conventions, memory and context, routes entries, renders them as skills and AGENTS.md, and guards against secrets. A project trove is the memory of one repository, kept in the repository at `.claude/trove/`. It is plain files that you commit, review and share like code. This page covers its layout, how entries get in, how they become skills, and how secrets are kept out. ## First principles An agent needs different knowledge at different moments. Before writing code it needs the house rules. Before changing behavior it needs to know what was decided and why. Before touching an unfamiliar area it needs a map. Loading all three into every session wastes the context window; loading none means relearning them every time. So a project trove keeps three sections, and each one becomes a Claude Code skill whose description names the moments it helps with. Claude Code reads the short descriptions up front and loads a full skill only when the task matches. The source of truth stays in small entry files; the skills are generated from them and never edited by hand. Two facts shape the rest. First, the skills are written for Claude Code, but every agent can read a file, so an `AGENTS.md` block points other agents at the same rendered files. Second, a map of the code goes stale as the code changes, so most of the context section is generated from the engine index and rebuilt on demand, while hand-written notes sit beside it untouched. ## Layout ``` .claude/ ├── trove/ │ ├── INDEX.md # links to the three sections │ ├── conventions/INDEX.md + entries/ │ ├── memory/INDEX.md + entries/ │ └── context/INDEX.md + entries/ # generated entries refreshed on re-index └── skills/ ├── -conventions/SKILL.md ├── -memory/SKILL.md └── -context/SKILL.md AGENTS.md # a marked trove block for other agents ``` `` is the repository folder name in lowercase kebab case, cut to 40 characters. Set `TROVE_PROJECT` to override it, and run `trove.sh project` to print it. Create the layout with `/trove:init` inside a Git repository, or from a shell: ``` bash /path/to/trove/plugins/trove/scripts/trove.sh init --project ``` Running `init --project` on an older flat project trove keeps its `entries/` folder and adds the section links. The engine reads both shapes: `trove ask`, `trove import-historical` and `trove ship` see flat and sectioned entries alike. ## The three sections * **`conventions/`**: how this repository is built. Style, structure, naming, testing, commit and pull request (PR) rules, and things to never do, phrased as rules. Types `convention` and `preference`. The `-conventions` skill is described for writing, editing, reviewing or committing code. * **`memory/`**: what happened and why. Decisions with their rationale, gotchas, incidents, history and external references. Types `decision`, `gotcha`, `reference`, `project` and `snippet`. The `-memory` skill is described for changing behavior, choosing an approach, debugging and “why is it like this” questions. * **`context/`**: where things live and how they connect. Mostly generated from the engine index, plus hand-written notes the engine cannot infer. Type `context`. The `-context` skill is described for orienting, locating code and planning changes across modules. A rule of thumb from the remember skill: if it tells an agent how to write code here, it is a convention; if it explains why something is the way it is, it is memory; if it says where things are and how they connect, it is context. ## Adding entries There are three ways in. All of them produce the same file format, described in [Personal trove](https://velofy.co/trove/personal-trove/). ### From Claude Code `/trove:remember `, or say “remember this”. The skill routes the entry, writes it, runs the secret guard, updates the section index and re-renders the section’s skill. ### From any shell or agent `trove remember` is the deterministic write path for scripts, Codex, Cursor, pi or you: ``` trove remember "Retry HTTP calls" --type convention \ --body "Wrap outbound HTTP calls in fetchWithRetry from src/retry.js." ``` ``` Remembered 'Retry HTTP calls' -> .claude/trove/conventions/entries/retry-http-calls.md (conventions) ``` * The title words are positional. The slug is the title in lowercase kebab case. * `--type` is required and must be one of `convention`, `decision`, `gotcha`, `preference`, `reference`, `project`, `snippet` or `context`. It routes the entry: `convention` and `preference` to `conventions/`, `context` to `context/`, everything else to `memory/`. `--section` overrides the route. * The body comes from `--body`, or from standard input when it is piped. * `--tags a,b` adds tags. * An entry whose slug already exists is refused. `--update` replaces it, keeps its original `created` date and refreshes its single index line. * An entry that looks like it contains a secret is refused before anything is written. The error names the line and the kind of secret, never the value. * With `--json` it prints `slug`, `path`, `section` and `updated`. `trove remember` writes the entry and the index line but does not re-render the skill. Run `trove.sh render
`, or let the next SessionStart hook do it. Without a project trove, `trove remember` writes into the personal trove’s flat `entries/`, and `--section` is an error there. With neither trove present it stops and asks you to create one. ### By hand Write a file into `
/entries/`, add a line at the top of that section’s `INDEX.md` (below ``), then render: ``` bash /path/to/trove/plugins/trove/scripts/trove.sh guard .claude/trove/memory/entries/my-entry.md bash /path/to/trove/plugins/trove/scripts/trove.sh render memory ``` `trove.sh route ` prints the section for a type. It accepts a few extra words that `trove remember` does not: `style`, `rule`, `naming` and `workflow` route to `conventions`; `architecture`, `map`, `subsystem`, `module` and `overview` route to `context`; anything else routes to `memory`. ## Rendering skills ``` bash /path/to/trove/plugins/trove/scripts/trove.sh render all ``` For each section, render writes `.claude/skills/-
/SKILL.md` with: * front matter with the skill `name` and a `description` that names when to load it, * a short instruction for the agent and the number of entries, * every entry inlined in `INDEX.md` order (newest first), each with its source path, * once the skill passes about 24,000 bytes, a “More entries” list of the remaining paths instead of their text. Set `TROVE_SKILL_MAX_BYTES` to change the limit. Rendering is deterministic and only rewrites a file whose content changed. The secret guard runs over each rendered skill and redacts anything that looks like a credential, with a warning naming the section to fix. `render all` also refreshes the `AGENTS.md` block. Claude Code picks up edits to existing skill folders mid-session. If `.claude/skills/` did not exist when the session started, run `/reload-skills`. The SessionStart hook re-renders any section whose `INDEX.md` or entries are newer than its skill, so hand edits and `git pull` never leave skills stale for long. ## The context section `trove.sh context` reads the engine output in `.trove/` and writes generated entries into `context/entries/`: * `architecture.md`: symbol, module and subsystem counts and the architecture summary. * `subsystem-.md`: one per subsystem. * `key-modules.md`: the 20 modules with the most symbols. Generated entries carry the front matter line `generated: trove-index` and are replaced wholesale on every run. Their index lines live between `` and `` in `context/INDEX.md`. Hand-written context entries and their index lines are kept. The command needs `jq` or `python3`; set `TROVE_JSON` to pick one. `trove.sh sync` runs `context` when `.trove/manifest.json` exists, then `render all`. `/trove:index` runs `trove index` followed by `trove.sh context`. ## The AGENTS.md block `init`, `render all` and `trove.sh agents` maintain a block between `` and `` in `AGENTS.md` at the repository root. It lists the three rendered skill files and their source folders, and tells other agents to read them before working and how to add an entry. If `AGENTS.md` does not exist it is created. If it exists, the block is appended the first time and replaced after that; the rest of the file is kept. ## The secret guard `trove.sh guard ...` scans for credential shapes and exits 1 on a hit, naming the file and line without printing the value. It looks for: * tokens with a known prefix: `sk-`, `AKIA` and `ASIA`, `ghp_` and the other `gh?_` forms, `github_pat_`, `glpat-`, `shpat_` and its siblings, `xoxb-` and the other Slack forms, `AIza` and `npm_`, * private key blocks, * assignments such as `token = ...` or `password: ...`, where the key names a credential (including passphrase, signing key, master key, session key and spaced spellings such as `api key`) and the value has at least 8 characters including a digit, or at least 20 characters. Placeholders such as `$TOKEN`, `${TOKEN}` and `` do not match. `--redact` rewrites the file with each match replaced by `[REDACTED]` instead of failing. `trove remember` uses the Rust detectors from the `trove-redact` crate, which `trove ship` and `trove ask` also use. Those Rust detectors check more shapes than this Bash guard, including bearer tokens, passwords inside web addresses, Stripe and SendGrid keys and high-entropy strings, so an entry written with `trove remember` gets the wider check. ## Environment variables * `TROVE_ROOT`: the repository root for `trove.sh`. Default: the Git top level, else the current directory. * `TROVE_PROJECT`: the project name used in skill names. * `TROVE_SKILL_MAX_BYTES`: the inline size limit per skill. Default `24000`. * `TROVE_JSON`: `jq` or `python3`, the reader `trove.sh context` uses. * `QUIET`: when set, `trove.sh` prints no progress lines.