Getting oriented

Concepts

A concept is a lesson about your code, saved as a Markdown file in your repository: a rule, and the reason it exists. Agents that later work on that code are shown it, so a lesson learned once isn’t lost when the session ends.

RepoQL checks each concept against the code before saving it, and checks it again as the code changes. Vocabulary does the same job for names: it records what your team calls things, so agents can find them.

How it works

Your agent saves a lesson. It calls capture_concept with the rule, the reason, where the rule applies and the evidence for it. Saving a concept →
RepoQL checks it. It reads the evidence and writes the file only if the evidence supports the rule.
You commit it. The concept is a file, so your team reviews and shares it like code. A concept is a file →
Agents see it when it matters. Before an agent edits a file the concept covers, RepoQL shows it the concept. How agents see them →
RepoQL rechecks it. When the code no longer supports the rule, the concept is flagged for a person to decide. Keeping them true →

A concept is a file

Watch this part

The lesson from the film, as RepoQL saves it at .repoql/concepts/rule/auth/SignOutRevokesCliTokens.md:

relevance: file:///src/auth/**
verification: file:///src/auth/SignOut.cs
file:///src/auth/TokenController.cs
ttl: 90 days

Invariant
Signing a user out also revokes their CLI tokens.

Why
Sign-out ended the user’s Wristbands, but the CLI signs in with its own token, so a signed-out user’s CLI kept working.

Every concept holds one idea in two parts. The invariant is the idea itself, in one sentence. The why is the reason, written for someone who wasn’t there.

The metadata above the text says where the concept applies and what proves it. relevance is where it applies: this rule covers all of src/auth/. verification is its evidence: two files. ttl is how many days that evidence stays trusted before RepoQL checks it again.

Because it’s an ordinary file, you can read it, edit it and review its diff. Committing it is how your team, and their agents, get it.

Saving a concept

Your agent saves a concept with capture_concept, either on its own when it learns something the next session will need, or when you ask:

“Save what you just learned about sign-out as a concept.”

When the concept has evidence, RepoQL’s checker reads it and judges the claim. If the evidence doesn’t support it, nothing is written, and the agent is told why, so it can fix the claim or the evidence and try again.

Checking uses inference. When inference isn’t available, the concept is saved with checking skipped. It has no verified date, so rechecks pass it by: capture it again once inference is back to have it checked.

Choosing a category

The category says what kind of idea a concept is, and whether it can be checked.

Category	Use it for	Evidence
`rule`	Something that must not break.	Optional, and encouraged
`knowledge`	A fact about the code, such as where something lives or how two parts connect.	Required
`shape`	Where things belong, and the form they take.	Optional
`principle`	An outcome the project wants, or something it refuses to do. It applies everywhere, so it has no relevance.	None
`wisdom`	A way of thinking about problems.	None

Only concepts with evidence are checked. A subcategory, such as auth in the example, groups concepts into a folder under their category.

How agents see them

Watch this part

A concept reaches an agent at the moment it’s relevant, and each one is shown at most once per session.

Before an edit. When an agent is about to change a file, the Claude Code and Codex plugins show it the concepts whose relevance covers that file.
In search results. explore adds the concepts that bear on the question for the files it returns.
At the start of a session. A concept marked universal is listed in an index, .repoql/concepts/README.md. RepoQL adds the index to your CLAUDE.md and mirrors it as a Cursor rule, and the Codex plugin loads it when a session starts. Keep this for ideas an agent needs before it opens any file.
When it looks. Concepts are addressable at concept:///, so explore and read search them like any other source.

Keeping them true

Code changes, and a concept that was true can stop being true. Every six hours, a running RepoQL host checks again any concept whose last passing check is more than half its ttl ago, and at least three days ago.

A pass updates verified with the date and commit.
A failure records last_failure with the date and the checker’s reason. The failure is shown every time the concept is read, until your agent or a teammate revises or removes the concept.

RepoQL never rewrites the claim itself. Deciding what’s true now is left to your agent or you. While inference is unavailable, rechecks wait.

The checker is a model, and it can be wrong. Specific evidence keeps it honest: a symbol, such as file:///src/auth/SignOut.cs#symbol=SignOut, is better than a folder.

Vocabulary

Watch this part

Vocabulary records your team’s names for things, with the plain words that should find them: Wristband means session. An agent that searches for “end a user’s sessions” can then find Wristband and the code that uses it.

Each entry is a row in .repoql/vocabulary.csv:

Column	Meaning
`term`	Your team’s name, such as `Wristband`.
`meaning`	What it is, in one sentence.
`aliases`	The everyday words that should find it, separated by semicolons.
`scope`	Optional. Globs for where this meaning applies.
`domain`	Optional. Which sense this is, when a term means different things in different places.

Agents add entries with capture_vocabulary. Entries aren’t fact-checked. RepoQL only warns when an alias already appears in your code, because that alias finds nothing new.

Vocabulary reaches agents in two ways. discover_vocabulary turns an agent’s words into yours. And when an agent reads a file, the plugins define the terms of yours that appear in it, once per session.

Across repositories

Watch this part

When you import a repository, its concepts and vocabulary come with it, under concept:///github/owner/repo/ and vocabulary:///github/owner/repo/. Their relevance moves with them, so they apply to the imported files. Searching concept:///** covers every repository at once.

In review

Watch this part

The concepts view of read returns the concepts that apply to a scope, most relevant first, within your token budget. A review agent can check a change against the concepts for the files it touches, then follow the change into imported repositories and check it against theirs.

File format

A concept is YAML frontmatter followed by Markdown. The body has an Invariant and, optionally, a Why, an Example and a Depth list of finer points. The frontmatter fields:

Field	Meaning
`description`	The central claim, repeated in the body as the invariant.
`category`	`rule`, `knowledge`, `shape`, `principle` or `wisdom`.
`subcategory`	Optional. A folder under the category, such as `auth`.
`tags`	Words an agent might search for.
`relevance`	Semicolon-separated globs for where the concept applies.
`verification`	Semicolon-separated addresses or URLs of the evidence.
`ttl`	Days the evidence stays trusted. Required with `verification`.
`universal`	`true` lists the concept in the index agents load at the start of a session.
`verified`	The date and commit of the last passing check.
`last_failure`	The date and reason of a failed recheck, cleared by the next pass.

Further reference

You can add both from a terminal, without an agent: rql concept add and rql vocabulary add. The installed manual covers them at help:///commands/concept.md and help:///commands/vocabulary.md, and the tool at help:///tools/capture-concept.md. The Keep what you learn guide covers choosing a lesson worth saving and writing a useful why.