claude-code-auto-memory/exercises/02-structure-memory.md

Exercise 02: Structure Memory

Concept: Auto Memory (CC-013) Level: Intermediate Time: ~15 minutes Builds on: Exercise 01

---

Objective

Build a structured memory system with a MEMORY.md index and separate topic files, and verify the index stays under the 200-line limit.

This exercise assumes you completed Exercise 01 and have seen at least one memory file created.

---

The Structure

Claude Code's memory system has two layers:

• MEMORY.md - the index file. Always loaded at session start. Keep it under 200 lines. Each entry is a one-line pointer to a topic file.
• Topic files - separate files with the actual detail. Loaded on demand. Names like user_preferences.md, feedback_formatting.md, project_status.md.

If MEMORY.md exceeds 200 lines, the bottom gets truncated on load and Claude loses context silently. The index-plus-topic-files pattern avoids this.

Memory is stored at ~/.claude/projects/<project-hash>/memory/. This is machine-local. Not in git, not synced.

---

Instructions

Step 1: Start Claude Code in this directory and give it several different types of memories to save. Paste each prompt separately:

First, a user preference:

Remember that I prefer verbose error messages over silent failures in
all code I write.

Then a feedback entry:

Remember feedback: never use default exports in TypeScript modules.
Always use named exports so imports are explicit.

Then a project note:

Remember about this project: this is a learning repo for CC-013. It has
three exercises and no production code. The goal is to demonstrate
cross-session memory, not to build anything.

Then a reference entry:

Remember for reference: the memory docs are at
https://fromaitochitta.com/cc-013

Step 2: Ask Claude to show you the memory directory structure.

Paste this prompt:

Show me all the files in the memory directory for this project. List
each filename and the first line of its contents.

You should see MEMORY.md plus 3-4 topic files. Each topic file holds one category of memory.

Step 3: Ask Claude to open MEMORY.md and read it to you.

Read MEMORY.md from the memory directory and show me the full contents.

Verify:

• MEMORY.md has one-line pointer entries for each topic file
• It does not reproduce the full detail inline
• The total line count is well under 200

---

Expected Output

A good result:

• MEMORY.md with 5-10 lines total, each pointing to a topic file
• 3-4 separate topic files holding the actual content
• No single file exceeding what could reasonably fit in context

A result that needs work:

• MEMORY.md that contains the full text of all memories inline
• Only a single flat file with all entries merged together
• Topic files with names so generic they give no information

---

Hints

Stuck? Try these:

1. If only one file was created: Claude may have written everything to MEMORY.md directly. Ask it to refactor: "Split MEMORY.md into an index with one-line entries, and move each category into its own topic file."
2. If the memory directory is empty: Make sure you are in the same directory you used in Exercise 01 and that your session is active.
3. If MEMORY.md is long: Prompt Claude: "MEMORY.md should be an index only. Move all detail into topic files and replace the entries in MEMORY.md with one-line summaries."

---

What You Learned

• Index vs. detail: MEMORY.md is a table of contents, not a notebook. Detail lives in topic files.
• The 200-line limit: MEMORY.md is fully loaded at session start. Over 200 lines, the tail gets cut. The index pattern keeps it safe.
• Memory types: Preferences, feedback, project state, and reference links each belong in their own file.

---

Next

For the real test, move to Exercise 03: Cross-Session Persistence.