Memory system should be hierarchical and live in the project folder

Current behavior

The memory system stores files in ~/.claude/projects/<project>/memory/ — a flat, hidden directory outside the project. It supports four types (user, feedback, project, reference) with an index file (MEMORY.md). Meanwhile, CLAUDE.md files are hierarchical and live in the actual project folder, but are designated for "instructions" rather than "memory."

In practice, the distinction between what belongs in CLAUDE.md vs memory is blurry. Both hold project context. Both inform future sessions. But they live in different places, follow different rules, and have different scoping behavior.

The experience

When working on a non-code project (a product research/design project with subfolders), the current system felt awkward:

• Memory is flat per project — no subfolder-level memory. If you have project/design/ and project/research/, they share one memory bucket with no way to scope context to a subfolder.
• Memory is hidden — it lives in ~/.claude/, not in the project. The user can't easily see, edit, or version-control it alongside their work.
• Two systems for one job — having both CLAUDE.md (hierarchical, in-project, for "instructions") and memory/ (flat, hidden, for "memories") creates cognitive overhead. The user has to understand which system handles what, and the answer isn't always obvious.

Proposed alternative: unified hierarchical summaries

Replace ~/.claude/projects/.../memory/ with a single summary.md file that lives in the project folder and its subfolders.

Core principles

1. Lives in the project — visible, editable, version-controllable. Not hidden in ~/.claude/.
2. Hierarchical — root folder gets a high-level summary; subfolders get their own summary.md with more granular detail. Loaded the same way CLAUDE.md currently is (walk up the tree, load subfolder ones on demand).
3. Combines everything — user preferences, project context, decisions, references, folder contents. One system, one place, one mental model.
4. Smart update frequency — not "when notable" (too infrequent) and not "every turn" (too noisy). Update when the turn changes the state of the project: decisions made, new information discovered, status changes, user preferences expressed. Skip quick factual Q&A, clarifications, casual conversation.
5. Holistic rewrites, not appending — each update should produce the best possible snapshot for a cold start. Rewrite sections as needed, consolidate, remove stale info. The file should read like a briefing document, not a changelog.
6. Silent updates — no "Let me update the summary" / "Summary updated" conversational text. The user knows it happens; announcing it wastes time and clutters the conversation.

Why this is better

• One system instead of two — no need to decide "is this a CLAUDE.md instruction or a memory?"
• Hierarchical by default — subfolder context is scoped naturally
• Visible to the user — it's in the project, not hidden in a dot folder
• Simpler mental model — "there's a summary at each level, deeper = more detail"
• Better quality — holistic rewrites produce a useful briefing; append-only logs become unreadable

Workaround

I've configured my user-level ~/.claude/CLAUDE.md to instruct Claude to ignore the built-in memory system and instead maintain summary.md files in the project folder. Full CLAUDE.md below — anyone can try this today.

<details>
<summary>My <code>~/.claude/CLAUDE.md</code></summary>

# Summary System

Instead of using the built-in memory system (`~/.claude/projects/.../memory/`), use a **summary.md** file that lives directly in the project folder and its subfolders.

## Rules

1. **Every project folder gets a `summary.md`** at its root. Subfolders can have their own `summary.md` too.
2. **Hierarchy**: The deeper you go, the more detail. A root `summary.md` is a high-level overview. A subfolder's `summary.md` has granular detail about that area.
3. **Lives in the project**: `summary.md` is part of the project, visible to the user, not hidden in `~/.claude/`.
4. **Do NOT use the built-in `~/.claude/projects/.../memory/` system**. Use `summary.md` instead.

## When to update

Not every turn — only when the turn **changes the state** of the project or the user's knowledge. Update after:
- Decisions made or changed
- New information discovered that affects the project
- Status changes on open items
- User preferences or feedback expressed

Do NOT update after:
- Quick factual questions and answers
- Clarifications about how things work
- Casual conversation
- Anything where the answer is already in the files or publicly available

When you do update, do it **silently** — no "Let me update the summary", no "Summary updated", no commentary. Just do the edit.

## How to update

**Do not append lines like a changelog.** Each update is a holistic rewrite of whatever sections need it. Read the current summary, then produce the best possible version of the document as if you were writing it fresh for someone arriving cold into this folder.

Ask yourself: "If a new Claude session opened this folder tomorrow with zero context, what would this file need to say?" Then make it say exactly that. This means:
- Rewrite sections, don't append to them
- Remove information that's no longer relevant
- Consolidate entries that say the same thing
- Keep it as concise as possible while being complete
- Dates belong only where they provide context (e.g., when a decision was made), not as a log

## Template

Every `summary.md` must use exactly this structure. Do not omit sections — if a section has no content yet, write "None yet."

# [Folder Name] — Summary

## User
Who the user is, their role, location, preferences, communication style, and how they like to work with Claude.

## Project
What this project/folder is about, its purpose, and current status.

## Decisions
Key decisions that have been made, with dates. What was chosen and why.

## Open Items
Pending tasks, unresolved questions, things to do next.

## References
Pointers to external resources, URLs, related files, exported conversations.

## Files
Table of files in this folder and what each one is.

| File | Description |
|---|---|
| `filename` | What it is |

## Meta
This file is part of a summary system that replaces Claude Code's built-in memory. Rules are defined in `~/.claude/CLAUDE.md`. Summary files live in the project folder (and subfolders), are hierarchical (deeper = more detail), and are updated when the project state changes.

**Last updated:** YYYY-MM-DD

</details>

---

🤖 Generated with Claude Code