remember: write to memory correctly

Governing doc: MEMORY-ARCHITECTURE.md in the memory dir. Read it if a rule is unclear. This skill is the WRITE path. Maintenance is memory-gc.

Step 0: should this be a memory at all

Save it only if BOTH are true:

• a future session needs it to act correctly, and
• it is not derivable from the code, git history, or an existing CLAUDE.md.

If it only matters to this conversation, do not save it. If the repo already records it, do not save it. If asked to "remember" something the code already says, ask what was non-obvious about it and save that instead.

Step 1: pick the type and the slug

• user who the user is, role, preferences, how they like to work.
• feedback a correction or a confirmed approach. MUST include the why.
• project ongoing work, goals, constraints not in the code/git.
• reference a pointer to an external resource.

Slug: undated for a standing rule (prefer_pytest), dated YYYY_MM_DD for an event (auth_refactor_shipped_2026_01_15). Filename matches the slug.

Step 2: check for an existing file first

Grep the memory dir for the topic. If a file already covers it, UPDATE that file. A new dated sibling is only for a genuinely new event, not new detail about an old one. This is where duplicates come from, so check before creating.

Step 3: write the file

---
name: <slug>
description: <one line, a decision hook: when would a future session need this>
metadata:
  type: user | feedback | project | reference
---

<the fact, stated plainly.>
**Why:** <for feedback/project. the reason, so it is not re-litigated later.>
**How to apply:** <the concrete action a future session should take.>

Related: [[other_slug]]

The description is a hook, not a summary. "when touching auth, read this", not "about auth". Link related memories with [[slug]].

Step 4: index it in the SAME edit (non-negotiable)

An unindexed file is an orphan: it silently stops existing for future sessions. In the same change:

• open thread that is active right now -> add a one-line entry to MEMORY.md ACTIVE NOW.
• a standing rule -> the rules section of MEMORY.md.
• everything else -> the right category in MEMORY-INDEX.md.

Keep the MEMORY.md line to ONE line. Detail stays in the topic file.

Step 5: keep the hot index honest

If MEMORY.md now has more than ~8 ACTIVE NOW entries or is over ~10KB, demote the stalest finished thread to MEMORY-INDEX.md (fold any hot-only detail into its topic file first). If unsure what to demote, run memory-gc.

Hard rules

• One fact per file.
• Never delete a memory. Superseded ones move to _archive/ (that is memory-gc's job).
• Index line and file in the same edit, always.
• The hot index is a table of contents, never a content store.