/log: session memory checkpoint

What this is

A deliberate, end-of-session pass over the project's existing auto-memory system. It does not introduce a new store, a changelog file, or a parallel notes system. It writes to the same memory/ directory and MEMORY.md index the system prompt already describes.

Why it exists as an explicit command: memory writes made during a session are reactive and partial. You save something the moment it seems notable, which means you save it before you know how the story ends. A theory that looked right in turn 20 gets disproven in turn 60, but the memory written in turn 25 is still sitting there asserting the wrong thing. At the end of the session you finally know which parts mattered, which were wrong, and what the actual conclusion was. This command is the moment to reconcile all of that.

Treat it as curation, not transcription. The goal is that a future session starts with what took this one hours to learn, and is not misled by claims that have since become false.

Step 1: locate the memory system

Read the current project's memory directory and index fresh. Never assume a layout from another project or from earlier in this session; the path is given in the system prompt and differs per project. Read MEMORY.md and skim the titles and descriptions of existing memory files so you know what is already recorded before deciding what is new.

If the project has a CLAUDE.md, skim it too. Anything already documented there does not belong in memory.

Step 2: reconstruct what actually happened

Go back over the session and pull out the things a future session would need and could not cheaply rederive:

• Root causes, and the wrong turns on the way there. If a problem was first misdiagnosed, record the misdiagnosis explicitly alongside the real cause. A plausible but wrong theory is a trap that will cost the next session the same hours it cost this one. "It looked like X, it was actually Y, here is how to tell them apart" is often the most valuable line you write.
• Decisions and the why behind them. The choice is visible in the code; the constraint or trade-off that forced it usually is not.
• User corrections and confirmations → feedback type. Both directions matter. "Don't do X" is easy to notice; "yes, that was the right call" is quieter and just as worth keeping, or you drift away from approaches the user already validated.
• New project facts → project type: who is doing what, deadlines, motivations, constraints, incidents. Convert relative dates to absolute ones.
• Things about the user → user type: their role, expertise, how they want to work.
• Pointers to external systems → reference type.
• Anything the user explicitly asked you to remember, in any phrasing.

Also note operator actions that were required and may not have happened: migrations to run, keys to set, dashboards to check. A pending action that silently never got done is a classic source of later mystery breakage.

Step 3: reconcile against existing memory (do not skip this)

This is the step that distinguishes a real checkpoint from a dump, and it is the one most easily skipped, because writing something new feels like progress while auditing something old feels like overhead.

For each existing memory file that touches a topic this session went near:

• Does anything you learned contradict it? If a memory says a bug is fixed, a guarantee holds, or a system behaves a certain way, and this session showed otherwise, correct that file. Do not leave a false claim standing next to a new true one; a future session may read either, and the confident-sounding stale one often wins.
• Do its concrete claims still hold? Memories that name a file, function, flag, or line number assert something that was true when written. Before repeating or relying on such a claim, verify it against the current code: grep for the symbol, open the file. If it no longer matches, say so in the file rather than silently deleting it: note what it claimed, what is actually there now, and that it needs re-checking. An honest "this entry says X but the code says Y; don't trust it without re-reading" is far more useful than a quiet edit that hides the drift.
• Is a correction better than a new file? Usually yes. Prefer amending the existing memory on that topic over creating a second one that competes with it. When you amend a claim that was previously stated confidently, mark the correction and date it so the change is legible.

Step 4: filter hard before writing

Do not save:

• Anything derivable from reading the current code, or from git log / git blame, including architecture, file paths, conventions, and who changed what.
• A blow-by-blow of the diffs. The commit carries that.
• Fix recipes whose result is already in the code.
• Ephemeral state: in-progress work, scratch context, what you were about to do. (That belongs in a handoff note; see step 6b.)
• Anything already in CLAUDE.md.

These exclusions hold even if the user asks for a broad "save everything". If they ask you to record something in this category, the useful move is to ask what was surprising about it and keep that instead.

The test: would a competent person with the repo in front of them already know this? If yes, it is not memory. If it took this session real work to discover, it is.

Step 5: write

Use the existing format exactly: one file per memory, in the project's memory directory.

---
name: {{short-kebab-case-slug}}
description: {{one-line summary, specific enough to judge relevance later}}
metadata:
  type: {{user | feedback | project | reference}}
---

{{Body. For feedback and project types, lead with the rule or fact, then a
**Why:** line and a **How to apply:** line. Link related memories with
[[their-slug]].}}

Link liberally with [[slug]]. A link to a memory that does not exist yet is fine; it marks something worth writing later.

Step 6: update the index

Bring MEMORY.md in line with what you just did. It is an index, never a store: one line per memory, roughly under 150 characters, - [Title](file.md): one-line hook.

Pay particular attention to index lines for files you corrected. An index line still summarizing the pre-correction claim will keep propagating the false version, since the index is what gets read first and most often.

Step 6b: update the spine (if the memory has one)

Some setups add two files that make a session survivable across restarts: log.md (what happened, append only) and handoff.md (what is in flight now). If the memory directory contains them, the index is not the whole job.

Append to log.md, one entry, never editing a past one:

## YYYY-MM-DD HH:MM | project | operation | one-line result

with operation one of work · decision · failure · handoff · ingest · lint, then two or three lines of detail. A session that produced nothing durable still gets an entry saying so.

Rewrite handoff.md from scratch. It is state, not history: what is in flight right now, ordered by priority, each item naming the project, the exact next action, and what is blocking it. Include anything left unresolved: open questions, decisions awaiting the user, work paused midway. If nothing is in flight, say that explicitly rather than leaving yesterday's items to be read as current.

The hard rule this exists for: never tell the user you will remember something across a restart, a /clear, or a compaction. Only files survive. If you ask the user to restart the app, write handoff.md in that same message, before they restart, not after.

Step 7: report back

Keep it short and make it auditable:

• Written: new memories, one line each, and why each earns its place.
• Corrected: existing memories you amended, and what specifically was wrong. Call these out clearly; they are the highest-value part of the pass and the user may want to sanity-check your reasoning.
• Deliberately left out: the notable things you considered and dropped, with the reason (derivable from code, ephemeral, already in CLAUDE.md). This is the user's chance to catch a bad judgment call and say "no, actually keep that."

Do not paste the memory file contents back into the conversation. Point to the files.

Judgment

A session with a genuine hard-won finding might justify one or two new memories plus a correction. A routine session may justify nothing at all, and saying "nothing here is worth persisting, here's why" is a perfectly good outcome. It is better than padding memory with restatements of the codebase, which dilute the signal in every future session that loads the index.

Err toward fewer, denser, more honest memories. Run memory-lint from time to time to catch what slipped through.