Concepts are knowledge your agent saves as Markdown files in your repository, with evidence to check and a scope that says where they apply.
The agent captures what it learns through capture_concept. RepoQL fact-checks the claim against the evidence the agent provides, then brings the concept into later work in the relevant area. Periodic revalidation checks whether that knowledge still holds as the code changes.
Adapted from a real RepoQL incident. The agent captures the lesson with evidence; a later check revisits that evidence. The lifecycle and passage of time are illustrative.
A concept is a file
A JSON refactor once left RepoQL acknowledging events while their data went unprocessed. The change looked routine: use a generated JSON reader in place of the existing one. It also changed the naming defaults, so the lowercase fields sent by the external service no longer bound correctly.
The concept preserves the lesson that is easy to miss in review. This readable adaptation would live at .repoql/concepts/rule/cloud/TestRealJsonPayloads.md:
Invariant When changing a JSON reader, test the caller’s literal payload. A test that serializes and deserializes the same object can pass while real requests lose fields.
Why The old reader used web defaults. Its generated replacement matched property names case-sensitively unless configured otherwise. The caller sent name; the reader expected Name. The request could be accepted while that property stayed null.
A round-trip test uses the same naming rules to produce and consume its JSON, so both halves agree even when the external caller uses a different spelling.
Example Cloud storage notifications arrived with lowercase fields. The merge endpoint acknowledged messages with an unusable path, leaving their files unprocessed. The fix set explicit naming options and pinned the field names. Regression tests now deserialize literal event payloads and assert that the path is populated.
Depth
Keep camelCase and case-insensitive options explicit on the generated JSON context.
Test the payload received from the external service, including its field names.
For an endpoint that acknowledges invalid messages, verify the resulting work as well as the HTTP status.
The file stores its metadata as YAML frontmatter and its explanation as Markdown. The evidence paths above are real. This adaptation focuses the repository’s SourceGenJsonNeedsNamingOptions concept on the action a future agent should take and scopes it to cloud code.
The agent captures; RepoQL checks
During an investigation, the agent may discover a constraint, explain a mechanism, or learn why a decision was made. It calls capture_concept with that understanding, the supporting source addresses, and the area of relevance. You can also ask it to capture something worth keeping.
RepoQL’s fact-checker reads the supplied evidence and evaluates the claim and its explanation. If the check rejects the capture, RepoQL returns the reason and writes no concept file. The agent can correct the claim or supply better evidence and try again.
The resulting file is ordinary repository content. You can read it, edit it, review its diff, and commit it alongside the code. Capturing a concept writes the local file; committing and sharing it remain separate actions.
Relevance connects knowledge to work
relevance describes where the concept is useful. verification points to the evidence that supports it. Those sets often differ: the JSON configuration, binding tests, and merge endpoint support this lesson, while an agent changing another cloud endpoint may also need it.
In the example, src/cloud/** covers the area where the lesson applies. RepoQL can surface the concept when an agent works there, keeping unrelated guidance out of the response. A universal concept belongs in the general concept index that repository instructions give the agent; use that for guidance needed before it chooses any files.
Revalidation catches context rot
A fact can be correct when captured and become wrong after a refactor. Each verifiable concept has a ttl, in days. While the host is running, RepoQL periodically finds concepts due for revalidation and reads their current evidence again.
A passing recheck refreshes the verification date and repository commit. A failing recheck records a dated failure on the concept and exposes that warning when the concept is read. It preserves the last successful check rather than making stale knowledge look fresh. An agent or maintainer can then revise the claim or remove it.
In the illustration, the code has changed since capture. RepoQL reads the evidence again before refreshing the check. If a later change makes the explanation obsolete, a failed recheck identifies the concept for review; it does not silently rewrite it.
Format and checking details
Field
Meaning
description
The short central claim, repeated as the body’s invariant.
category
knowledge requires evidence. rule can carry evidence. wisdom is not fact-checked.
relevance
A semicolon-separated string of file patterns where the concept applies.
verification
A semicolon-separated string of source addresses or URLs for checking the claim.
ttl
Evidence shelf life in days. Required when verification evidence is supplied.
universal: false
Keeps this scoped concept out of the general index. Omitting the field defaults to universal.
verified
RepoQL’s date and commit metadata, added during capture and refreshed on a passing recheck. Not shown in the illustrative document above.
last_failure
A failed recheck’s date and summary. Cleared after a subsequent passing recheck.
The host looks for due concepts every six hours. A concept becomes due halfway through its TTL, with a minimum age of three days. For ttl: 90, that means rechecking from day 45, rather than waiting until day 90. This is background work in a running host.
Fact-checking uses inference. When inference or authentication is unavailable, capture can save the file with checking reported as skipped; background revalidation waits until checking is available. Inspect the returned result, since a saved file alone does not prove a successful check. Failed or inconclusive background checks do not refresh the verification date. The checker can also be wrong, so keep the evidence specific and review it when a decision depends on the claim.
Read concepts through concept:///, or use the concepts read view to retrieve guidance relevant to a source scope. The Keep what you learn guide covers writing a useful explanation.
Further reference
In the installed manual: help:///tools/capture-concept.md, help:///commands/concept.md.