Claude Code /memory

Posted on Sunday, July 5, 2026

 


When you run /memory in Claude Code, it will open a menu that shows you every memory file currently loaded in this session.

 


Researching /memory

You can find some details on /memory at How Claude remembers your project https://code.claude.com/docs/en/memory [1]

Let’s run the /memory command and see what we get.

 

  > /memory

 

 


 


 

The first thing you will see here is the “Auto-memory” setting.  It defaults to on.

What does this mean?

If this is set to “on” it might save memories from your current session in the ~/.claude/projects/<your-project>/memory/  
folder

Looking at what I have on my machine the <your-project> is a folder named after the path where you are running Claude

For example I have ~/.claude/projects/-tmp/memory which means it was saved when I ran claude in my /tmp folder

 


If I look in here I see a few memory files  MEMORY.md and setup_fast_mode_indicator.md

The main file here is the MEMORY.md file.  Claude will create/edit these sometimes based on what you are having Claude do.  In my own case it does not seem to happen often.  I have 62 project folders and only 5 have memory folders.

I need to do some more research to better understand this.

 


 


Let me walk down this one by one…

First one

  1.  User memory   Saved in ~/.claude/CLAUDE.md

This is talking about using your memory file located at ~/.claude/CLAUDE.md

In my case right now this file does not exist so… there is nothing to load… I think this just references it here to say you could persist memory to this file if you wanted to.

Let me do that and see if the prompt changes.

I am going to run this prompt

 

Create my personal user-level memory file at `~/.claude/CLAUDE.md`.

If the file doesn't exist, create it with a clean basic structure.

Add the following personal preferences:

## My Preferences

### General Rules
- Always prefer `pnpm` over `npm` when both are available
- Use meaningful variable and function names
- Prefer early returns over deeply nested conditionals
- Keep functions relatively small and focused 

### Communication Style
- Be direct and concise
- Show code examples when explaining things
- Explain *why* you're making a suggestion, not just what to do 

### Code Quality

- Write clean, readable code over clever code
- Add comments only when they explain *why*, not *what*
- Follow the existing code style in whatever project we're working in

 

 

OK now let me run /memory again

 

  > /memory

 

 


The text did not change… seems odd to me

OK I can select it and press enter and it will open the CLAUDE.md file it referenced.

Hmmm let me set up a more robust example…

 


A more Robust example

 

OK let’s set up a better test.  But first let’s walk through some isms.


  1.  When you start Claude code it will load several memory files
  2. The first one it will load is User memory file which is located at ~/.claude/CLAUDE.md  (this will apply to any instance of Claude you are running on your system)
  3. The next memory(ies) will be loaded from the ~/.claude/rules folder.  Here you can put several Markdown files that can have unique names
  4. The next memory(ies) will be loaded from the local directory or any directory above it.  This file must be called CLAUDE.md.   As an example you could have a CLAUDE.md file in the base of your git repo.  And/or you could also have the file in a .claude directory so .claude/CLAUDE.md
  5. Next you have Project memory which are memories auto created/edited/saved by Claude and placed in ~/.claude/projects/<your-project>/memory/  
  6. Last you load Agent Memory user scope and project scope
  7. One special case!! Any memory file can reference another file using the @filename  Any file referenced like this does not need to be a Markdown but it needs to be text


OK I think I understand the rules well enough now so let’s make an example.

 

 

1.      Confirm you have a ~/.claude/CLAUDE.md file (it not make one) 

 

  > cat ~/.claude/CLAUDE.md

 

 

2.      Put a memory file in the ~/.claude/rules folder

 

  > mkdir ~/.claude/rules
  > cd ~/.claude/rules
  > vi git-workflow.md

 

 

Put this in it

 

# Git Workflow

- Use conventional commit messages (e.g., `feat:`, `fix:`, `refactor:`)
- Create a branch for every feature or bug fix
- Rebase onto `main` before opening a pull request
- Never force push to shared branches

 

 

 

3.      Create a folder structure and place some CLAUDE.md files in it. 

 

> mkdir -p /tmp/one_dir/two_dir/three_dir
> mkdir /tmp/one_dir/two_dir/three_dir/.claude
> mkdir /tmp/one_dir/two_dir/.claude
> mkdir /tmp/one_dir/.claude

 

 

Now create the CLAUDE.md files

 

> vi /tmp/one_dir/.claude/CLAUDE.md

 

 

Place the following in it

 

# General Coding Rules

## Core Principles

- Write clean, readable code over clever code
- Keep functions small and focused (ideally under 30 lines)
- Use meaningful names for variables, functions, and files
- Prefer early returns over deeply nested conditionals 

## Code Quality
- Always run the linter and formatter before committing
- Add comments only when they explain *why*, not *what* the code does
- Follow the existing code style in the project
- Avoid magic numbers — use named constants instead 

## Error Handling
- Handle errors explicitly instead of ignoring them
- Use meaningful error messages
- Prefer throwing specific errors over generic ones

 

 

I am going to lazy copy this to the next directory

 

> cp /tmp/one_dir/.claude/CLAUDE.md /tmp/one_dir/two_dir/.claude/CLAUDE.md

 

 

Then for the final one

 

> vi /tmp/one_dir/two_dir/three_dir/.claude/CLAUDE.md

 

 

Place this in it

 

 

# Project Memory

## Reference Data

- **US States**: See @us_states.json (contains state name, capital, and population for all 50 states)

## Rules
- Always use the data from @us_states.json when answering questions about U.S. states.
- Do not make up population numbers or capitals.
- If asked for information not present in the JSON, clearly state that the data is not available.

 

 


