Session 2.5: Make Claude remember (across sessions and across breakages)

How to run this session

This guide is built to be handed to an AI assistant, which then walks you through it one step at a time. Claude Code in a terminal, Claude Desktop, and Codex all work. Save this page to your machine, open a fresh assistant session, give it this file, and paste this:

Walk me through Session 2.5 one step at a time.
Give me only the current step. Stop after each step and wait for me to say it's done.
Before each step, check whether it's already done on this machine, and skip it if it is.
Tell me what each command does before I run it.
Start at the beginning.

Then work through it together. Tell the assistant when a step is finished, or paste the error when one isn’t.

Assistant: the rules below govern this whole session. They override any default habit of reading a document and summarizing it.

  1. One step per message. Give the learner the current step and nothing else. Do not list the steps that follow, do not preview what is coming, and do not merge two steps because they look short. An outline of the session counts as revealing the steps, so do not produce one. If the learner asks how long this will take, give a count and a time estimate rather than a list.
  2. Stop and wait. End each step by asking the learner to do it and report back. Do not continue until they answer.
  3. Check before you instruct. Most steps name a way to tell whether the work is already done on this machine. Ask for that check first. When it passes, say the step is already satisfied and move on.
  4. Explain before you instruct. For every command, say in one or two sentences what it actually does and why this step exists, before the learner runs it.
  5. Debug in place. When something fails, fix it with the learner here. Do not send them to a documentation page, and do not skip ahead.
  6. Resume cleanly. If the learner comes back later and says where they stopped, confirm that position and give the next step only. Do not recap what they already did.
  7. Posture. Every example uses public sources, invented scenarios, or the learner’s own personal material. Never ask for anything belonging to their employer or a client. If they offer some, redirect to a public equivalent.
  8. Audience. A capable professional on macOS who has not lived in a terminal day to day. Write peer to peer. Do not explain the learner’s own field back to them.
  9. The Reference Sections below are addressed to you, not to the learner. They are stage directions. Turn them into steps and deliver them one at a time. Never paste them at the learner.
  10. Which tool the learner uses. This curriculum works with Claude Code or Codex. The learner’s CLAUDE.md or AGENTS.md records which one; if it does not, ask once and do not ask again. Where a step below has a ### Claude Code version and a ### Codex version, deliver only theirs and do not mention the other exists. Everywhere else the work is identical, so say “your assistant” rather than assuming Claude. This is about the tool the learner installs and works in, not about which assistant is reading this guide.

About 60 minutes. Run this from ~/ai-training, the working directory you made in Session 2.1.

Posture: public, synthetic, or personal data only. Memory infrastructure today is about the structure of the working directory itself — what gets remembered, where, and how. Nothing internal lands in CLAUDE.md or MEMORY.md.

Why memory is the most-undervalued technique

The single biggest difference between someone who’s used Claude Code for a week and someone who’s used it for a year is: the year-old user’s working directories remember things. Their CLAUDE.md says “I prefer Times New Roman 12pt black labels in figures, 4:3 default, here are my palette hex codes” and Claude reads that on every session and produces the right figure on the first try.

Without memory infrastructure, every session starts from zero. You re-explain who you are, what your style is, what tools are installed, what conventions matter. That re-explanation is a 5-minute tax per session — multiplied by every session you’ll run for years.

The memory layer has three distinct files because they answer three distinct questions:

Plus two recovery files:

Practice task

By the end of this session you will have, in ~/ai-training/:

  1. An expanded CLAUDE.md — durable rules and context that survive every session.
  2. A real MEMORY.md file — curated facts that update over time, with a clear structure.
  3. A session-log.md — chronological audit trail, one entry per substantive session.
  4. A decisions/ folder with one real decision record from today.
  5. A known-issues.md listing one real recurring failure mode and its workaround.
  6. A /refresh slash command that loads your MEMORY.md file and session-log.md on demand.
  7. A successful self-recovery: you’ll deliberately break something, diagnose it, fix it, and write the fix down — all in this session.

Seven artifacts. Six of them are the memory system; the seventh is proof the system works under stress.

A production version of this is what every project looks like: CLAUDE.md (permanent rules), MEMORY.md file (curated state, updated by a /memory skill), session-log.md (chronological, written by /mexit on exit). Plus the cross-machine variant — memory-macbook.md and memory-mini.md per project, MEMORY.md is a symlink to the current machine’s file, CLAUDE.md tells Claude to also read the other machine’s file. Each machine writes its own; both machines read both. No Dropbox sync conflicts.

