commit eb5a4f0f6a9ec359ec2dbbd9ba6945a3f8a5720a Author: Kjell Tore Guttormsen Date: Mon Mar 30 10:35:20 2026 +0200 feat(cc-013): add auto memory companion repo with three exercises Companion repo for CC-013. Covers triggering memory, structuring MEMORY.md with index and topic files, and proving cross-session persistence shapes Claude behavior. Co-Authored-By: Claude Sonnet 4.6 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3969a10 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# Auto Memory: Claude Code Remembers What You Teach It + +## What this project is + +A companion repo for the From AI to Chitta article on **Auto Memory** +(concept ID: `CC-013`). It contains exercises that let you build and +verify a working cross-session memory system in Claude Code. + +Article: https://fromaitochitta.com/cc-013 + +## How to use this + +1. Open Claude Code in this directory: `cd claude-code-auto-memory && claude` +2. Work through exercises in order: `exercises/01-trigger-memory.md`, then 02, then 03 +3. Each exercise has concrete steps with expected output +4. Compare your results to the expected output described in each exercise + +## Code quality expectations + +- This is a learning repo. Clarity over cleverness. +- Every exercise must run without modification on a clean clone +- No external dependencies +- If something does not work as expected, that is useful information: note it + +## Project structure + +``` +exercises/ Numbered exercises with steps and expected output +CLAUDE.md This file: project instructions +README.md Overview for anyone who clones this repo +``` + +## Domain + +Claude Code Memory and Instructions + +## Memory + +Keep session notes in a local `MEMORY.md` (gitignored). This file +(CLAUDE.md) is for instructions. MEMORY.md is for state. + +Note: memory files for this project are stored at +`~/.claude/projects//memory/`. Machine-local only. diff --git a/README.md b/README.md new file mode 100644 index 0000000..fb0f9fa --- /dev/null +++ b/README.md @@ -0,0 +1,82 @@ +# Auto Memory: Claude Code Remembers What You Teach It + +Claude Code can remember preferences, decisions, and context across +sessions. This is not a plugin or an add-on. It is built in. Once you +know how to trigger it, Claude gets progressively more useful with +every session. + +Companion repo for the article +[Auto Memory: Claude Code Remembers What You Teach It](https://fromaitochitta.com/cc-013) on From AI to Chitta. + +--- + +## What You Will Learn + +By working through the exercises in this repo, you will be able to: + +- Trigger auto memory by telling Claude what to remember, and verify + the memory file was created +- Structure MEMORY.md with a lightweight index and separate topic files + to stay under the 200-line limit +- Prove that memory persists across sessions and shapes Claude's behavior + without you repeating yourself + +These are not theoretical outcomes. Complete the exercises and you will +have a working memory system in your own project. + +## Prerequisites + +- Claude Code v2.1.59 or later installed (`claude --version` prints a version) +- A Claude Pro, Team, or Enterprise subscription +- A project directory to practice on (this repo works fine) + +No npm install, no Docker, no build step. + +## Exercises + +| # | Exercise | What It Covers | +|---|----------|---------------| +| 01 | [Trigger Memory](exercises/01-trigger-memory.md) | Make Claude remember something and verify it sticks | +| 02 | [Structure Memory](exercises/02-structure-memory.md) | MEMORY.md index and topic files, the 200-line limit | +| 03 | [Cross-Session Persistence](exercises/03-cross-session.md) | Prove memory accumulates and shapes behavior | + +Start at `exercises/01-trigger-memory.md`. Each exercise links to the next. + +## How to Use This Repo + +**"Show me what it does":** Browse `exercises/` and read through +the steps. Understand the pattern before you run anything. + +**"Let me actually do it":** Open Claude Code in this directory +and follow the exercises in order. Each one has an expected output +section so you know when you have succeeded. + +```bash +git clone https://git.fromaitochitta.com/fromaitochitta/claude-code-auto-memory.git +cd claude-code-auto-memory +claude +``` + +Then open `exercises/01-trigger-memory.md` and follow the steps. + +## A Note on Machine-Local Memory + +Memory files are stored on your local machine under +`~/.claude/projects//memory/`. They are not synced to +git, not shared with other machines, and not visible to anyone else. +If you clone this repo on a different machine, you start fresh. +This is by design. + +## Domain + +**Claude Code Memory and Instructions** - This repo is part of the +Claude Code Memory and Instructions series on From AI to Chitta. +See the full series for related concepts. + +## About + +Built by [Kjell Tore Guttormsen](https://fromaitochitta.com) as +part of the From AI to Chitta project, exploring the intersection +of AI tools and inner development. + +MIT License. diff --git a/exercises/01-trigger-memory.md b/exercises/01-trigger-memory.md new file mode 100644 index 0000000..432c7d0 --- /dev/null +++ b/exercises/01-trigger-memory.md @@ -0,0 +1,112 @@ +# Exercise 01: Trigger Memory + +**Concept:** Auto Memory (CC-013) +**Level:** Basic +**Time:** ~10 minutes + +--- + +## Objective + +Tell Claude something to remember, verify the memory file was created, +and confirm it survives a new session. + +This is your first hands-on contact with auto memory. No prior experience +with Claude Code memory required. + +--- + +## Before You Start + +Confirm you have: + +- [ ] Claude Code v2.1.59 or later installed (`claude --version` prints a version) +- [ ] This repo cloned and open in Claude Code +- [ ] Started Claude Code in this directory (`claude`) + +--- + +## Instructions + +**Step 1:** Start Claude Code in this directory. + +```bash +cd claude-code-auto-memory +claude +``` + +**Step 2:** Paste this prompt into Claude Code: + +``` +Remember that I prefer 2-space indentation and single quotes in TypeScript. +``` + +Claude will confirm the preference and save it to memory. You should see +a tool call to write a file under `~/.claude/projects/`. + +**Step 3:** Find the memory file that was just created. + +Paste this into Claude Code: + +``` +Where did you save that memory? Show me the path and the file contents. +``` + +Claude will tell you the exact path. It will be somewhere under: + +``` +~/.claude/projects//memory/ +``` + +The `` is a deterministic hash of the project directory path. +You can also find it yourself: + +```bash +ls ~/.claude/projects/ +``` + +Look for a directory that corresponds to this repo. Open the memory file +inside it and read what was saved. + +**Step 4:** Start a new session and test recall. + +In Claude Code, type `/clear` to start a fresh conversation. Then paste: + +``` +What are my TypeScript preferences? +``` + +Claude should recall 2-space indentation and single quotes without you +repeating them. + +--- + +## Expected Output + +After completing the steps above, you should see: + +- A new file in `~/.claude/projects//memory/` containing + your TypeScript preferences +- Claude confirming the memory was saved during Step 2 +- After `/clear`, Claude recalling both preferences without any prompt + +If Claude says it has no preferences on file, check that you are in the +same directory as Step 1. The project hash is derived from the directory +path, so a different working directory means a different memory store. + +--- + +## What You Learned + +- **"Remember" is the trigger:** Phrases like "remember that" or "save this" + cause Claude to write a memory file explicitly +- **Project-scoped storage:** Memories are stored per project, not globally, + so different projects have separate memory stores +- **Machine-local:** The memory files are on your machine only. They are not + in git and not shared across machines. + +--- + +## Next + +Ready to go further? Move to [Exercise 02: Structure Memory](./02-structure-memory.md). diff --git a/exercises/02-structure-memory.md b/exercises/02-structure-memory.md new file mode 100644 index 0000000..de8bf2c --- /dev/null +++ b/exercises/02-structure-memory.md @@ -0,0 +1,141 @@ +# Exercise 02: Structure Memory + +**Concept:** Auto Memory (CC-013) +**Level:** Intermediate +**Time:** ~15 minutes +**Builds on:** [Exercise 01](./01-trigger-memory.md) + +--- + +## 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//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](./03-cross-session.md). diff --git a/exercises/03-cross-session.md b/exercises/03-cross-session.md new file mode 100644 index 0000000..7eaed2e --- /dev/null +++ b/exercises/03-cross-session.md @@ -0,0 +1,173 @@ +# Exercise 03: Cross-Session Persistence + +**Concept:** Auto Memory (CC-013) +**Level:** Advanced +**Time:** ~20 minutes +**Builds on:** [Exercise 01](./01-trigger-memory.md) and [Exercise 02](./02-structure-memory.md) + +--- + +## Objective + +Prove that memory persists across fully closed sessions and silently +shapes Claude's behavior, without you repeating any preferences. + +This is the payoff exercise. You are not just creating memory files. +You are watching them change how Claude writes code. + +--- + +## The Scenario + +You have a coding preference. You tell Claude once. You close Claude +Code entirely. You reopen it. You ask Claude to write code. Without +mentioning the preference, you check whether Claude followed it. + +This is the pattern that makes auto memory genuinely useful: you +teach Claude once, and it holds. + +--- + +## Instructions + +**Step 1:** In a fresh Claude Code session, register a preference +you can test in code. Paste this prompt: + +``` +Remember that I never use semicolons in TypeScript. No exceptions. +Write this to the user preferences memory file. +``` + +Claude will save it. Confirm the save. + +**Step 2:** Close Claude Code completely. + +Not just `/clear`. Exit the process entirely: + +``` +/exit +``` + +Or close the terminal window and open a new one. + +**Step 3:** Reopen Claude Code in the same project directory. + +```bash +cd claude-code-auto-memory +claude +``` + +Do not mention the no-semicolons preference. Do not paste any context +about your style. Just open it. + +**Step 4:** Ask Claude to write a TypeScript function. Paste this: + +``` +Write a TypeScript function called formatDate that takes a Date object +and returns a string in YYYY-MM-DD format. +``` + +Read the output carefully. Count the semicolons. + +**Step 5:** Check whether memory was loaded. + +``` +What TypeScript preferences do you have on file for me? +``` + +Claude should list the no-semicolons rule and any preferences from +earlier exercises, without you supplying them. + +**Step 6:** Add a project-level memory about this session. + +``` +Remember about this session: I completed all three auto memory exercises +today. The project is a learning repo for CC-013. Next time, start by +reading the exercise files to see what was covered. +``` + +This creates a lightweight session log. Open a new session and verify +Claude greets you with context about what was done. + +--- + +## What a Strong Solution Looks Like + +A strong result: + +- The `formatDate` function contains no semicolons, even though you + never mentioned the preference in this session +- Claude lists your preferences accurately when asked in Step 5 +- The session note from Step 6 appears in memory and loads next session + +A result that misses the point: + +- Claude produces code with semicolons because the memory was not loaded +- Claude says it has no preferences on file (likely a path or session issue) +- The session note is never saved to a file + +--- + +## Troubleshooting + +**Claude does not follow the preference:** Check that you are in exactly +the same directory as Step 1. Run `pwd` and compare. The project hash +is path-specific. + +**Memory shows nothing from earlier exercises:** If you used `/clear` +instead of fully exiting and reopening, that may not have reset the +session the same way. Try a full exit and reopen. + +**The function has semicolons despite the rule:** This can happen if +the memory file was saved but Claude did not load it. Ask Claude: +"Read the memory directory and tell me every file in it." If it is +empty, the save in Step 1 did not complete. + +--- + +## Challenge + +If you finish early or want to go further: + +- **Challenge A:** Register three conflicting preferences across two sessions + and see how Claude resolves them. Which one wins? +- **Challenge B:** Delete one topic file manually from `~/.claude/projects/` + and verify Claude no longer applies that preference. +- **Challenge C:** Set up memory in a different project on your machine and + confirm the two projects have separate, independent memory stores. + +--- + +## Reflection + +After completing this exercise, consider: + +- What preferences or context would be most valuable to store in your + real projects? +- What is the difference between memory in CLAUDE.md (checked into git, + shared with the team) and memory in the project memory store (local only)? +- Where does auto memory break down, and when would you use CLAUDE.md instead? + +There is no right answer to these questions. The reflection is for you. + +--- + +## What You Learned + +- **Memory accumulates progressively:** Each session leaves a trace. + Claude becomes more tuned to your context over time. +- **Silent behavior shaping:** You do not need to repeat preferences. + They are loaded automatically and applied without prompting. +- **Machine-local scope:** Everything in `~/.claude/projects/` stays + on your machine. Moving to a new machine means rebuilding memory. + This is a tradeoff worth knowing. + +--- + +## What Is Next + +You have now worked through all three exercises for Auto Memory. + +Return to the article at https://fromaitochitta.com/cc-013 for +the broader context, or explore related concepts in the +Claude Code Memory and Instructions series.