Guide

Keeping what you learn

The costly part of working in a large codebase is rarely writing the code. It is the hours spent discovering why something is the way it is. That discovery evaporates when the session ends, and capture_concept is where it goes instead.

If you already keep a handoff file (the note an agent writes before /clear so the next session does not start cold), this is that practice with the two things a loose file cannot give it: an address, and a trigger. A concept is not re-read when someone remembers to. It surfaces on its own, to whoever touches the files it is about.

1 · Notice the moment

The signal is a specific feeling: I wish I had known that three hours ago. A platform behaving unlike its documentation, a constraint with no visible cause, a fix that looks arbitrary until you know what it prevents. Capture it before moving on. You will not come back.

2 · Reduce it to one sentence

The invariant is the whole thing. If it needs “and” to be stated, it is two concepts and should be captured as two. Everything else goes in the fields underneath, where it does not dilute the claim: the mechanism, the stakes, the case that makes it click.

3 · Say where it applies

Relevance is a set of URI globs, and it is what makes a concept useful rather than merely stored: anyone who opens a matching file is handed it, without having to know it exists or go looking.

capture_concept( name="CloudRunCpuIsPerRequest", category="rule", invariant="Background work after the response crawls on Cloud Run.", why="CPU is allocated per request, so a task started after the" "response returns runs at a fraction of a core.", relevance="file:///src/cloud/**", isUniversal=false)

4 · Give it evidence, if it can have any

A claim about code should point at the code that proves it. Anchor the verification at the symbol rather than the line, because #symbol=Name keeps resolving as the file moves under it. Set a ttlDays for how long that evidence stays trusted before it is checked again.

5 · Read what is already there

Before solving something that feels hard, ask whether it has been solved. Concepts answer to the same addresses as everything else.

read("file:///src/cloud/** => concepts") read("concept:///rule/cloud/** => structure")

The store is nothing exotic: plain markdown under .repoql/concepts/ in the repository itself. It is committed, diffed, and reviewed like any other file, it reads fine without RepoQL, and it never leaves the machine. Written this way, the lesson stops being something a person remembers and starts being something the repository knows.

This page names what exists. The depth behind every name ships inside the binary at help:///: the bounds, the failure modes, how they compose. It answers to explore and read exactly like your code does. Install it, and your agent has the manual.