claude: add the Persistent memory section — point at the /snapshot canon, don't restate it

Adds "## Persistent memory (`persistent-memory.md`)" to the global CLAUDE.md, placed directly
after the cognitive-load-reduction section because persistent memory is that mission's instrument:
it is what lets the operator re-enter a project without reloading its context.

Deliberately a POINTER, not a copy. The canon is the /snapshot skill
(~/.claude/skills/snapshot -> ~/development/galdrabok/skills/snapshot, version-controlled there);
the section says so explicitly and forbids restating it here or in a project CLAUDE.md, because a
second copy is a sync surface that drifts silently.

What it does carry is the four things a session needs BEFORE it loads the skill: read
persistent-memory.md at session start; check /tmp/<althing-handle>-handoff.md and its 1h staleness
rule; never bulk-read persistent-memory.d/; commit memory alongside the work. Plus the three-way
split (project CLAUDE.md / auto-memory / persistent-memory) with the redundancy test, because that
boundary is the one sessions actually get wrong.

Fleet state at time of writing: 48 repos carry persistent-memory.md, 18 carry persistent-memory.d/.
Stamped with the date so it reads as a snapshot rather than a standing fact.
This commit is contained in:
Your Name
2026-08-06 18:17:37 -07:00
parent 1a243a142c
commit c7a3ecea33
+95 -8
View File
@@ -117,6 +117,59 @@ decisions, and sharpens it with the decision-tree-for-pending-calls
requirement. `/elitk` is the grade and the tool; its King framing — requirement. `/elitk` is the grade and the tool; its King framing —
smart reader, zero jargon — is exactly the operator mid-context-shift. smart reader, zero jargon — is exactly the operator mid-context-shift.
## Persistent memory (`persistent-memory.md`)
Most Corviduo repos carry a `persistent-memory.md` at their root — the
durable record of **intent and supporting evidence** (goals, dated
decisions, foot-gun warnings, in-flight state) that survives a context
reset. As of 2026-08-07, 48 repos have one and 18 have the companion
`persistent-memory.d/`. It is the direct instrument of the
cognitive-load-reduction mission above: it is what lets the operator
re-enter a project without reloading its context from scratch.
**The canon lives in the `/snapshot` skill**
(`~/.claude/skills/snapshot/SKILL.md`, contract alongside it) — file
schema, section taxonomy, the two-tier index/detail split, the soft
cap and its archival guards, the handoff file. **Do not restate that
canon here or in a project `CLAUDE.md`.** A second copy is a sync
surface that drifts silently; point at the skill instead. Read it when
writing memory, not from recall.
What every session needs before it loads the skill:
1. **Read `persistent-memory.md` at session start**, alongside the
project `CLAUDE.md` and auto-memory. It is one input among three,
not the single source of truth.
2. **Check the handoff.** `persistent-memory.md` opens with a
handoff-check header naming `/tmp/<althing-handle>-handoff.md`. If
that file exists and its `Written:` stamp is under an hour old, read
it, then delete it. Older: stale — delete unread. This is the
post-`/clear` resume vector; no pasted prompt required.
3. **Never bulk-read `persistent-memory.d/`.** The dated log sections
are two-tier: a one-line index entry lives in `persistent-memory.md`,
the full body in `persistent-memory.d/<slug>.md`. Pull a detail file
only when its index line is relevant. Bulk-reading defeats the entire
point of the split.
4. **Commit memory alongside the work.** Any pending
`persistent-memory.md`, `persistent-memory.d/` or
`archival-memory.md` changes ship in the same commit as whatever
prompted them. Durable memory that lags the code defeats its own
purpose. (Memory-snapshot-only commits still skip the version bump —
see the SemVer SKIP list.)
**The three-way split, restated because sessions get it wrong:**
project `CLAUDE.md` owns mechanical conventions (how code is written —
stable per repo); `~/.claude/projects/<sanitized-cwd>/memory/` owns
user/feedback/project/reference traits (durable across sessions);
`persistent-memory.md` owns temporal state and dated decisions (what
`CLAUDE.md` by design cannot carry). Before adding a row to
persistent-memory, ask: *could a session that read only `CLAUDE.md`
figure this out?* If yes, it belongs in `CLAUDE.md`.
**`/snapshot` is operator-invoked, never automatic.** Reset hygiene is
his call. `/handoff` is the sibling for transferring active work to an
agent of another family — different artifact, different purpose.
## Conversational register / personality ## Conversational register / personality
In conversation, be a bit less dry — you have a personality, use it. In conversation, be a bit less dry — you have a personality, use it.
@@ -311,8 +364,9 @@ For work implemented directly in-session. This is the **House Code
Discipline** — the canonical full pipeline, end to end: Discipline** — the canonical full pipeline, end to end:
> **concept** (heid refinement optional) → **contract** → **contract > **concept** (heid refinement optional) → **contract** → **contract
> review** → **TDD slices** (all of them) → **heid code-review** → > review** → **seam review** → **TDD slices** (all of them) → **heid
> **fixup** → **heid bug-hunt** → **fixup** → **merge/commit** > code-review** → **fixup** → **heid bug-hunt** → **fixup** →
> **merge/commit**
As numbered stages: As numbered stages:
@@ -323,20 +377,53 @@ As numbered stages:
first per the rule above). first per the rule above).
3. **Contract review.** `/heid-contract-review`, then **fixup** the 3. **Contract review.** `/heid-contract-review`, then **fixup** the
contract per triaged findings. contract per triaged findings.
4. **TDD slices.** `/tdd` — red-green-refactor against the contract, 4. **Seam review — the sibling-aware second gate.**
`/heid-contract-review` is **artifact-only by design**: the arms read
one `.contract.md` and are forbidden the `depends_on` siblings, the
config, and the design docs. That firewall is exactly what buys the
fresh-eyes property — and it means the cold pass **structurally
cannot check a single cross-module seam.**
So after the cold pass and its fixup, run a pass that *does* see the
siblings: for every symbol, type, field, and comparand the contract
borrows from a `depends_on` module, check it against **the real
module surface** — the actual `.py`, not the sibling contract's
prose. Caller-side, in-session, no dispatch. It is a reading, not a
consult; do it directly rather than delegating, because the value is
in holding both surfaces at once.
**What it catches that neither neighbour can.** The cold panel cannot
see the sibling. A same-model self-review shares the author's priming
and converges with it. Type and comparand drift across a module
boundary is invisible to both. Expected symptom: a contract naming a
field, parameter, or return shape the sibling module does not
actually have.
**Provenance.** All four arms of the 2026-08-01 Edict U7 panel
proposed this independently in their meta-notes — 4-of-4, unprompted,
in no flag list, and the only thing they agreed on without being
asked. Converges with the pass that had already caught three real
mismatches before U5's first line of code, and that found
`core.config.load_catalog` never validated its slot keys, days before
U7's contract would have depended on it.
5. **TDD slices.** `/tdd` — red-green-refactor against the contract,
through *all* the slices, not just a single tracer bullet. through *all* the slices, not just a single tracer bullet.
5. **Heid code-review.** `/heid-code-review` (code-vs-contract drift), 6. **Heid code-review.** `/heid-code-review` (code-vs-contract drift),
then **fixup** the code per triaged findings. then **fixup** the code per triaged findings.
6. **Heid bug-hunt.** `/heid-bug-hunt` (diff-scoped robustness hunt — 7. **Heid bug-hunt.** `/heid-bug-hunt` (diff-scoped robustness hunt —
crashes, leaks, removed guards, caller breaks, false rejects), then crashes, leaks, removed guards, caller breaks, false rejects), then
**fixup** per triaged findings. **fixup** per triaged findings.
7. **Merge/commit** when clean. 8. **Merge/commit** when clean.
**Partial discipline for surgical fixes.** Surgical / localized work — **Partial discipline for surgical fixes.** Surgical / localized work —
one-liners, small bug fixes, surgical test updates — does not need the one-liners, small bug fixes, surgical test updates — does not need the
full front matter: **TDD + bug-hunt is the acceptable reduced full front matter: **TDD + bug-hunt is the acceptable reduced
discipline** (drop the concept → contract → contract-review ceremony, discipline** (drop the concept → contract → contract-review → seam-review
keep the two implementation-quality gates). Composes with the front matter, keep the two implementation-quality gates). One exception
worth naming: if a surgical fix *changes a signature or a shared value
shape*, keep the seam review — that is precisely the change whose blast
radius lands in another module, and it is cheap when the diff is small.
Composes with the
Contract-skip privilege above: skip *authoring* a contract, but update Contract-skip privilege above: skip *authoring* a contract, but update
any live contract governing the touched behavior in the same commit so any live contract governing the touched behavior in the same commit so
it stays canonical. When in doubt about whether a fix is "surgical it stays canonical. When in doubt about whether a fix is "surgical