Tool
capture_concept
Save a repository rule or explanation so future agent sessions can find and use it.
Some discoveries matter long after the task that revealed them: why a component has a constraint, which assumption a test protects, or what must be checked before changing a subsystem. capture_concept records one such idea as a Markdown file under .repoql/concepts/.
For how this knowledge reaches future sessions, read Concepts.
Write the decision a future reader needs
A concept starts with a short statement of what holds true or what work should preserve. Add the reason, an example, and evidence where they help someone apply it. The aim is to retain the understanding that would otherwise have to be rediscovered.
Concept files can be reviewed, edited, and committed with the code. Capturing one writes a local file; it does not commit or publish it. Keeping what you learn explains how to choose and review a useful concept.
Choose when it should appear
relevance names the files where the idea applies. RepoQL can include contextual hints during an agent’s work in that area, and the concepts read view retrieves relevant concepts directly.
A universal concept is included in the repository’s general concept index. Use that for rules an agent needs before choosing which files to touch. A subsystem-specific rule usually belongs in contextual guidance. Delivery depends on the agent’s RepoQL integration; opening a file in any editor does not automatically display a concept.
Treat verification as evidence, not a guarantee
For rules and knowledge, verification sources let the checker compare the claim with code or documentation. Verification uses inference and can be skipped when that service is unavailable, or report an inconclusive result. Read its outcome even when the file was successfully written.
A concept can still become stale. Keep it close to the evidence, revisit it when the governing code changes, and remove a rule when its constraint no longer applies.
Example: retain a website publishing rule
This repository records a rule that commands shown on the website must be run before shipping. The useful information is the obligation and where it applies, rather than a transcript of the session that discovered drift.
| Part of the concept | Example |
|---|---|
| Name | WebsiteCommandsMustBeRunBeforeShipping |
| Invariant | A command shown on the website ships only after being run verbatim against the current rql binary. |
| Category | rule |
| Relevance | file:///src/cloud/website/** |
| Universal | false |
Fields and categories
| Field | Use |
|---|---|
| name | Required. CamelCase identifier and filename. |
| category | Required. wisdom, rule, or knowledge. |
| invariant | Required. The central statement, up to 240 characters. |
| relevance | Required. URI patterns for where the idea applies. |
| isUniversal | Required. Whether it belongs in the general concept index. |
| why · example · depth | Optional explanation and supporting detail. |
| tags · subcategory | Optional organisation within the concept collection. |
| verification · ttlDays | Evidence addresses and a positive interval for rechecking. Applies to rules and knowledge. |
Wisdom captures a general principle and ignores verification fields. Rules describe constraints; verification is encouraged. Knowledge records factual context and requires verification sources. Personal preferences and temporary task status belong in session notes or the agent’s own memory.
Further reference
In the installed manual: help:///tools/capture-concept.md, help:///commands/concept.md.