open/claude-code-auto-memory
1
0
Fork 0
Code Activity Actions

feat(cc-013): add auto memory companion repo with three exercises

Browse source 
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 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-03-30 10:35:20 +02:00
commit eb5a4f0f6a
5 changed files with 551 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

43
CLAUDE.md Normal file
View file

@ -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/<project-hash>/memory/`. Machine-local only.

82
README.md Normal file
View file

@ -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/<project-hash>/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.

112
exercises/01-trigger-memory.md Normal file
View file

@ -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/<project-hash>/memory/
```
The `<project-hash>` 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/<project-hash>/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).

141
exercises/02-structure-memory.md Normal file
View file

@ -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/<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](./03-cross-session.md).

173
exercises/03-cross-session.md Normal file
View file

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