Capture

Capture

Decide whether this session produced something worth keeping, and route it. This skill is the only path to a memory store — never write into one directly, or the reach narrowing, the content gate and the collision handling are all skipped.

Routing to "nothing" is a successful outcome, not a failure. Most sessions produce no durable memory, and a store full of near-misses is worse than a small one.

What qualifies

A memory must clear all three to be worth keeping.

• It transfers. It would still be true, and still useful, to someone working in a different repository. A lesson that is only true of one file on one branch is a code comment. Test: "name the project or platform this applies to, and why." If the answer is "any project, it's just how the tool works", it belongs in that tool's documentation, not here.
• It is a conclusion, not a log. What is true and what to do about it — never a narration of the session that produced it. "Fixed the checkout bug, rebased, updated the changelog" is a commit message.
• It is about the work, not a person. No names, handles or emails anywhere, and no "who did what". Describe the artifact — the bug, the pattern, the decision. Identifiers age badly and carry no signal even in a store of one.

A learning — something discovered that was not obvious

• the investigation was real, not a documentation lookup
• the error message was misleading and the root cause was not where it pointed
• a workaround for a genuine tool or framework limitation
• a workflow or performance property found by experiment

A decision — a deliberate choice about how something should work

• an architectural choice, with the alternatives it beat
• a convention established and backed by something: lint config, a written doc, team agreement, or consistent existing usage
• a trade-off resolved between competing concerns

A personal preference is not a decision. "I prefer", "I like", "my style" — those do not qualify. Consistent use in the codebase is the strongest evidence a convention is real.

What does not

• Public documentation. Anything a reader could look up in a language reference, a framework README, or public API docs. Test: "is this true of the tool everywhere, for everyone?" If yes, it belongs in that tool's docs, not here.
• A log of what happened. "Fixed the checkout bug, rebased, updated the changelog" is a commit message. A memory is a conclusion, not a diary.
• Machine-local configuration. A path on this machine, a personal shell alias, an environment quirk of one laptop. Suggest a note in the project's own local config file instead — that suggestion is a successful outcome.
• Anything that names a person. No names, handles or emails, anywhere. Describe the artifact — the bug, the pattern, the decision — not who touched it. Identifiers age badly and carry no signal.

How to write it

The title is the claim, not the topic. Retries need an idempotency key — not Notes on retries. A future session reads titles before it reads bodies.

The body is for a reader with none of your context: what is true, why, and what it means for what they are about to do. Include the evidence that convinced you. If you are stating a figure that rots — a version, a count, a benchmark — date it.

Set confidence honestly. verified means you checked it against code, a doc, or a run, and it requires saying how in verification. If you are reasoning from one observation, it is inferred.

Choosing reach — the decision that matters most

Reach is the field that determines who ever sees this. Getting it wrong in the wide direction pollutes every project; getting it wrong in the narrow direction hides the lesson from the repo that needed it.

Prefer platform over general. A hard-won dependency lesson feels universal and almost never is. general requires a generality explaining why it reaches everywhere; if you cannot write that sentence, it is not general.

Name every project the lesson applies to in projects — the field is a list precisely so a lesson spanning two repositories reaches both without either knowing about the other.

Steps

Do these in order. Step 1 is the one that gets skipped, which is why step 5 exists.

1. Search first. Call search or recall for what you are about to write.

2. Take the branch the result dictates, and there are only four:

   • Already captured, nothing to add — stop. This is a success, not a failure.
   • Extends an existing memory — write the better version with supersedes: [<the old one>]. The old memory is marked and kept, never deleted: what was believed at the time is evidence that it changed.
   • Related but distinct — write it with related: [<the sibling>]. The link is written on both files.
   • Genuinely new — write it.

3. Judge it against the sections above. Most sessions stop here, and that is correct.

4. Write it with remember, choosing reach deliberately and setting kind to learning or decision.

5. Print the receipt, in one line, before you stop:

   KB search: "<query>" -> <n> hits, <what they covered> -> <branch taken>
   

   This is not ceremony. Step 1 is invisible when it is skipped — a session that never searched and a session that searched and found nothing produce identical output, and the store fills with near-twins either way. The receipt makes the branch visible, which is the only thing that makes skipping it noticeable.

6. Read what came back. The tool reports what it changed: a narrowed scope, a capped confidence, a quarantined file, and which memories it superseded or linked. Those are not noise — a narrowed scope means your reach claim was wider than your own projects list, and a quarantine means the memory carried something that must not leave this machine.