dont-forget:that — Persist Durable Knowledge

• Treat persistence as a behavior change, not a transcript archive. Save only knowledge that would make a future session act differently; otherwise say "nothing worth persisting" and create nothing.
• Save what is true of this user's world and nowhere else: their projects, their machines, the decisions they made, the way their environment misbehaves. Knowledge that ships with the tool — how a documented flag behaves, what a framework does by default — is already in every model and every manual, and in the vault it is the worst kind of noise: written in common words, it matches many queries and answers none, while the byte budget drops real fragments to make room for it. The exception is the user's own position: a rule, principle, or lesson they state in their own words is theirs even when the world has said something like it before ("progression should grow sideways, not just further"). Record it, and keep their sentence verbatim as a > quote under the title with the date it was said; your rewording, if any, goes below the quote, never in place of it.
• Redact passwords, tokens, keys, and other secrets as <REDACTED> before any content is written or shown in a write payload. The writer scans for them too and returns a warning beside the status — it warns, it does not block, so a warning means the secret is now in the vault: say so and name the credential to rotate.
• Separate two or more independent claims into two or more notes. Never combine unrelated claims. If a claim cannot fit in a one-phrase title, split it further.
• Route an actionable code-bound "never X" or "always Y" rule away from the vault and into .claude/rules/<domain>.md in the relevant project. Give that file frontmatter with paths: globs controlling when it loads and a one-line human description:. Search existing rule files by paths: before choosing a file. Use ~/.claude/rules/ only when the rule genuinely applies across projects; choose the most specific scope. A fact about the code belongs next to the code, where the same pull request that changes the behavior changes the rule; a fact about the world around the code belongs in the vault.

Shape the note around the claim

• The vault's rules live in its own README.md at the vault root, in Russian, and outrank this file wherever they differ: the vault is the data, this plugin is the engine. Read it once per session before the first write.
• Write type: atom for a card. session notes come from the session skill, MOC pages are born from demand rather than written by hand, and where the knowledge came from is the source: field rather than a type. The filename is <Kind> — <complete claim>.md, where Kind is the capitalised kind: of the note — Gotcha, Decision, Principle, Stance, Pain — and Fact for a fact or insight that carries no kind: (renamed from Atom — on 13.09.2026); keep # and / out of its stem. The writer files the note by its project: into that project's folder (gamedev/, gym/, bts/) and into _unsorted/ when there is none: send only the filename, never a path. _inbox/ is different: it is the user's own drop folder, never written by an agent, and sorted only when the user asks. A . is fine — a claim like bash 3.2 or search.py keeps it.
• A claim-title is prose, and prose reaches for punctuation a file name cannot carry. Say the claim without : * ? " < > | — an em dash or a comma carries the same turn, Gotcha — Счётчик завышается Beat-батчем: в тени becomes Gotcha — Счётчик завышается Beat-батчем, в тени. The writer refuses the rest and names the portable form; take that name verbatim, into the title line and into every [[link]] to the note, so the note and its links stay one thing. This is not pedantry about Windows: the user reads the vault in an app on the other side of the machine, and a note it cannot open is a note that was never written.
• Express a decision as: "in context X, facing Y, chose Z and rejected W", followed by Because: and Fails-when:.
• Express a gotcha as GIVEN / WHEN / THEN, followed by Because:, Fails-when: (the provoking input and the wrong outcome, so the note is found by its symptom) and a dated precedent.
• Give a principle, pain, or stance the slots Job, Pain, Done-well, and Anti-goal.
• Give a fact or insight a claim-title, a BLUF, and supporting evidence.
• Add kind: only for decision, gotcha, principle, pain, or stance; facts and insights do not receive it.
• If this card corrects or refutes an existing card — a fix that stopped working, a version that changed the behaviour — the new card links it as supersedes [[Old]], and in the same step the old card gets died: YYYY-MM-DD in its frontmatter, written back with action: "replace" and its expected_sha. Nothing else in the old card changes. Without the mark, search keeps ranking the stale fix first: the link from the new card alone does not reach a reader who only found the old one.
• A claim about something outside the user's control that can go false with nobody around to write a correction — a service's rules, a price, a model's prompting advice, a DNS record — gets a dies-when: frontmatter field naming the event that ends it (dies-when: DNS record for the bridge is repointed). Recall reads it and says "may be dead" when the event has plausibly happened; nothing sweeps these conditions on a schedule. A permanent rule, or a claim a later card would correct, gets no condition — do not invent one to fill the slot.
• A claim about a tool's behaviour names the version it was seen on (codex-cli 0.155), so a reader can tell whether it still applies.
• Every vault note needs YAML frontmatter. Include type: atom, creation date, tags with atom as the first tag, and source identifying where the knowledge came from. Add aliases only when useful and project when the claim is project-bound. A project is any domain the user works in, not only a repository: a game they design, their training, their health, their own habits all count, and each gets a project: of its own (gamedev, gym, self) so recall on "load" or "recovery" does not mix the body with the backend. Nothing about the domain makes a claim ineligible; the only test is whether it changes a future session's behaviour.
• The vault is a git repository. A note about the user's health, mood, money, or other people is still theirs to keep, but say once, before writing it, that it will be committed with the rest, and ask whether it belongs in the vault's untracked folder instead. Do not decide that for them, and do not ask again for the same domain in the same session.

