Memory System Design — Design Guidelines for User, Project, and Reference Memory

Using the Claude Code memory system, you can retain user preferences, project decisions, and references to external resources across conversations. This page covers in order: the differences between 4 memory types, designing the MEMORY.md index, and actual operation.

---

What Is the Memory System?

The memory system is a file-based mechanism for Claude Code to retain information across conversations. Normally, Claude Code resets its state when a session ends. By using memory files, Claude can reference the previous context in the next session as well.

Memory is saved in the ~/.claude/projects/<project-path>/memory/ directory. <project-path> is the path to the project’s root directory with / converted to -.

~/.claude/projects/
└── -Users-yourname-github-myproject/
    └── memory/
        ├── MEMORY.md          # Index file
        ├── user-background.md
        ├── feedback-response-style.md
        └── project-current-sprint.md

MEMORY.md is the index file. When Claude Code refers to the memory directory, it reads this file first. There is a limit of 200 lines and 150 characters per line, and anything exceeding this is truncated.

---

The 4 Memory Types and How to Use Them

Memory files are classified into 4 types using the metadata.type field in the frontmatter.

Type	What is recorded	Example records
user	User’s role, skills, preferences	”Skilled in React, beginner at Go”
feedback	Instructions and corrections to Claude	”Don’t write a summary at the end of responses”
project	Current work, decisions, deadlines	”Merge freeze until 2026-05-30”
reference	Pointers to external resources	”Bug management is done in Linear’s INGEST project”

By using each type appropriately, it becomes easier for Claude to judge which information to reference in which context.

---

How It Works: The Structure of Memory Files

frontmatter Format

---
name: short-kebab-case-slug
description: A one-sentence description of the memory's contents
metadata:
  type: user | feedback | project | reference
---

• name: A slug that identifies the file. Match it to the filename
• description: A one-line description listed in the MEMORY.md index
• metadata.type: Specify one of the 4 types

The Body of a Memory File

After the frontmatter, write the information to Claude directly in Markdown. Always write “Why (why this information is needed)” and “How to apply (how to apply it).”

---
name: user-background
description: User's technical background and preferences
metadata:
  type: user
---

Frontend engineer. Skilled in React/TypeScript. Has never written Go.

**Why:** To provide explanations tailored to the technical level.
**How to apply:** Make explanations implementation-oriented and actively use React examples. If Go knowledge is needed, explain from the basics carefully.

The Format of the MEMORY.md Index

Each line of MEMORY.md is written in the following format.

- [title](file.md) — one-line hook (a word about what is written)

Example of an actual MEMORY.md:

# Memory Index

- [user-background](user-background.md) — Frontend engineer skilled in React/TypeScript
- [feedback-response-style](feedback-response-style.md) — Don't write a summary at the end of responses
- [project-current-sprint](project-current-sprint.md) — Merge freeze until 2026-05-30
- [reference-linear](reference-linear.md) — Bug management in Linear's INGEST project

---

Best Practices

Do Not Save Code Patterns or Git History

Do not write information that can be obtained with git log, grep, or cat into memory. Memory is a place to save “context Claude should know about” — not a place to duplicate information that can be obtained from the repository. It only wastes the context window.

Always Write the Why

Memory becomes outdated over time. Writing down why that information was saved makes it easier to judge when to update or delete it.

// Style to avoid: No Why
Don't write a summary at the end.

// Recommended: Has Why
Don't write a summary at the end.
**Why:** The user can read the diff directly, so repeated explanations are unnecessary.

Save Both Successes and Failures in feedback

Record not only “approaches that were asked to be redone” but also “approaches that were explicitly confirmed as good.” Saving only failures leaves Claude without enough material to judge which approaches are effective.

Use Absolute Dates for project Memory

Relative expressions like “Thursday” or “next week” lose meaning when the memory is read later. Write in absolute dates like 2026-05-30.

// Style to avoid: Relative date
Merge freeze until next week.

// Recommended: Absolute date
Merge freeze until 2026-05-30.

Update and Delete Old Memory

If old information remains after the situation has changed, Claude risks operating on incorrect premises. Review memory at regular intervals such as sprint end or project completion.

---