The self-tech-support half is what keeps that system alive when something breaks. Three real episodes from the tech-support archive: a Notion MCP that started returning 401 (expired key, debated re-keying vs. routing through a different connector, chose the second; decision record so the rationale survives); all user-scope MCP servers vanishing after a config rebuild (root cause: edited .mcp.json instead of .claude.json; decision record so the mistake doesn’t recur); both Google MCP servers needing simultaneous re-auth (fixed via direct curl to the OAuth endpoint, no Claude session required). The pattern across all three: when something breaks, write down what you did to fix it before the memory of the fix evaporates.

Reference Sections

Claude: walk the user through the memory system build, then the deliberate-breakage exercise. Peer-tone. Two rules:

  1. Don’t write the memory files in the abstract. Every entry has to come from something the user has actually said or done in the previous four sessions. If you find yourself inventing preferences, stop and ask.
  2. The deliberate-breakage exercise is real. Pick something the user can actually break and recover. Don’t simulate. The point is the recovery.

Design: this session is the spine of the rest of the curriculum. 2.6’s corpus pipeline depends on a solid memory layer. 2.7’s voice profile lives in the MEMORY.md file. 2.8’s brief reads MEMORY.md to know which sources to scan. The structure has to be right today.

Confirm the setup

Before any memory work:

  1. ~/ai-training/CLAUDE.md exists from Session 2.1. Open it; the user should still recognize what’s in there.
  2. The user has been through Sessions 2.2, 2.3, 2.4, so there’s real material to write into MEMORY.md (Gmail MCP installed, memo-template.docx exists, figure preferences picked). The session is about capturing* what’s already been decided, not inventing new preferences.*

Step A — Expand CLAUDE.md (10 minutes)

Already done? Open ~/ai-training/CLAUDE.md. If Background, Goals, Tools, and Working style are already filled in rather than the Session 2.1 skeleton, skip to Step B.

The CLAUDE.md from Session 2.1 was a skeleton. Today it gets real. Keep the existing structure; add what’s missing.

Open ~/ai-training/CLAUDE.md. The full version should include, at minimum:

# Claude Code Working Directory

## Posture
- Personal laptop. Public, synthetic, or personal data ONLY.
- Never paste internal work-product, real client/colleague names, or
  confidential material into this directory.
- See POLICY-personal-laptop.md.