You can see here it references another memory file @us_states.json

 

Now let’s create that file 

 

> vi /tmp/one_dir/two_dir/three_dir/.claude/us_states.json

 

 

And place the following in it

 

[

  {"state": "Alabama", "capital": "Montgomery", "population": 5108468},
  {"state": "Alaska", "capital": "Juneau", "population": 733406},
  {"state": "Arizona", "capital": "Phoenix", "population": 7431344},
  {"state": "Arkansas", "capital": "Little Rock", "population": 3067732},
  {"state": "California", "capital": "Sacramento", "population": 39355309},
  {"state": "Colorado", "capital": "Denver", "population": 5893634},
  {"state": "Connecticut", "capital": "Hartford", "population": 3626205},
  {"state": "Delaware", "capital": "Dover", "population": 1031890},
  {"state": "Florida", "capital": "Tallahassee", "population": 22610726},
  {"state": "Georgia", "capital": "Atlanta", "population": 11029227},
  {"state": "Hawaii", "capital": "Honolulu", "population": 1441553},
  {"state": "Idaho", "capital": "Boise", "population": 1964726},
  {"state": "Illinois", "capital": "Springfield", "population": 12549689},
  {"state": "Indiana", "capital": "Indianapolis", "population": 6833037},
  {"state": "Iowa", "capital": "Des Moines", "population": 3207004},
  {"state": "Kansas", "capital": "Topeka", "population": 2940865},
  {"state": "Kentucky", "capital": "Frankfort", "population": 4553941},
  {"state": "Louisiana", "capital": "Baton Rouge", "population": 4573749},
  {"state": "Maine", "capital": "Augusta", "population": 1395722},
  {"state": "Maryland", "capital": "Annapolis", "population": 6180253},
  {"state": "Massachusetts", "capital": "Boston", "population": 7001399},
  {"state": "Michigan", "capital": "Lansing", "population": 10037261},
  {"state": "Minnesota", "capital": "Saint Paul", "population": 5778915},
  {"state": "Mississippi", "capital": "Jackson", "population": 2939690},
  {"state": "Missouri", "capital": "Jefferson City", "population": 6196156},
  {"state": "Montana", "capital": "Helena", "population": 1132812},
  {"state": "Nebraska", "capital": "Lincoln", "population": 1978379},
  {"state": "Nevada", "capital": "Carson City", "population": 3194176},
  {"state": "New Hampshire", "capital": "Concord", "population": 1402054},
  {"state": "New Jersey", "capital": "Trenton", "population": 9290841},
  {"state": "New Mexico", "capital": "Santa Fe", "population": 2120220},
  {"state": "New York", "capital": "Albany", "population": 19849399},
  {"state": "North Carolina", "capital": "Raleigh", "population": 10986227},
  {"state": "North Dakota", "capital": "Bismarck", "population": 796568},
  {"state": "Ohio", "capital": "Columbus", "population": 11883304},
  {"state": "Oklahoma", "capital": "Oklahoma City", "population": 4053824},
  {"state": "Oregon", "capital": "Salem", "population": 4233358},
  {"state": "Pennsylvania", "capital": "Harrisburg", "population": 12972008},
  {"state": "Rhode Island", "capital": "Providence", "population": 1095962},
  {"state": "South Carolina", "capital": "Columbia", "population": 5373555},
  {"state": "South Dakota", "capital": "Pierre", "population": 919318},
  {"state": "Tennessee", "capital": "Nashville", "population": 7126489},
  {"state": "Texas", "capital": "Austin", "population": 31709821},
  {"state": "Utah", "capital": "Salt Lake City", "population": 3417734},
  {"state": "Vermont", "capital": "Montpelier", "population": 648493},
  {"state": "Virginia", "capital": "Richmond", "population": 8811195},
  {"state": "Washington", "capital": "Olympia", "population": 7812880},
  {"state": "West Virginia", "capital": "Charleston", "population": 1770071},
  {"state": "Wisconsin", "capital": "Madison", "population": 5910955},
  {"state": "Wyoming", "capital": "Cheyenne", "population": 584057}
] 

 

 

OK now lets go the final folder and start claude

 

> cd /tmp/one_dir/two_dir/three_dir/
> claude

 

 

Now run /memory

 

> /memory

 

 

Now what do we see?

We see the User memory as expected but below that we now see the ~/.claude/rules/git-workflow.md file

And after that we see the different CLAUDE.md files that are being taken in that are higher up in the directories from where we started

 

/tmp/CLAUDE.md
/tmp/one_dir/.claude/CLAUDE.md
/tmp/one_dir/two_dir/.claude/CLAUDE.md

 


If I scroll down further I can see the .claude/CLAUDE.md in the folder I started Claude code in and I can see the memory file it references us_states.json

After that I see project memory, then auto-memory and finally any memory folders attached to any agents I have created locally or that happen to be in the project I am in.

OK neat I think I am getting this.

 

 

Final Thoughts

 

I need to do some more research on this…

But the walk away is you can put information that you want to persist between sessions in your memory files (Typically CLAUDE.md files).
There is a structure to it, some are on your user level in ~/.claude and some can be on the project level.   Running /memory will show you what was loaded.

I do need to do some more research on creating useful memories, but I think that if you pre-populate your local memory files you can get a big boost in doing your daily tasks.  In the same vein if you make good Memory files in a project you can help everyone get their job done better when running Claude from within a project.

 

… The research goes on…




References

[1]       How Claude remembers your project
            https://code.claude.com/docs/en/memory
            Accessed 07/2026

 

 

 

 

 

 

 

 

 



 

 

 

 

 

 



 

 

No comments:

Post a Comment