Hands-on Exercise

Step 1: Check the Project’s Memory Directory

Run the following command in the terminal to check the list of memory directories.

ls ~/.claude/projects/

Example output:

-Users-yourname-github-ai-learning-playground
-Users-yourname-github-another-project

Confirm that a directory corresponding to the project’s path exists.

✅ Verify: If a directory corresponding to the project you are currently working on is displayed, the memory system is active. If the directory does not exist, it is automatically created when you open that project in Claude Code once.

---

Step 2: Check the MEMORY.md Index

Check the MEMORY.md in the project’s memory directory. Replace <path> with the actual path.

cat ~/.claude/projects/<path>/memory/MEMORY.md

Read the list of memory files recorded in the index and the description of each.

✅ Verify: If the file is displayed, the index check is complete. If the file is empty or does not exist, create a feedback memory and add it to the index in the next step.

---

Step 3: Create a New Feedback Memory

Create a memory file that records feedback to Claude. Replace <path> with the actual path.

Content of the file to create:

---
name: feedback-response-style
description: Feedback on Claude's responses
metadata:
  type: feedback
---

Don't write a summary at the end of responses.

**Why:** The user can read the diff directly, so repeated explanations are unnecessary.
**How to apply:** When the work is complete, briefly convey only the next steps. Omit the bulleted list summary for confirmation.

After saving the file in the terminal, confirm the file has been created with the following command.

ls ~/.claude/projects/<path>/memory/

✅ Verify: If feedback-response-style.md appears in the list, creation was successful.

---

Step 4: Add an Entry to MEMORY.md

Edit MEMORY.md and add the created memory file to the index.

- [feedback-response-style](feedback-response-style.md) — Don't write a summary at the end of responses

Example of MEMORY.md after adding:

# Memory Index

- [feedback-response-style](feedback-response-style.md) — Don't write a summary at the end of responses

Launch Claude Code in the next session and confirm that Claude references the instruction “don’t write a summary at the end” and operates accordingly.

✅ Verify: Confirm by cat on MEMORY.md that the entry has been added. You can check the memory loading state in the next session with the /memory command.

---

Summary

• The memory system is session-spanning memory saved as files in ~/.claude/projects/<path>/memory/
• MEMORY.md is an index file with a limit of 200 lines and 150 characters per line
• Memory is classified into 4 types: user, feedback, project, and reference
• Always writing Why and How to apply makes it easier to judge when to update when it becomes outdated
• Do not save code or git history in memory; use absolute dates for project memory
• Regularly review old memory and update/delete it to maintain context freshness

---

Next Steps

• Harness Testing and Validation — Move on to systematically verifying that the entire configuration including memory functions as intended
• Settings JSON Design — Review the settings for permissions and environment variables used in combination with memory

---

Frequently Asked Questions

Q: How many memory files can be created?

A: There is no limit on the number of files. However, the amount of information Claude Code can reference at session start depends on context window limitations. Since information exceeding the 200-line limit of the MEMORY.md index is truncated, it is recommended to place high-priority memories at the top.

Q: Can memory be shared across multiple projects?

A: Currently, memory is saved in per-project directories, so automatic sharing across projects is not possible. For information common to multiple projects (such as the user’s technical background), you can handle it by manually copying to each project’s memory or by writing it in a global CLAUDE.md.

Q: Does Claude automatically update memory?

A: When Claude Code’s automatic memory feature is enabled, Claude may automatically generate and update memory files based on conversation content. It is recommended to periodically check the contents of automatically updated memory and verify that no unintended information has been saved.

Q: What happens when a memory file is deleted?

A: If a file is deleted, Claude will no longer reference that information from the next session. Also delete the index entry in MEMORY.md. If a file listed in the index does not exist, Claude Code may report an error.

Q: What is the difference between the /memory command and manually creating files?

A: The /memory command verbally conveys information to Claude, and Claude automatically generates memory files. Manually creating files lets you control the frontmatter type and the Why / How to apply sections yourself. Manual creation is recommended for important design decisions or detailed context.

See the references for the external specifications and background sources used on this page.[1][2]

References

1. Anthropic, Claude Code documentation
2. Anthropic, Claude API documentation