Remember That

Read back through the current session and identify things worth remembering. Focus on:

High-signal learnings (always capture):

• Direct corrections: "no, use X not Y", "that's wrong", "actually..."
• Explicit requests: "remember:", "always do X", "never do Y"
• Process demonstrations: the user showed you a multi-step workflow
• Repeated corrections: you made the same mistake more than once in this session
• Tool rejections: the user blocked a tool call and explained why

Medium-signal learnings (capture if substantive):

• Preferences expressed through feedback: "perfect, do it like that", "yes exactly"
• Domain knowledge shared in passing: project relationships, team structure, technical constraints
• Conventions demonstrated by example: naming patterns, file organization, communication style

Low-signal (skip unless explicitly asked):

• One-off task details that won't recur
• Information already in CLAUDE.md or existing memory files
• Debugging steps specific to a transient issue
• Things derivable from code, git history, or project structure

Before listing anything, check what's already persisted. Read:

1. The project's CLAUDE.md (if it exists in the working directory)
2. The user's global ~/.claude/CLAUDE.md
3. The project's auto-memory index at ~/.claude/projects/<project-path>/memory/MEMORY.md (if it exists)
4. Project documentation directories — scan for existing docs structures (see "Discovering Project Docs" below)

Filter out anything that's already captured. The goal is net new knowledge only.

Discovering Project Docs

Many projects maintain their own documentation beyond CLAUDE.md. Before proposing where to save learnings, check whether the project has a docs structure that should receive certain types of knowledge. Look for:

• docs/, documentation/, wiki/, notes/ directories
• Architecture docs: docs/architecture.md, docs/adr/, ARCHITECTURE.md
• Runbooks or guides: docs/runbooks/, docs/guides/
• Design docs or specs: docs/design/, docs/specs/, docs/plans/
• READMEs in subdirectories that document specific subsystems

Also check CLAUDE.md and CONTRIBUTING.md for references to where documentation lives — projects sometimes have non-obvious locations (e.g., docs/docs/plans/ in a Docusaurus project).

When you find a project docs structure, certain learnings belong there instead of (or in addition to) CLAUDE.md:

• Architecture insights from deep dives — understanding of how systems connect, why things are structured a certain way → architecture docs
• Process/workflow documentation — deployment steps, release procedures, onboarding steps → runbooks or guides
• Design decisions and rationale — why a particular approach was chosen → ADRs or design docs
• Subsystem knowledge — deep understanding of a specific module or service → that subsystem's README or docs section

The key distinction: CLAUDE.md tells Claude how to behave. Project docs capture knowledge about the system that benefits anyone (human or AI) reading them. When a learning is more about understanding than instruction, it likely belongs in project docs.

Step 2: Present the Learning Plan

Keep the summary short and scannable. Show the destination path and a one-line description of what you'd save — no verbatim content previews, no routing rationale. The user can see where things are going and ask questions if something looks wrong. Group by destination:

Here's what I'd save from this session:

**Project CLAUDE.md** (`./CLAUDE.md`)
- Add no-database-mocking rule to Testing section (with why: mocks hid a prod migration failure)

**Global CLAUDE.md** (`~/.claude/CLAUDE.md`)
- Preference for integration tests over mocks across all projects

**Project Docs** (`docs/runbooks/deployment.md`)
- Full 5-step deployment process

**Auto-Memory**
- feedback: testing approach correction (repeated twice this session)

Always show the actual file paths. For CLAUDE.md updates, note whether it's project-level or global scope.

Routing Rules

Use these to decide where each learning goes:

Strong directives ("always use X", "never do Y") → CLAUDE.md. Softer context ("user prefers concise answers", "the migration is driven by compliance") → auto-memory.

Step 3: Wait for Confirmation

Do not write anything until the user approves. They might:

• Approve everything: "looks good" / "yes" / "go ahead"
• Edit the list: "skip the first one" / "actually put that in global instead"
• Add something you missed: "also remember that..."
• Reject everything: "nevermind" / "not worth saving"

Respect their edits. If they redirect scope (e.g., "that should be project-level, not global"), follow their judgment — they know their setup better than you do.

Step 4: Write the Learnings

Once approved, write each learning to its destination.

Writing to CLAUDE.md files

Learnings should fit naturally into the existing document structure — not land as isolated bullets tacked onto the end. Think about what process or workflow the learning belongs to, and integrate it there.

1. Read the current file first and understand its sections and structure
2. Find the process or workflow the learning belongs to. If the file has a "## Making Commits" section and you're adding a lint step, add it as a numbered step in that workflow — not as a standalone "## Linting" section
3. If no relevant section exists, create one that frames the learning as part of a workflow. For example, instead of "- Use make lint, not golangci-lint directly", create:

   ## Making Commits
   Before submitting a commit:
   1. Run `make lint` to check for lint errors (use `make lint`, not `golangci-lint` directly — it includes extra checks)
   2. Fix any errors before committing
   

4. Keep the same style and formatting as the rest of the file
5. Don't duplicate existing content — if you're reinforcing something already there, strengthen the existing wording instead

Writing to project docs

When adding to an existing project doc:

1. Read the current file and understand its structure and voice
2. Add the learning in the appropriate section, matching the existing style
3. If the doc uses a specific format (e.g., ADR template, numbered sections), follow it
4. Attribute the source where useful — "discovered during [date] session investigating [topic]"

When creating a new doc in the project's docs structure:

1. Follow existing naming conventions in that directory
2. Match the format of sibling docs
3. Keep it focused — one doc per topic, not a dump of everything learned

Always cross-reference from CLAUDE.md. When you create or update a project doc, also add a pointer in the project's CLAUDE.md so Claude knows the doc exists and when to consult it. For example, if you create docs/runbooks/deployment.md, add a line to CLAUDE.md like:

- See `docs/runbooks/deployment.md` for the full deployment process

Without this cross-reference, the doc might exist but Claude won't know to look there in future sessions.

If the project doesn't have an obvious docs structure and the learning is substantial enough to warrant its own doc (e.g., a full architecture deep-dive), suggest creating one and let the user decide where it should live.

Writing to auto-memory

Follow the auto-memory system's conventions:

1. Create a file in ~/.claude/projects/<project-path>/memory/ with a descriptive kebab-case name (e.g., feedback_testing-approach.md, user_background.md)
2. Use the standard frontmatter format:

---