## Background
- Role: [the user's actual role]
- Comfortable with: [what the user knows]
- New to: [what's still novel — terminal patterns, MCP servers, etc.]

## Goals for this curriculum
- [the user's stated goals from Session 2.1's conversation]

## Tools available on this machine
- Claude Code built-ins: WebSearch, WebFetch, file/shell access
- pandoc, markitdown, marker-pdf, python-docx (Session 2.3)
- pandas, matplotlib (Session 2.4)
- MCP servers connected: [list, e.g. Gmail via Composio]

## File conventions in this directory
- memos/<slug>/ — memo projects (Session 2.3 pattern)
- exhibits/<slug>/ — figures and supporting data (Session 2.4 pattern)
- prompts/ — saved prompts I rerun
- decisions/ — point-in-time decision records
- known-issues.md — recurring failures and workarounds
- session-log.md — chronological audit trail (append-only)

## Working style
- Peer-level technical explanation. No over-scaffolding.
- Surface the why, not just the how.
- When I propose something internal-sounding, redirect to a public/synthetic analogue.
- At session start, type /refresh to load your MEMORY.md file and recent session-log on demand.

Important: Do not add a line like Read MEMORY.md or See MEMORY.md inside CLAUDE.md itself. CLAUDE.md auto-loads on every session start — if it told Claude to read the MEMORY.md file, that file would get pulled into context automatically every time, defeating the point of keeping it as a separate, on-demand store. CLAUDE.md holds permanent rules; /refresh loads your MEMORY.md file when you actually need it.

Claude: walk the user through each section. Read out loud what’s already there from 2.1. Ask “is this still true?” for each. Update where the answer is no.

The CLAUDE.md is permanent rules. It changes infrequently. When it changes, the change is deliberate — not “I added a tool” but “I want Claude to behave differently.”

Step B — Write a real MEMORY.md file (15 minutes)

Already done? Open ~/ai-training/MEMORY.md. If it already has sections for Memo conventions, Inbox triage, and Connected MCP servers beyond the Session 2.4 figure preferences, skip to Step C.

~/ai-training/MEMORY.md already has the figure preferences section from 2.4. Now expand it.

The right structure for your MEMORY.md file:

# Memory — ai-training

## Index
- Figure preferences (added 2026-04-22)
- Memo conventions (added 2026-04-29)
- Inbox triage prompt (added 2026-04-29)
- Connected MCP servers (updated 2026-05-06)

## Figure preferences
[from Session 2.4 — already exists]

## Memo conventions
- Pattern: memos/<slug>/{source.md, memo-spec.md, drafts/, memo.docx}
- Drafts named v1-outline, v2-outline, v1-full, v2-full, v3-final.
- Voice-critique pass is a discrete step after structural revisions.
- Final-step pandoc conversion only; iterate in markdown.
- Reference template: ~/ai-training/templates/memo-template.docx

## Inbox triage
- Saved prompt at prompts/inbox-triage.md
- Drafts-only default — never wire send into a scheduled job.
- Multi-account: one MCP call per account, merge in single pass.

## Connected MCP servers
- Gmail (Composio / Rube) — connected 2026-04-29, user scope.
  Test query: search for "verification" in Updates category.

## Goals in flight
- [the user's running domain example — from 2.1's conversation]
- Custom briefing tool by Session 2.8 on [topic].

Claude: this is the most important file in the directory. Walk through each section with the user. Every entry should be something the user has actually decided or done. If a section is “what would be useful later,” that goes in CLAUDE.md goals, not the MEMORY.md file.

The Index at the top is the read-first map. When your MEMORY.md file grows, the index keeps it scannable.

Step C — Start session-log.md (5 minutes)

Already done? Run ls ~/ai-training. If session-log.md is already there with entries through Session 2.4, skip to Step D.

session-log.md is chronological. One entry per substantive session, written at the end. Each entry is short — 5–10 lines. Always include the Claude Code session ID so you can re-enter the exact conversation later if you left something mid-task.

The session ID appears in the banner at the start of every Claude Code session. To resume a specific session: claude --resume <id>.

Create ~/ai-training/session-log.md:

# Session log — ai-training

## 2026-04-22 — Session 2.1: Setup and live-web demo
Installed Claude Code, Wispr Flow, iTerm2. Created ~/ai-training/.
Ran first WebFetch + WebSearch. Two output files (wikipedia-summary.md,
recent-event.md). Picked [topic] as running example.
Session: abc123def456 (resume: claude --resume abc123def456)

## 2026-04-29 — Session 2.2: Inbox triage
Connected Gmail MCP (Composio). Built triage prompt. Five drafts in
Drafts folder. Saved prompt to prompts/inbox-triage.md.
Session: bcd234ef5678 (resume: claude --resume bcd234ef5678)

## 2026-05-06 — Session 2.3: Memo iteration
Memo on [public source]. memos/<slug>/ pattern installed. drafts/
versioning. memo-template.docx built. memo.docx shipped.
Session: cde345fg6789 (resume: claude --resume cde345fg6789)

## 2026-05-06 — Session 2.4: Figure iteration
FRED UNRATE figure. exhibits/unemployment-rate/. Style preferences
written to your MEMORY.md file.
Session: def456gh7890 (resume: claude --resume def456gh7890)

## 2026-05-06 — Session 2.5: Memory infrastructure
This session. Built CLAUDE.md, MEMORY.md file, session-log.md. Created
/refresh. Decision record: [the one from Step E]. known-issues.md
seeded with [the failure recovered today].
Session: [get this from the session banner] (resume: claude --resume <id>)

Claude: backfill entries for the previous four sessions using actual dates the user remembers. Ask for the session ID for today’s session — it’s in the banner at the top of this chat. Then add today’s entry. The user reads each one back; if any is wrong, fix it.

Append-only. Never edit a past entry; if context updates, write a new entry referencing the old one.

Step D — Build the /refresh slash command (10 minutes)

Already done? Run ls ~/ai-training/.claude/commands. If refresh.md is already there, skip to Step E.

A slash command is just a markdown file in .claude/commands/ that Claude reads when you type the slash name.

mkdir -p ~/ai-training/.claude/commands

What this does. Creates the .claude/commands folder Claude Code checks for slash commands, the same mkdir -p pattern as Session 2.1.

Create ~/ai-training/.claude/commands/refresh.md:

Read MEMORY.md in the current working directory and load everything in it into this session.
Then read the last 5 entries of session-log.md and known-issues.md.

After reading, give me a 3-line summary: (a) what kind of project this is,
(b) what's in flight right now, (c) any open issues to watch for. Then
ask what we're working on today.

Worth knowing. CLAUDE.md auto-loads into every session, so anything that grows over time, like MEMORY.md, has to load on demand instead or it would bloat every session regardless of what you’re doing. That’s what /refresh is for: type it when you want full context, skip it for a quick one-off task.

For global scope (available in any project, not just ~/ai-training), create the file at ~/.claude/commands/refresh.md instead.

Save. Now in any Claude session opened from ~/ai-training/, typing /refresh runs that prompt. Test it:

/refresh

What this does. Runs the saved prompt in refresh.md, pulling MEMORY.md and the recent session-log into this session on demand.

Claude: confirm the command resolves and you read the MEMORY.md file and session-log.md. The 3-line summary should reflect what’s actually in those files, not generic platitudes.

This pattern — slash commands as saved prompts — generalizes. Anything the user re-runs more than twice becomes a slash command. By Session 2.7 there are several.

Step E — Deliberate breakage and decision record (15 minutes)

Now break something. Pick something low-risk but real:

Pick one. Make the change.

Now diagnose and fix, so the decision record below describes something real instead of a guess. With Claude:

Something feels off — I notice [symptom]. Walk me through diagnosis.
Check known-issues.md first; if there's a documented match, apply
the workaround. If not, isolate the cause.

Claude: actually do the diagnosis. Don’t pretend to debug; check what’s broken, narrow it down, propose the fix. The user makes the fix.

Once it’s fixed, write the decision record. Create ~/ai-training/decisions/:

mkdir -p ~/ai-training/decisions

What this does. Creates the decisions/ folder, the same mkdir -p pattern as Session 2.1.

Then decisions/2026-05-06-mcp-server-recovery.md (or whatever today’s date and the appropriate slug):

---
date: 2026-05-06
context: <one line on what broke>
---

## Symptom
[what the user noticed]

## Root cause
[what was actually wrong]

## Options considered
1. <option> — [pros/cons]
2. <option> — [pros/cons]

## Decision
[what was chosen and why]

## Followups
- [anything to monitor]
- Add to known-issues.md: yes/no

If the failure is something that could recur, add a one-line entry to known-issues.md:

# Known issues — ai-training

## MCP server "looks installed" but `claude mcp list` shows it disconnected
- Cause: registered with wrong scope (project-scope or local-scope when
  it should be user-scope).
- Fix: `claude mcp remove <name>` then `claude mcp add --scope user <name>`.
- See decisions/2026-05-06-mcp-server-recovery.md.

Tell the user: “That decision record and the known-issues entry are why future-you doesn’t repeat this debugging. The cost of writing them now is three minutes; the saved cost when this happens again is an hour.”

Micro-skills introduced

Name these out loud:

Wrapping up Session 2.5

Three things to try this week:

  1. Run /refresh at the start of every session for the next week. Notice when the 3-line summary tells you something useful and when it reads like noise. Tighten CLAUDE.md and MEMORY.md until the summary is consistently useful.
  2. Write one decision record per session, even if it feels small. “I picked Composio for Gmail MCP because Rube was rate-limited” is a fine decision record. The discipline of writing matters more than the gravity of the decision.
  3. Add to known-issues.md when something breaks. One line per failure. By Session 2.10, this file should have 5–10 entries — and most of those entries should let you recover in 30 seconds rather than 30 minutes.

Feedback.

The user submits feedback at https://docs.google.com/forms/d/e/1FAIpQLSfTljjTKAQmjXGwSTH_VK217hx1U44CslTeVN6KBRD9DfrJKA/viewform.

Claude: paste the URL into chat. The form mirrors the questions below. Collect answers conversationally first, then have the user click through and submit.

  1. On a 1–5 scale, how useful did this session feel?
  2. The three-file split (CLAUDE.md / MEMORY.md / session-log.md) — does the distinction feel real, or did it feel arbitrary?
  3. The deliberate breakage — did the recovery loop click? Did writing the decision record feel like it earned its three minutes?
  4. Will you actually run /refresh at session start? Honestly?
  5. What’s one thing you’d want to store in your MEMORY.md file that the template above didn’t anticipate?
  6. What confused you most this session?
  7. Anything you want covered in Session 2.6 that you didn’t see here?

Tell the user: “Your instructor uses these to tailor next week’s session.”

Good to know

The memory system is loadbearing for everything that follows. Sessions 2.6, 2.7, 2.8, 2.9 all read MEMORY.md or CLAUDE.md as durable context. Bad memory hygiene now means bad sessions later.

Don’t over-write CLAUDE.md. If you find yourself adding to CLAUDE.md every session, something else is wrong — either the additions are state (belong in MEMORY.md) or session events (belong in session-log.md). CLAUDE.md should change rarely.

Memory-as-symlinks is a power move, not a starter move. The cross-machine pattern (two memory-*.md files, MEMORY.md as a symlink) is right when you actually work across two machines on the same project. Don’t pre-build it.

Decision records age well. A six-month-old decision record reads as obvious in retrospect — “of course we chose that.” That’s why people skip writing them. Write them anyway. Six months later, the question won’t be “what did we do?” — it will be “why did we do it?”, and the rationale will be gone if you didn’t write it down.

The /refresh pattern generalizes. Every working directory deserves its own /refresh calibrated to its own files. Each loads the right context for its work.