Tool

capture_concept

Save something you learned about a repository, so the next agent session starts knowing it. capture_concept checks the fields, fact-checks the claim against the code when you give evidence, and writes one Markdown file under .repoql/concepts/.

What concepts are, and how they reach agents, is covered in Concepts. This page is about calling the tool well.

If you	Use
Learned a rule or fact the next session needs	`capture_concept`
Learned what your team calls something	`capture_vocabulary`, below
Want the concepts that apply to some files	`read` with `=> concepts`

Pick the category first

The category decides which other fields are required, allowed or refused. Categories explains what each one is for.

Category	Relevance · verification · universal
`principle`	No relevance: it applies everywhere. No verification. Always universal.
`wisdom`	Relevance required. No verification. Universal is your choice.
`rule`	Relevance required. Verification optional and encouraged. Universal is your choice.
`shape`	Relevance required: the location it keeps coherent. Verification optional. Universal is your choice.
`knowledge`	Relevance required. Verification required. Universal is your choice.

“No” means refused, not ignored. A principle with relevance, or wisdom with verification, is rejected with a message that names the fix.

Write the fields

The invariant is one idea in one short sentence, at most 240 characters. The reason, the stakes and the story go in why, example and depth. If you want to write “and” or “or”, you probably have two concepts.

Relevance is where the idea applies, as addresses such as file:///src/auth/**. The concept is offered to agents working on matching files. It must match at least one indexed file, or the capture is refused. Cover where the idea applies, not just where you learned it.

isUniversal decides whether every future session carries the concept up front. Ask one question: could an agent break this without ever opening a file that relevance names? If yes, make it universal. If no, leave it contextual. It still surfaces when an agent works in those files.

Verification names the evidence, anchored as closely as you can: #symbol= follows a declaration as the code moves. With verification, give ttlDays: how many days the evidence stays trusted before it is checked again.

The name is CamelCase and starts with a capital letter. It is the file name too. Capturing the same name again replaces the concept, and moves it if the category changed.

Refusals and fact-checks

Fields are checked first. A capture that fails writes nothing, and each error names the field and what to do. This knowledge concept has no verification:

Terminal

rql concept add RefreshReplacesTheToken knowledge \
  "Refreshing a CLI token issues a new token in place of the old one." \
  --tags "refresh,cli tokens" --relevance "file:///src/auth/**"

Output

Concept validation failed.
- verification: Verification is required for knowledge concepts — a map that cannot be re-checked misleads the moment things move.
Help: rql read "help:///tools/capture-concept.md" — Capture concept help

With verification, the claim is then fact-checked against the evidence. If the check fails, nothing is written. It can also pass with a warning, so read what it says. If you aren’t signed in to cloud inference, the check is skipped and the result says so.

What comes back

Terminal

rql concept add RefreshReplacesTheToken knowledge \
  "Refreshing a CLI token issues a new token in place of the old one." \
  --tags "refresh,cli tokens" --relevance "file:///src/auth/**" \
  --verification "file:///src/auth/TokenService.cs#symbol=TokenService.Refresh" \
  --ttl-days 180 --subcategory auth --contextual

Output

Captured concept: concept:///knowledge/auth/RefreshReplacesTheToken.md
Path: .repoql/concepts/knowledge/auth/RefreshReplacesTheToken.md
Verification: passed - WARN - `TokenService.Refresh` delegates to `store.Replace(token)`, which returns a fresh token string in place of the expiring one, matching the invariant that refresh issues a new token replacing the old.  Craft: The invariant is verifiable, but citing the `TokenStore.Replace` implementation alongside `Refresh` would make the "new token replaces old" claim directly evidenced rather than inferred from the method name.

The written file, first lines

---
description: "Refreshing a CLI token issues a new token in place of the old one."
tags:
  - "refresh"
  - "cli tokens"
category: knowledge
subcategory: auth
universal: false
relevance: "file:///src/auth/**"
verification: "file:///src/auth/TokenService.cs#symbol=TokenService.Refresh"
ttl: 180
verified:
  date: "2026-09-29"
  commit: "c7a114319626"
---

An address for the new concept, and its path on disk.
The fact-check verdict. It passed, with a warning: the evidence shows the method delegates, not what the store does. Adding the store’s method to the verification would make the claim directly evidenced.
A verified stamp in the file, with the date and the commit it was checked against.

The file is written, not committed. Review it and commit it with your code. Each capture also rebuilds .repoql/concepts/README.md, the index of universal concepts.

capture_vocabulary

capture_vocabulary records your team’s name for something, with the plain words that should find it. It takes a term and a one-sentence meaning, both required. aliases is a semicolon-separated list of outside words, such as session;login session. scope limits where the sense applies, domain separates two senses of one term, and worktree works as it does for concepts.

Entries aren’t fact-checked. The result tells you which aliases already appear in your repository. From a terminal, use rql vocabulary add. discover_vocabulary shows an entry being added and then found.

Parameters

MCP · CLI	Meaning
`name` · first argument	Required. CamelCase name, which is also the file name.
`category` · second argument	Required. `principle`, `wisdom`, `rule`, `shape` or `knowledge`.
`invariant` · third argument	Required. One idea in one short sentence, at most 240 characters.
`tags` · `--tags`	Required. Comma-separated words an agent would search for. Name related concepts here.
`isUniversal` · `--contextual`	Required through MCP: `true` loads the concept into every session up front. The CLI records universal unless you pass `--contextual`.
`relevance` · `--relevance`	Where the idea applies, as semicolon-separated addresses. Required for every category except principle.
`verification` · `--verification`	Semicolon-separated addresses or web links that prove the claim. Required for knowledge, refused for principle and wisdom.
`ttlDays` · `--ttl-days`	Days before the evidence is checked again. Required with verification.
`subcategory` · `--subcategory`	A lowercase shelf under the category, which becomes a folder.
`why` · `--why`	Why the invariant holds: the mechanism, the stakes, the context.
`example` · `--example`	A concrete case that makes the invariant click.
`depth` · `--depth`	Extra points, one per line: distinctions, trade-offs, related concepts.
`worktree` · `--worktree`	Write into a mounted git worktree’s `.repoql/concepts/`, on its branch. Import the worktree’s directory first.

Further reference

In the installed manual: help:///tools/capture-concept.md, help:///commands/concept.md and help:///commands/vocabulary.md.