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

About 60 minutes. Open a Claude Code session in ~/ai-training and hand it this guide:

Read the file at /Users/<you>/ai-training/week-5-guide.md (or wherever you saved it) and walk me through Session 2.5.
I've completed Sessions 2.1 through 2.4.

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.

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 — 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 reads CLAUDE.md, MEMORY.md, and session-log.md at session start.
  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 (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.

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:

Step 1: Hand Claude this guide

From inside ~/ai-training, start claude and paste:

Read the file at /Users/<you>/ai-training/week-5-guide.md (or wherever you saved it) and walk me through the Reference Sections.
I've completed Sessions 2.1 through 2.4.

Claude takes over.

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 system. 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)

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, run /refresh to load CLAUDE.md, MEMORY.md, and session-log.md.

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 (15 minutes)

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

The right structure for MEMORY.md:

# 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 MEMORY.md.

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

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

session-log.md is chronological. One entry per substantive session, written at the end. Each entry is short — 5–10 lines.

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.

## 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.

## 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.

## 2026-05-06 — Session 2.4: Figure iteration
FRED UNRATE figure. exhibits/unemployment-rate/. Style preferences
written to MEMORY.md.

## 2026-05-06 — Session 2.5: Memory infrastructure
This session. Built CLAUDE.md, MEMORY.md, session-log.md. Created
/refresh. Decision record: [the one from Step E]. known-issues.md
seeded with [the failure recovered today].

Claude: backfill entries for the previous four sessions using actual dates the user remembers. 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)

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

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

Read the following files in this directory, in order:

1. CLAUDE.md — the durable rules and context for this project.
2. MEMORY.md — curated state and preferences. Read the index first, then
   the sections that look relevant to today's task.
3. session-log.md — the last 5 entries.
4. known-issues.md — scan the list before diagnosing any new problem.

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.

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

/refresh

Claude: confirm the command resolves and you read all four files. The 3-line summary should reflect what’s actually in CLAUDE.md and MEMORY.md, 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. 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

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 remember in MEMORY.md 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.