Say where it lands before it lands

• Before any write, search the vault for the claim's key words and its synonyms (python3 "${CLAUDE_PLUGIN_ROOT}/scripts/search.py" "<words>"), read what comes back, and tell the user in one or two lines where the new claim lands — one of four: new (nothing close), continues [[X]] (same cause, another case: a merge candidate), contradicts [[Y]] (date) (say which is newer and that the older may be superseded; never silently drop either), or already there (nothing to write). Only then write. This line is the product, not a courtesy: it is the one moment the user sees the vault working, and a repeated cause found here is a root the pile alone will never show. Skipping it because the claim "looks new" is how the vault grew 570 typed notes and fewer than ten generalisations.
• Count what the search returned. When the claim continues a third card on the same cause and no Godnote — page covers it yet, say so and offer to build one; on the user's word, write it. This is the only trigger the synthesis layer has besides a direct request; there is no scheduler. Measured before it existed: 570 cards, fewer than ten generalisations.
• A contradiction is not resolved by the write. Name it in the new note's ## Links with the date of the older claim, and offer — never do unasked — to add a Disputed-by: line to the older note so a reader of either sees both.

Godnote — a page built from cards

• A godnote is one conclusion drawn from several cards: the root under a pile of symptoms, "what we know about X". Filename Godnote — <conclusion>.md, frontmatter type: godnote, project:, date, tags: [godnote]; the body is a BLUF, then the argument, then ## Cards listing every card it was built from as a [[link]] with one line each. A godnote with no cards behind it is a claim, not a page.
• Cards outrank godnotes. A card was written by the script, at the time, in the user's words; a godnote is a rewrite. When they disagree, the card is right and the godnote is stale: rebuild it wholesale from its cards, do not patch a paragraph.
• legacy: true marks the pages written before this rule, with no cards behind them. They are not evidence. Rebuild one when the work touches it, never in bulk.

Preserve the knowledge graph

• Expect the writer to answer rejected when the note has no [[link]] outside a code block, or a decision or gotcha lacks Because: or Fails-when:. That is the shape the graph and the reader need, and the writer holds it because a checklist line did not: three weeks after it became prose, atoms carrying Fails-when fell from 73% to 41%. Fix the note and repeat the call; there is no flag around it.
• Expect neighbours beside a created status: the nearest notes the vault already holds. Offer them to the user as links with one line each on why they touch this claim — a bare link is noise — and, on their word, add the accepted ones under ## Links with action: "replace" and expected_sha. Never add them unasked.
• Expect the writer to answer similar instead of writing, with the notes it thinks say this already. That check is no longer yours to remember to run — but the decision is yours to put to the user: update one of those notes, or write a new one and repeat the call with duplicates_checked: true. Never pick silently, and never repeat the call with the flag just to get past the answer.
• Merge into an existing note only when the two share a cause, not a symptom. Two deploys that broke because migrations were skipped are one note, gaining a second dated case. A deploy broken by migrations and one broken by an out-of-memory kill are two notes: merged, they become "prod sometimes falls over", which is true and useless at the moment it would have to help. When merging, append the new case with its project and date and leave the existing wording alone — search lives on rare words, and generalising "arrays break in bash 3.2" into "shell arrays behave oddly" costs the note the very query that finds it. Unsure whether the cause is the same: write the separate note. A wrong split shows up in the vault audit and is glued back; a wrong merge quietly loses a fact nobody misses until search fails them.
• End each note with ## Links, or the vault's established equivalent. Link a MOC when a fitting one already exists; when none does, link the notes the claim actually touches and stop there. MOC pages arise from demand — a name linked often enough earns one — so inventing a hub to satisfy this line produces exactly the disconnected page the rule was meant to prevent. When the claim clearly belongs to a broader topic that has no note yet, link that topic by its bare name ([[OAuth]]), never by a hub name ([[MOC — OAuth]]): a bare name linked often enough is the demand signal that earns a MOC, whereas a hand-written MOC — link is the invented hub this rule forbids — and the demand counter, which only sees bare names, never records it, so the hub it was reaching for can never be born. Put links in prose, never inside code blocks.
• Write vault notes only by sending the complete filename and Markdown content JSON to python3 "${CLAUDE_PLUGIN_ROOT}/scripts/vault-write.py". On exists-same, report that the note was already present. On conflict, stop and tell the user; never replace or reconcile the content on your own.